> For the complete documentation index, see [llms.txt](https://docs.giro.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/idempotencia.md).

# Idempotência

A API GTFgts oferece idempotência em **dois pontos** do fluxo:

1. **Na submissão** de operações FGTS, via o header `Idempotency-Key` — reenviar a mesma chave com o mesmo corpo devolve o `requestId` existente, sem publicar a operação de novo. A mesma chave com corpo diferente é recusada com `422`.
2. **Na entrega de webhook**, via o par (`requestId`, `eventType`) — como a entrega é *at-least-once*, use esse par para deduplicar reentregas do mesmo evento.

***

## Idempotência na submissão (`Idempotency-Key`)

O originator envia o header `Idempotency-Key` com um valor único por operação. A API usa essa chave para identificar submissões duplicadas:

1. **Primeira requisição** com a chave: admitida normalmente e associada a um `requestId`.
2. **Requisição duplicada** com a mesma chave e o mesmo corpo: a API retorna o **mesmo `requestId`** — a operação não é reprocessada.
3. **Mesma chave com corpo diferente**: a API responde `422 IDEMPOTENCY_KEY_PAYLOAD_MISMATCH` e não enfileira nada. Ver [Mesma chave, corpo diferente](#payload-diferente).

```
Originador                              GTFgts API
    │                                       │
    │── POST /api/v1/fgts/endorsements ─────>│
    │   Idempotency-Key: abc-123            │
    │                                       │  (admite, gera requestId)
    │<───────── 202 { requestId } ──────────│
    │                                       │
    │── POST /api/v1/fgts/endorsements ─────>│  (mesma chave)
    │   Idempotency-Key: abc-123            │
    │                                       │  (detecta duplicata, não reprocessa)
    │<───────── 202 { requestId } ──────────│  (mesmo requestId)
```

### Header

| Header            | Tipo     | Obrigatório | Descrição                                                                                                                                                                                                               |
| ----------------- | -------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Idempotency-Key` | `string` | Não         | Chave única por operação. Máximo 100 caracteres (a [retentativa de averbação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/retentar-averbacao.md) aceita até 255). |

{% hint style="warning" %}
Chave com mais de 100 caracteres é recusada com `400 VALIDATION_ERROR`, com o detalhe em `errors.idempotencyKey`. UUIDs (36 caracteres) cabem com folga.
{% endhint %}

{% hint style="info" %}
O header é **opcional**. Se não for enviado, a requisição é admitida normalmente, sem controle de idempotência de negócio.
{% endhint %}

### Escopo

A chave tem escopo **por originator**. A mesma chave usada por originators diferentes é tratada como chaves distintas — uma chave de um originator nunca colide com a de outro.

### Endpoints suportados

A `Idempotency-Key` é aceita em **todas** as submissões de operação FGTS:

| Endpoint                                                     | Operação                                   |
| ------------------------------------------------------------ | ------------------------------------------ |
| `POST /api/v1/fgts/balance-queries`                          | Consulta de saldo                          |
| `POST /api/v1/fgts/batch/balance-queries`                    | Consulta de saldo em lote                  |
| `POST /api/v1/fgts/endorsements`                             | Averbação                                  |
| `POST /api/v1/fgts/guarantee-maintenances`                   | Manutenção de garantia                     |
| `POST /api/v1/fgts/reserve-cancellations`                    | Cancelamento de reserva                    |
| `POST /api/v1/fgts/reserve-value-queries`                    | Consulta de valor reservado                |
| `POST /api/v1/fgts/reserve-protocol-queries`                 | Consulta de protocolos por reserva         |
| `POST /api/v1/fgts/protocol-status-queries`                  | Consulta de status por protocolo           |
| `POST /api/v1/fgts/endorsements/{reserveIdentifier}/retries` | Retentativa de averbação por identificador |

Nas rotas de contrato a chave também é aceita, com a mesma regra de corpo: `POST .../contracts/{contractNumber}/reserve-cancellations`, `.../guarantee-maintenances`, `.../endorsement-retries` e `.../payment-approval`. Em `POST /api/v1/fgts/contracts` a chave é obrigatória e a divergência de corpo responde `409 CONTRACT_IDEMPOTENCY_CONFLICT` (ver [Submeter Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/submeter-contrato.md)).

### Mesma chave, corpo diferente (`422`) <a href="#payload-diferente" id="payload-diferente"></a>

A API guarda, junto da chave, uma impressão digital do corpo da requisição e dos identificadores da URL (`contractNumber`, `reserveIdentifier`). A impressão é um hash: o conteúdo da requisição, inclusive o CPF, não fica guardado em claro. Num reenvio com a mesma `Idempotency-Key`:

| Reenvio                                        | Resposta                                                                                                                               |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Mesmo corpo                                    | A resposta da primeira admissão (mesmo `requestId`), como sempre.                                                                      |
| Corpo diferente, ou outro identificador na URL | `422 Unprocessable Entity` com `errorCode = IDEMPOTENCY_KEY_PAYLOAD_MISMATCH`. Nada é enfileirado e a operação original não é afetada. |

A comparação é pelo conteúdo, não pelo texto: ordem dos campos, campo ausente versus `null` e zeros à direita em valores decimais (`1234.5` e `1234.50`) **não** contam como diferença.

```http
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros#business-rule-violation",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Idempotency-Key already used with a different payload. Send a new Idempotency-Key for a different request.",
  "instance": "/api/v1/fgts/balance-queries",
  "errorCode": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH",
  "timestamp": "2026-10-13T12:00:00Z"
}
```

O que fazer:

* **Era outra operação** (outro CPF, outro valor, outro contrato): gere uma chave nova.
* **Era a mesma operação**: reenvie exatamente o corpo original. Não altere o corpo para "corrigir" uma operação já admitida — acompanhe o `requestId` original.

{% hint style="info" %}
Quando a primeira requisição é **recusada** (`4xx`) ou **não chega a ser enfileirada** (`503 SUBMISSION_TEMPORARILY_UNAVAILABLE` nas submissões de operação FGTS), a chave é liberada e pode ser reusada com o corpo corrigido. Depois de um timeout, ou de `503` na retentativa de averbação e nas rotas de contrato, o desfecho da primeira chamada é desconhecido: reenvie **o mesmo corpo** com a mesma chave.
{% endhint %}

{% hint style="info" %}
Chaves admitidas antes desta verificação existir não têm impressão digital e continuam respondendo como antes, sem comparação de corpo, até expirarem. Na averbação **sem** `Idempotency-Key`, o reenvio continua deduplicado pelo `reserveIdentifier`, sem comparação de corpo.
{% endhint %}

### Boas práticas

1. **Use UUIDs como chave.** Qualquer string até 100 caracteres é aceita, mas UUIDs (v4) garantem unicidade sem coordenação.

```
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
```

2. **Gere a chave no lado do cliente** antes de enviar a requisição. Não reutilize chaves entre operações diferentes: a mesma chave com outro corpo é recusada com `422 IDEMPOTENCY_KEY_PAYLOAD_MISMATCH`.
3. **Implemente retry com a mesma chave e o mesmo corpo.** Em caso de timeout ou erro de rede, reenvie a operação com a mesma `Idempotency-Key` e o corpo idêntico: se ela já foi admitida, você receberá de volta o mesmo `requestId`, sem submeter em duplicidade.

### Exemplo

```http
POST /api/v1/fgts/endorsements HTTP/1.1
Host: ingress.gtfgts.staging.giro.tech
Authorization: Bearer {token}
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

{
  "cpf": "12345678901",
  "operationKind": "FIDUCIARY_ASSIGNMENT",
  "periods": [
    { "transferDate": "2030-09-01", "amount": 1234.56 }
  ]
}
```

Resposta (primeira admissão **e** reenvio com a mesma chave e o mesmo corpo):

```http
HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "QUEUED"
}
```

***

## Idempotência na entrega de webhook (`requestId`)

A entrega de webhook é **at-least-once** com retry e back-off exponencial — ou seja, o mesmo resultado **pode ser entregue mais de uma vez**. Para deduplicar reentregas no seu endpoint, use o par (`data.requestId`, `eventType`) como **chave de idempotência**: registre os pares já processados e ignore reentregas do mesmo par. O `requestId` sozinho não basta — a mesma operação emite mais de um evento (ex.: `CANCEL_RESERVE_UNDER_REVIEW` e depois `CANCEL_RESERVE_FAILED`).

{% hint style="info" %}
O `requestId` é o mesmo identificador retornado na admissão (`202`) e usado no polling. Ele correlaciona, de ponta a ponta, a **submissão**, o **status** e a **notificação de webhook**.
{% endhint %}

Detalhes da semântica de entrega (`2xx`/`4xx`/`5xx` e retry) em [Retry e Garantias de Entrega](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/retry-e-garantias.md).

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