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

# Changelog da API

Registro das mudanças relevantes da **API GTFgts (Originator)** — novos endpoints, webhooks e alterações de contrato.

Convenção de formato:

* **Data** — cada release é identificada por uma data no formato ISO `AAAA-MM-DD`. **A mais recente fica no topo.**
* **Categorias por entrada** — cada mudança é classificada em uma destas categorias:
  * **Adicionado** — novos endpoints, campos opcionais ou eventos.
  * **Alterado** — mudança de comportamento ou ampliação de contrato já existente (ex.: novo valor de enum).
  * **Corrigido** — correção de bug ou de comportamento divergente do documentado.
  * **Removido / Descontinuado** — remoção ou deprecação de endpoint, campo ou evento.

Convenção de compatibilidade:

* **Aditivo (não-breaking)** — novos endpoints, campos opcionais ou eventos. **Retrocompatível**: integrações existentes continuam funcionando sem mudança.
* **Breaking** — remoção de campo, mudança de tipo ou de comportamento que exige ação do integrador. Sempre sinalizado explicitamente.

> Catálogo completo de eventos em [Webhooks — Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md). Códigos de erro em [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md).

***

## 2026-10-15

### Comprovante no cancelamento por contrato

**Adicionado** · **Aditivo (não-breaking)**

* [Submeter Solicitação de Encerramento](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/encerramento/submeter-solicitacao.md) (`POST /api/v1/fgts/contracts/{contractNumber}/reserve-cancellations`) ganha o campo opcional **`paymentProof`** `{contentBase64, contentType, filename}`: o comprovante do pagamento ou do estorno feito pelo cliente, que chega à análise interna da Giro junto com a solicitação. Ele **não** é enviado à Caixa.
* Tipos aceitos: `application/pdf`, `image/png` e `image/jpeg`, até **5 MiB** decodificados. O conteúdo precisa ser do tipo declarado.
* Códigos de erro novos, só para pedidos com o campo: `400` `PAYMENT_PROOF_UNSUPPORTED_CONTENT_TYPE`, `PAYMENT_PROOF_INVALID_BASE64`, `PAYMENT_PROOF_CONTENT_MISMATCH` e `413` `PAYMENT_PROOF_TOO_LARGE`. Comprovante recusado não registra a solicitação. Ver [Erros de formalização de contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#formalizacao).
* O cancelamento de reserva por identificador (`POST /api/v1/fgts/reserve-cancellations`) **não** recebe comprovante: um `paymentProof` enviado ali é ignorado, sem erro. Para anexar o comprovante, use a rota por contrato.
* Integrações que não enviam o campo não mudam nada.

***

## 2026-10-14

### Cancelamento de contrato com CCB no provedor passa pela operação da Giro

**Alterado** — `DELETE /api/v1/fgts/contracts/{contractNumber}` em `PENDING_DISBURSEMENT` (CCB recebida pelo provedor, sem desembolso) passa a responder `202` em **todas** as fases, com `cancellation.waitingFor = CCB_ARCHIVE_CONFIRMATION`. A Giro arquiva a CCB no provedor antes de desaverbar; o desfecho chega por webhook. Antes, as fases com revisão de conta respondiam `200`.

**Adicionado** — evento `CONTRACT_CANCELLATION_REJECTED` e código `CONTRACT_ALREADY_DISBURSED` (webhook, polling de operação e `409` no `DELETE` repetido): o provedor já pagou a CCB e o cancelamento foi interrompido. Para desfazer a operação, envie a desistência (`SEVEN_DAYS_REGRET`) em `reserve-cancellations`. Os cancelamentos de reserva (`reserve-cancellations`) de contratos nesse estado passam pela mesma confirmação e terminam em `CANCEL_RESERVE_COMPLETED` ou `CANCEL_RESERVE_FAILED` com esse código.

Aditivo, exceto pela troca `200` → `202` no `DELETE` em `PENDING_DISBURSEMENT` com revisão de conta aberta ou expirada: quem trata só `200` como sucesso precisa aceitar `202`.

***

## 2026-10-13

### `Idempotency-Key` reusada com outro corpo responde `422`

**Alterado** · **Breaking** (só para quem reusa a mesma chave com outro corpo)

* Num reenvio com a mesma `Idempotency-Key` e corpo diferente (ou outro `contractNumber`/`reserveIdentifier` na URL), a API passa a responder `422` com `errorCode = IDEMPOTENCY_KEY_PAYLOAD_MISMATCH` e não enfileira nada. Antes, devolvia o `requestId` da primeira submissão, e a operação nova era descartada em silêncio. Vale para as submissões de operações FGTS, a retentativa de averbação e as rotas de contrato `reserve-cancellations`, `guarantee-maintenances`, `endorsement-retries` e `payment-approval`. Mesma chave com o mesmo corpo segue devolvendo o `requestId` original. `POST /contracts` não muda: continua em `409 CONTRACT_IDEMPOTENCY_CONFLICT`. Ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/idempotencia.md#payload-diferente).

***

## 2026-10-05

### `Idempotency-Key` com no máximo 100 caracteres

**Alterado** · **Breaking** (só para quem enviava chaves com mais de 100 caracteres)

* O header `Idempotency-Key` passa de 255 para **100 caracteres** nas **submissões de operações FGTS** (averbação, consultas, cancelamento de reserva, manutenção de garantia e status de protocolo; ver [operações FGTS](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/operacoes-fgts.md)) e em `POST /contracts` ([Submeter Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/submeter-contrato.md)). A retentativa de averbação (`/endorsements/{reserveIdentifier}/retries`) e as demais rotas de contrato **seguem em 255**. Acima disso a API responde `400 VALIDATION_ERROR`, com o detalhe em `errors.idempotencyKey`. Em produção nenhuma chave existente passa de 51 caracteres. UUIDs não são afetados.

### `paidAt` em meia-noite de Brasília

**Alterado** · **Aditivo (não-breaking)** para quem já trata o campo como data

* `milestones.paidAt` em [Consultar Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md) passa a ser a data do pagamento à meia-noite de Brasília (`T03:00:00Z`), em vez de meia-noite UTC (`T00:00:00Z`). Quem converte para o fuso local deve usar a data (05/10), não o instante.

## 2026-10-04

### Averbação, manutenção de garantia e cancelamento de reserva não são canceláveis pelo `DELETE` da operação

**Alterado** · **Breaking de comportamento** (só para quem cancelava essas operações pelo `requestId`)

* [Cancelar Solicitação de Operação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/gerenciar-operacoes/cancelar-operacao.md) (`DELETE /api/v1/fgts/operations/{requestId}`) passa a responder **`409 OPERATION_NOT_CANCELLABLE`** para averbação, manutenção de garantia e cancelamento de reserva **mesmo antes de começarem a ser processadas** (estado `QUEUED`). Antes, enquanto estavam em `QUEUED`, eram canceladas com `200`. Vale para as submetidas pelas rotas de operação e pelas rotas de contrato.
* O `errorCode` e o `detail` são os mesmos do conflito por estado (`Operation is not in a cancellable state: {requestId}`). Nenhum campo novo.
* As consultas (saldo, valor reservado, protocolos da reserva e status de protocolo) continuam canceláveis enquanto estão em `QUEUED`.
* Para desfazer uma averbação, use o [Cancelamento de reserva](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-cancelamento-reserva.md) ou o [cancelamento do contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md).

### `DOCUMENT_GENERATION_FAILED` deixa de ser terminal

**Alterado** · **Aditivo (não-breaking)** para quem trata eventos fora de ordem

* Depois de [`CONTRACT_DOCUMENT_GENERATION_FAILED`](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md), o contrato pode receber **`CONTRACT_DOCUMENT_GENERATED`**: quando a geração da CCB é concluída depois (resultado atrasado ou geração refeita pelo suporte), o contrato volta de `DOCUMENT_GENERATION_FAILED` para `AWAITING_SIGNED_DOCUMENT` e o fluxo do Modo B segue normalmente — baixe a CCB, colete a assinatura e envie o documento assinado.
* Não feche o contrato no seu lado ao receber `CONTRACT_DOCUMENT_GENERATION_FAILED`. Antes de submeter contrato novo, confirme com o suporte.
* Não há nova tentativa automática além disso: sem resultado atrasado nem ação do suporte, o contrato permanece em `DOCUMENT_GENERATION_FAILED`.

## 2026-10-02

### Link do comprovante também no `GET` do contrato

**Adicionado** · **Aditivo (não-breaking)**

* [Consultar Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md) (`GET /api/v1/fgts/contracts/{contractNumber}`) ganha o campo opcional **`paymentReceiptUrl`**: o mesmo link do comprovante que chega no webhook [`CONTRACT_PAID`](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md). Não é mais preciso guardar o link só para reexibir o comprovante.
* O campo aparece depois do pagamento, inclusive quando o desembolso chega após um cancelamento, e fica ausente enquanto não houver comprovante. Ausência **não** significa que o pagamento falhou.
* **Continua sendo uma credencial.** Quem tem o link abre o comprovante sem autenticação: não o publique, não o grave em log nem o envie por canal aberto.
* Integrações que ignoram campos desconhecidos não precisam de nenhuma ação.

***

## 2026-10-01

### Catálogo completo de erros e correções da documentação

**Corrigido · Documentação (a API não mudou).**

[Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md) ganha um [Catálogo de códigos](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#catalogo): erros HTTP de borda, valores de `status` do polling, `error.code` de operação, códigos crus da Caixa por operação, estados de contrato que indicam falha e a regra de entrega de webhook — cada um com rota, quando ocorre e o que fazer. Várias páginas descreviam o comportamento de forma diferente da API, e foram corrigidas para refletir o que ela de fato devolve:

* **Código `14` da Caixa** é "já existe solicitação com o mesmo identificador", retentado automaticamente — não "saldo insuficiente" (que é o `37`).
* **Nomes de `error.code`**: a Caixa indeferindo cancelamento ou manutenção devolve `CANCELLATION_DENIED` e `MAINTENANCE_DENIED`, não `CANCEL_RESERVE_DENIED`/`MAINTAIN_GUARANTEE_DENIED`. A rejeição na revisão manual é `GUARANTEE_APPROVAL_REJECTED`, com `status = FAILED` no polling — não `RESERVE_CANCELLATION_REJECTED`/`CANCELLED`.
* **`error.code` nas consultas** é o código classificado (`PROVIDER_ERROR`, `CPF_NOT_OPERABLE`…), não o nome do evento (`BALANCE_QUERY_FAILED`, `QUERY_PROTOCOL_STATUS_FAILED`).
* **Entrega de webhook**: `408` e `429` do seu endpoint são retentados, como `5xx`. São até 4 reentregas (\~1, 5, 30 e 120 min). Deduplique por (`requestId`, `eventType`): o `requestId` sozinho descarta o desfecho final de operações que emitem mais de um evento.
* **Eventos `CONTRACT_*`**: `data.status` é o marco do contrato (`ENDORSED`, `PAID`, `CANCELLED`…), não `COMPLETED`/`FAILED`. `CONTRACT_PAYMENT_FAILED` traz o motivo em `error`, não em `reason`.
* **Eventos documentados**: `*_CANCELLED` (7 eventos, `error.code = OPERATOR_CANCELLED`), `MAINTAIN_GUARANTEE_UNDER_REVIEW`, `CONTRACT_ENDORSEMENT_RETRYING` e `CONTRACT_DOCUMENT_GENERATION_FAILED`.
* **PDF assinado inválido ou acima de 10 MiB** responde `400 VALIDATION_ERROR` com o motivo em `errors.signedDocumentBase64` — não `CONTRACT_DOCUMENT_INVALID_PDF` nem `413`. O `415` sai sem `errorCode`.
* **`403 ORIGINATOR_OWNERSHIP_VIOLATION`** só ocorre em `GET /api/v1/fgts/operations/{requestId}`; nas demais rotas, recurso de outro originator responde `404`.
* **`GET /api/v1/fgts/contracts/{contractNumber}`**: o campo `error` vem sempre `null`; o motivo de uma falha chega pelo webhook. Documentados o bloco `retry` e os estados `PENDING_PAYMENT_APPROVAL` e `DOCUMENT_GENERATION_FAILED`.
* **Polling**: documentados `AWAITING_PROVIDER` e `CANCELLED`; em `NEEDS_VERIFICATION` o campo `error` já vem preenchido.
* **`INGRESS_RATE_LIMIT_EXCEEDED`** traz só `Retry-After: 1`, sem `X-RateLimit-*`. `POST /api/v1/webhooks` usa `RATE_LIMIT_EXCEEDED` (25 req/min). `UPSTREAM_UNAVAILABLE` não traz `Retry-After`. Indisponibilidade na aprovação de pagamento é `SUBMISSION_TEMPORARILY_UNAVAILABLE`, não `SERVICE_UNAVAILABLE`.

***

## 2026-09-26

### Cancelamento de contrato em todo o ciclo, até o desembolso

**Alterado · Breaking de comportamento (sem mudança de campos obrigatórios).**

[Cancelar Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md) passa a aceitar contratos em `PENDING_CCB_CONFIRMATION` e `PENDING_DISBURSEMENT`, que antes respondiam `409 CONTRACT_NOT_CANCELLABLE`. Quando o contrato está no meio de uma etapa que não pode ser interrompida, a resposta é **`202 Accepted`** e o pedido é executado sozinho ao fim da etapa. Trate `202` como sucesso e aguarde o webhook.

O que muda para quem já integra:

* **`202 Accepted`** é uma resposta nova do `DELETE .../contracts/{contractNumber}`.
* **Contrato já averbado que é cancelado** (`PENDING_PAYMENT_APPROVAL`, `PENDING_FORMALIZATION`) passa a terminar em `CANCELLED` com `CONTRACT_CANCELLED` (`CANCELLED_BY_ORIGINATOR`). Antes terminava em `FORMALIZATION_FAILED` com `CONTRACT_FORMALIZATION_FAILED`. Falha real de formalização continua com `CONTRACT_FORMALIZATION_FAILED`.
* **Novo `reason.code`** no `CONTRACT_CANCELLED`: `DISBURSEMENT_REVISION_EXPIRED` — a Giro cancela o contrato 1 dia após o vencimento de uma revisão de conta de desembolso sem nova conta.

**Adicionado · Aditivo (não-breaking).**

* [Consultar Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md) ganha `disbursement` (`phase`, `phaseSince`, `overdue`) em `PENDING_DISBURSEMENT` e `cancellation` quando há pedido de cancelamento.
* `revision` continua presente depois do prazo, com `expired: true` (antes sumia).
* [Revisar Conta de Desembolso](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/revisar-conta-desembolso.md) ganha o `409` com `errorCode = ACCOUNT_AMENDMENT_IN_FLIGHT` quando já há um ajuste de conta em curso para o contrato. Antes o segundo envio era aceito e disparava um segundo ajuste no provedor.

***

## 2026-09-25

### `contractNumber` informado pelo originador: quando a geração automática falha

**Corrigido (documentação) · Aditivo (não-breaking).**

A página [Submeter contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/submeter-contrato.md) passa a documentar o `422` com `errorCode = CONTRACT_NUMBER_ALLOCATION_EXHAUSTED`. Ele acontece quando o `contractNumber` é omitido e a Giro.Tech encontra 5 números seguidos da sua sequência já usados por CCBs que você numerou. O comportamento da API não mudou: o código já existia e não estava documentado.

A página também passa a orientar a informar o `contractNumber` sempre ou nunca, e a começar acima do maior número já recebido ao passar a informá-lo.

***

## 2026-09-21

### Consulta de saldo respondida pelo cache também dispara webhook

**Corrigido · Aditivo (não-breaking).**

Em [Consultar Saldo](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-consulta-saldo.md) e [Consultar Saldo em Lote](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-consulta-saldo-lote.md), a resposta `200` (saldo inline, vindo de cache) não gerava webhook, e o `requestId` devolvido não era consultável em `GET /api/v1/fgts/operations/{requestId}`. Agora a consulta também é enfileirada: o webhook é enviado com o mesmo `requestId` e o mesmo saldo, e o polling desse `requestId` funciona. O `200` inline não muda.

Quem trata o `200` e também processa webhooks recebe o resultado duas vezes para o mesmo `requestId` — trate a entrega de forma idempotente pelo `requestId`.

***

## 2026-09-17

### `daysToCompensate` passa a aceitar os dias corridos até o vencimento

**Corrigido · Aditivo (não-breaking).**

Em [Submeter contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/submeter-contrato.md), `installments[].daysToCompensate` aceitava no máximo `365`, o que obrigava a truncar o valor nas parcelas que vencem mais de um ano depois da contratação. O campo deve levar os **dias corridos entre `contractDate` e o `dueDate` da parcela**, sem truncar — o limite de 365 dias vale só para o IOF diário, que já vem calculado em `iofAmount`.

* O teto passa de `365` para `3660`; valores entre `366` e `3660` deixam de ser recusados com `400`.
* Exemplo: contrato em 2026-08-24 com parcelas em 2027-09-28, 2028-09-28 e 2029-09-28 leva `400`, `766` e `1131`.
* **Ação recomendada:** se a sua integração trunca o valor em 365, envie os dias corridos. Quem já envia valores até 365 continua aceito.

***

## 2026-09-14

### Cancelar contrato com a averbação em andamento

**Corrigido · Aditivo (não-breaking).**

A documentação de [Cancelar contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md) já listava `PENDING_ENDORSEMENT` como cancelável, mas o [`DELETE .../contracts/{contractNumber}`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md) respondia `409 CONTRACT_NOT_CANCELLABLE` nesse estado — inclusive quando a averbação estava parada na janela de retentativa da Caixa (por exemplo, aguardando a autorização do trabalhador). Agora o comportamento bate com o documentado:

* O `DELETE` responde `200` com `status = CANCELLED` na hora, e o webhook `CONTRACT_CANCELLED` chega com `data.reason.code = CANCELLED_BY_ORIGINATOR`.
* A Giro interrompe as tentativas de averbação e confere a reserva na Caixa. Se a averbação já tiver saído, a reserva é desaverbada automaticamente — não é preciso chamar [`POST .../reserve-cancellations`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/encerramento/submeter-solicitacao.md).

Quem já trata `CONTRACT_CANCELLED` não precisa mudar nada.

### Manutenção de garantia: `periods[].amount` é o valor nominal

**Corrigido · documentação (não-breaking).**

A descrição de `periods[].amount` em [`POST /api/v1/fgts/guarantee-maintenances`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-manutencao-garantia.md) dizia apenas "valor monetário do período". Ela agora explicita que o campo é o **valor nominal** do período, o mesmo averbado na Caixa. Em antecipações, não informe o valor presente pago pelo tomador: a Giro.Tech calcula o valor presente a partir do nominal. O contrato e a validação não mudaram.

***

## 2026-09-10

### Averbação recusada agora fecha: cancelamento manual, código 52 e janela de retentativa

**Alterado · Aditivo (não-breaking).**

`ENDORSEMENT_REJECTED` deixou de ser um estado sem saída. Antes, um contrato recusado pela Caixa só podia voltar por [`POST .../endorsement-retries`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/retentar-averbacao.md); o [`DELETE .../contracts/{contractNumber}`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md) respondia `409` e não havia como encerrá-lo. Três mudanças:

* **Cancelar uma averbação recusada passou a funcionar.** O `DELETE` responde `200` com `status = CANCELLED` — não há reserva na Caixa a reverter, então o contrato não passa por `REVERSING_ENDORSEMENT`. Cancelar abre mão das retentativas restantes, e `CANCELLED` não tem volta.
* **Código 52 da Caixa cancela na chegada do resultado.** "Trabalhador já possui quantidade máxima permitida de operação de reserva" não muda com retentativa — insistir bate no mesmo teto. O contrato vai direto a `CANCELLED`, com `CONTRACT_CANCELLED` / `reason.code = ENDORSEMENT_DENIED_NOT_RETRYABLE`. O `CONTRACT_ENDORSEMENT_REJECTED` continua chegando antes, com o código e o `originalErrors` da Caixa.
* **Recusa não retentada dentro da janela é cancelada pela Giro**, com `reason.code = ENDORSEMENT_RETRY_WINDOW_EXPIRED`. O contrato não fica mais parado indefinidamente esperando uma retentativa que não vem.

**`CONTRACT_CANCELLED` passa a ser emitido de verdade** — o evento já constava do catálogo, e agora chega nos três casos, sempre com `data.reason` (`{ code, message }`). Cancelamento pedido pelo originador leva `CANCELLED_BY_ORIGINATOR`. Quem já trata o evento não precisa mudar nada; quem programa por `reason.code` distingue os três.

Ver [Cancelar contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md), [Retentar averbação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/retentar-averbacao.md), [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md), [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md#contract_cancelled) e [Fluxo de formalização](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-formalizacao.md).

***

## 2026-09-03

### `contractNumber` nos webhooks de operação FGTS

**Adicionado · Aditivo (não-breaking).**

`data.contractNumber` passa a acompanhar os eventos das **operações de reserva** — `ENDORSEMENT_*`, `CANCEL_RESERVE_*` e `MAINTAIN_GUARANTEE_*` — quando a garantia pertence a um contrato. Antes o campo só existia nos eventos `source = CONTRACT` da saga de formalização, e quem integrava por webhook precisava guardar o par `requestId` → contrato por conta própria para correlacionar o desfecho.

Você **não precisa informar o contrato** para receber o campo: no cancelamento e na manutenção, em que o corpo aceita `reserveIdentifier`, a plataforma resolve o número a partir da própria garantia. Vale em todos os desfechos, inclusive nos intermediários `CANCEL_RESERVE_UNDER_REVIEW` e `MAINTAIN_GUARANTEE_UNDER_REVIEW`, emitidos antes de qualquer chamada à Caixa.

As consultas (saldo, valor reservado, protocolos) continuam sem o campo — não têm contrato associado. O campo segue **opcional** e nenhum integrador precisa mudar nada para continuar funcionando.

Ver [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md#estrutura-do-data), [Submeter averbação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-averbacao.md#resultado-no-webhook), [Submeter cancelamento de reserva](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-cancelamento-reserva.md#resultado-no-webhook) e [Submeter manutenção de garantia](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-manutencao-garantia.md#resultado-no-webhook).

***

## 2026-08-30

### Consulta de saldo recusada durante manutenção programada da Caixa

**Adicionado · Aditivo (não-breaking).**

`POST /api/v1/fgts/balance-queries` passa a responder `503` com `errorCode: CAIXA_MAINTENANCE_WINDOW` enquanto a Caixa estiver em janela de manutenção programada, em vez de aceitar a consulta e deixá-la enfileirada até a Caixa voltar. A resposta traz `maintenanceEndsAt` (fim previsto da janela, UTC) e o header `Retry-After` com os segundos restantes.

A requisição **não** é enfileirada e a `Idempotency-Key` **não** é consumida: reenviar o mesmo corpo com a mesma chave depois da janela produz uma consulta nova. `maintenanceEndsAt` é um limite superior — a janela pode ser encerrada antes quando a Caixa volta mais cedo.

Só a rota interativa é recusada. `POST /api/v1/fgts/batch/balance-queries`, averbação e as demais operações continuam sendo aceitas e são processadas quando a janela fecha.

Ver [Janela de manutenção da Caixa](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#caixa-maintenance-window).

***

## 2026-08-27

### Coerência entre `financialTerms` e `installments` passa a ser recusada

**Alterado · Breaking.**

`POST /api/v1/contracts` conferia apenas formato e limites de cada valor de `financialTerms`. Agora confere também as identidades entre eles e as parcelas, e recusa a divergência com `400` e `errorCode: VALIDATION_ERROR`:

```
disbursementAmount + iofAmount + (tacAmount ou insuranceAmount) = financedAmount
contractAmount = Σ installments[].amount
contractAmount = financedAmount + totalInterest
financedAmount = Σ installments[].principalAmount
totalInterest  = Σ installments[].interestAmount
iofAmount      = Σ installments[].iofAmount
financedAmount ≠ disbursementAmount quando há IOF, TAC ou seguro
tacAmount e insuranceAmount são alternativos — nunca os dois positivos
```

O motivo é a garantia. A CCB imprime `financedAmount + totalInterest` como "Saldo Devedor Financiamento", e o lastro cedido fiduciariamente é a soma das parcelas averbadas na Caixa. Quando `financedAmount` chega já com os juros embutidos, os dois números divergem e a cédula sai afirmando um saldo devedor maior que a garantia — abaixo dos 100% que a própria cláusula de garantia exige.

No FGTS o IOF e a TAC não são financiados, e não financiar significa descontar do desembolso — por isso o valor do empréstimo é igual ao valor financiado. No consignado é o contrário, e copiar aquele de-para é o que produz cédula com "Valor do Empréstimo" igual ao saldo devedor.

A resposta da recusa traz o valor recebido e o calculado de cada identidade que não fechou.

A tolerância é de um centavo por parcela (`0,01 × installmentCount`), porque o rateio de centavos entre parcelas não fecha exato.

**Ação necessária:** confira que `financedAmount` carrega a soma dos `principalAmount` (o que o tomador pegou emprestado), e não o total que ele vai pagar — esse é o `contractAmount`. Detalhe em [Submeter contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/submeter-contrato.md).

### `tac` e `insurance` da simulação passam a entrar no CET

**Corrigido · Retrocompatível.**

`POST /api/v1/simulations` já aceitava `tac` e `insurance`, mas quando acompanhados de `tacFinanced: true` ou `insuranceFinanced: true` a tarifa era somada ao saldo de amortização em vez de sair do desembolso. Como as parcelas do FGTS são repasses fixos da Caixa, somar ao saldo não altera pagamento nenhum: só reduzia a amortização e o IOF, **aumentava** o `disbursementAmount` e deixava a tarifa fora do CET. Com 5 parcelas de R$ 500,00 a 1,799% a.m. e TAC de R$ 100,00, o `annualEffectiveCost` saía **25,90%** — abaixo dos 26,12% da mesma simulação sem tarifa alguma, e muito abaixo dos 30,58% corretos.

Agora `tac` e `insurance` são **sempre** retidos no desembolso, como já acontecia em [Submeter contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/submeter-contrato.md):

```
disbursementAmount = netAmount − totalIof − tac − insurance
```

E como o CET é a TIR do fluxo que parte desse desembolso, cobrar tarifa passa a **aumentar** `monthlyEffectiveCost` e `annualEffectiveCost`. As parcelas, o `totalIof` e o `netAmount` não mudam.

### `tacFinanced` e `insuranceFinanced`

**Descontinuado · Retrocompatível.** Os dois campos continuam sendo aceitos e agora são **ignorados** — enviá-los produz o mesmo resultado que omiti-los. Serão removidos numa versão futura; pare de enviá-los.

A página [Criar Simulação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/simulacoes/criar-simulacao.md) passa a listar `tac` e `insurance`, que existiam no contrato e não estavam documentados.

***

## 2026-08-25

### `financialTerms.insuranceAmount` e documentação completa das condições financeiras

**Adicionado · Retrocompatível.**

`financialTerms` ganha o campo opcional **`insuranceAmount`** — o prêmio de seguro embutido no crédito, descontado do líquido junto com IOF e TAC. Ele é guardado e **reservado**: o contrato do banco emissor ainda não tem campo de seguro, então o valor não é repassado. Quem imprime o campo 16 do Quadro I da CCB ("Valor do Prêmio") continua sendo `contractInfo.insurancePremiumAmount`.

### Campos que existiam no contrato e faltavam nesta documentação

**Corrigido.** Não houve mudança de comportamento — a API já aceitava todos eles.

A página [Submeter contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/submeter-contrato.md) não listava `financedAmount`, `totalInterest` e `firstInstallmentAmount` (obrigatórios no Modo B, sem os quais a CCB não é gerada), nem o `generateDocument`, nem o bloco `contractInfo` inteiro. Todos foram documentados.

As descrições de **`contractAmount`** e **`financedAmount`** também foram reescritas: diziam apenas "Valor total do contrato" e "Valor financiado", o que não distinguia um do outro. Agora estão explícitos —

* **`financedAmount`** é **quanto o tomador pegou emprestado**. É ele que preenche os campos 1 ("Valor do Empréstimo") e 4 ("Valor Financiado") do Quadro I da CCB, que carregam o mesmo número.
* **`contractAmount`** é **quanto ele vai pagar no total**: a soma das parcelas, que aparece no campo 5 ("Saldo Devedor Financiamento").

IOF, TAC e seguro são **financiados** — o tomador os amortiza ao longo das parcelas e recebe o líquido já descontado: `disbursementAmount = financedAmount − iofAmount − tacAmount − insuranceAmount`.

### Exemplos coerentes

**Corrigido.** Os exemplos de payload traziam números que se contradiziam: `financedAmount` calculado como `contractAmount + encargos` convivendo com `disbursementAmount` calculado como `contractAmount − encargos` — duas convenções opostas no mesmo bloco, e nenhuma identidade fechava. O cronograma também mostrava 12 parcelas mensais, forma que não existe na antecipação do saque-aniversário (são períodos anuais, no máximo 5).

Foram substituídos por um contrato real de 3 parcelas anuais, em que as somas fecham. Se você integrou copiando os valores antigos, confira o seu cálculo contra a nova seção [Como os valores se relacionam](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/submeter-contrato.md#como-os-valores-se-relacionam).

A página passa a explicar também por que o IOF e a tarifa saem os dois do desembolso por motivos diferentes — o IOF é financiado e amortizado nas parcelas, a TAC não — e que `tacAmount` e `insuranceAmount` são alternativos. Nada disso muda a validação: a API continua aceitando os valores como você os envia, sem derivar nem recusar.

### `retry.lastProviderError` também no webhook

**Adicionado · Retrocompatível.**

O bloco `retry` dos eventos `ENDORSEMENT_RETRYING` e `CONTRACT_ENDORSEMENT_RETRYING` ganha o campo **`lastProviderError`**, com o que a Caixa respondeu na tentativa que abriu o ciclo: `provider`, `code`, `description`, `httpStatus`, `requestIdentifier` e `occurredAt`.

É o **mesmo campo, na mesma forma e no mesmo caminho** já disponível em [Consultar Status](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md#campo-retry-retryprogress). Antes, webhook e polling reportavam a causa da espera de formas diferentes: a consulta em `retry.lastProviderError` com `error` nulo, o webhook apenas em `error.originalErrors`. Quem usava os dois canais recebia respostas divergentes sobre existir erro.

A distinção que muda o que fazer:

* código **`7`** (`httpStatus 403`) — autorização pendente. **Peça ao trabalhador que autorize no app do FGTS.** A próxima tentativa converte; mediana de 4 a 5 tentativas, cerca de 75 minutos.
* códigos **`3`**, **`14`**, **`524`** — instabilidade da Caixa. Sem ação do seu lado.

O campo `error` continua presente nesses eventos, com o mesmo dado em `error.originalErrors`. **Ele não significa que a averbação falhou** — `RETRYING` é intermediário por definição, e é sempre seguido de um terminal. Programe pelo `retry.lastProviderError`.

***

## 2026-08-24

### `retry.lastProviderError` diz por que a averbação está esperando

**Adicionado · Retrocompatível.**

O bloco `retry` de [Consultar Status](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md) ganha o campo opcional **`lastProviderError`**, com o que a Caixa respondeu na tentativa que colocou a operação na janela de retentativa: `provider`, `code`, `description`, `httpStatus` e `requestIdentifier`.

Até aqui o bloco dizia **quantas** tentativas já foram feitas e **até quando** a janela vai, mas não **por quê** — e `error` é `null` durante a janela de propósito, porque a operação não falhou. Sem o novo campo, distinguir "esperando o trabalhador autorizar" de "instabilidade da Caixa" exigia interpretar texto livre.

A distinção muda o que fazer:

* código **`7`** (`httpStatus 403`) — autorização pendente. **Peça ao trabalhador que autorize no app do FGTS.** A próxima tentativa converte: a mediana observada é de 4 a 5 tentativas, cerca de 75 minutos.
* códigos **`3`**, **`14`**, **`524`** — instabilidade da Caixa. Não há ação do seu lado; a janela resolve sozinha.

`error` continua `null` enquanto `status = RETRYING`, e uma operação terminal segue reportando a causa por `error.originalErrors` como antes.

***

## 2026-08-22

### `source` deixa de expor `CACHE_HIT`

**Removido · Retrocompatível.**

O campo `source` passa a assumir apenas `CAIXA_CALL` ou `NA`. O valor `CACHE_HIT` **não é mais emitido** — nem na resposta `200` de [Consulta de Saldo](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-consulta-saldo.md), nem em [Consultar Status](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md), nem nos [payloads de webhook](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md).

Se a plataforma serviu a resposta a partir de um valor já apurado é detalhe interno de entrega: o saldo nasceu na Caixa de qualquer forma, foi validado por ela e vale sob o mesmo contrato de frescor. O campo `activeRequestCount` continua refletindo o momento da apuração do saldo, não o da requisição.

**Ação necessária:** nenhuma. Integrações que ramificavam em `CACHE_HIT` passam a receber `CAIXA_CALL`, que é o caminho já previsto para resultado apurado. O contrato de status (`200` com `COMPLETED` · `202` com `QUEUED`) **não muda**, e o `200` síncrono segue sendo otimização oportunista e não garantida — o fluxo assíncrono continua sendo o caminho padrão.

***

## 2026-08-21

### `periods` aceita parcelas em qualquer ano

**Alterado** · **Aditivo (não-breaking)**

* A validação de `periods` (averbação e simulação) **não exige mais anos consecutivos nem um ano-calendário por parcela**. Requisições antes recusadas com `400` e a mensagem *"installment years must be sequential (consecutive years)"* ou *"installments must be in distinct years (one per year)"* passam a ser aceitas.
* **Por que muda:** os períodos disponíveis na Caixa têm buracos — período já penhorado em outra operação some do saldo disponível —, então uma série legítima pode pular anos. A regra de consecutividade recusava operação válida.
* **Continua valendo:** máximo de 5 parcelas, e a primeira parcela (menor `transferDate`) deve estar estritamente no futuro.
* **Ação do integrador:** nenhuma. Quem já enviava anos consecutivos segue funcionando.

### Visibilidade da retentativa automática de averbação

**Adicionado** · **Aditivo (não-breaking)**

* Quando a Caixa responde um código transiente à averbação, a Giro reenvia a **mesma reserva** a cada 15 minutos por até **72 horas**, sem ação do originador. Esse comportamento já existia; o que muda é que agora ele é **observável**.
* Dois eventos novos, ambos **não-terminais**: **`ENDORSEMENT_RETRYING`** (averbação direta) e **`CONTRACT_ENDORSEMENT_RETRYING`** (fluxo de contrato). Trazem `data.retry` com `providerAttempt`, `nextAttemptAt`, `windowExpiresAt` e `eligible`, além do código transiente da Caixa em `error`.
* Os dois GETs passam a expor o mesmo bloco enquanto a janela está aberta: [`GET /api/v1/fgts/operations/{requestId}`](https://github.com/giro-tech/giro-tech-docs/tree/github-to-gitbook/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/consultar-operacao.md) — que agora responde `status = RETRYING` em vez de `QUEUED` — e [`GET /api/v1/fgts/contracts/{contractNumber}`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md), em `retry`.
* **`providerAttempt` não é o seu limite de retentativas.** Ele conta as tentativas **automáticas da Giro** (até \~288 numa janela cheia). O seu limite de retentativas manuais continua sendo **3 por reserva**.
* **Durante a janela, a retentativa manual é recusada** com `409 ENDORSEMENT_NOT_RETRYABLE` — daí `eligible: false`. Quando a janela se esgota sem sucesso, chega o evento terminal com `error.code = TRANSIENT_PROVIDER_RETRY_EXHAUSTED`, e aí sim o endpoint de retentativa aceita.
* **Volume:** um evento por tentativa, de 15 em 15 minutos. Se o seu fluxo só precisa do desfecho, ignore o `eventType` novo e continue tratando apenas os terminais — nenhuma integração existente muda de comportamento.

***

## 2026-08-19

### Recusa por data ganha código próprio: `OPERATION_NOT_YET_ALLOWED`

**Alterado** · **Aditivo (não-breaking)**

* Quando a Caixa recusa uma operação **só até uma data** (*"Operação não permitida antes de 02/09/2026."*), o `error.code` do [`OperationError`](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#operation-not-yet-allowed) passa a ser **`OPERATION_NOT_YET_ALLOWED`**. Antes esse desfecho vinha como `CPF_NOT_OPERABLE` na consulta de saldo e como `ENDORSEMENT_DENIED` na averbação, no cancelamento e na manutenção — dois códigos que dizem algo diferente do que de fato ocorreu.
* **Por que muda:** `CPF_NOT_OPERABLE` afirma um impedimento na conta do trabalhador, que só se resolve na Caixa; `ENDORSEMENT_DENIED` afirma negativa de mérito. Aqui não há nem uma coisa nem outra — a mesma operação passa a partir da data. O código novo permite reenviar na data em vez de descartar o caso.
* **A data continua chegando em `error.message` e em `originalErrors[].description`**, como texto. Não há campo estruturado com a data; programe pelo `error.code`.
* **Ação recomendada:** quem trata `ENDORSEMENT_DENIED` ou `CPF_NOT_OPERABLE` como desfecho definitivo passa a receber `OPERATION_NOT_YET_ALLOWED` nesses casos. Se o seu tratamento é por lista de códigos conhecidos, inclua o novo; o comportamento seguro para código desconhecido continua sendo tratar como falha e não reenviar automaticamente.

***

### Parcela do contrato aceita os campos bancários do documento

**Adicionado** · **Aditivo (não-breaking)**

* Cada item de `installments[]` em [`POST /api/v1/fgts/contracts`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/submeter-contrato.md) ganha cinco campos **opcionais**: **`tariffAmount`** (tarifa da parcela, 0–999999,99), **`documentNumber`** (máx. 10), **`ourNumber`** (máx. 32), **`ourNumberBankCode`** (máx. 3) e **`participantControl`** (máx. 25).
* São campos de **repasse**: a Giro valida só o tamanho e encaminha o valor ao GTBanker exatamente como recebido — respectivamente `valor_tarifa_parcela`, `numero_documento`, `nosso_numero`, `banco_nosso_numero` e `participante_controle`. Nenhum deles altera precificação, cronograma ou o desfecho da formalização.
* **Campo omitido não é enviado.** Ele não vai como nulo nem como string vazia: some do payload, e a parcela é formalizada como antes.
* Quem já integra **não precisa de nenhuma ação** — as parcelas continuam válidas sem esses campos.

***

### `CONTRACT_PAID` passa a trazer o link do comprovante do desembolso

**Adicionado** · **Aditivo (não-breaking)**

* O evento [`CONTRACT_PAID`](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md) ganha o campo opcional **`data.paymentReceiptUrl`** — a URL do comprovante do desembolso, emitida pelo banco liquidante. O mesmo valor também aparece em `data.result.paymentReceiptUrl`.
* **Trate a URL como credencial.** Quem tem o link abre o comprovante, **sem autenticação**. Não a publique, não a grave em log nem a envie por e-mail aberto; para repassá-la ao cliente final, use canal autenticado.
* ~~Não existe endpoint para recuperá-la depois.~~ Desde 2026-10-02 ela também volta em [Consultar Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md) — ver a entrada daquela data.
* O campo é **opcional**: quando o banco não devolve comprovante, ele vem ausente. Ausência **não** significa que o pagamento falhou — o desembolso confirmado continua sendo o próprio `CONTRACT_PAID`.
* Integrações que ignoram campos desconhecidos não precisam de nenhuma ação.

***

## 2026-08-18

### Status do contrato: três valores renomeados e o enum reordenado

**Alterado** · **Breaking**

* O valor `FORMALIZED` do campo `status` em `GET /api/v1/fgts/contracts/{contractNumber}` passa a ser **`PENDING_DISBURSEMENT`**. O estado é o mesmo — o provedor confirmou o recebimento da CCB e o contrato aguarda o desembolso. O nome anterior descrevia o marco já cumprido; o novo descreve o que ainda falta acontecer.
* **O evento `CONTRACT_FORMALIZED` não muda**, e o `milestone` dele continua sendo `FORMALIZED`. Milestone é o nome do marco no webhook, não o estado do contrato — como já ocorre com `PAYMENT_FAILED` e `DOCUMENT_GENERATED`, que não têm status correspondente.
* **Ação necessária:** quem compara `status == "FORMALIZED"` na consulta de contrato precisa passar a comparar `PENDING_DISBURSEMENT`. Quem reage ao evento `CONTRACT_FORMALIZED` não precisa mudar nada.
* O status `FORMALIZED` da **API GTPayroll** é de outra máquina de estados e **não muda**.
* Junto com ele, mais dois valores do mesmo campo mudam de nome: **`SENT_TO_GTBANKER` → `PENDING_CCB_CONFIRMATION`** (a CCB foi entregue e aguarda a confirmação de recebimento) e **`PAID` → `DISBURSED`** (desembolso confirmado). O enum passa a declarar os valores na ordem do fluxo, e ganha `DOCUMENT_GENERATION_FAILED`, que a API já podia devolver e não estava documentado.
* `DISBURSED` também desfaz uma ambiguidade que existia: `PAID` continua existindo na API, mas **só** como `periodStatus` de período do FGTS (código `4` da Caixa) — que não muda.
* Os eventos de webhook **não mudam**: `CONTRACT_SENT_TO_GTBANKER`, `CONTRACT_FORMALIZED` e `CONTRACT_PAID` seguem com os mesmos nomes e os mesmos `milestone` (`SENT_TO_GTBANKER`, `FORMALIZED`, `PAID`).

### Averbação: retentativa automática de 72 h para erro transitório da Caixa

**Alterado** · **Aditivo (não-breaking)**

* Erro **transitório** da Caixa numa averbação (serviço indisponível, pedido de nova tentativa) passa a ser retentado pela Giro **a cada 15 minutos, por até 72 horas**, antes de virar `ENDORSEMENT_FAILED`. Antes, as tentativas se esgotavam em segundos e o erro chegava quase imediatamente.
* Cada ciclo faz **consulta pelo `reserveIdentifier` antes de reenviar**: se a averbação tiver se efetivado, o resultado é resolvido pelo protocolo encontrado. O reenvio reusa sempre o **mesmo `reserveIdentifier`** — não nasce reserva nova em nenhum ciclo.
* **Cada retentativa solicitada por você abre a sua própria janela de 72 h.** Com o teto de 3 retentativas, o pior caso vai a **288 h — 12 dias** até a reserva se esgotar de vez. O teto de 3 retentativas por reserva **não mudou**.
* **Nenhuma mudança de contrato**: mesmos endpoints, mesmos campos, mesmos eventos. O que muda é **quando** o `ENDORSEMENT_FAILED` chega.
* **Ação recomendada:** revise timeouts e travas de conciliação amarrados à averbação. Uma operação legitimamente em andamento pode ficar dias em estado não-terminal, sem evento — ver [Fluxo assíncrono e polling](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-assincrono-e-polling.md).
* Averbação **negada** pela Caixa não passa pela janela: continua falhando na primeira resposta, porque insistir não mudaria o resultado.

***

## 2026-08-17

### `*_NEEDS_VERIFICATION` traz `error.code = EXPIRED_TTL`

**Corrigido** · **Aditivo (não-breaking)**

* Os guias diziam que os eventos `*_NEEDS_VERIFICATION` (`status = EXPIRED`) vinham **sem `result` nem `error`**. O `result` de fato não vem, mas o `error` **sempre vem**, com `code = EXPIRED_TTL` e `source = NA` no `data`. Só a descrição estava errada — o payload nunca mudou, e o [contrato OpenAPI](https://github.com/giro-tech/giro-tech-docs/tree/github-to-gitbook/openapi/gtfgts-ingress/gtfgts-ingress.openapi.yaml) já registrava `error` como presente quando `status = EXPIRED`.
* `EXPIRED_TTL` é **marcador de expiração, não veredito da Caixa**. Não o trate como recusa: não houve recusa.
* Também corrigido o "expirou aguardando a Caixa". A expiração acontece por tempo limite interno **enquanto a operação ainda está na fila da Giro**, tipicamente antes de ser despachada — não é tempo esgotado esperando resposta da Caixa. A orientação prática não muda: verifique por polling antes de assumir o desfecho, e a averbação segue [retentável](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/retentar-averbacao.md).

### `ENDORSEMENT_NEEDS_VERIFICATION` é retentável

**Corrigido** · **Aditivo (não-breaking)**

* A [retentativa por identificador](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/retentar-averbacao.md) mandava usar o endpoint apenas depois de um `ENDORSEMENT_FAILED`. Faltava dizer que uma averbação encerrada em **`ENDORSEMENT_NEEDS_VERIFICATION`** (`status = EXPIRED`) também admite retentativa.
* O evento significa que a averbação terminou **sem veredito da Caixa** — nenhuma negativa foi emitida. É o caso em que a retentativa mais compensa, e ele estava documentado apenas como "verifique por polling", sem indicar o caminho de saída.
* **Comportamento não mudou** — a rota sempre aceitou esses casos. A correção é de documentação.
* Confirme o desfecho por [polling](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md) antes de pedir a retentativa: se a operação tiver se resolvido no intervalo, não há o que retentar. O [teto de 3 retentativas](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/retentar-averbacao.md#teto-de-tentativas) por reserva continua valendo.

***

## 2026-08-14

### Retentativa de averbação — duas rotas novas

**Adicionado** · **Aditivo (não-breaking)**

* [Retentativa de Averbação por identificador](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/retentar-averbacao.md) (`POST /api/v1/fgts/endorsements/{reserveIdentifier}/retries`): solicita nova tentativa de averbação para uma reserva recusada. **Sem corpo**; `Idempotency-Key` opcional (máx. 255). Responde `202 { requestId, status: QUEUED }`.
* [Retentar Averbação do Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/retentar-averbacao.md) (`POST /api/v1/fgts/contracts/{contractNumber}/endorsement-retries`): mesma operação para um contrato (CCB) em `ENDORSEMENT_REJECTED`. **Sem corpo**; `Idempotency-Key` opcional (máx. 255). Responde `202` no mesmo formato.
* A retentativa **reusa o mesmo `reserveIdentifier`** — a chave da reserva na Caixa. **Não nasce reserva nova**, e os períodos da averbação original são preservados.
* **Teto de 3 retentativas** por reserva — **4 tentativas no total**, contando a averbação original. Não é preciso classificar o erro da Caixa: não há taxonomia separando falhas "retentáveis" de "terminais", e uma averbação que chegou à Caixa e foi recusada é sempre retentável. **Não** são retentáveis: reserva que não está em falha (`409 ENDORSEMENT_NOT_RETRYABLE`), averbação recusada por `reserveIdentifier` duplicado — que nunca chegou à Caixa (`409 ENDORSEMENT_NOT_RETRYABLE`) — e reserva em formato legado de períodos (`409 ENDORSEMENT_RETRY_UNSUPPORTED_LEGACY_RECORD`).
* **As duas rotas divergem na forma como a recusa por teto chega:**
  * **por reserva** — recusa **síncrona**, na própria resposta: `409` com `errorCode` `ENDORSEMENT_RETRY_LIMIT_EXCEEDED`. Reserva em estado não-retentável devolve `409 ENDORSEMENT_NOT_RETRYABLE`;
  * **por contrato** — a resposta é **sempre `202`**, que confirma apenas a aceitação do pedido; a recusa chega **depois, por webhook**, como `CONTRACT_ENDORSEMENT_REJECTED`.
* **No caminho de contrato, a causa da recusa vem no `data.error.code` do evento.** O `eventType` é sempre `CONTRACT_ENDORSEMENT_REJECTED`, mas o `data.error.code` distingue: `ENDORSEMENT_RETRY_LIMIT_EXCEEDED` (teto — nenhuma chamada à Caixa foi feita), `ENDORSEMENT_NOT_RETRYABLE`, `ENDORSEMENT_RETRY_UNSUPPORTED_LEGACY_RECORD`, ou o código da recusa da Caixa (com `data.error.originalErrors` preenchido). Programe pelo `data.error.code`, não pelo `eventType`.
* **A retentativa não emite evento de webhook próprio.** A trilha entregue é: recusa → **silêncio** → desfecho da nova tentativa (`ENDORSEMENT_COMPLETED` / `ENDORSEMENT_FAILED` / `ENDORSEMENT_NEEDS_VERIFICATION` na rota por reserva; `CONTRACT_ENDORSED` / `CONTRACT_ENDORSEMENT_REJECTED` na rota por contrato). O silêncio é **esperado**, não é evento perdido.
* `errorCode` `ENDORSEMENT_RETRY_LIMIT_EXCEEDED`, `ENDORSEMENT_NOT_RETRYABLE` (409), `GUARANTEE_NOT_FOUND` (404), `GUARANTEE_LEDGER_UNAVAILABLE` (503) e `CONTRACT_INVALID_STATUS` (409) na referência de [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md).

{% hint style="info" %}
Envie `Idempotency-Key` nestas rotas. O header é opcional, mas sem ele não há deduplicação: um duplo-clique gasta **duas das quatro tentativas** disponíveis.
{% endhint %}

### `reserveIdentifier` — 13 **ou** 14 caracteres

**Corrigido** · Aditivo (documentação)

* O `reserveIdentifier` era documentado como tendo **13 caracteres fixos**, com o padrão `^GT[FD][0-9]{8}[0-9A-HJKMNP-TV-Z]{2}$`. O identificador tem **13 ou 14 caracteres** — o código do originador no final tem 2 **ou 3** caracteres —, e o padrão correto é `^GT[FD][0-9]{8}[0-9A-HJKMNP-TV-Z]{2,3}$`. Ambos são válidos (ex.: `GTD00000042AB` e `GTD00000042GV8`). Documentar 13 fixo levava o integrador a tratar um identificador legítimo como inválido.

### Rate limit — contagem de cenários corrigida

**Corrigido** · Aditivo (documentação)

* [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#rate-limit-exceeded) anunciava "**três** cenários" de `429` e listava **dois**. O terceiro (`PROTOCOL_RATE_LIMITED`) existia quando a consulta de status por protocolo era síncrona (`GET /api/v1/fgts/protocols/{protocolo}`); a rota virou assíncrona em 2026-06-25, o código deixou de existir e o item foi removido — mas a contagem ficou. São **dois** cenários: `INGRESS_RATE_LIMIT_EXCEEDED` e `RATE_LIMIT_EXCEEDED`.

### Polling — recusas consultáveis (`404` → `200 FAILED`) e `originalRequestId`

**Alterado** · **Mudança de comportamento observável**

* [`GET /api/v1/fgts/operations/{requestId}`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md) **deixa de responder `404` permanente para operação recusada**. Recusas na admissão do processamento — averbação duplicada e recusas de gate de cancelamento/manutenção — passam a responder `200` com `status = FAILED` já na primeira consulta, com o **mesmo `error.code`** do evento `FAILED` entregue por webhook. Quem tratava `404` como "ainda processando" deve passar a programar pelo `error.code`; o `404` agora significa apenas `requestId` inexistente. Ver [Recusas são consultáveis](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-assincrono-e-polling.md#recusas-consultaveis).

**Adicionado** · **Aditivo (não-breaking)**

* Campo `error.originalRequestId` no `OperationError` — presente quando `error.code` ∈ {`ENDORSEMENT_ALREADY_SUBMITTED`, `GUARANTEE_OPERATION_DUPLICATE`, `GUARANTEE_APPROVAL_ALREADY_PENDING`}: o `requestId` da operação original em andamento (ou concluída), para acompanhar o desfecho real. Ver [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#originalrequestid).
* Campo `reserveIdentifier` no **topo da resposta de status** do polling, quando a operação tem reserva associada e o identificador é conhecido — o mesmo valor entregue nos eventos de webhook; polling e webhook passam a entregar o identificador nos **dois canais**.

### Webhooks — `reserveIdentifier` nos eventos `FAILED` de recusa

**Adicionado** · **Aditivo (não-breaking)**

* Os eventos `*_FAILED` de **recusa** (averbação duplicada, recusa de gate) também passam a carregar `data.reserveIdentifier` quando conhecido. O campo continua **opcional** — não dependa da presença. Ver [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md).

### Cancelamento de reserva — aceita `contractNumber` OU `reserveIdentifier`

**Alterado** · **Mudança de comportamento observável** (400 para quem enviava os dois campos)

* [`POST /api/v1/fgts/reserve-cancellations`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-cancelamento-reserva.md) passa a aceitar **exatamente um** de dois identificadores: `reserveIdentifier` (`^[A-Za-z0-9._-]{1,50}$`) **ou** `contractNumber` (`^\d{1,8}$` — cancela a garantia mais recente do contrato). Antes, `reserveIdentifier` era obrigatório.
* Enviar **os dois** campos juntos (ou **nenhum**) retorna `400 VALIDATION_ERROR`. Quem enviava `contractNumber` como campo extra — antes ignorado — **passa a receber `400`**: remova um dos dois.

***

## 2026-08-13

### Encerramento de contrato — rota corrigida e corpo simplificado

**Corrigido** · **Breaking** para quem integrou com `.../termination-requests`

* `POST /api/v1/fgts/contracts/{contractNumber}/termination-requests` e `GET .../termination-requests/{id}` foram **removidos da especificação**. Eles constavam do OpenAPI, da collection do Postman e desta documentação desde 2026-06-27, mas **nunca existiram no serviço** — toda chamada respondia `404`. O contrato foi publicado à frente da implementação, que permanece pendente, e nunca foi retratado.
* O encerramento de contrato vigente é feito por [`POST /api/v1/fgts/contracts/{contractNumber}/reserve-cancellations`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/encerramento/submeter-solicitacao.md), implementado e testado ponta a ponta. Equivalência dos motivos: `WITHDRAWAL` → `SEVEN_DAYS_REGRET`; `EARLY_SETTLEMENT` → `SETTLEMENT_DISCHARGE`.
* O acompanhamento é o polling **genérico** [`GET /api/v1/fgts/operations/{requestId}`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md), que responde `200` desde o registro com `status = PENDING_MANUAL_APPROVAL` enquanto a solicitação aguarda a autorização interna. Não há endpoint de status dedicado.
* Os eventos de webhook do desfecho são `CANCEL_RESERVE_*`, já ativos. Os eventos `CONTRACT_TERMINATION_*`, documentados como *planejados*, foram **removidos** da referência: nenhum serviço os emite hoje. Serão redocumentados se e quando forem implementados.
* `errorCode` `CONTRACT_NOT_ELIGIBLE_FOR_TERMINATION` (409) **não existe** e foi substituído na referência de [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md) por `CONTRACT_NO_ACTIVE_RESERVATION`, o código realmente retornado.

**Alterado** · Aditivo (retrocompatível)

* `POST /api/v1/fgts/contracts/{contractNumber}/reserve-cancellations` deixou de exigir `cpf` e `reserveIdentifier` no corpo. O `contractNumber` do path já identifica a operação: o CPF é derivado do contrato e a reserva ativa é resolvida internamente. Os dois campos eram obrigatórios e depois descartados. Integrações que continuem enviando-os seguem funcionando — campos desconhecidos são ignorados.

### Operações FGTS (Legado) — `contractNumber` e formato do `reserveIdentifier`

**Corrigido** · Aditivo (documentação)

* [Submeter Averbação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-averbacao.md) (`POST /api/v1/fgts/endorsements`): a tabela do corpo e o exemplo omitiam `contractNumber`, que é **obrigatório**. Copiar o exemplo publicado resultava em `400 VALIDATION_ERROR` com `{"contractNumber":"must not be blank"}` (medido em homologação). A resposta de exemplo também passa a mostrar `reserveIdentifier`, devolvido no `202`.
* [Cancelamento de Reserva](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-cancelamento-reserva.md) (`POST /api/v1/fgts/reserve-cancellations`): `reserveIdentifier` era descrito como `string` de 1–50 caracteres e os exemplos usavam valores (`RES-20240901-001`, `orig-456:res-3`) que não existem. O identificador real tem 13 caracteres no formato `^GT[FD][0-9]{8}[0-9A-HJKMNP-TV-Z]{2}$` e vem do `202` da averbação.

### Contrato — `daysToCompensate` obrigatório em cada parcela

**Alterado** · **Breaking**

* [Submeter Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/submeter-contrato.md) (`POST /api/v1/fgts/contracts`): `installments[].daysToCompensate` passa a ser **obrigatório** (`integer`, 0–365). O campo alimenta `dias_compensar` no GTBanker. Parcela omitindo o campo é rejeitada com `400`. Integrações que não enviavam o valor precisam passar a enviá-lo.

***

## 2026-08-11

### Revisão de desembolso — `availableActions`, `dueAt` e bloco `revision` na consulta

**Adicionado** · **Aditivo (não-breaking)**

* Webhook [`CONTRACT_PAYMENT_REVISION`](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md): campo `data.availableActions` (`NEW_ACCOUNT` e/ou `RETRY`) informando **o que o provedor aceita** naquele ticket de revisão. `["NEW_ACCOUNT"]` (falha de dados bancários) só admite conta/PIX **diferente** da que falhou; `["NEW_ACCOUNT","RETRY"]` (instabilidade bancária) também admite o reenvio da **mesma** conta. O campo é **ausente** em tickets abertos antes desta entrega — ausência significa "não informado" e deve ser tratada como `["NEW_ACCOUNT"]`, o comportamento histórico. Detalhes em [Revisar Conta de Desembolso](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/revisar-conta-desembolso.md).
* Webhook `CONTRACT_PAYMENT_REVISION`: campo `data.dueAt` — o instante **exato** (ISO-8601 UTC) em que o ticket expira. Use-o, e não `dueDate`, para decidir se ainda há tempo de emendar.
* [Consultar Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md) (`GET /api/v1/fgts/contracts/{contractNumber}`): bloco `revision` (`dueDate`, `dueAt`, `availableActions`), presente **apenas** enquanto há revisão aberta. Permite reconciliar por polling quando o webhook se perdeu.

**Corrigido**

* `data.dueDate` do `CONTRACT_PAYMENT_REVISION` era derivado em UTC a partir do prazo enviado pelo provedor, que é um instante. Como o prazo costuma cair à meia-noite no fuso de São Paulo, a data exibida podia sugerir um dia inteiro a mais de janela do que o provedor de fato aceitava — e a emenda enviada nesse intervalo era recusada. O prazo passou a ser guardado e comparado como instante; `dueDate` agora é o dia correspondente no fuso de São Paulo e o novo `dueAt` traz o valor exato.
* [Consultar Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md): o campo `milestones` era documentado mas vinha sempre `null` — os marcos (`receivedAt`, `endorsedAt`, `sentAt`, `formalizedAt`, `paidAt`) não eram montados na resposta. Passa a ser preenchido conforme documentado. **Aditivo**: quem já tratava `milestones` como opcional continua funcionando.

***

## 2026-07-23

### Download da CCB — documento assinado do originador vs. documento gerado pela Giro

**Adicionado** · **Aditivo (não-breaking)**

* [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`): obtém uma URL temporária (presigned) para baixar o **PDF assinado da CCB enviado pelo originador** — Modo A (`signedDocumentBase64`) ou Modo B (`POST .../documents`). Disponível assim que o documento é anexado (contrato em `RECEIVED` em diante). Erros: `401 UNAUTHORIZED`, `404 CONTRACT_SIGNED_DOCUMENT_NOT_AVAILABLE` (documento ainda não anexado — Modo B em `AWAITING_SIGNED_DOCUMENT`, contrato inexistente ou fora do escopo do token) e `503 SUBMISSION_TEMPORARILY_UNAVAILABLE`.
* `errorCode` `CONTRACT_SIGNED_DOCUMENT_NOT_AVAILABLE` (404) na referência de [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#formalizacao).

**Corrigido**

* [Baixar CCB (gerada pela Giro)](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/baixar-documento-ccb.md) (`GET .../documents/template`): a documentação descrevia o retorno como "a CCB assinada/formalizada". O endpoint devolve o **documento da CCB gerado pela Giro** ao final da formalização (evento `CONTRACT_DOCUMENT_GENERATED`, após `FORMALIZED`) — **não** o PDF assinado enviado pelo originador. A página foi renomeada para "Baixar CCB (gerada pela Giro)"; para o documento assinado, use [Baixar CCB Assinada](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/baixar-ccb-assinada.md).

***

## 2026-07-10

### Webhooks — `reserveIdentifier` e `protocolNumber` nas operações de reserva

**Corrigido**

* Os eventos de **averbação**, **cancelamento de reserva** e **manutenção de garantia** passam a entregar `data.reserveIdentifier` e `data.protocolNumber`. Os dois campos estavam documentados, mas nunca eram enviados: o produtor gravava as chaves internas `reservationRef` e `caixaProtocol`, que o consumidor não lia. **Aditivo** — integrações existentes continuam funcionando; passam apenas a receber dois campos a mais.

**Removido**

* Chaves `reservationRef` e `caixaProtocol` de `data.result`, nesses mesmos eventos. Nunca fizeram parte do contrato documentado — eram nomes internos que vazavam no payload. Foram substituídas, no mesmo objeto, por `reserveIdentifier` e `protocolNumber`. Se a sua integração lia esses nomes, migre para os documentados.

**Esclarecido** (sem mudança de comportamento)

* O tipo de `protocolNumber` depende da operação, e a documentação passou a refletir isso:

  * `string` em averbação, cancelamento de reserva, manutenção de garantia e encerramento de contrato — tanto em `data.protocolNumber` quanto em `data.result.protocolNumber`;
  * `number` na consulta de status por protocolo, na listagem de protocolos da reserva e dentro de `data.result.protocols[]`.

  O valor pode exceder o inteiro seguro de JSON (2⁵³−1). Onde o campo é `string`, trate-o como opaco.

***

## 2026-07-04

### Consulta de saldo — remoção de `periodCount`

**Removido**

* Campo `periodCount` do corpo de `POST /api/v1/fgts/balance-queries` e `POST /api/v1/fgts/batch/balance-queries`. O cache é chaveado apenas por `cpf`. Clientes legados que ainda enviam `periodCount` têm o campo ignorado (não gera `400`).
* Coleção Postman **GTFgts-E2E-Originator** — removida da documentação pública; use **GTFgts-Ingress** (endpoints) e **GTFgts-Webhook-Events** (payloads de callback).

**Alterado**

* [Consultar Saldo](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-consulta-saldo.md) e [Consultar Saldo em Lote](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-consulta-saldo-lote.md): corpo `{ "cpf": "..." }`.
* [Operações FGTS](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/operacoes-fgts.md): descrição do contrato de entrada atualizada (campos flat, sem wrapper `payload`).
* [Fluxo de formalização](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-formalizacao.md): seção de coleções Postman atualizada (Ingress + Webhook Events).

***

## 2026-06-29

### Payment approval gate (liberação de pagamento)

**Adicionado**

* [Aprovar Pagamento](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/aprovar-pagamento.md) (`POST /api/v1/fgts/contracts/{contractNumber}/payment-approval`): aprova o pagamento de um contrato em `PENDING_PAYMENT_APPROVAL` quando a integração está configurada com aprovação manual. Retorna `202 Accepted` com `status = PENDING_FORMALIZATION`; o processamento continua de forma assíncrona. Erros: `404 CONTRACT_NOT_FOUND`, `409 CONTRACT_NOT_PENDING_PAYMENT_APPROVAL`.
* Evento de webhook `CONTRACT_PAYMENT_APPROVAL_REQUIRED` (`source = CONTRACT`): emitido após averbação confirmada, quando aguarda aprovação manual; inclui `endorsedAt` no `data`. Ver [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md) e [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md).
* Status de negócio `PENDING_PAYMENT_APPROVAL` no ciclo de vida do contrato. Ver [Fluxo de formalização](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-formalizacao.md).

**Alterado**

* [Cancelar Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md): cancelamento em `PENDING_PAYMENT_APPROVAL` ou `PENDING_FORMALIZATION` dispara reversão da averbação (`REVERSING_ENDORSEMENT`) em vez de `CANCELLED`.
* Bundle OpenAPI (`openapi/gtfgts-ingress/gtfgts-ingress.openapi.yaml`) e webhook (`openapi/gtfgts-webhook/gtfgts-webhook.openapi.yaml`) sincronizados com os repositórios de origem.

***

## 2026-06-29

### Gate de aprovação de pagamento (payment approval gate)

**Adicionado**

* [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 a integração exige confirmação do originador. Após averbação, o contrato permanece em `PENDING_PAYMENT_APPROVAL` até esta chamada. Resposta `202` com `{ contractNumber, clientReference, status: PENDING_FORMALIZATION, message }`. Header opcional `Idempotency-Key`.
* Evento de webhook `CONTRACT_PAYMENT_APPROVAL_REQUIRED` (`source = CONTRACT`) — adicional a `CONTRACT_ENDORSED`; payload inclui `endorsedAt`. Ver [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md).

**Alterado**

* [Cancelar Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md): em `PENDING_PAYMENT_APPROVAL` ou `PENDING_FORMALIZATION`, o `DELETE` inicia reversão da reserva (`REVERSING_ENDORSEMENT`) em vez de `CANCELLED` direto.

***

## 2026-06-27

### Cancelamento de contrato FGTS ativo (desaverbação)

{% hint style="danger" %}
**Retratado em 2026-08-13.** Os endpoints `.../termination-requests` descritos nesta entrada **nunca chegaram a ser implementados** e sempre responderam `404` — o contrato foi publicado antes do código. A capacidade de encerramento está disponível em [`POST .../contracts/{contractNumber}/reserve-cancellations`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/encerramento/submeter-solicitacao.md) — ver a entrada de 2026-08-13.
{% endhint %}

**Adicionado**

* [Submeter Solicitação de Encerramento](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/encerramento/submeter-solicitacao.md) (`POST /api/v1/fgts/contracts/{contractNumber}/termination-requests`): encerra um **contrato FGTS já vigente** por desistência ou quitação antecipada, levando à desaverbação da garantia junto à Caixa. Operação **assíncrona** com **análise interna da Giro** antes do envio à Caixa — `202` com `{ requestId, contractNumber, status: PENDING_MANUAL_APPROVAL, message }`. Corpo: `terminationType` (obrigatório, enum `EARLY_SETTLEMENT` | `WITHDRAWAL`) e `note` (opcional, máx. 500). Erros: `400 VALIDATION_ERROR`, `404 CONTRACT_NOT_FOUND`, `409 CONTRACT_NOT_ELIGIBLE_FOR_TERMINATION` e `503 SERVICE_UNAVAILABLE`.
* [Consultar Status da Solicitação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/encerramento/consultar-status.md) (`GET /api/v1/fgts/contracts/{contractNumber}/termination-requests/{id}`): acompanha a solicitação em **qualquer fase**, com `status` **normalizado** — `PENDING_MANUAL_APPROVAL` enquanto em análise interna; `COMPLETED` ou `FAILED` nos terminais. É o caminho de acompanhamento do encerramento (não o polling genérico `/operations/{requestId}`).
* `errorCode` `CONTRACT_NOT_FOUND` (404) e `CONTRACT_NOT_ELIGIBLE_FOR_TERMINATION` (409) na referência de [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md).

**Planejado**

* `source` `CONTRACT` e eventos de webhook `CONTRACT_TERMINATION_REQUESTED`/`CONTRACT_TERMINATION_UNDER_REVIEW` (intermediários), `CONTRACT_TERMINATION_COMPLETED`, `CONTRACT_TERMINATION_REJECTED` e `CONTRACT_TERMINATION_FAILED` (terminais), com `contractNumber` no nível superior do `data` e `code` `CONTRACT_TERMINATION_REJECTED` no `error`. **Ainda não ativos** na entrega de webhook — seguem o mesmo gate de release do serviço de webhook. Documentação removida em 2026-08-13 junto com a retratação acima.

***

## 2026-06-26

### Sincronização de artefatos e coleção E2E

**Adicionado**

* Coleção Postman **GTFgts-E2E-Originator** — jornada ponta-a-ponta: consulta de saldo + polling, simulação, formalização (Modo A/B), operações FGTS isoladas (averbação, protocolo, valor reservado), cancelamento e revisão de desembolso. Disponível em [Fluxo de formalização](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-formalizacao.md#colecoes-postman-e2e) e no README da API.

**Alterado**

* Bundle OpenAPI (`openapi/gtfgts-ingress/gtfgts-ingress.openapi.yaml`) e coleção **GTFgts-Ingress** sincronizados com o repositório `gtfgts-ingress` (26/jun): endpoints de formalização, `protocol-status-queries` e correções recentes de spec.

***

## 2026-06-25

### Consultar Status por Protocolo — operação agora assíncrona

**Alterado** · **Breaking**

* [Consultar Status por Protocolo](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/consultar-status-protocolo.md) deixa de ser uma consulta **síncrona** (`GET /api/v1/fgts/protocols/{protocolNumber}` → `200` com `protocolStatus` inline) e passa a ser uma operação **assíncrona**: `POST /api/v1/fgts/protocol-status-queries` → `202` com `{ requestId, status: QUEUED }`. A consulta agora passa pela **mesma fila priorizada** das demais operações FGTS (prioridade `NORMAL`), garantindo priorização justa entre originadores. Atualize as integrações que usam o endpoint `GET` antigo.
  * **Request**: corpo JSON com campo único `protocolNumber` (`string` numérica, 1–18 dígitos); header `Idempotency-Key` opcional.
  * **Resultado**: entregue por [webhook](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md) (`source = QUERY_PROTOCOL_STATUS`, eventos `QUERY_PROTOCOL_STATUS_COMPLETED` / `QUERY_PROTOCOL_STATUS_FAILED`) ou por [polling](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md) em `GET /api/v1/fgts/operations/{requestId}`. No `COMPLETED`, o `result` traz o `protocolStatus` atual e os dados de detalhe do protocolo.
  * Erros de borda da submissão: `400 VALIDATION_ERROR`, `401 UNAUTHORIZED`, `403 ORIGINATOR_OWNERSHIP_VIOLATION`, `429 INGRESS_RATE_LIMIT_EXCEEDED`, `500 INTERNAL_ERROR`.

### Consulta de Saldo — resposta síncrona (`200`) agora é oportunista

**Alterado** · **Não-breaking**

* A [Consulta de Saldo](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-consulta-saldo.md) (e a [versão em lote](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-consulta-saldo-lote.md)) pode responder `202` mesmo havendo um saldo recente no sistema: o `200 OK` síncrono (saldo inline) passou a ser uma **otimização oportunista e não garantida**. O contrato (`200` | `202`) **não muda** — integrações que já tratam o `202` (webhook/polling) seguem funcionando. Garanta o fluxo assíncrono como caminho padrão.

***

## 2026-06-24

### Formalização de contrato — novos endpoints

**Adicionado** · **Aditivo (não-breaking)**

* Nova seção [Contratos (Formalização)](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos.md) com 6 endpoints sob `/api/v1/fgts/contracts` para submeter e acompanhar contratos (CCB) de empréstimo com garantia FGTS:
  * [Submeter Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/submeter-contrato.md) — `POST /api/v1/fgts/contracts`. Síncrono (`201` com `contractNumber`); header `Idempotency-Key` **obrigatório**; PDF assinado opcional em `signedDocumentBase64` (presente → Modo A `RECEIVED`; ausente → Modo B `AWAITING_SIGNED_DOCUMENT`).
  * [Enviar Documento Assinado](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/enviar-documento-assinado.md) — `POST /api/v1/fgts/contracts/{contractNumber}/documents` (Modo B).
  * [Consultar Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md) — `GET /api/v1/fgts/contracts/{contractNumber}`.
  * [Cancelar Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md) — `DELETE /api/v1/fgts/contracts/{contractNumber}`.
  * [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` (após o evento `CONTRACT_PAYMENT_REVISION`).
  * [Baixar Documento (CCB)](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/baixar-documento-ccb.md) — `GET /api/v1/fgts/contracts/{contractNumber}/documents/template` (URL presigned, disponível após `FORMALIZED`).
* Guia [Fluxo de Formalização](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-formalizacao.md): ciclo de vida do contrato (`status`), Modo A/B, revisão de desembolso e download da CCB. Termos novos em [Glossário](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/glossario.md); erros em [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md).

***

## 2026-06-22

### Eventos de formalização de contrato (`source = CONTRACT`)

**Adicionado** · **Aditivo (não-breaking)**

* Novo `source` **`CONTRACT`** e **11** eventos `CONTRACT_*` de webhook — *milestones* da saga de formalização de contrato (CCB): `CONTRACT_RECEIVED`, `CONTRACT_ENDORSED`, `CONTRACT_ENDORSEMENT_REJECTED`, `CONTRACT_SENT_TO_GTBANKER`, `CONTRACT_FORMALIZED`, `CONTRACT_PAID`, `CONTRACT_FORMALIZATION_FAILED`, `CONTRACT_PAYMENT_FAILED`, `CONTRACT_PAYMENT_REVISION`, `CONTRACT_CANCELLED`, `CONTRACT_DOCUMENT_GENERATED`. Catálogo em [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md) e [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md).
* Campos `data.contractNumber` + `data.clientReference` (correlação da saga, por par) nos eventos `source = CONTRACT`; `data.dueDate` + `data.reason` em `CONTRACT_PAYMENT_REVISION` e `data.reason` em `CONTRACT_PAYMENT_FAILED`. Os eventos de contrato **não** carregam `data.result`.

***

## 2026-06-18

### Desaverbação com gate de revisão manual

**Adicionado**

* Campo **obrigatório** `cancellationType` (enum: `SEVEN_DAYS_REGRET`, `SETTLEMENT_DISCHARGE`, `OPERATIONAL_ERROR`, `FRAUD_PREVENTION`, `BANK_REJECTION`, `JUDICIAL_ORDER`, `OTHER`) no corpo de [Submeter Cancelamento de Reserva](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-cancelamento-reserva.md) (`POST /api/v1/fgts/reserve-cancellations`): motivo estruturado do cancelamento, usado pela Giro na revisão manual. Requisições sem o campo recebem `400 VALIDATION_ERROR`.
* Campo `reason` (opcional, `string` máx. 2000) no corpo de [Submeter Cancelamento de Reserva](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-cancelamento-reserva.md) (`POST /api/v1/fgts/reserve-cancellations`): justificativa textual livre usada pela Giro na revisão manual.
* Estado intermediário `PENDING_MANUAL_APPROVAL` no ciclo de vida do `status`, exclusivo do cancelamento de reserva: toda desaverbação é retida nesse estado aguardando aprovação manual da Giro antes do envio à Caixa. Aprovada → `QUEUED`; rejeitada → `CANCELLED`. Ver [Fluxo assíncrono e polling](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-assincrono-e-polling.md).
* Evento de webhook `CANCEL_RESERVE_UNDER_REVIEW` (intermediário/não-terminal), emitido quando a desaverbação entra em revisão manual. **Sempre** seguido por um terminal (`CANCEL_RESERVE_COMPLETED` ou `CANCEL_RESERVE_FAILED`). Catálogo em [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md) e [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md).
* `code` `RESERVE_CANCELLATION_REJECTED` no `error` (`OperationError`) do evento `CANCEL_RESERVE_FAILED`, entregue quando a desaverbação é rejeitada na revisão manual.

### Endpoint de consulta de valor reservado renomeado

**Alterado** · **Breaking**

* O path de [Submeter Consulta de Valor Reservado](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-consulta-valor-reservado.md) mudou de `POST /api/v1/fgts/reserved-value-queries` para **`POST /api/v1/fgts/reserve-value-queries`**, padronizando o prefixo `reserve-*` com [Consulta de Protocolos por Reserva](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-consulta-protocolos-reserva.md) (`POST /api/v1/fgts/reserve-protocol-queries`). Atualize as integrações que usam o path antigo; corpo, resposta e comportamento permanecem inalterados.

***

## 2026-06-17

### Cancelamento de operação por `requestId`

**Adicionado**

* [Cancelar Operação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/gerenciar-operacoes/cancelar-operacao.md) (`DELETE /api/v1/fgts/operations/{requestId}`): cancela uma operação FGTS pelo `requestId` enquanto ela ainda não começou a ser processada. Operação **síncrona** e **idempotente** — `200` com `{ requestId, status: CANCELLED, cancelledAt }`. Erros: `404 OPERATION_NOT_FOUND`, `409 OPERATION_NOT_CANCELLABLE` (operação já em processamento ou finalizada) e `503 DISPATCHER_UNAVAILABLE`.
* Estado terminal `CANCELLED` no ciclo de vida do `status` — ver [Fluxo assíncrono e polling](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-assincrono-e-polling.md).
* `errorCode` `OPERATION_NOT_CANCELLABLE` (409) na referência de [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#conflict).

***

## 2026-06-16

### Consulta de status do protocolo — contrato detalhado

**Alterado**

* [Consultar Status do Protocolo](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/consultar-status-protocolo.md) (`GET /api/v1/fgts/protocols/{protocolNumber}`): documentação alinhada ao contrato em produção. O campo de status no corpo `200` é `protocolStatus` (enum `ENDORSED`, `PROCESSING`, `REJECTED`, `NOT_FOUND`, `RATE_LIMITED`); o corpo é `protocolNumber` + `protocolStatus` + `result`. Erros padronizados: `403 ORIGINATOR_OWNERSHIP_VIOLATION`, `404 PROTOCOL_NOT_FOUND` e `429 PROTOCOL_RATE_LIMITED` (com header `Retry-After`). **⚠️ Descontinuado em 2026-06-25** — a consulta passou a ser assíncrona (`POST /api/v1/fgts/protocol-status-queries`); ver a entrada de 2026-06-25.

**Adicionado**

* Guia [Status da operação vs. status do protocolo](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-assincrono-e-polling.md#protocolo-vs-operacao): quando usar o polling por `requestId` e quando usar a consulta por número de protocolo.
* `errorCode` `PROTOCOL_RATE_LIMITED` (429) na referência de [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#rate-limit-exceeded).

***

## 2026-06-15

### Release inicial da API GTFgts (Originator)

Primeira versão pública da API de crédito com garantia FGTS para originators. Cobre a submissão assíncrona de operações FGTS, o acompanhamento por polling, a simulação de empréstimo, o cadastro de webhook e a entrega de resultados por notificação.

**Adicionado**

* **Operações FGTS** (assíncronas, prioridade `NORMAL`, retorno `202 { requestId, status }`):
  * [Submeter Averbação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-averbacao.md) — `POST /api/v1/fgts/endorsements`
  * [Submeter Cancelamento de Reserva](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-cancelamento-reserva.md) — `POST /api/v1/fgts/reserve-cancellations`
  * [Submeter Consulta de Saldo](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-consulta-saldo.md) — `POST /api/v1/fgts/balance-queries` (com **resposta em cache**: `200` quando há valor recente em cache)
  * [Submeter Consulta de Valor Reservado](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-consulta-valor-reservado.md) — `POST /api/v1/fgts/reserve-value-queries`
  * [Submeter Consulta de Protocolos por Reserva](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-consulta-protocolos-reserva.md) — `POST /api/v1/fgts/reserve-protocol-queries`
* **Consulta em lote** com prioridade `DEFERRED`: [Submeter Consulta de Saldo em Lote](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-consulta-saldo-lote.md) — `POST /api/v1/fgts/batch/balance-queries`.
* **Acompanhamento**: [Consultar Status da Operação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md) (`GET /api/v1/fgts/operations/{requestId}`) e [Consultar Status do Protocolo](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/consultar-status-protocolo.md) (`GET /api/v1/fgts/protocols/{protocolNumber}` — **descontinuado em 2026-06-25**, agora `POST /api/v1/fgts/protocol-status-queries`).
* **Simulações**: [Criar Simulação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/simulacoes/criar-simulacao.md) (`POST /api/v1/simulations`) e [Buscar Simulação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/simulacoes/buscar-simulacao.md) (`GET /api/v1/simulations/{id}`).
* **Cadastro de webhook** escopado ao originator: [Criar](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/cadastro-webhook/criar-cadastro-webhook.md), [Obter](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/cadastro-webhook/obter-cadastro-webhook.md), [Atualizar](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/cadastro-webhook/atualizar-cadastro-webhook.md) e [Remover](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/cadastro-webhook/remover-cadastro-webhook.md) (`/api/v1/webhooks`).
* **Entrega de webhook** (`WebhookEnvelope` com `source`, `eventType`, `data`) com semântica *at-least-once* e retry com back-off exponencial. Catálogo de eventos em [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md).
* **Header de idempotência** `Idempotency-Key` nas submissões de operação — reenviar a mesma chave retorna o `requestId` existente sem reprocessar. Ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/idempotencia.md).
* **Rate limit** por originator: acima da cota normal, a operação pode ser admitida com prioridade `DEFERRED` (`202`); acima do limite, a requisição é rejeitada com `429`. Ver [Prioridades e rate limit](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/prioridades-e-rate-limit.md).
