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

# Operações FGTS

A API GTFgts expõe **7 operações FGTS**, cada uma em um endpoint dedicado sob `/api/v1/fgts/`. Todas compartilham o mesmo contrato de entrada e de admissão:

* **Corpo:** campos **flat** no JSON raiz — `cpf` (obrigatório em todas) mais os campos específicos de cada operação. A consulta de saldo usa apenas `{ cpf }`.
* **Header opcional:** `Idempotency-Key` (máx. 100; retentativa de averbação: 255). Ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/idempotencia.md).
* **Retorno:** `202 Accepted` com `{ requestId, status: QUEUED }`. A consulta de saldo pode retornar `200` quando há valor recente em cache.

O desfecho chega por **webhook** ou por **polling** (`GET /api/v1/fgts/operations/{requestId}`). Ver [Fluxo assíncrono e polling](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-assincrono-e-polling.md).

{% hint style="danger" %}
**Averbação** e **cancelamento de reserva** isolados (`POST /api/v1/fgts/endorsements`, `POST /api/v1/fgts/reserve-cancellations`) são **legado**. Novas integrações devem usar o fluxo de [**Contratos (Formalização)**](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos.md) — a averbação e o cancelamento/reversão ocorrem automaticamente após [Submeter Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/submeter-contrato.md). Ver [Fluxo de formalização](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-formalizacao.md).
{% endhint %}

{% hint style="info" %}
Cada operação expõe os campos da Caixa diretamente no corpo (sem wrapper `payload`). O campo comum a todas é o `cpf`.
{% endhint %}

***

## Catálogo de operações

| Operação                               | Endpoint                                     | Prioridade                            | `result` no `COMPLETED`                                         |
| -------------------------------------- | -------------------------------------------- | ------------------------------------- | --------------------------------------------------------------- |
| **Consulta de saldo FGTS**             | `POST /api/v1/fgts/balance-queries`          | `NORMAL` (resposta em cache)          | `BalanceResult` (saldo com `periods[]`) ou `BalanceNoResult`    |
| **Consulta de saldo em lote**          | `POST /api/v1/fgts/batch/balance-queries`    | `DEFERRED`                            | Objeto livre com o saldo (mesmo formato da consulta individual) |
| **Averbação (Legado)**                 | `POST /api/v1/fgts/endorsements`             | `NORMAL`                              | `ProtocolResult` da Caixa                                       |
| **Manutenção de garantia**             | `POST /api/v1/fgts/guarantee-maintenances`   | `NORMAL`                              | `ProtocolResult` da Caixa                                       |
| **Cancelamento de reserva (Legado)**   | `POST /api/v1/fgts/reserve-cancellations`    | `NORMAL` (com gate de revisão manual) | `ProtocolResult` da Caixa                                       |
| **Consulta de valor reservado**        | `POST /api/v1/fgts/reserve-value-queries`    | `NORMAL`                              | `ReservedValueResult` (períodos da reserva)                     |
| **Consulta de protocolos por reserva** | `POST /api/v1/fgts/reserve-protocol-queries` | `NORMAL`                              | `ProtocolListResult` (lista de protocolos)                      |
| **Consulta de status por protocolo**   | `POST /api/v1/fgts/protocol-status-queries`  | `NORMAL`                              | Status atual do protocolo (`protocolStatus` + dados de detalhe) |

{% hint style="info" %}
O **encerramento de contrato vigente** (desistência / quitação antecipada) **não** é operação FGTS-Caixa — está em [Encerramento de contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/encerramento.md). O **cancelamento durante formalização** está em [Cancelar Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md).
{% endhint %}

***

## Consulta de saldo FGTS

**O que faz:** consulta o saldo/margem FGTS de um trabalhador. É a única operação com **resposta em cache** — havendo valor recente em cache para o CPF, pode responder `200` síncrono com o saldo inline; caso contrário, responde `202` e segue o fluxo assíncrono.

* **Endpoint:** `POST /api/v1/fgts/balance-queries`
* **Prioridade:** `NORMAL`
* **Corpo:** `cpf` (obrigatório).
* **`result` (COMPLETED):** `BalanceResult` (saldo com `periods[]`) ou `BalanceNoResult`.

```json
{
  "workerCpf": "12345678901",
  "balanceDate": "2026-05-20",
  "hasDisregardedBalance": false,
  "activeRequestCount": 2,
  "periods": [
    { "transferDate": "2026-05-01", "amount": 1250.50 }
  ]
}
```

Referência: [Submeter consulta de saldo](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-consulta-saldo.md).

***

## Consulta de saldo em lote

**O que faz:** mesma consulta de saldo, porém com prioridade `DEFERRED`. A própria rota `/batch/` é o sinal de prioridade (o cliente não envia um campo de prioridade). Indicada para processamento fora do tempo real (ex.: sincronização noturna de saldos), sem competir com o tráfego em tempo real.

* **Endpoint:** `POST /api/v1/fgts/batch/balance-queries`
* **Prioridade:** `DEFERRED`
* **Corpo:** mesmo da consulta de saldo individual.
* **`result` (COMPLETED):** mesmo formato (`BalanceResult`).

Referência: [Submeter consulta de saldo em lote](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-consulta-saldo-lote.md). Ver também [Prioridades e rate limit](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/prioridades-e-rate-limit.md).

***

## Averbação (Legado) <a href="#averbacao-legado" id="averbacao-legado"></a>

{% hint style="danger" %}
**Legado.** Use o fluxo de [**Contratos (Formalização)**](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos.md) em novas integrações — veja [Submeter Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/submeter-contrato.md) e [Fluxo de formalização](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-formalizacao.md).
{% endhint %}

**O que faz:** averba a operação FGTS junto à Caixa. Quando concluída, a Caixa gera um **protocolo** como comprovante.

* **Endpoint:** `POST /api/v1/fgts/endorsements`
* **Prioridade:** `NORMAL`
* **`result` (COMPLETED):** `ProtocolResult`.

```json
{
  "protocolNumber": "123456789",
  "protocolStatus": "ENDORSED",
  "detail": { "href": "/fgts/v1/protocolos/123456789", "rel": "self" }
}
```

O `protocolStatus` reflete o status do protocolo: `ENDORSED` (averbado), `PROCESSING` (em processamento), `REJECTED` (rejeitado), `NOT_FOUND` (não encontrado), `RATE_LIMITED` (limitado por rate limit). O mesmo status pode ser consultado depois em [Consultar Status por Protocolo](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/consultar-status-protocolo.md).

**Averbação recusada?** Peça uma nova tentativa em `POST /api/v1/fgts/endorsements/{reserveIdentifier}/retries`, reusando o **mesmo** `reserveIdentifier` — não nasce reserva nova. São **3 retentativas** por reserva (4 tentativas no total), e o teto atingido volta na própria resposta como `409 ENDORSEMENT_RETRY_LIMIT_EXCEEDED`. Referência: [Retentativa de Averbação por identificador](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/retentar-averbacao.md).

Referência: [Submeter averbação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-averbacao.md).

***

## Manutenção de garantia

**O que faz:** realiza a amortização parcial ou a quitação total de uma garantia FGTS junto à Caixa. Quando concluída, a Caixa gera um **protocolo** como comprovante.

* **Endpoint:** `POST /api/v1/fgts/guarantee-maintenances`
* **Prioridade:** `NORMAL`
* **Corpo:** `cpf` (obrigatório), `reserveIdentifier` (obrigatório), `operationKind` (obrigatório: `AMORTIZATION` para amortização parcial ou `SETTLEMENT` para quitação total), `periods[]` com `transferDate` (`yyyy-MM-dd`) e `amount`.
* **`result` (COMPLETED):** `ProtocolResult`.

```json
{
  "protocolNumber": "987654321",
  "protocolStatus": "ENDORSED",
  "detail": { "href": "/fgts/v1/protocolos/987654321", "rel": "self" }
}
```

Referência: [Submeter manutenção de garantia](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-manutencao-garantia.md).

***

## Cancelamento de reserva (Legado) <a href="#cancelamento-de-reserva" id="cancelamento-de-reserva"></a>

{% hint style="danger" %}
**Legado.** Use [Cancelar Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md) no fluxo de [**Contratos (Formalização)**](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos.md) em novas integrações — veja [Fluxo de formalização](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-formalizacao.md).
{% endhint %}

**O que faz:** cancela uma reserva FGTS. Quando concluído, a Caixa gera um `ProtocolResult` como comprovante do cancelamento.

* **Endpoint:** `POST /api/v1/fgts/reserve-cancellations`
* **Prioridade:** `NORMAL`
* **`result` (COMPLETED):** `ProtocolResult` (mesmo formato da averbação).

{% hint style="info" %}
Todo cancelamento de reserva passa por um **gate de revisão manual da Giro** antes do envio à Caixa. Ao ser submetido, entra no estado intermediário `PENDING_MANUAL_APPROVAL` e emite o evento `CANCEL_RESERVE_UNDER_REVIEW`; aprovado, segue para a fila normal (`QUEUED`); rejeitado, é encerrado com `CANCEL_RESERVE_FAILED` (`error.code = GUARANTEE_APPROVAL_REJECTED`; no polling, `status = FAILED`). O corpo aceita ainda `cancellationType` (obrigatório) e `reason` (opcional) — ver [Submeter cancelamento de reserva](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-cancelamento-reserva.md).
{% endhint %}

Referência: [Submeter cancelamento de reserva](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-cancelamento-reserva.md).

***

## Consulta de valor reservado

**O que faz:** consulta o valor reservado de uma reserva FGTS. O `result` traz uma `ReservedValueResult` com os períodos da reserva e seus valores original/atualizado.

* **Endpoint:** `POST /api/v1/fgts/reserve-value-queries`
* **Prioridade:** `NORMAL`
* **`result` (COMPLETED):** `ReservedValueResult`.

```json
{
  "reserveIdentifier": "RES-20240901-001",
  "periods": [
    {
      "periodStatus": "GUARANTEED",
      "transferDate": "2024-09-01",
      "originalAmount": 1500,
      "updatedAmount": 1234.56
    }
  ]
}
```

Referência: [Submeter consulta de valor reservado](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-consulta-valor-reservado.md).

***

## Consulta de protocolos por reserva

**O que faz:** lista todos os protocolos associados a uma reserva FGTS. O `result` traz uma `ProtocolListResult`.

* **Endpoint:** `POST /api/v1/fgts/reserve-protocol-queries`
* **Prioridade:** `NORMAL`
* **`result` (COMPLETED):** `ProtocolListResult`.

```json
{
  "protocols": [
    { "protocolNumber": 123456789, "protocolStatus": "ENDORSED" },
    { "protocolNumber": 987654321, "protocolStatus": "PROCESSING" }
  ]
}
```

Referência: [Submeter consulta de protocolos por reserva](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-consulta-protocolos-reserva.md).

***

## Encerramento de contrato

Desistência ou quitação antecipada de **contrato já vigente** não é operação FGTS-Caixa — documentação em [Encerramento de contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/encerramento.md). Cancelamento **durante formalização** em [Cancelar Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md).

***

## Acompanhamento do desfecho

Para todas as operações, o status e o `result`/`error` são consultados em [`GET /api/v1/fgts/operations/{requestId}`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md) ou recebidos por [webhook](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md). Quando uma operação falha, o `result` é substituído por um `error` (`OperationError`) — ver [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#operationerror).

## Consulta de status por protocolo

Quando uma averbação ou manutenção de garantia conclui, o `result` traz o número do **protocolo** da Caixa. Se mais tarde você tiver apenas esse número (e não o `requestId`), submeta uma consulta de status do protocolo em [`POST /api/v1/fgts/protocol-status-queries`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/consultar-status-protocolo.md). Como as demais operações, é **assíncrona** (`202` com `requestId`, prioridade `NORMAL`): o resultado chega por webhook ou polling e traz o `protocolStatus` atual (`ENDORSED`, `PROCESSING`, `REJECTED`, `NOT_FOUND`, `RATE_LIMITED`) e os dados de detalhe.

É uma consulta **pontual por número de protocolo**, distinta do acompanhamento da operação que **você** submeteu por `requestId`. Quando usar cada uma está em [Status da operação vs. status do protocolo](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-assincrono-e-polling.md#protocolo-vs-operacao).

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