> 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/guias/fluxo-formalizacao.md).

# Fluxo de Formalização

A **formalização de contrato** é o fluxo em que o originador submete uma proposta de empréstimo com garantia FGTS (uma CCB) e a Giro.Tech cuida do ciclo completo: **averba a garantia na Caixa**, **envia o contrato ao provedor bancário (GTBanker)** e **acompanha a formalização e o pagamento** ao tomador. Diferente das [operações FGTS](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/operacoes-fgts.md), a submissão é **síncrona** — o restante é assíncrono, acompanhado por webhook ou polling.

{% hint style="info" %}
Esse fluxo usa endpoints e identificadores **próprios** de contrato (`/api/v1/fgts/contracts/**`, `contractNumber`), distintos das operações FGTS-Caixa (`/api/v1/fgts/operations/**`, `requestId`). Os eventos de webhook chegam com `source = CONTRACT`. Ver [Contratos (Formalização)](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos.md).
{% endhint %}

{% hint style="danger" %}
**Averbação** e **cancelamento de reserva** via endpoints isolados (`POST /api/v1/fgts/endorsements`, `POST /api/v1/fgts/reserve-cancellations`) são **legado**. O fluxo atual concentra esses passos em **Contratos**: submissão em [Submeter Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/submeter-contrato.md), cancelamento/reversão em [Cancelar Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md).
{% endhint %}

***

## Visão geral

```
Submeter contrato → 201 { contractNumber } → (averbação → envio ao provedor → formalização → pagamento) → webhook (source: CONTRACT) OU polling do GET
```

O originador **submete** um contrato em `POST /api/v1/fgts/contracts` e recebe imediatamente `201 Created` com o `contractNumber` gerado (sequencial por originator). A partir daí, todo o andamento é **assíncrono**: a Giro averba a garantia na **Caixa**, envia o payload e o documento ao **provedor (GTBanker)**, confirma a **formalização** e acompanha o **pagamento** ao tomador.

Acompanhe os marcos de duas formas:

* **Webhook (recomendado)** — a Giro envia um `POST` para a URL cadastrada a cada milestone, com `source = CONTRACT`. Ver [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md).
* **Polling (fallback/reconciliação)** — consulte `GET /api/v1/fgts/contracts/{contractNumber}` para obter o `status` atual e os marcos do contrato.

{% hint style="info" %}
A submissão (`201`) confirma apenas que o contrato foi **recebido**. Ela **não** significa averbado, formalizado nem pago — acompanhe esses desfechos por webhook ou polling.
{% endhint %}

***

## Modo A vs Modo B

O envio do **PDF assinado da CCB** define o modo de entrada e o `status` inicial do contrato:

| Modo       | Como                                                                                                                                         | `status` inicial           |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| **Modo A** | O PDF assinado (base64) vai **junto** na submissão, no campo `signedDocumentBase64`.                                                         | `RECEIVED`                 |
| **Modo B** | O contrato é submetido **sem** o PDF; o documento assinado é enviado **depois** em `POST /api/v1/fgts/contracts/{contractNumber}/documents`. | `AWAITING_SIGNED_DOCUMENT` |

No **Modo B**, o contrato fica em `AWAITING_SIGNED_DOCUMENT` até o documento assinado ser anexado; nesse momento transita para `RECEIVED` e a formalização prossegue normalmente. Tentar anexar o documento quando o contrato **não** está em `AWAITING_SIGNED_DOCUMENT` retorna `409` — ver [Erros de formalização de contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#formalizacao).

***

## Ciclo de vida (status)

O contrato parte de `RECEIVED` (ou `AWAITING_SIGNED_DOCUMENT`, no Modo B) e caminha pelos marcos de averbação, formalização e pagamento até um estado **terminal**. A sequência típica de sucesso é:

```
RECEIVED → PENDING_ENDORSEMENT → ENDORSED → PENDING_FORMALIZATION → PENDING_CCB_CONFIRMATION → PENDING_DISBURSEMENT → DISBURSED
```

Quando o originador tem o **gate de aprovação de pagamento** habilitado (`requiresPaymentApproval = true`), a sequência inclui uma pausa após a averbação:

```
RECEIVED → … → ENDORSED → PENDING_PAYMENT_APPROVAL → (POST .../payment-approval) → PENDING_FORMALIZATION → … → DISBURSED
```

Nesse caso, a Giro emite `CONTRACT_PAYMENT_APPROVAL_REQUIRED` e aguarda a aprovação explícita do originador antes de enviar a CCB ao provedor. Originadores sem o gate seguem direto de `ENDORSED` para `PENDING_FORMALIZATION`.

Os ramos de falha e cancelamento desviam dessa sequência: a averbação pode ser recusada (`ENDORSEMENT_REJECTED` — de onde é possível [retentar](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/retentar-averbacao.md), voltando a `PENDING_ENDORSEMENT`, ou [cancelar](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md), indo a `CANCELLED`), o envio ao provedor pode falhar (`FORMALIZATION_FAILED`, que dispara a **compensação** — `REVERSING_ENDORSEMENT` desfaz a averbação na Caixa, podendo terminar em `REVERSAL_FAILED` se a reversão não concluir), e o originador pode cancelar um contrato em qualquer estado antes do desembolso (`CANCELLED`, passando por `REVERSING_ENDORSEMENT` quando há reserva na Caixa).

```mermaid
flowchart TD
    A[AWAITING_SIGNED_DOCUMENT] --> R[RECEIVED]
    R --> PE[PENDING_ENDORSEMENT]
    PE --> E[ENDORSED]
    PE --> ER[ENDORSEMENT_REJECTED]
    ER -->|retentativa| PE
    ER -->|cancelamento, código 52 ou janela expirada| C
    E --> PF[PENDING_FORMALIZATION]
    E --> PPA[PENDING_PAYMENT_APPROVAL]
    PPA --> PF
    PPA --> RE
    PF --> S[PENDING_CCB_CONFIRMATION]
    S --> F[PENDING_DISBURSEMENT]
    S --> FF[FORMALIZATION_FAILED]
    FF --> RE[REVERSING_ENDORSEMENT]
    RE --> RF[REVERSAL_FAILED]
    F --> P[DISBURSED]
    R --> C[CANCELLED]
    PE --> C
    E --> C
```

| `status`                   | Terminal?               | Significado                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AWAITING_SIGNED_DOCUMENT` | não                     | **Modo B**: contrato recebido, aguardando o PDF assinado da CCB (`POST .../documents`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `RECEIVED`                 | não                     | Contrato (e, no Modo A, o PDF) recebido e validado. A formalização vai prosseguir.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `PENDING_ENDORSEMENT`      | não                     | Aguardando a averbação da garantia na Caixa.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `ENDORSED`                 | não                     | Garantia averbada/reservada na Caixa.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `PENDING_PAYMENT_APPROVAL` | não                     | Gate ativo: averbado, aguardando aprovação de pagamento pelo originador (`POST .../payment-approval`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `ENDORSEMENT_REJECTED`     | **sim**, mas retentável | A Caixa recusou a averbação. É o único estado que admite [retentativa de averbação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/retentar-averbacao.md) (`POST .../endorsement-retries`), que devolve o contrato a `PENDING_ENDORSEMENT` reusando o mesmo `reserveIdentifier`. São 3 retentativas por reserva — 4 tentativas no total. Também aceita [cancelamento](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md), que leva a `CANCELLED` — irreversível, e abre mão das retentativas restantes. **Não é um estado de repouso:** sem retentativa dentro da janela, a Giro cancela o contrato e emite `CONTRACT_CANCELLED` (ver abaixo). |
| `PENDING_FORMALIZATION`    | não                     | Averbado; preparando o envio ao provedor (GTBanker).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `PENDING_CCB_CONFIRMATION` | não                     | Payload e documento enviados ao provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `PENDING_DISBURSEMENT`     | não                     | O provedor confirmou o recebimento da CCB. A partir daqui, o PDF da CCB fica disponível para download.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `DISBURSED`                | **sim**                 | Desembolso ao tomador confirmado. Desfecho de sucesso.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `REVERSING_ENDORSEMENT`    | não                     | A averbação está sendo desfeita na Caixa — após falha no provedor (termina em `FORMALIZATION_FAILED`) ou num cancelamento (termina em `CANCELLED`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `FORMALIZATION_FAILED`     | **sim**                 | Falha/recusa no provedor; a garantia é liberada (compensação).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `REVERSAL_FAILED`          | **sim**                 | A reversão da averbação (compensação) não concluiu — requer tratamento da Giro.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `CANCELLED`                | **sim**                 | Contrato cancelado pelo originador (`DELETE`), ainda não-terminal no momento do cancelamento.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

{% hint style="info" %}
O `status` do **contrato** é independente do `status` assíncrono das **operações FGTS** (`QUEUED` → `COMPLETED`/`FAILED`/…). Um mesmo contrato gera **vários** `requestId` ao longo da saga; a correlação dos eventos de contrato é feita pelo `contractNumber` (+ `clientReference`, se você o forneceu). Ver [Glossário](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/glossario.md#formalizacao-contratos).
{% endhint %}

***

## Revisão de desembolso

Quando o provedor **recusa a conta de desembolso** informada, a Giro emite o evento `CONTRACT_PAYMENT_REVISION`. Para destravar o pagamento, o originador corrige a conta chamando:

```
PUT /api/v1/fgts/contracts/{contractNumber}/disbursement-account
```

com a conta corrigida — **PIX** ou **conta bancária** (informe **exatamente um** dos dois; o XOR é validado na borda, ver [Erros de formalização de contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#formalizacao)). Se a nova conta também for recusada pelo provedor, a chamada retorna `422`.

O `data` do `CONTRACT_PAYMENT_REVISION` traz o que você precisa para decidir:

| Campo              | Para quê                                                                                                                                                                             |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `availableActions` | O que o provedor aceita: `NEW_ACCOUNT` (conta/PIX **diferente** da que falhou) e/ou `RETRY` (reenviar a **mesma** conta). Ausente em tickets antigos — trate como `["NEW_ACCOUNT"]`. |
| `dueAt`            | Instante exato em que o ticket expira. **É este que decide se ainda dá tempo.**                                                                                                      |
| `dueDate`          | Último dia, no fuso de São Paulo, em que a emenda ainda é aceita — quando `dueAt` cai à meia-noite, é o dia **anterior**. Mantido por compatibilidade.                               |
| `reason`           | Motivo da revisão (`code` + `message`).                                                                                                                                              |

O mesmo estado aparece em `revision` na [consulta do contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md), útil se o webhook se perdeu. Detalhes e cenários de teste em [Revisar Conta de Desembolso](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/revisar-conta-desembolso.md).

{% hint style="warning" %}
`CONTRACT_PAYMENT_REVISION` é **acionável**: reenvie a conta de desembolso antes de `data.dueAt`, respeitando `data.availableActions`. Já o `CONTRACT_PAYMENT_FAILED` é **informativo** — uma falha de desembolso em resolução pela Giro, sem ação do originador.
{% endhint %}

***

## Documento da CCB

Dois artefatos da CCB ficam disponíveis para download, cada um com seu endpoint:

* **PDF assinado enviado pelo originador** — `GET /api/v1/fgts/contracts/{contractNumber}/documents/signed`. Disponível assim que o documento assinado é anexado (Modo A na submissão ou Modo B via `POST .../documents`); antes disso retorna `404` (`CONTRACT_SIGNED_DOCUMENT_NOT_AVAILABLE`).
* **Documento gerado pela Giro** — `GET /api/v1/fgts/contracts/{contractNumber}/documents/template`. Após o contrato chegar a `PENDING_DISBURSEMENT`, a Giro emite o evento `CONTRACT_DOCUMENT_GENERATED` e este documento fica disponível; antes disso retorna `404` (`CONTRACT_DOCUMENT_NOT_AVAILABLE`).

Ambos respondem com uma **URL temporária (presigned)** de vida curta — baixe o arquivo logo após obtê-la.

***

## Mapa evento ↔ status

Os eventos de webhook `CONTRACT_*` (`source = CONTRACT`) marcam os milestones do ciclo de vida. A tabela abaixo relaciona cada evento ao marco correspondente. O catálogo completo está em [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md).

| `eventType`                     | Marco / `status` correspondente                                                                                                                                                                                                                                                                         |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CONTRACT_RECEIVED`             | Contrato (CCB) recebido e validado (`RECEIVED`).                                                                                                                                                                                                                                                        |
| `CONTRACT_ENDORSED`             | Averbação/reserva confirmada na Caixa (`ENDORSED`).                                                                                                                                                                                                                                                     |
| `CONTRACT_ENDORSEMENT_REJECTED` | A Caixa recusou a averbação (`ENDORSEMENT_REJECTED`) — ou o teto de retentativas foi atingido. É possível [retentar](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/retentar-averbacao.md).                                                                                  |
| `CONTRACT_CANCELLED`            | O contrato foi cancelado. `data.reason.code` diz por quê: `CANCELLED_BY_ORIGINATOR`, `ENDORSEMENT_DENIED_NOT_RETRYABLE` (código 52 da Caixa), `ENDORSEMENT_RETRY_WINDOW_EXPIRED` (recusa não retentada dentro da janela) ou `DISBURSEMENT_REVISION_EXPIRED` (revisão de conta expirada sem nova conta). |
| `CONTRACT_SENT_TO_GTBANKER`     | Payload e documento enviados ao provedor (`PENDING_CCB_CONFIRMATION`).                                                                                                                                                                                                                                  |
| `CONTRACT_FORMALIZED`           | O provedor confirmou o recebimento da CCB (`PENDING_DISBURSEMENT`).                                                                                                                                                                                                                                     |
| `CONTRACT_PAID`                 | Desembolso ao tomador confirmado (`DISBURSED`).                                                                                                                                                                                                                                                         |
| `CONTRACT_PAYMENT_REVISION`     | Pagamento em revisão — **reenvie a conta de desembolso** (ação do originador).                                                                                                                                                                                                                          |
| `CONTRACT_PAYMENT_FAILED`       | Falha no desembolso — **informativo** (em resolução pela Giro).                                                                                                                                                                                                                                         |
| `CONTRACT_FORMALIZATION_FAILED` | Falha/recusa no provedor; a garantia é liberada via compensação (`FORMALIZATION_FAILED`).                                                                                                                                                                                                               |
| `CONTRACT_DOCUMENT_GENERATED`   | PDF da CCB gerado e disponível para download.                                                                                                                                                                                                                                                           |
| `CONTRACT_CANCELLED`            | Contrato cancelado pelo originador (`CANCELLED`).                                                                                                                                                                                                                                                       |

{% hint style="info" %}
Os eventos `CONTRACT_*` **não** seguem os sufixos de desfecho (`*_COMPLETED`/`*_FAILED`/`*_NEEDS_VERIFICATION`/`*_UNDER_REVIEW`) das operações FGTS-Caixa — cada um é um milestone próprio da saga de formalização. Ver [Eventos de formalização de contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md#eventos-de-formalizacao-de-contrato).
{% endhint %}

***

## Coleções Postman

| Coleção                                                                                                                                                                            | Uso                                                     |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| [GTFgts-Ingress.postman\_collection.json](https://github.com/giro-tech/giro-tech-docs/tree/github-to-gitbook/.gitbook/assets/GTFgts-Ingress.postman_collection.json)               | Catálogo completo de endpoints REST (gerado do OpenAPI) |
| [GTFgts-Webhook-Events.postman\_collection.json](https://github.com/giro-tech/giro-tech-docs/tree/github-to-gitbook/.gitbook/assets/GTFgts-Webhook-Events.postman_collection.json) | Exemplos de payload de cada evento de webhook           |

{% file src="/files/OaLcSyEbJ9ibwMnkwdkI" %}
GTFgts — coleção Postman (API REST do originator).
{% endfile %}

Para validar o receptor de webhook, importe a coleção de eventos descrita em [Webhooks — Collection Postman](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks.md#collection-postman).

A jornada comercial típica **antes** da formalização inclui [consulta de saldo](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/operacoes-fgts.md#consulta-de-saldo-fgts) (assíncrona, com polling) e [simulação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/simulacoes/criar-simulacao.md). Modo A/B define apenas **como o PDF entra** — não substituem essas etapas.

***

## Próximos passos

* [Contratos (Formalização)](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos.md) — a referência dos endpoints de contrato.
* [Cancelar Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md) — cancelamento durante a formalização (pré-terminal).
* [Encerramento de contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/encerramento.md) — desistência ou quitação antecipada de contrato vigente.
* [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md) — o catálogo de eventos `CONTRACT_*` entregues por webhook.
* [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#formalizacao) — os cenários de erro específicos da formalização.

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