> For the complete documentation index, see [llms.txt](https://docs.giro.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/baixar-documento-ccb.md).

# Baixar CCB (gerada pela Giro)

Obtém uma **URL temporária** para baixar o PDF da **CCB gerada pela Giro** ao final da formalização. A URL é uma *presigned URL* do S3, de vida curta — baixe o documento antes de `expiresAt`.

{% hint style="info" %}
Este endpoint devolve o documento **gerado pela Giro**, emitido quando o contrato chega a `PENDING_DISBURSEMENT` (evento `CONTRACT_DOCUMENT_GENERATED`). Antes disso, retorna `404`. **Não** é o PDF assinado que você enviou — para esse, use [Baixar CCB Assinada](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/baixar-ccb-assinada.md).
{% endhint %}

{% hint style="warning" %}
A URL *presigned* dá acesso direto ao PDF **sem autenticação adicional**. Trate-a como sensível: não a registre em logs nem a compartilhe, e inicie o download antes de `expiresAt`.
{% endhint %}

## Request

`GET /api/v1/fgts/contracts/{contractNumber}/documents/template`

Autenticado: `Authorization: Bearer {originatorToken}` (perfil `ROLE_ORIGINATOR`).

### Parâmetros

| Parâmetro        | Local | Tipo                    | Obrigatório | Descrição                               |
| ---------------- | ----- | ----------------------- | ----------- | --------------------------------------- |
| `contractNumber` | path  | `string` (`^\d{1,20}$`) | Sim         | Número do contrato gerado na submissão. |

## Response

| Campo            | Tipo                    | Descrição                                                                                                   |
| ---------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------- |
| `contractNumber` | `string`                | Número do contrato.                                                                                         |
| `url`            | `string` (URL)          | URL *presigned* do S3 para baixar o PDF da CCB gerada pela Giro. Acesso direto, sem autenticação adicional. |
| `expiresAt`      | `string` (ISO-8601 UTC) | Instante em que a URL expira. Baixe o documento antes disso.                                                |

* **200 OK** — URL de download gerada.

## Exemplo

```http
GET /api/v1/fgts/contracts/00012345/documents/template HTTP/1.1
Host: ingress.gtfgts.staging.giro.tech
Authorization: Bearer {originatorToken}
```

```json
{
  "contractNumber": "00012345",
  "url": "https://storage.giro.tech/00012345_generated.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=...",
  "expiresAt": "2026-06-24T14:10:00Z"
}
```

A `url` é de **vida curta**: faça o download antes de `expiresAt`. Para obter o documento depois de expirado, chame este endpoint novamente para gerar uma nova URL.

## Erros

| Código | Situação                                                                                                                                                                                                       |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `contractNumber` fora do padrão — `errorCode = VALIDATION_ERROR`                                                                                                                                               |
| 401    | Token ausente, inválido ou expirado — `errorCode = UNAUTHORIZED`                                                                                                                                               |
| 404    | Documento gerado indisponível (contrato ainda não `PENDING_DISBURSEMENT`, ou em `DOCUMENT_GENERATION_FAILED`), contrato inexistente ou fora do escopo do token — `errorCode = CONTRACT_DOCUMENT_NOT_AVAILABLE` |
| 500    | Erro interno inesperado — `errorCode = INTERNAL_ERROR`                                                                                                                                                         |
| 503    | Serviço temporariamente indisponível — `errorCode = SUBMISSION_TEMPORARILY_UNAVAILABLE` (header `Retry-After: 5`)                                                                                              |

Os erros seguem o formato `ProblemDetail` (RFC 7807), com o campo `errorCode`. Ver [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md).

## Obtém a URL de download do documento CCB de um contrato

> Retorna uma URL pré-assinada (presigned S3) do documento modelo da CCB associado ao contrato. O ingress \*\*não\*\* baixa o binário — apenas repassa a URL do formalizer. A URL expira em um tempo curto (ver \`expiresAt\`); o cliente deve iniciar o download imediatamente.\
> \*\*Disponibilidade:\*\* o documento é gerado pelo formalizer após a formalização ser concluída (status \`PENDING\_DISBURSEMENT\`). Se ainda não estiver disponível, retorna \`404\` com \`errorCode: CONTRACT\_DOCUMENT\_NOT\_AVAILABLE\`.\
> \*\*Escopo por originador:\*\* o \`X-Originator-Id\` é carimbado internamente pelo ingress (assinado via HMAC); o formalizer escopa a consulta pelo originador autenticado. Um \`contractNumber\` fora do escopo do token resolve para \`404\`.

```json
{"openapi":"3.0.3","info":{"title":"gtfgts-ingress Public API","version":"0.0.1"},"tags":[{"name":"fgts-contracts","description":"Submissão e acompanhamento de contratos (formalização) FGTS."}],"servers":[{"url":"https://ingress.gtfgts.staging.giro.tech","description":"Homologação (testes e validação da integração)"},{"url":"https://gtfgts.giro.tech","description":"Produção (operações reais)"},{"url":"http://localhost:8080","description":"Local (bootRun -Pprofiles=local)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT de originator fornecido pela GTLab no cadastro do originator. Identifica e autoriza o originator em todos os endpoints `/api/v1/**`.\nInclua no header: `Authorization: Bearer <token>`."}}},"paths":{"/api/v1/fgts/contracts/{contractNumber}/documents/template":{"get":{"operationId":"getContractDocument","tags":["fgts-contracts"],"summary":"Obtém a URL de download do documento CCB de um contrato","description":"Retorna uma URL pré-assinada (presigned S3) do documento modelo da CCB associado ao contrato. O ingress **não** baixa o binário — apenas repassa a URL do formalizer. A URL expira em um tempo curto (ver `expiresAt`); o cliente deve iniciar o download imediatamente.\n**Disponibilidade:** o documento é gerado pelo formalizer após a formalização ser concluída (status `PENDING_DISBURSEMENT`). Se ainda não estiver disponível, retorna `404` com `errorCode: CONTRACT_DOCUMENT_NOT_AVAILABLE`.\n**Escopo por originador:** o `X-Originator-Id` é carimbado internamente pelo ingress (assinado via HMAC); o formalizer escopa a consulta pelo originador autenticado. Um `contractNumber` fora do escopo do token resolve para `404`.","parameters":[{"name":"contractNumber","in":"path","required":true,"description":"Número do contrato gerado pelo formalizer. Validado na borda contra o padrão `^\\d{1,20}$` para prevenção de path traversal.","schema":{"type":"string","pattern":"^\\d{1,20}$"}}],"responses":{"200":{"description":"URL presigned disponível.","content":{"application/json":{"schema":{"type":"object","description":"Resposta de `GET /api/v1/fgts/contracts/{contractNumber}/documents/template`. Contém a URL presigned S3 do documento modelo da CCB. O ingress não baixa o binário — apenas repassa a URL gerada pelo formalizer. A URL tem tempo de vida curto; o cliente deve iniciar o download antes de `expiresAt`.","required":["contractNumber","url","expiresAt"],"properties":{"contractNumber":{"type":"string","description":"Número do contrato ao qual o documento pertence."},"url":{"type":"string","format":"uri","description":"URL pré-assinada (presigned S3) para download do PDF da CCB. Válida até `expiresAt`; acesso direto sem autenticação adicional."},"expiresAt":{"type":"string","format":"date-time","description":"Instante (ISO-8601 UTC) em que a URL presigned expira. O cliente deve iniciar o download antes desse momento."}}}}}},"401":{"description":"Não autenticado — JWT ausente, inválido ou expirado. Autentique-se e inclua o token no header `Authorization: Bearer <token>`.","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro estruturado segundo RFC 7807 — Problem Details for HTTP APIs. Campos adicionais `errorCode` (código canônico GTLab estável) e `timestamp` (instante do erro no servidor) são extensões proprietárias. O campo `errors` (mapa campo→mensagem) é incluído nos erros que apontam para um campo do request: validação de Bean Validation (`errorCode: VALIDATION_ERROR`, HTTP 400) e rejeições de regra de negócio que identificam o campo culpado (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Nos erros que não têm campo associado (`401`, `403`, `404`, `429`, `500`, `503`, e rejeições de negócio sem campo) o campo `errors` está ausente.","properties":{"type":{"type":"string","format":"uri","description":"URI de referência do tipo de problema."},"title":{"type":"string","description":"Título legível do tipo de problema."},"status":{"type":"integer","format":"int32","description":"HTTP status code do problema."},"detail":{"type":"string","description":"Descrição legível específica desta ocorrência do problema."},"instance":{"type":"string","description":"URI reference (relativa ou absoluta) que identifica esta ocorrência específica do problema. Geralmente o path do endpoint que gerou o erro."},"errorCode":{"type":"string","description":"Código de erro canônico GTLab estável para uso programático."},"timestamp":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no servidor (ISO-8601 UTC)."},"errors":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Mapa de erros no formato `{ \"campo\": \"mensagem\" }`, onde cada chave nomeia um campo do **request enviado por você**. Presente quando `errorCode` é `VALIDATION_ERROR` (falha de Bean Validation — `@NotBlank`, `@NotNull`, `@Size`, `@Pattern`, etc.) e também em rejeições de regra de negócio que conseguem apontar o campo culpado, como `CONTRACT_INSTALLMENTS_MISMATCH`. Quando presente, `detail` é `\"One or more fields were invalid. See 'errors' for details.\"`. Ausente em erros sem campo associado (`401`, `403`, `404`, `429`, `500`, `503`) e em rejeições de negócio que não se referem a um campo do request."}}}}}},"404":{"description":"Recurso não encontrado — identificador inexistente ou ainda não processado.","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro estruturado segundo RFC 7807 — Problem Details for HTTP APIs. Campos adicionais `errorCode` (código canônico GTLab estável) e `timestamp` (instante do erro no servidor) são extensões proprietárias. O campo `errors` (mapa campo→mensagem) é incluído nos erros que apontam para um campo do request: validação de Bean Validation (`errorCode: VALIDATION_ERROR`, HTTP 400) e rejeições de regra de negócio que identificam o campo culpado (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Nos erros que não têm campo associado (`401`, `403`, `404`, `429`, `500`, `503`, e rejeições de negócio sem campo) o campo `errors` está ausente.","properties":{"type":{"type":"string","format":"uri","description":"URI de referência do tipo de problema."},"title":{"type":"string","description":"Título legível do tipo de problema."},"status":{"type":"integer","format":"int32","description":"HTTP status code do problema."},"detail":{"type":"string","description":"Descrição legível específica desta ocorrência do problema."},"instance":{"type":"string","description":"URI reference (relativa ou absoluta) que identifica esta ocorrência específica do problema. Geralmente o path do endpoint que gerou o erro."},"errorCode":{"type":"string","description":"Código de erro canônico GTLab estável para uso programático."},"timestamp":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no servidor (ISO-8601 UTC)."},"errors":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Mapa de erros no formato `{ \"campo\": \"mensagem\" }`, onde cada chave nomeia um campo do **request enviado por você**. Presente quando `errorCode` é `VALIDATION_ERROR` (falha de Bean Validation — `@NotBlank`, `@NotNull`, `@Size`, `@Pattern`, etc.) e também em rejeições de regra de negócio que conseguem apontar o campo culpado, como `CONTRACT_INSTALLMENTS_MISMATCH`. Quando presente, `detail` é `\"One or more fields were invalid. See 'errors' for details.\"`. Ausente em erros sem campo associado (`401`, `403`, `404`, `429`, `500`, `503`) e em rejeições de negócio que não se referem a um campo do request."}}}}}},"503":{"description":"Serviço temporariamente indisponível. Aguarde `Retry-After` segundos e tente novamente.","headers":{"Retry-After":{"description":"Segundos recomendados até a próxima tentativa.","schema":{"type":"integer","format":"int64"}}},"content":{"application/problem+json":{"schema":{"type":"object","description":"Erro estruturado segundo RFC 7807 — Problem Details for HTTP APIs. Campos adicionais `errorCode` (código canônico GTLab estável) e `timestamp` (instante do erro no servidor) são extensões proprietárias. O campo `errors` (mapa campo→mensagem) é incluído nos erros que apontam para um campo do request: validação de Bean Validation (`errorCode: VALIDATION_ERROR`, HTTP 400) e rejeições de regra de negócio que identificam o campo culpado (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Nos erros que não têm campo associado (`401`, `403`, `404`, `429`, `500`, `503`, e rejeições de negócio sem campo) o campo `errors` está ausente.","properties":{"type":{"type":"string","format":"uri","description":"URI de referência do tipo de problema."},"title":{"type":"string","description":"Título legível do tipo de problema."},"status":{"type":"integer","format":"int32","description":"HTTP status code do problema."},"detail":{"type":"string","description":"Descrição legível específica desta ocorrência do problema."},"instance":{"type":"string","description":"URI reference (relativa ou absoluta) que identifica esta ocorrência específica do problema. Geralmente o path do endpoint que gerou o erro."},"errorCode":{"type":"string","description":"Código de erro canônico GTLab estável para uso programático."},"timestamp":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no servidor (ISO-8601 UTC)."},"errors":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Mapa de erros no formato `{ \"campo\": \"mensagem\" }`, onde cada chave nomeia um campo do **request enviado por você**. Presente quando `errorCode` é `VALIDATION_ERROR` (falha de Bean Validation — `@NotBlank`, `@NotNull`, `@Size`, `@Pattern`, etc.) e também em rejeições de regra de negócio que conseguem apontar o campo culpado, como `CONTRACT_INSTALLMENTS_MISMATCH`. Quando presente, `detail` é `\"One or more fields were invalid. See 'errors' for details.\"`. Ausente em erros sem campo associado (`401`, `403`, `404`, `429`, `500`, `503`) e em rejeições de negócio que não se referem a um campo do request."}}}}}}}}}}}
```

## Relacionado

* Para baixar o **PDF assinado que você enviou**, veja [Baixar CCB Assinada](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/baixar-ccb-assinada.md).
* O momento em que o documento gerado fica disponível (estado `PENDING_DISBURSEMENT`) é notificado no webhook cadastrado (`source = CONTRACT`). Consulte [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md), [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md) e o [Fluxo de formalização](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-formalizacao.md).

{% embed url="<https://giro.tech/central-de-atendimento/>" %}
