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

# Contratos (Formalização)

Nesta seção o originador **submete um contrato de empréstimo com garantia FGTS** (uma CCB — Cédula de Crédito Bancário) e a Giro.Tech cuida da **formalização**: averba a garantia na Caixa, envia o contrato ao provedor bancário e acompanha o pagamento ao tomador.

## Modelo

```
Submeter contrato → 201 { contractNumber, status } → (formalização) → webhook (source: CONTRACT) OU polling do GET
```

A **submissão é síncrona**: a API responde `201` com o `contractNumber` gerado (sequencial por originador). Todo o **andamento posterior é assíncrono** — averbação na Caixa, envio ao provedor, formalização e pagamento — e chega ao originador por [webhook](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md) (`source = CONTRACT`) ou por [polling](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md) do `GET`.

{% hint style="info" %}
A submissão (`201`) confirma apenas que o contrato foi **recebido**. O contrato ainda passa por averbação, envio ao provedor e formalização — acompanhe esses marcos via [webhook](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md) ou consultando o `GET /api/v1/fgts/contracts/{contractNumber}`.
{% endhint %}

## Modo A vs Modo B

O envio do **PDF assinado da CCB** define o modo de entrada:

| Modo       | Como                                                                                                                                                                                                               | `status` inicial           |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
| **Modo A** | O PDF assinado vai **junto** na submissão (campo `signedDocumentBase64`).                                                                                                                                          | `RECEIVED`                 |
| **Modo B** | O contrato é submetido **sem** o PDF; o documento assinado é enviado **depois** em [`POST .../documents`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/enviar-documento-assinado.md). | `AWAITING_SIGNED_DOCUMENT` |

No **Modo B**, o contrato fica em `AWAITING_SIGNED_DOCUMENT` até o documento assinado ser anexado, quando então segue direto para `PENDING_ENDORSEMENT` e a formalização prossegue. Se a geração da CCB falhar, o contrato vai para `DOCUMENT_GENERATION_FAILED` (webhook `CONTRACT_DOCUMENT_GENERATION_FAILED`). Esse estado não é terminal: se a geração for concluída depois — resultado atrasado ou geração refeita pelo suporte —, o contrato volta a `AWAITING_SIGNED_DOCUMENT` e o webhook `CONTRACT_DOCUMENT_GENERATED` é emitido.

## Cancelamento vs encerramento

| Situação                                                     | Seção                                                                                                                 | Endpoint                                         |
| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| Contrato **em formalização** (pré-terminal)                  | [Cancelar Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md)   | `DELETE /api/v1/fgts/contracts/{contractNumber}` |
| Contrato **já vigente** — desistência ou quitação antecipada | [Encerramento de contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/encerramento.md) | `POST .../reserve-cancellations`                 |

## Formalização

| Operação                                                                                                                             | Método e Path                                                      | Descrição                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Submeter contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/submeter-contrato.md)                  | `POST /api/v1/fgts/contracts`                                      | Submete uma CCB para formalização (Modo A com PDF assinado, ou Modo B sem)                                                                                                                |
| [Enviar documento assinado](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/enviar-documento-assinado.md)  | `POST /api/v1/fgts/contracts/{contractNumber}/documents`           | Anexa o PDF assinado da CCB (fluxo Modo B)                                                                                                                                                |
| [Consultar contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md)                | `GET /api/v1/fgts/contracts/{contractNumber}`                      | Consulta o status e os marcos de formalização do contrato                                                                                                                                 |
| [Retentar averbação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/retentar-averbacao.md)                | `POST /api/v1/fgts/contracts/{contractNumber}/endorsement-retries` | Nova tentativa de averbação para contrato em `ENDORSEMENT_REJECTED`, reusando o mesmo `reserveIdentifier`. Teto de 3 retentativas; recusa por teto chega **por webhook**, não na resposta |
| [Aprovar pagamento](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/aprovar-pagamento.md)                  | `POST /api/v1/fgts/contracts/{contractNumber}/payment-approval`    | Aprova manualmente o pagamento quando o gate está ativo (`requiresPaymentApproval`)                                                                                                       |
| [Cancelar contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md)                  | `DELETE /api/v1/fgts/contracts/{contractNumber}`                   | Cancela durante a formalização (pré-terminal)                                                                                                                                             |
| [Revisar conta de desembolso](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/revisar-conta-desembolso.md) | `PUT /api/v1/fgts/contracts/{contractNumber}/disbursement-account` | Atualiza a conta de pagamento quando o provedor pede revisão                                                                                                                              |
| [Baixar CCB (gerada pela Giro)](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/baixar-documento-ccb.md)   | `GET /api/v1/fgts/contracts/{contractNumber}/documents/template`   | URL temporária para baixar o documento da CCB gerado pela Giro ao final da formalização                                                                                                   |
| [Baixar CCB assinada](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/baixar-ccb-assinada.md)              | `GET /api/v1/fgts/contracts/{contractNumber}/documents/signed`     | URL temporária para baixar o PDF assinado que o originador enviou                                                                                                                         |

## Encerramento

| Operação                                                                                                                               | Método e Path                                                        | Descrição                                              |
| -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------ |
| [Submeter solicitação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/encerramento/submeter-solicitacao.md) | `POST /api/v1/fgts/contracts/{contractNumber}/reserve-cancellations` | Desistência ou quitação antecipada de contrato vigente |
| [Acompanhar o desfecho](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/encerramento/consultar-status.md)    | `GET /api/v1/fgts/operations/{requestId}`                            | Acompanha a solicitação de encerramento                |

Entenda o ciclo completo em [Fluxo de formalização](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-formalizacao.md).

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