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

# Operações FGTS

As operações FGTS são **submetidas de forma assíncrona** à API, que admite a requisição, encaminha para processamento em background e responde imediatamente com um `requestId`. O resultado chega depois, via [webhook cadastrado](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md) ou por [polling de status](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md).

## Modelo assíncrono

```
Submeter operação → 202 { requestId, status: QUEUED } → (processamento) → webhook OU polling
```

As operações de escrita e as consultas (saldo individual, valor reservado, protocolos por reserva e status por protocolo) são admitidas com prioridade `NORMAL`; a consulta de saldo em lote usa prioridade `DEFERRED` (menor prioridade, indicada para grandes volumes). A consulta de saldo individual pode ter **resposta síncrona quando há valor recente em cache**: em cache HIT, o saldo retorna inline (`200`) sem necessidade de polling, e o webhook é enviado também, com o mesmo `requestId`.

Detalhes de comportamento estão nos guias:

* [Fluxo assíncrono e polling](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-assincrono-e-polling.md)
* [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/idempotencia.md)
* [Prioridades e rate limit](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/prioridades-e-rate-limit.md)

## Operações disponíveis

As operações se organizam em três grupos:

### [Submeter operações](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes.md)

| Operação                                                                                                                                                                      | Método e Path                                                | Descrição                                                                                                                                                                  |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Consultar Saldo](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-consulta-saldo.md)                               | `POST /api/v1/fgts/balance-queries`                          | Consulta de saldo/margem FGTS (prioridade `NORMAL`, com resposta em cache quando há valor recente)                                                                         |
| [Consultar 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`                    | Consulta de saldo/margem FGTS em lote (prioridade `DEFERRED`)                                                                                                              |
| [Averbação (Legado)](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-averbacao.md)                                 | `POST /api/v1/fgts/endorsements`                             | Averbação FGTS isolada (prioridade `NORMAL`); substituída pelo fluxo de Contratos                                                                                          |
| [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` | Nova tentativa de averbação para uma reserva recusada, reusando o mesmo `reserveIdentifier`. Teto de 3 retentativas; recusa por teto volta **na própria resposta** (`409`) |
| [Cancelamento de Reserva (Legado)](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-cancelamento-reserva.md)        | `POST /api/v1/fgts/reserve-cancellations`                    | Cancelamento de reserva FGTS isolado (prioridade `NORMAL`); substituído pelo fluxo de Contratos                                                                            |
| [Consultar 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`                    | Consulta de valor reservado FGTS (prioridade `NORMAL`)                                                                                                                     |
| [Consultar 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 de protocolos por ID de reserva (prioridade `NORMAL`)                                                                                                             |
| [Consultar Status por Protocolo](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/consultar-status-protocolo.md)             | `POST /api/v1/fgts/protocol-status-queries`                  | Consulta assíncrona do status atual de um protocolo junto à Caixa (prioridade `NORMAL`)                                                                                    |

### [Acompanhar resultado](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado.md)

| Operação                                                                                                                                                         | Método e Path                             | Descrição                                                     |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------- |
| [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}` | Polling do status e resultado de uma operação por `requestId` |

### [Gerenciar operações](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/gerenciar-operacoes.md)

| Operação                                                                                                                                                    | Método e Path                                | Descrição                                                                                       |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| [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}` | Cancela uma operação por `requestId` enquanto ela ainda não começou a ser processada (síncrono) |

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