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

# Payloads

Estrutura do corpo entregue em cada evento de webhook do GTFgts: **como** é o `data`, a forma do `error`/`OperationError`, o mapeamento `eventType → result` e os exemplos JSON de cada evento. Para o catálogo de **quais** `source` e `eventType` existem, ver [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md).

Todos os exemplos são extraídos do contrato de entrega ([gtfgts-webhook.openapi.yaml](https://github.com/giro-tech/giro-tech-docs/tree/github-to-gitbook/openapi/gtfgts-webhook/gtfgts-webhook.openapi.yaml)).

***

## Estrutura do `data`

O objeto `data` tem a **mesma estrutura** para todos os eventos. Os campos `requestId`, `status` e `source` estão sempre presentes; os demais aparecem conforme o tipo de operação e o `status`.

| Campo               | Tipo                                     | Descrição                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `requestId`         | `string`                                 | Identificador de correlação que casa com a requisição FGTS original. **Use, junto com o `eventType`, como chave de idempotência** para deduplicar reentregas — a mesma operação emite mais de um evento. Sempre presente.                                                                                                                                                                                                                                                                                                                                                                     |
| `contractNumber`    | `string` (opcional)                      | Número de negócio do contrato (CCB), sequencial por originator. Presente nos eventos `source = CONTRACT` (chave de correlação da saga de formalização) **e** nos eventos das operações de reserva — averbação, cancelamento de reserva e manutenção de garantia — cuja garantia pertence a um contrato. Nessas três, o número é resolvido pela plataforma a partir da própria garantia: ele sai no evento mesmo quando você submeteu a operação por `reserveIdentifier`, sem informar o contrato. Ausente nas consultas (saldo, valor reservado, protocolos), que não têm contrato associado. |
| `clientReference`   | `string` (opcional)                      | **Eventos `source = CONTRACT`.** Id do cliente que você forneceu, ecoado para correlação/exibição. Ausente no tráfego FGTS-Caixa.                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `reserveIdentifier` | `string` (opcional)                      | Identificador lógico da reserva. Presente no nível superior do `data` quando a operação tem reserva associada e o identificador é conhecido — **inclusive** nos eventos `*_FAILED` de recusa (averbação duplicada, recusa de gate); ausente caso contrário. O mesmo valor também é entregue no [polling](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md).                                                                                                                                                   |
| `protocolNumber`    | `string` (opcional)                      | Protocolo da Caixa. Presente no nível superior do `data` quando a operação gera número de protocolo Caixa; ausente caso contrário. Enviado como **string**, não número: o protocolo pode exceder a faixa segura de inteiro em JSON e preservar zeros à esquerda.                                                                                                                                                                                                                                                                                                                              |
| `status`            | `string`                                 | Nas operações FGTS-Caixa, o status da operação: `COMPLETED` = concluída; `FAILED` = negada/com erro; `EXPIRED` = expirou sem desfecho, ainda na fila da Giro (verifique); `UNDER_REVIEW` = em revisão manual; `RETRYING` = em retentativa automática; `CANCELLED` = cancelada pela Giro na fila. Nos eventos `source = CONTRACT`, o **marco** do contrato — ver a seção *Eventos de contrato* abaixo. Sempre presente.                                                                                                                                                                        |
| `source`            | `string`                                 | Origem do resultado: `CAIXA_CALL` (saldo apurado na Caixa) ou `NA` (operação que não chama a Caixa diretamente). Sempre presente.                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `result`            | `object` (opcional)                      | Nó completo do resultado. **Opaco** — trate como JSON livre. Em operações **Caixa**: presente apenas em `status = COMPLETED`, ausente em `FAILED`/`EXPIRED`. Nos eventos `source = CONTRACT` é o **nó de milestone do serviço de formalização** (`ContractMilestoneResult`, com ao menos `milestone`), presente quando o serviço de formalização o envia — sempre em `CONTRACT_PAYMENT_REVISION`/`CONTRACT_PAYMENT_FAILED`.                                                                                                                                                                   |
| `error`             | `object` (`OperationError`, opcional)    | Erro canônico GTLab. Presente em `FAILED` e `EXPIRED`, em `CANCELLED` (`code = OPERATOR_CANCELLED`), em `RETRYING` (o motivo da espera) e nos eventos de falha `CONTRACT_*`. Catálogo em [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#catalogo-operacao).                                                                                                                                                                                                                                                                                                  |
| `dueDate`           | `string` (date, opcional)                | **Apenas `CONTRACT_PAYMENT_REVISION`.** Último dia (fuso de São Paulo) em que a emenda ainda é aceita — quando `dueAt` cai à meia-noite, é o dia **anterior**. Para decidir se ainda há tempo, use `dueAt`.                                                                                                                                                                                                                                                                                                                                                                                   |
| `dueAt`             | `string` (date-time, opcional)           | **Apenas `CONTRACT_PAYMENT_REVISION`.** Instante exato (ISO-8601 UTC) em que o ticket expira — ex.: `2026-06-26T02:59:59Z`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `availableActions`  | `array<string>` (opcional)               | **Apenas `CONTRACT_PAYMENT_REVISION`.** 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 a ausência como `NEW_ACCOUNT`.                                                                                                                                                                                                                                                                                                                                                           |
| `reason`            | `object` (`{ code, message }`, opcional) | **Eventos `CONTRACT_PAYMENT_REVISION` / `CONTRACT_CANCELLED`.** O `CONTRACT_PAYMENT_FAILED` traz o motivo em `error`, não aqui. Motivo (em inglês) da revisão, da falha de pagamento ou do cancelamento.                                                                                                                                                                                                                                                                                                                                                                                      |

{% hint style="info" %}
**`contractNumber`, `reserveIdentifier` e `protocolNumber`, quando presentes, aparecem no nível superior do `data`** — você os encontra tanto em `data.reserveIdentifier`/`data.protocolNumber` quanto dentro de `data.result`. O campo **`result` é opaco**: sua forma varia conforme a operação (ex.: `periods[]` com saldos na consulta de saldo; `protocolNumber`/`protocolStatus` na averbação). Trate-o como um objeto JSON livre, lendo apenas as chaves de que precisa.
{% endhint %}

***

## Qual `data` esperar para cada `eventType`

A estrutura do `data` é a mesma dentro de cada **grupo de desfecho** (o sufixo do `eventType`), independentemente da operação. Em vez de decorar 28 formatos diferentes, você lida com **seis grupos** (o agrupamento completo está em [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md)):

| Grupo (sufixo do `eventType`) | `status`              | Campos presentes em `data`                                                                                                                                                                                                                | Significado                                                                                                                                                                                                                                                         |
| ----------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `*_COMPLETED`                 | `COMPLETED`           | `requestId`, `status`, `source`, `result` (+ `reserveIdentifier`/`protocolNumber` quando houver)                                                                                                                                          | Operação concluída com sucesso. O resultado vem em `result`.                                                                                                                                                                                                        |
| `BALANCE_QUERY_NO_BALANCE`    | `COMPLETED`           | `requestId`, `status`, `source`, `result` (com `result.hasBalance = false`)                                                                                                                                                               | Consulta de saldo concluída, mas **sem saldo FGTS** disponível. Caso especial do `COMPLETED`.                                                                                                                                                                       |
| `*_FAILED`                    | `FAILED` ou `EXPIRED` | `requestId`, `status`, `source`, `error` (+ `error.originalErrors[]` quando a Caixa foi chamada e retornou erro; + `reserveIdentifier` quando conhecido — inclusive nos eventos de **recusa**, ex. averbação duplicada ou recusa de gate) | Operação negada/com erro. Não há `result`. Nas **consultas** (`BALANCE_QUERY`, `QUERY_RESERVED_VALUE`), a expiração também é entregue aqui, com `status = EXPIRED`.                                                                                                 |
| `*_NEEDS_VERIFICATION`        | `EXPIRED`             | `requestId`, `status`, `source`, `error` (+ `reserveIdentifier` quando houver)                                                                                                                                                            | A operação expirou sem desfecho, ainda na fila da Giro. **Não há `result`**; o `error` traz apenas `code = EXPIRED_TTL`, que marca a expiração e **não** é veredito da Caixa — **verifique** por polling antes de assumir um resultado.                             |
| `*_UNDER_REVIEW`              | `UNDER_REVIEW`        | `requestId`, `status`, `source` (+ `reserveIdentifier` quando houver)                                                                                                                                                                     | **Intermediário** (não-terminal): o cancelamento de reserva ou a manutenção de garantia entrou em **revisão manual** da Giro. **Não há `result` nem `error`** — a operação ainda não foi à Caixa. **Sempre** seguido por um terminal (`*_COMPLETED` ou `*_FAILED`). |
| `*_CANCELLED`                 | `CANCELLED`           | `requestId`, `status`, `source`, `error` (`code = OPERATOR_CANCELLED`)                                                                                                                                                                    | A Giro cancelou a operação enquanto ela ainda estava na fila. Terminal. O `DELETE` feito por você **não** gera este evento.                                                                                                                                         |

Os campos `requestId`, `status` e `source` estão **sempre** presentes em todos os grupos. `reserveIdentifier` e `protocolNumber` aparecem no nível superior do `data` apenas quando a operação tem reserva/protocolo associado, e `contractNumber` apenas nas operações de reserva cuja garantia pertence a um contrato — em qualquer um dos cinco grupos, inclusive `*_UNDER_REVIEW` e `*_FAILED`.

### Mapeamento por `eventType`

A coluna **Conteúdo de `result`** descreve o que costuma vir no resultado de cada operação **quando concluída** (`*_COMPLETED`). Lembre que o `result` é **opaco**: os campos abaixo são os típicos de cada operação, mas trate-o sempre como objeto JSON livre e leia apenas as chaves de que precisa.

| `eventType`                             | `source` do envelope    | Grupo                      | Conteúdo de `result` (em `COMPLETED`)                                                                                         |
| --------------------------------------- | ----------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `BALANCE_QUERY_COMPLETED`               | `BALANCE_QUERY`         | `*_COMPLETED`              | `BalanceResult` — saldo com `periods[]` (`workerCpf`, `balanceDate`, `periods`).                                              |
| `BALANCE_QUERY_NO_BALANCE`              | `BALANCE_QUERY`         | `BALANCE_QUERY_NO_BALANCE` | `hasBalance = false` — sem saldo disponível.                                                                                  |
| `BALANCE_QUERY_FAILED`                  | `BALANCE_QUERY`         | `*_FAILED`                 | — (sem `result`; ver `error`).                                                                                                |
| `ENDORSEMENT_COMPLETED`                 | `ENDORSEMENT`           | `*_COMPLETED`              | `ProtocolResult` — `protocolNumber`, `protocolStatus`, `detail`. `protocolNumber` também no nível superior.                   |
| `ENDORSEMENT_FAILED`                    | `ENDORSEMENT`           | `*_FAILED`                 | — (sem `result`; ver `error`).                                                                                                |
| `ENDORSEMENT_NEEDS_VERIFICATION`        | `ENDORSEMENT`           | `*_NEEDS_VERIFICATION`     | — (expirou; sem `result`; `error.code = EXPIRED_TTL`).                                                                        |
| `MAINTAIN_GUARANTEE_COMPLETED`          | `MAINTAIN_GUARANTEE`    | `*_COMPLETED`              | `ProtocolResult` — `protocolNumber`, `protocolStatus`, `detail`.                                                              |
| `MAINTAIN_GUARANTEE_FAILED`             | `MAINTAIN_GUARANTEE`    | `*_FAILED`                 | — (sem `result`; ver `error`).                                                                                                |
| `MAINTAIN_GUARANTEE_NEEDS_VERIFICATION` | `MAINTAIN_GUARANTEE`    | `*_NEEDS_VERIFICATION`     | — (expirou; sem `result`; `error.code = EXPIRED_TTL`).                                                                        |
| `CANCEL_RESERVE_UNDER_REVIEW`           | `CANCEL_RESERVE`        | `*_UNDER_REVIEW`           | — (em revisão manual; sem `result` nem `error`).                                                                              |
| `CANCEL_RESERVE_COMPLETED`              | `CANCEL_RESERVE`        | `*_COMPLETED`              | `ProtocolResult` — `protocolNumber`, `protocolStatus`, `detail`.                                                              |
| `CANCEL_RESERVE_FAILED`                 | `CANCEL_RESERVE`        | `*_FAILED`                 | — (sem `result`; ver `error`).                                                                                                |
| `CANCEL_RESERVE_NEEDS_VERIFICATION`     | `CANCEL_RESERVE`        | `*_NEEDS_VERIFICATION`     | — (expirou; sem `result`; `error.code = EXPIRED_TTL`).                                                                        |
| `QUERY_RESERVED_VALUE_COMPLETED`        | `QUERY_RESERVED_VALUE`  | `*_COMPLETED`              | `ReservedValueResult` — `periods[]` atualizados e `operationKind`.                                                            |
| `QUERY_RESERVED_VALUE_FAILED`           | `QUERY_RESERVED_VALUE`  | `*_FAILED`                 | — (sem `result`; ver `error`).                                                                                                |
| `LIST_PROTOCOLS_COMPLETED`              | `LIST_PROTOCOLS_BY_ID`  | `*_COMPLETED`              | Lista de protocolos associados à reserva.                                                                                     |
| `LIST_PROTOCOLS_FAILED`                 | `LIST_PROTOCOLS_BY_ID`  | `*_FAILED`                 | — (sem `result`; ver `error`).                                                                                                |
| `QUERY_PROTOCOL_STATUS_COMPLETED`       | `QUERY_PROTOCOL_STATUS` | `*_COMPLETED`              | Status atual do protocolo — `protocolNumber`, `protocolStatus` e dados de detalhe. `protocolNumber` também no nível superior. |
| `QUERY_PROTOCOL_STATUS_FAILED`          | `QUERY_PROTOCOL_STATUS` | `*_FAILED`                 | — (sem `result`; ver `error`).                                                                                                |

***

## `error` (`OperationError`)

Presente em `data.error` quando `status = FAILED` ou `EXPIRED`. É a estrutura de erro canônica do GTLab — definida pela plataforma e repassada sem alteração.

| Campo               | Tipo                | Descrição                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`              | `string`            | Código de erro GTLab **estável** para uso programático (não muda entre releases). Ex.: `ENDORSEMENT_DENIED`, `PROVIDER_ERROR`, `CPF_NOT_OPERABLE`, `GUARANTEE_APPROVAL_REJECTED` (rejeição na revisão manual), `OPERATOR_CANCELLED` (eventos `*_CANCELLED`), `OPERATION_NOT_YET_ALLOWED` (a Caixa só permite a operação a partir de uma data — ver [Erros](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#operation-not-yet-allowed)). |
| `message`           | `string`            | Resumo legível do erro.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `originalErrors`    | `array` (opcional)  | Erros brutos do provedor (Caixa). Presente **apenas** quando a API da Caixa foi de fato chamada e retornou erro. Cada item corresponde a uma reserva (suporte a operações multi-reserva).                                                                                                                                                                                                                                                                |
| `originalRequestId` | `string` (opcional) | Presente **apenas** quando `code` ∈ {`ENDORSEMENT_ALREADY_SUBMITTED`, `GUARANTEE_OPERATION_DUPLICATE`, `GUARANTEE_APPROVAL_ALREADY_PENDING`}: o `requestId` da operação que de fato está em andamento (ou concluída). O mesmo valor entregue no polling — ver [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#originalrequestid).                                                                                        |

### `originalErrors[]` (`OriginalError`)

Cada item da lista é o erro bruto retornado pela Caixa para uma reserva.

| Campo               | Tipo                           | Descrição                                                                                                                                                                                  |
| ------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `provider`          | `string`                       | Provedor que produziu o erro (ex.: `CAIXA`).                                                                                                                                               |
| `code`              | `string`                       | Código de erro específico do provedor (código bruto da Caixa, ex.: `"37"`; tabela em [Códigos da Caixa](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#catalogo-caixa)). |
| `description`       | `string` (opcional)            | Descrição legível do erro retornada pelo provedor.                                                                                                                                         |
| `httpStatus`        | `integer` (opcional)           | HTTP status retornado pelo provedor para este erro específico.                                                                                                                             |
| `requestIdentifier` | `string` (opcional)            | Identificador da reserva na requisição Caixa que falhou.                                                                                                                                   |
| `occurredAt`        | `string` (date-time, opcional) | Timestamp ISO-8601 UTC de quando o erro ocorreu na Caixa.                                                                                                                                  |

***

## Eventos de contrato (`source = CONTRACT`)

Os eventos `CONTRACT_*` (saga de formalização — catálogo em [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md)) **não** trazem um `result` de operação **Caixa**. Quando o serviço de formalização envia um nó de milestone, ele vem em `data.result` como um **`ContractMilestoneResult`** (opaco, com ao menos `milestone`). O `data` traz:

* **Sempre:** `requestId`, `status`, `source` (= `NA`), `contractNumber`, `clientReference`.
* **`CONTRACT_PAYMENT_REVISION`:** `dueDate`, `dueAt`, `availableActions` e `reason` (`{ code, message }`) no topo de `data`, **e também** em `data.result` (`{ milestone, dueDate, dueAt, availableActions, reason }`). `availableActions` diz o que o provedor aceita naquele ticket — ver [Revisar Conta de Desembolso](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/revisar-conta-desembolso.md).
* **Falhas** (`CONTRACT_ENDORSEMENT_REJECTED`, `CONTRACT_FORMALIZATION_FAILED`, `CONTRACT_PAYMENT_FAILED`, `CONTRACT_DOCUMENT_GENERATION_FAILED`): `error` (`OperationError`). No `CONTRACT_PAYMENT_FAILED`, `error.code` é o código do banco liquidante e não há `reason` nem `dueDate`. No `CONTRACT_FORMALIZATION_FAILED` e no `CONTRACT_DOCUMENT_GENERATION_FAILED`, `error.code` vem `null` e a causa está em `error.message`.
* **Demais milestones** (`RECEIVED`, `ENDORSED`, `SENT_TO_GTBANKER`, `FORMALIZED`, `PAID`, `CANCELLED`, `DOCUMENT_GENERATED`): correlação pelo par + `status`; podem trazer um `result` de milestone conforme o serviço de formalização.

{% hint style="info" %}
`dueDate`/`dueAt`/`availableActions`/`reason` vêm sempre normalizados em inglês (ex.: `NEW_ACCOUNT`, `RETRY`). Eventos `CONTRACT_*` são sempre em **inglês** e **não** carregam PII crua (sem CPF em claro).
{% endhint %}

Nos eventos `source = CONTRACT`, o `data.status` é o **marco** do contrato que o evento representa — `ENDORSED`, `PAID`, `CANCELLED`, `PENDING_PAYMENT_APPROVAL`… — e **não** `COMPLETED`/`FAILED`. A coluna `status` da tabela abaixo traz o valor de cada evento. Decida pelo `eventType`; o `status` repete a mesma informação. O **estado de negócio** do contrato (`RECEIVED`, `ENDORSED`, `PAID`, …) é obtido no polling em [`GET /api/v1/fgts/contracts/{contractNumber}`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md).

### Mapeamento por `eventType`

Todos os eventos `CONTRACT_*` trazem sempre `requestId`, `status`, `source` (= `NA`), `contractNumber` e `clientReference`. A tabela lista o `status` (o marco) de cada evento e os campos que vêm **além** desses.

| `eventType`                           | `status`                     | Campos extras em `data`                                        | Quando                                                                                                                                                                                                                                                     |
| ------------------------------------- | ---------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CONTRACT_RECEIVED`                   | `RECEIVED`                   | —                                                              | Contrato (CCB) recebido e validado (ack).                                                                                                                                                                                                                  |
| `CONTRACT_ENDORSED`                   | `ENDORSED`                   | —                                                              | Averbação/reserva confirmada na Caixa.                                                                                                                                                                                                                     |
| `CONTRACT_PAYMENT_APPROVAL_REQUIRED`  | `PENDING_PAYMENT_APPROVAL`   | `endorsedAt`                                                   | Gate ativo: contrato aguarda aprovação de pagamento pelo originador.                                                                                                                                                                                       |
| `CONTRACT_ENDORSEMENT_REJECTED`       | `ENDORSEMENT_REJECTED`       | `error`                                                        | A Caixa recusou a averbação — ou a janela de retentativa automática se esgotou (`error.code = TRANSIENT_PROVIDER_RETRY_EXHAUSTED`).                                                                                                                        |
| `CONTRACT_ENDORSEMENT_RETRYING`       | `RETRYING`                   | `retry` + `error`                                              | **Não-terminal**: a Caixa devolveu um código transiente e a Giro já reagendou. O contrato segue em `PENDING_ENDORSEMENT`; não é preciso agir.                                                                                                              |
| `CONTRACT_SENT_TO_GTBANKER`           | `SENT_TO_GTBANKER`           | —                                                              | Payload e documento enviados ao GTBanker.                                                                                                                                                                                                                  |
| `CONTRACT_FORMALIZED`                 | `FORMALIZED`                 | —                                                              | O GTBanker confirmou o recebimento da CCB.                                                                                                                                                                                                                 |
| `CONTRACT_PAID`                       | `PAID`                       | `paymentReceiptUrl` (opcional) + `result`                      | Desembolso confirmado. `paymentReceiptUrl` é o comprovante — trate como credencial.                                                                                                                                                                        |
| `CONTRACT_FORMALIZATION_FAILED`       | `FORMALIZATION_FAILED`       | `error`                                                        | Falha/recusa no GTBanker. Nem sempre é terminal: o contrato pode seguir retido para nova tentativa, sem liberar a reserva — acompanhe o próximo evento.                                                                                                    |
| `CONTRACT_PAYMENT_FAILED`             | `PAYMENT_FAILED`             | `error` (`{ code, message }`) + `result` (`{ milestone }`)     | Falha no desembolso — informativo (em resolução pela Giro; **sem** `dueDate`). Aguarde `CONTRACT_PAID` ou `CONTRACT_PAYMENT_REVISION`.                                                                                                                     |
| `CONTRACT_PAYMENT_REVISION`           | `PAYMENT_REVISION`           | `dueDate` + `dueAt` + `availableActions` + `reason` + `result` | Pagamento em revisão: reenvie a conta de desembolso até `dueAt`, respeitando `availableActions`.                                                                                                                                                           |
| `CONTRACT_CANCELLED`                  | `CANCELLED`                  | `reason`                                                       | Contrato cancelado. `reason.code`: `CANCELLED_BY_ORIGINATOR`, `ENDORSEMENT_DENIED_NOT_RETRYABLE` (código 52 da Caixa), `ENDORSEMENT_RETRY_WINDOW_EXPIRED` (recusa não retentada na janela) ou `DISBURSEMENT_REVISION_EXPIRED` (revisão de conta expirada). |
| `CONTRACT_DOCUMENT_GENERATED`         | `DOCUMENT_GENERATED`         | —                                                              | Documento (PDF) do contrato gerado.                                                                                                                                                                                                                        |
| `CONTRACT_DOCUMENT_GENERATION_FAILED` | `DOCUMENT_GENERATION_FAILED` | `error` (`code` `null`; causa em `message`)                    | A geração da CCB falhou; o contrato fica em `DOCUMENT_GENERATION_FAILED`. Acione o suporte. **Não é terminal**: pode ser seguido de `CONTRACT_DOCUMENT_GENERATED` para o mesmo `contractNumber`, com o contrato de volta a `AWAITING_SIGNED_DOCUMENT`.     |

### CONTRACT\_ENDORSED

Averbação confirmada na Caixa — o contrato avança para `ENDORSED` (visível no [GET](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md)); o `data.status` do evento é `ENDORSED`. Sem `error`; correlação pelo par `contractNumber` + `clientReference`.

```json
{
  "source": "CONTRACT",
  "eventType": "CONTRACT_ENDORSED",
  "data": {
    "requestId": "c0000001-aaaa-bbbb-cccc-000000000003",
    "contractNumber": "00012345",
    "clientReference": "orig-ref-2026-0001",
    "status": "ENDORSED",
    "source": "NA"
  }
}
```

***

### CONTRACT\_PAYMENT\_APPROVAL\_REQUIRED

Gate de aprovação de pagamento ativo — o contrato aguarda em `PENDING_PAYMENT_APPROVAL` até o originador chamar [`POST .../payment-approval`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/aprovar-pagamento.md). O campo `endorsedAt` indica quando a averbação na Caixa foi confirmada.

```json
{
  "source": "CONTRACT",
  "eventType": "CONTRACT_PAYMENT_APPROVAL_REQUIRED",
  "data": {
    "requestId": "c0000001-aaaa-bbbb-cccc-000000000003:CONTRACT_PAYMENT_APPROVAL_REQUIRED",
    "contractNumber": "00012345",
    "clientReference": "orig-ref-2026-0001",
    "status": "PENDING_PAYMENT_APPROVAL",
    "source": "NA",
    "endorsedAt": "2026-06-29T14:30:00Z"
  }
}
```

***

### CONTRACT\_ENDORSEMENT\_REJECTED

Averbação **rejeitada** pela Caixa — o contrato vai para `ENDORSEMENT_REJECTED` (visível no GET) e o evento traz `error` (`OperationError`, em inglês) com `data.status = FAILED`. Não há `result`.

```json
{
  "source": "CONTRACT",
  "eventType": "CONTRACT_ENDORSEMENT_REJECTED",
  "data": {
    "requestId": "c0000001-aaaa-bbbb-cccc-000000000004",
    "contractNumber": "00012345",
    "clientReference": "orig-ref-2026-0001",
    "status": "ENDORSEMENT_REJECTED",
    "source": "NA",
    "error": {
      "code": "ENDORSEMENT_DENIED",
      "message": "Endorsement denied by Caixa"
    }
  }
}
```

***

### CONTRACT\_ENDORSEMENT\_RETRYING

Averbação em **retentativa automática**. A Caixa devolveu um código transiente (serviço indisponível ou pedido explícito de nova tentativa) e a Giro reenvia a **mesma reserva** a cada 15 minutos, por até 72 horas, sem que o originador precise fazer nada. O contrato permanece em `PENDING_ENDORSEMENT` durante toda a janela.

O bloco `retry` diz em que ponto da janela estamos:

* `providerAttempt` — quantas tentativas **nossas** já foram feitas (pode chegar a \~288 numa janela cheia). **Não confunda** com o seu limite de retentativas manuais, que é de **3 por reserva**.
* `nextAttemptAt` — quando tentaremos de novo.
* `windowExpiresAt` — quando a janela acaba. Passado esse instante sem sucesso, chega `CONTRACT_ENDORSEMENT_REJECTED` com `error.code = TRANSIENT_PROVIDER_RETRY_EXHAUSTED`.
* `eligible` — sempre `false` aqui: uma retentativa manual durante a janela é recusada com `409 ENDORSEMENT_NOT_RETRYABLE`, porque a garantia ainda está em processamento.
* `lastProviderError` — **o que a Caixa respondeu** na tentativa que abriu este ciclo: `provider`, `code`, `description`, `httpStatus`, `requestIdentifier` e `occurredAt`. É o mesmo campo, na mesma forma e no mesmo caminho de [Consultar Status](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md#campo-retry-retryprogress) — os dois canais contam a mesma história.

{% hint style="warning" %}
**É o `lastProviderError` que diz se há algo a fazer.**

O código **`7`** (`httpStatus 403`) significa que o trabalhador ainda **não autorizou** a operação no app do FGTS. **Peça a ele que autorize** — a próxima tentativa automática converte, e a mediana observada é de 4 a 5 tentativas, cerca de 75 minutos. Já os códigos **`3`**, **`14`** e **`524`** são instabilidade da Caixa: não há ação do seu lado, a janela resolve sozinha.

**O campo `error` neste evento não significa que a averbação falhou.** Ela continua em andamento — `ENDORSEMENT_RETRYING` é intermediário por definição. O `error` está ali por compatibilidade e carrega o mesmo dado da Caixa em `error.originalErrors`. Programe pelo `retry.lastProviderError`.
{% endhint %}

```json
{
  "source": "CONTRACT",
  "eventType": "CONTRACT_ENDORSEMENT_RETRYING",
  "data": {
    "requestId": "c0000001-aaaa-bbbb-cccc-000000000005",
    "contractNumber": "00012345",
    "clientReference": "orig-ref-2026-0001",
    "status": "RETRYING",
    "source": "NA",
    "retry": {
      "providerAttempt": 7,
      "nextAttemptAt": "2026-08-20T15:30:00Z",
      "windowExpiresAt": "2026-08-23T09:00:00Z",
      "eligible": false,
      "lastProviderError": {
        "provider": "CAIXA",
        "code": "7",
        "description": "Instituição Fiduciária não possui autorização do Trabalhador para Operação Fiduciária",
        "httpStatus": 403,
        "requestIdentifier": "GTD00000042AB",
        "occurredAt": "2026-08-20T15:15:00Z"
      }
    },
    "error": {
      "code": "PROVIDER_RETRY_WINDOW",
      "message": "Caixa transient error (code 7); verify found no protocol",
      "originalErrors": [
        {
          "provider": "CAIXA",
          "code": "7",
          "description": "Instituição Fiduciária não possui autorização do Trabalhador para Operação Fiduciária",
          "httpStatus": 403,
          "requestIdentifier": "GTD00000042AB",
          "occurredAt": "2026-08-20T15:15:00Z"
        }
      ]
    }
  }
}
```

{% hint style="warning" %}
Este evento pode chegar **dezenas de vezes** para o mesmo contrato — um por tentativa, de 15 em 15 minutos. Trate-o como idempotente: o par `contractNumber` + `providerAttempt` identifica cada tentativa. Se você só precisa do desfecho, ignore este `eventType` e espere o terminal.
{% endhint %}

***

### CONTRACT\_PAID

Desembolso confirmado. `paymentReceiptUrl` traz o comprovante emitido pelo banco liquidante; correlação pelo par `contractNumber` + `clientReference`.

```json
{
  "source": "CONTRACT",
  "eventType": "CONTRACT_PAID",
  "data": {
    "requestId": "c0000001-aaaa-bbbb-cccc-000000000006",
    "contractNumber": "00000042",
    "clientReference": "cli-abc-987",
    "paymentReceiptUrl": "https://receipts.example.com/0195aa08-7f58-51b9-79c4-cc88e7a150b1/out/2282d8a0-ca23-4089-b04a-161e88c1fab2",
    "status": "PAID",
    "source": "NA",
    "result": {
      "milestone": "PAID",
      "paymentReceiptUrl": "https://receipts.example.com/0195aa08-7f58-51b9-79c4-cc88e7a150b1/out/2282d8a0-ca23-4089-b04a-161e88c1fab2"
    }
  }
}
```

{% hint style="warning" %}
**`paymentReceiptUrl` é uma 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. Ela também volta no campo `paymentReceiptUrl` de [Consultar Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md), então não é preciso guardá-la só para reexibir o comprovante. O campo é opcional: quando o banco não devolve o comprovante ele vem ausente, e isso **não** significa que o pagamento falhou.
{% endhint %}

### CONTRACT\_PAYMENT\_FAILED

Falha no desembolso — **informativo** (em resolução pela Giro). Sem `dueDate` nem `reason`; o motivo vem em `error` e `data.result` traz o nó de milestone.

```json
{
  "source": "CONTRACT",
  "eventType": "CONTRACT_PAYMENT_FAILED",
  "data": {
    "requestId": "c0000001-aaaa-bbbb-cccc-000000000008",
    "contractNumber": "00000042",
    "clientReference": "cli-abc-987",
    "status": "PAYMENT_FAILED",
    "source": "NA",
    "error": {
      "code": "SALDO_INSUFICIENTE",
      "message": "Saldo insuficiente na conta bancária"
    },
    "result": {
      "milestone": "PAYMENT_FAILED"
    }
  }
}
```

### CONTRACT\_CANCELLED

Contrato encerrado sem desembolso. `reason.code` distingue o cancelamento pedido pelo originador dos três automáticos. Quando havia reserva na Caixa, o evento só sai depois que ela é desaverbada; o evento **não** carrega `error` — o código da Caixa vem no `CONTRACT_ENDORSEMENT_REJECTED` que chega antes.

| `reason.code`                      | Quando                                                                                                                                                                                                                                        |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CANCELLED_BY_ORIGINATOR`          | [`DELETE .../contracts/{contractNumber}`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md), em qualquer estado antes do desembolso — inclusive pedido respondido com `202` e executado depois. |
| `ENDORSEMENT_DENIED_NOT_RETRYABLE` | Recusa da Caixa que retentar não resolve — código 52 ("Trabalhador já possui quantidade máxima permitida de operação de reserva"). Cancelado na chegada do resultado.                                                                         |
| `ENDORSEMENT_RETRY_WINDOW_EXPIRED` | Averbação recusada e não retentada dentro da janela.                                                                                                                                                                                          |
| `DISBURSEMENT_REVISION_EXPIRED`    | Revisão de conta de desembolso expirada sem nova conta; cancelado 1 dia após o vencimento, com a reserva desaverbada.                                                                                                                         |

```json
{
  "source": "CONTRACT",
  "eventType": "CONTRACT_CANCELLED",
  "data": {
    "requestId": "c0000001-aaaa-bbbb-cccc-000000000009",
    "contractNumber": "00000042",
    "clientReference": "cli-abc-987",
    "reason": {
      "code": "ENDORSEMENT_DENIED_NOT_RETRYABLE",
      "message": "52:Trabalhador ja possui quantidade maxima permitida de operacao de reserva"
    },
    "status": "CANCELLED",
    "source": "NA",
    "result": {
      "milestone": "CANCELLED"
    }
  }
}
```

### CONTRACT\_PAYMENT\_REVISION

Pagamento em revisão: o originador deve **reenviar a conta de desembolso** antes de `dueAt` via [`PUT /api/v1/fgts/contracts/{contractNumber}/disbursement-account`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/revisar-conta-desembolso.md), respeitando `availableActions`. `reason` traz o motivo (em inglês).

```json
{
  "source": "CONTRACT",
  "eventType": "CONTRACT_PAYMENT_REVISION",
  "data": {
    "requestId": "c0000001-aaaa-bbbb-cccc-000000000009",
    "contractNumber": "00000042",
    "clientReference": "cli-abc-987",
    "dueDate": "2026-06-25",
    "reason": {
      "code": "ACCOUNT_INVALID",
      "message": "Disbursement account rejected"
    },
    "status": "PAYMENT_REVISION",
    "source": "NA",
    "result": {
      "milestone": "PAYMENT_REVISION",
      "dueDate": "2026-06-25",
      "reason": {
        "code": "ACCOUNT_INVALID",
        "message": "Disbursement account rejected"
      }
    }
  }
}
```

***

## Exemplos por evento

Os exemplos abaixo são reproduzidos **na íntegra** do contrato de entrega.

* [ENDORSEMENT\_FAILED](#endorsement_failed)
* [ENDORSEMENT\_COMPLETED](#endorsement_completed)
* [ENDORSEMENT\_NEEDS\_VERIFICATION](#endorsement_needs_verification)
* [BALANCE\_QUERY\_NO\_BALANCE](#balance_query_no_balance)
* [CANCEL\_RESERVE\_COMPLETED](#cancel_reserve_completed)
* [BALANCE\_QUERY\_COMPLETED](#balance_query_completed)
* [BALANCE\_QUERY\_FAILED](#balance_query_failed)
* [MAINTAIN\_GUARANTEE\_COMPLETED](#maintain_guarantee_completed)
* [MAINTAIN\_GUARANTEE\_FAILED](#maintain_guarantee_failed)
* [MAINTAIN\_GUARANTEE\_NEEDS\_VERIFICATION](#maintain_guarantee_needs_verification)
* [CANCEL\_RESERVE\_UNDER\_REVIEW](#cancel_reserve_under_review)
* [CANCEL\_RESERVE\_FAILED](#cancel_reserve_failed)
* [CANCEL\_RESERVE\_NEEDS\_VERIFICATION](#cancel_reserve_needs_verification)
* [QUERY\_RESERVED\_VALUE\_COMPLETED](#query_reserved_value_completed)
* [QUERY\_RESERVED\_VALUE\_FAILED](#query_reserved_value_failed)
* [LIST\_PROTOCOLS\_COMPLETED](#list_protocols_completed)
* [LIST\_PROTOCOLS\_COMPLETED (lista vazia)](#list_protocols_completed-lista-vazia)
* [LIST\_PROTOCOLS\_FAILED](#list_protocols_failed)

### ENDORSEMENT\_FAILED

Averbação negada, com `error` (`OperationError`) e `originalErrors` — a Caixa foi chamada e retornou erro.

```json
{
  "source": "ENDORSEMENT",
  "eventType": "ENDORSEMENT_FAILED",
  "data": {
    "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "reserveIdentifier": "orig-123:res-1",
    "status": "FAILED",
    "source": "CAIXA_CALL",
    "error": {
      "code": "ENDORSEMENT_DENIED",
      "message": "Endorsement denied by Caixa",
      "originalErrors": [
        {
          "provider": "CAIXA",
          "code": "14",
          "description": "Averbacao negada — saldo insuficiente",
          "httpStatus": 422,
          "requestIdentifier": "orig-123:res-1",
          "occurredAt": "2026-06-15T10:00:03Z"
        }
      ]
    }
  }
}
```

***

### ENDORSEMENT\_COMPLETED

Averbação concluída, com `result` e os identificadores `reserveIdentifier`/`protocolNumber` presentes no nível superior do `data`.

```json
{
  "source": "ENDORSEMENT",
  "eventType": "ENDORSEMENT_COMPLETED",
  "data": {
    "requestId": "b2c3d479-4372-a567-58cc-f47ac10b0e02",
    "reserveIdentifier": "orig-123:res-1",
    "protocolNumber": "123456789",
    "status": "COMPLETED",
    "source": "CAIXA_CALL",
    "result": {
      "protocolNumber": "123456789",
      "protocolStatus": "ENDORSED",
      "detail": { "href": "/fgts/v1/protocolos/123456789", "rel": "self" }
    }
  }
}
```

***

### ENDORSEMENT\_NEEDS\_VERIFICATION

Averbação **expirada** (`status = EXPIRED`): a operação atingiu o tempo limite interno sem chegar a um desfecho, ainda na fila da Giro — não é tempo esgotado esperando resposta da Caixa. Não há `result`; o `error` traz apenas `code = EXPIRED_TTL`, que marca a expiração e **não** é veredito da Caixa. **Verifique** o status por polling em [`GET /api/v1/fgts/operations/{requestId}`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md) antes de assumir qualquer resultado.

```json
{
  "source": "ENDORSEMENT",
  "eventType": "ENDORSEMENT_NEEDS_VERIFICATION",
  "data": {
    "requestId": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
    "reserveIdentifier": "orig-123:res-2",
    "status": "EXPIRED",
    "source": "NA",
    "error": {
      "code": "EXPIRED_TTL"
    }
  }
}
```

***

### BALANCE\_QUERY\_NO\_BALANCE

Consulta de saldo concluída, porém **sem saldo FGTS** disponível. Repare em `result.hasBalance = false`.

```json
{
  "source": "BALANCE_QUERY",
  "eventType": "BALANCE_QUERY_NO_BALANCE",
  "data": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef0987654321",
    "status": "COMPLETED",
    "source": "CAIXA_CALL",
    "result": {
      "hasBalance": false
    }
  }
}
```

***

### CANCEL\_RESERVE\_COMPLETED

Cancelamento de reserva concluído. O `result` é um `ProtocolResult` (mesmo formato da averbação).

```json
{
  "source": "CANCEL_RESERVE",
  "eventType": "CANCEL_RESERVE_COMPLETED",
  "data": {
    "requestId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "contractNumber": "00005031",
    "reserveIdentifier": "orig-456:res-3",
    "protocolNumber": "555444333",
    "status": "COMPLETED",
    "source": "CAIXA_CALL",
    "result": {
      "protocolNumber": "555444333",
      "protocolStatus": "ENDORSED",
      "detail": { "href": "/fgts/v1/protocolos/555444333", "rel": "self" }
    }
  }
}
```

***

### BALANCE\_QUERY\_COMPLETED

Consulta de saldo concluída com saldo disponível — `result` é um `BalanceResult` com `periods[]`.

```json
{
  "source": "BALANCE_QUERY",
  "eventType": "BALANCE_QUERY_COMPLETED",
  "data": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef0987654321",
    "status": "COMPLETED",
    "source": "CAIXA_CALL",
    "result": {
      "workerCpf": "12345678901",
      "balanceDate": "2026-05-20",
      "hasDisregardedBalance": false,
      "activeRequestCount": 2,
      "periods": [
        { "transferDate": "2026-05-01", "amount": 1250.50 },
        { "transferDate": "2026-04-01", "amount": 980.00 }
      ]
    }
  }
}
```

***

### BALANCE\_QUERY\_FAILED

Falha na consulta de saldo — a Caixa foi chamada e retornou erro.

```json
{
  "source": "BALANCE_QUERY",
  "eventType": "BALANCE_QUERY_FAILED",
  "data": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef0987654323",
    "status": "FAILED",
    "source": "CAIXA_CALL",
    "error": {
      "code": "PROVIDER_ERROR",
      "message": "Balance query failed — Caixa returned error",
      "originalErrors": [
        { "provider": "CAIXA", "code": "99", "description": "Erro interno da Caixa", "httpStatus": 500, "occurredAt": "2026-06-15T10:00:03Z" }
      ]
    }
  }
}
```

***

### MAINTAIN\_GUARANTEE\_COMPLETED

Manutenção de garantia concluída — `result` é um `ProtocolResult`.

```json
{
  "source": "MAINTAIN_GUARANTEE",
  "eventType": "MAINTAIN_GUARANTEE_COMPLETED",
  "data": {
    "requestId": "e3f4a5b6-c7d8-9012-efab-234567890123",
    "reserveIdentifier": "orig-456:res-2",
    "protocolNumber": "987654321",
    "status": "COMPLETED",
    "source": "CAIXA_CALL",
    "result": {
      "protocolNumber": "987654321",
      "protocolStatus": "ENDORSED",
      "detail": { "href": "/fgts/v1/protocolos/987654321", "rel": "self" }
    }
  }
}
```

***

### MAINTAIN\_GUARANTEE\_FAILED

Falha na manutenção de garantia.

```json
{
  "source": "MAINTAIN_GUARANTEE",
  "eventType": "MAINTAIN_GUARANTEE_FAILED",
  "data": {
    "requestId": "e3f4a5b6-c7d8-9012-efab-234567890124",
    "reserveIdentifier": "orig-456:res-2",
    "status": "FAILED",
    "source": "CAIXA_CALL",
    "error": {
      "code": "MAINTENANCE_DENIED",
      "message": "Maintain guarantee denied by Caixa"
    }
  }
}
```

***

### MAINTAIN\_GUARANTEE\_NEEDS\_VERIFICATION

Manutenção de garantia **expirada** (`status = EXPIRED`) — sem `result`; o `error` traz apenas `code = EXPIRED_TTL`, que marca a expiração e **não** é veredito da Caixa. Verifique por polling.

```json
{
  "source": "MAINTAIN_GUARANTEE",
  "eventType": "MAINTAIN_GUARANTEE_NEEDS_VERIFICATION",
  "data": {
    "requestId": "e3f4a5b6-c7d8-9012-efab-234567890125",
    "reserveIdentifier": "orig-456:res-3",
    "status": "EXPIRED",
    "source": "NA",
    "error": {
      "code": "EXPIRED_TTL"
    }
  }
}
```

***

### CANCEL\_RESERVE\_UNDER\_REVIEW

Cancelamento de reserva aceito e em **revisão manual** da Giro (`data.status = UNDER_REVIEW`; no polling da operação esse estado aparece como `PENDING_MANUAL_APPROVAL`). Evento **intermediário**, sem `result` nem `error` — a operação ainda não foi à Caixa. **Sempre** seguido por um terminal (`CANCEL_RESERVE_COMPLETED` ou `CANCEL_RESERVE_FAILED`).

```json
{
  "source": "CANCEL_RESERVE",
  "eventType": "CANCEL_RESERVE_UNDER_REVIEW",
  "data": {
    "requestId": "c3d4e5f6-a7b8-9012-cdef-123456789011",
    "reserveIdentifier": "orig-456:res-3",
    "status": "UNDER_REVIEW",
    "source": "NA"
  }
}
```

***

### CANCEL\_RESERVE\_FAILED

Falha no cancelamento de reserva.

```json
{
  "source": "CANCEL_RESERVE",
  "eventType": "CANCEL_RESERVE_FAILED",
  "data": {
    "requestId": "c3d4e5f6-a7b8-9012-cdef-123456789013",
    "reserveIdentifier": "orig-456:res-3",
    "status": "FAILED",
    "source": "CAIXA_CALL",
    "error": {
      "code": "CANCELLATION_DENIED",
      "message": "Cancel reserve denied by Caixa"
    }
  }
}
```

Quando a falha é uma **rejeição na revisão manual** (antes do envio à Caixa), o `error.code` é `GUARANTEE_APPROVAL_REJECTED` e não há `originalErrors[]`. Se o contrato tinha a CCB no provedor bancário sem desembolso e a operação da Giro confirmou que ela já foi paga, o `error.code` é `CONTRACT_ALREADY_DISBURSED` (envie a desistência, `SEVEN_DAYS_REGRET`). O mesmo vale para a manutenção de garantia.

```json
{
  "source": "CANCEL_RESERVE",
  "eventType": "CANCEL_RESERVE_FAILED",
  "data": {
    "requestId": "c3d4e5f6-a7b8-9012-cdef-123456789011",
    "reserveIdentifier": "orig-456:res-3",
    "status": "FAILED",
    "source": "NA",
    "error": {
      "code": "GUARANTEE_APPROVAL_REJECTED",
      "message": "Operation rejected in manual approval"
    }
  }
}
```

***

### CANCEL\_RESERVE\_NEEDS\_VERIFICATION

Cancelamento de reserva **expirado** (`status = EXPIRED`) — sem `result`; o `error` traz apenas `code = EXPIRED_TTL`, que marca a expiração e **não** é veredito da Caixa. Verifique por polling.

```json
{
  "source": "CANCEL_RESERVE",
  "eventType": "CANCEL_RESERVE_NEEDS_VERIFICATION",
  "data": {
    "requestId": "c3d4e5f6-a7b8-9012-cdef-123456789014",
    "reserveIdentifier": "orig-456:res-4",
    "status": "EXPIRED",
    "source": "NA",
    "error": {
      "code": "EXPIRED_TTL"
    }
  }
}
```

***

### QUERY\_RESERVED\_VALUE\_COMPLETED

Consulta de valor reservado concluída — `result` é um `ReservedValueResult` com `periods[]` atualizados e `operationKind`.

```json
{
  "source": "QUERY_RESERVED_VALUE",
  "eventType": "QUERY_RESERVED_VALUE_COMPLETED",
  "data": {
    "requestId": "d4e5f6a7-b8c9-0123-defa-345678901234",
    "reserveIdentifier": "orig-123:res-1",
    "status": "COMPLETED",
    "source": "CAIXA_CALL",
    "result": {
      "reserveIdentifier": "orig-123:res-1",
      "workerCpf": "12345678901",
      "requestDateTime": "2026-05-25T10:30:00Z",
      "operationKind": "FIDUCIARY_ASSIGNMENT",
      "periods": [
        { "transferDate": "2026-05-01", "periodStatus": "GUARANTEED", "originalAmount": 1000.00, "updatedAmount": 950.00 }
      ]
    }
  }
}
```

***

### QUERY\_RESERVED\_VALUE\_FAILED

Falha na consulta de valor reservado.

```json
{
  "source": "QUERY_RESERVED_VALUE",
  "eventType": "QUERY_RESERVED_VALUE_FAILED",
  "data": {
    "requestId": "d4e5f6a7-b8c9-0123-defa-345678901235",
    "reserveIdentifier": "orig-123:res-1",
    "status": "FAILED",
    "source": "CAIXA_CALL",
    "error": {
      "code": "QUERY_RESERVED_VALUE_FAILED",
      "message": "Query reserved value failed — Caixa returned error"
    }
  }
}
```

***

### LIST\_PROTOCOLS\_COMPLETED

Listagem de protocolos por reserva — `result` é um `ProtocolListResult` com `protocols[]`.

```json
{
  "source": "LIST_PROTOCOLS_BY_ID",
  "eventType": "LIST_PROTOCOLS_COMPLETED",
  "data": {
    "requestId": "f5a6b7c8-d9e0-1234-efab-456789012345",
    "reserveIdentifier": "orig-789:res-1",
    "protocolNumber": 111222333,
    "status": "COMPLETED",
    "source": "CAIXA_CALL",
    "result": {
      "protocols": [
        { "protocolNumber": 111222333, "protocolStatus": "ENDORSED", "detail": { "href": "/fgts/v1/protocolos/111222333", "rel": "self" } }
      ]
    }
  }
}
```

***

### LIST\_PROTOCOLS\_COMPLETED (lista vazia)

Listagem concluída sem protocolos encontrados — `protocols` é uma lista vazia. Quando a Caixa responde "nenhum resultado" (código cru `30`), o desfecho é `LIST_PROTOCOLS_FAILED` com `error.code = PROVIDER_ERROR`: trate os dois casos como reserva sem protocolos.

```json
{
  "source": "LIST_PROTOCOLS_BY_ID",
  "eventType": "LIST_PROTOCOLS_COMPLETED",
  "data": {
    "requestId": "f5a6b7c8-d9e0-1234-efab-456789012346",
    "reserveIdentifier": "orig-789:res-2",
    "status": "COMPLETED",
    "source": "CAIXA_CALL",
    "result": { "protocols": [] }
  }
}
```

***

### LIST\_PROTOCOLS\_FAILED

Falha na listagem de protocolos.

```json
{
  "source": "LIST_PROTOCOLS_BY_ID",
  "eventType": "LIST_PROTOCOLS_FAILED",
  "data": {
    "requestId": "f5a6b7c8-d9e0-1234-efab-456789012347",
    "reserveIdentifier": "orig-789:res-3",
    "status": "FAILED",
    "source": "CAIXA_CALL",
    "error": {
      "code": "LIST_PROTOCOLS_FAILED",
      "message": "List protocols failed — Caixa returned error"
    }
  }
}
```

***

**Referência:** o desfecho de qualquer operação também pode ser consultado a qualquer momento por polling em [Consultar Status da Operação FGTS](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md). Para correlacionar e deduplicar notificações, ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/idempotencia.md). Para o fluxo assíncrono completo e os estados da operação, ver [Fluxo assíncrono e polling](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-assincrono-e-polling.md).
