> 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/enviar-documento-assinado.md).

# Enviar Documento Assinado

Anexa o **PDF assinado da CCB** a um contrato submetido no **Modo B** — ou seja, que está em `AWAITING_SIGNED_DOCUMENT`. Ao receber o documento, o contrato transita para `RECEIVED` e a formalização prossegue.

{% hint style="info" %}
Use esta operação apenas no fluxo **Modo B** (contrato submetido sem `signedDocumentBase64`). No **Modo A**, o documento já foi enviado na própria submissão e o contrato não está em `AWAITING_SIGNED_DOCUMENT` — anexar novamente retorna `409`. Ver [Submeter contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/submeter-contrato.md).
{% endhint %}

## Request

`POST /api/v1/fgts/contracts/{contractNumber}/documents`

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. |

### Corpo

`Content-Type: application/json`. O PDF trafega como **base64** em campo JSON (não há upload `multipart`).

| Campo                  | Tipo              | Obrigatório | Descrição                                 |
| ---------------------- | ----------------- | ----------- | ----------------------------------------- |
| `signedDocumentBase64` | `string` (base64) | Sim         | PDF assinado da CCB codificado em base64. |

## Response

| Campo             | Tipo                | Descrição                                                   |
| ----------------- | ------------------- | ----------------------------------------------------------- |
| `contractNumber`  | `string`            | Número do contrato.                                         |
| `status`          | `string`            | `RECEIVED` — documento anexado; a formalização prossegue.   |
| `clientReference` | `string` (nullable) | Eco do `clientReference` informado na submissão, ou `null`. |

* **201 Created** — documento assinado anexado; contrato em `RECEIVED`.

## Exemplo

```http
POST /api/v1/fgts/contracts/00012346/documents HTTP/1.1
Host: ingress.gtfgts.staging.giro.tech
Authorization: Bearer {originatorToken}
Content-Type: application/json

{
  "signedDocumentBase64": "JVBERi0xLjQKJ..."
}
```

O campo `signedDocumentBase64` contém o **PDF assinado da CCB** codificado em base64 (valor encurtado no exemplo).

```json
{
  "contractNumber": "00012346",
  "status": "RECEIVED",
  "clientReference": "CLI-2024-00042"
}
```

## Próximo passo

Acompanhe a formalização por [Consultar contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md) ou pelo [webhook](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md) (`source = CONTRACT`).

## Erros

| Código | Situação                                                                                                                                                                                                                                                 |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `signedDocumentBase64` ausente, em branco, Base64 inválido, sem cabeçalho `%PDF-` ou acima de 10 MiB decodificado — `errorCode = VALIDATION_ERROR`, com o motivo em `errors.signedDocumentBase64`                                                        |
| 401    | Token ausente, inválido ou expirado — `errorCode = UNAUTHORIZED`                                                                                                                                                                                         |
| 404    | Contrato inexistente ou fora do escopo do token — `errorCode = CONTRACT_NOT_FOUND`                                                                                                                                                                       |
| 409    | Contrato não está em `AWAITING_SIGNED_DOCUMENT` — `errorCode = CONTRACT_IDEMPOTENCY_CONFLICT`                                                                                                                                                            |
| 415    | Content-Type da requisição não é `application/json` — resposta padrão do framework, **sem** `errorCode`                                                                                                                                                  |
| 4xx    | O serviço de formalização recusou a requisição — o `errorCode` dele é repassado, ou `CONTRACT_REQUEST_REJECTED` quando não há código próprio. Ver [Erros de formalização](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#formalizacao) |
| 429    | Rate limit excedido (30 req/min por originator) — `errorCode = RATE_LIMIT_EXCEEDED` (headers `Retry-After`, `X-RateLimit-*`)                                                                                                                             |
| 503    | Serviço de formalização temporariamente indisponível — `errorCode = SUBMISSION_TEMPORARILY_UNAVAILABLE` (header `Retry-After: 5`)                                                                                                                        |
| 500    | Erro interno inesperado — `errorCode = INTERNAL_ERROR`                                                                                                                                                                                                   |

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).

## Envia o PDF assinado de um contrato (Modo B)

> Upload posterior do documento assinado para um contrato submetido em Modo B (\`status: AWAITING\_SIGNED\_DOCUMENT\`). A requisição é \`application/json\` (\`AttachSignedDocumentRequest\`) com o campo \`signedDocumentBase64\` (\*\*obrigatório\*\*).\
> O ingress repassa o corpo ao formalizer e devolve o \`201 { contractNumber, status, clientReference }\` com o status atualizado.

```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":{"post":{"operationId":"submitSignedDocument","tags":["fgts-contracts"],"summary":"Envia o PDF assinado de um contrato (Modo B)","description":"Upload posterior do documento assinado para um contrato submetido em Modo B (`status: AWAITING_SIGNED_DOCUMENT`). A requisição é `application/json` (`AttachSignedDocumentRequest`) com o campo `signedDocumentBase64` (**obrigatório**).\nO ingress repassa o corpo ao formalizer e devolve o `201 { contractNumber, status, clientReference }` com o status atualizado.","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 antes do gateway.","schema":{"type":"string","pattern":"^\\d{1,20}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Corpo JSON de `POST /api/v1/fgts/contracts/{contractNumber}/documents` (Modo B). Carrega o PDF assinado da CCB em base64; o contrato deve estar em `AWAITING_SIGNED_DOCUMENT`.","required":["signedDocumentBase64"],"properties":{"signedDocumentBase64":{"type":"string","format":"byte","description":"PDF assinado da CCB codificado em base64 (**obrigatório**). Deve representar um `application/pdf` válido de até 10 MiB decodificado. Ausente, em branco, base64 inválido, sem o cabeçalho `%PDF-` ou acima do limite → `400` `VALIDATION_ERROR`, com o motivo em `errors.signedDocumentBase64`."}}}}}},"responses":{"201":{"description":"Documento aceito; o status do contrato é atualizado pelo formalizer.","content":{"application/json":{"schema":{"type":"object","description":"Resposta de `POST /api/v1/fgts/contracts` (e `/documents`, `/reprocess`). Repassa a resposta do formalizer. O ingress **não** gera o `contractNumber`; não há `contractId` (D16) nem `s3Key` (interno ao formalizer).","required":["contractNumber","status"],"properties":{"contractNumber":{"type":"string","description":"Número do contrato gerado pelo formalizer, sequencial por originador. O ingress NÃO gera este número."},"status":{"type":"string","enum":["RECEIVED","AWAITING_SIGNED_DOCUMENT"],"description":"Status inicial atribuído pelo formalizer na admissão. `RECEIVED`: contrato recebido (PDF presente). `AWAITING_SIGNED_DOCUMENT`: aguardando upload posterior do documento assinado."},"clientReference":{"type":"string","nullable":true,"maxLength":255,"description":"Identificador do cliente no originador, ecoado da requisição."}}}}}},"400":{"description":"Requisição inválida — falha de validação de Bean Validation (campos obrigatórios ausentes, formatos incorretos, CPF com dígitos errados, etc.). O campo `errors` contém um mapa `{ \"campo\": \"mensagem\" }` para cada campo inválido. O campo `title` é sempre `\"Bean validation error\"` e `detail` é sempre `\"One or more fields were invalid. See 'errors' for details.\"`.\nRejeições de regra de negócio também chegam como `400`, com `errorCode` próprio (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Quando a rejeição aponta um campo do request, ela traz o mesmo `errors` e o mesmo `detail`; quando não há campo associado, `errors` é omitido e `detail` é o reason phrase do status.","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."}}}}}},"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."}}}}}},"409":{"description":"Conflito com o estado atual do recurso — o pedido é válido, mas não cabe no estado em que o recurso está. O caso específico vem no `errorCode` do corpo; a descrição de cada rota lista os códigos que ela pode devolver.","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."}}}}}},"415":{"description":"`Content-Type` da requisição diferente de `application/json`. Resposta padrão do framework: `type: about:blank` e **sem** `errorCode` nem `timestamp`.","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."}}}}}}}}}}}
```

## Resultado no webhook

Os marcos seguintes de formalização chegam ao webhook cadastrado com `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/>" %}
