> 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/fluxo-assincrono-e-polling.md).

# Fluxo Assíncrono e Polling

Toda operação FGTS da API GTFgts é **assíncrona**. O originator **submete** a operação, recebe imediatamente um `202 Accepted` com um `requestId`, e acompanha o desfecho por **webhook** (recomendado) ou por **polling** do status. A única exceção é a consulta de saldo, que **pode** responder `200` de forma síncrona quando há um valor recente aproveitável em cache — uma otimização oportunista e **não garantida** (ver [Resposta em cache da consulta de saldo](#fast-path)).

***

## O ciclo em três passos

| Etapa                         | Endpoint                                  | Resultado                                                                                                                     |
| ----------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **1. Submeter**               | `POST /api/v1/fgts/{operação}`            | `202 Accepted` com `requestId` e `status: QUEUED` (a consulta de saldo **pode** responder `200` quando há cache aproveitável) |
| **2a. Webhook** (recomendado) | entrega `POST` para a URL cadastrada      | `WebhookEnvelope` com `source`, `eventType` e `data`                                                                          |
| **2b. Polling** (fallback)    | `GET /api/v1/fgts/operations/{requestId}` | `status` atual e, em estado terminal, `result` ou `error`                                                                     |

```mermaid
sequenceDiagram
    participant O as Originator
    participant G as GTFgts API
    participant C as Caixa
    O->>G: POST /api/v1/fgts/endorsements { cpf, payload }
    G-->>O: 202 Accepted { requestId, status: QUEUED }
    G->>C: processa a operação (assíncrono)
    C-->>G: resultado (protocolo / saldo / erro)
    G-->>O: POST webhook { source, eventType, data }
    Note over O,G: alternativa/reconciliação: GET /api/v1/fgts/operations/{requestId}
    O->>G: GET /api/v1/fgts/operations/{requestId}
    G-->>O: 200 { status: COMPLETED, source, result }
```

{% hint style="info" %}
O `requestId` (UUID) é a **chave de correlação e de idempotência** de ponta a ponta: use-o para casar a notificação de webhook com a submissão e para deduplicar reentregas. Ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/idempotencia.md).
{% endhint %}

***

## Ciclo de vida do `status`

O polling (`GET /api/v1/fgts/operations/{requestId}`) retorna o `status` atual da operação, **sem filtrar nenhum estado**. A operação parte de `QUEUED` e caminha até um estado **terminal** (`COMPLETED`, `FAILED`, `FAILED_NEEDS_MANUAL` ou `EXPIRED`). Há ainda o estado terminal `CANCELLED`, alcançado quando a operação é cancelada via `DELETE /api/v1/fgts/operations/{requestId}` antes de começar a ser processada — ver [Cancelar operação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/gerenciar-operacoes/cancelar-operacao.md). O **cancelamento de reserva** (`CANCEL_RESERVE`) e a **manutenção de garantia** (`MAINTAIN_GUARANTEE`) podem passar por um estado intermediário, `PENDING_MANUAL_APPROVAL`: toda desaverbação entra nesse estado ao ser submetida e aguarda **aprovação manual da Giro** antes de seguir para a fila normal — ver [Cancelamento de reserva (Legado)](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/operacoes-fgts.md#cancelamento-de-reserva).

{% hint style="danger" %}
**Legado.** Os endpoints isolados de **averbação** (`POST /api/v1/fgts/endorsements`) e **cancelamento de reserva** (`POST /api/v1/fgts/reserve-cancellations`) não devem ser usados em novas integrações. Averbação e reversão de reserva ocorrem pelo fluxo de [**Contratos (Formalização)**](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos.md) — veja [Fluxo de formalização](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-formalizacao.md).
{% endhint %}

{% hint style="info" %}
O [encerramento de contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/encerramento.md) (`POST /api/v1/fgts/contracts/{contractNumber}/reserve-cancellations`) **é** acompanhado por este mesmo polling: o endpoint responde `200` desde o registro, com `status = PENDING_MANUAL_APPROVAL` enquanto a solicitação aguarda a autorização interna da Giro, e `COMPLETED` ou `FAILED` nos terminais.
{% endhint %}

```mermaid
stateDiagram-v2
    [*] --> QUEUED
    [*] --> PENDING_MANUAL_APPROVAL
    QUEUED --> DISPATCHING
    QUEUED --> CANCELLED
    PENDING_MANUAL_APPROVAL --> QUEUED
    PENDING_MANUAL_APPROVAL --> FAILED
    DISPATCHING --> IN_FLIGHT
    IN_FLIGHT --> COMPLETED
    IN_FLIGHT --> FAILED
    IN_FLIGHT --> EXPIRED
    IN_FLIGHT --> NEEDS_VERIFICATION
    IN_FLIGHT --> RETRYING
    IN_FLIGHT --> AWAITING_PROVIDER
    AWAITING_PROVIDER --> COMPLETED
    AWAITING_PROVIDER --> FAILED
    RETRYING --> DISPATCHING
    NEEDS_VERIFICATION --> COMPLETED
    NEEDS_VERIFICATION --> FAILED_NEEDS_MANUAL
    COMPLETED --> [*]
    FAILED --> [*]
    FAILED_NEEDS_MANUAL --> [*]
    EXPIRED --> [*]
    CANCELLED --> [*]
```

| `status`                  | Terminal? | Significado                                                                                                                                                                                                                                                                                                                                   |
| ------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PENDING_MANUAL_APPROVAL` | não       | **Cancelamento de reserva** (`CANCEL_RESERVE`) ou **manutenção de garantia** (`MAINTAIN_GUARANTEE`) admitido e retido aguardando **aprovação manual da Giro** antes de ser enviado à Caixa. Aprovado → segue para a fila (no intervalo, o polling mostra `DISPATCHING`); rejeitado → `FAILED` com `error.code = GUARANTEE_APPROVAL_REJECTED`. |
| `QUEUED`                  | não       | Operação admitida e enfileirada, aguardando processamento.                                                                                                                                                                                                                                                                                    |
| `DISPATCHING`             | não       | A plataforma está despachando a operação para a Caixa.                                                                                                                                                                                                                                                                                        |
| `IN_FLIGHT`               | não       | Operação em trânsito na Caixa, aguardando o desfecho.                                                                                                                                                                                                                                                                                         |
| `AWAITING_PROVIDER`       | não       | Averbação aceita pela Caixa e ainda em processamento do lado dela; a plataforma reconsulta periodicamente. Não reenvie.                                                                                                                                                                                                                       |
| `NEEDS_VERIFICATION`      | não       | O desfecho é incerto e a plataforma está confirmando junto à Caixa. O campo `error` já vem preenchido (`<OPERAÇÃO>_NEEDS_VERIFICATION`), mas **não** é desfecho.                                                                                                                                                                              |
| `RETRYING`                | não       | A operação está sendo reprocessada após uma falha transitória — ver [Retentativa automática](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#retrying).                                                                                                                                                                      |
| `COMPLETED`               | **sim**   | Operação concluída com sucesso. O campo `result` está presente.                                                                                                                                                                                                                                                                               |
| `FAILED`                  | **sim**   | Operação negada ou com erro. O campo `error` (`OperationError`) está presente.                                                                                                                                                                                                                                                                |
| `FAILED_NEEDS_MANUAL`     | **sim**   | Falhou e requer intervenção manual da operação. O campo `error` está presente.                                                                                                                                                                                                                                                                |
| `EXPIRED`                 | **sim**   | A operação expirou aguardando resposta da Caixa. O campo `error` está presente.                                                                                                                                                                                                                                                               |
| `CANCELLED`               | **sim**   | A operação foi cancelada via `DELETE /api/v1/fgts/operations/{requestId}` antes de começar a ser processada. O campo `cancelledAt` traz o instante do cancelamento.                                                                                                                                                                           |

{% hint style="info" %}
O campo `result` aparece **apenas** quando `status = COMPLETED`. O campo `error` aparece **apenas** quando `status` é `FAILED`, `FAILED_NEEDS_MANUAL` ou `EXPIRED`. O `error` é um `OperationError` (erro da operação Caixa), distinto dos erros de borda. Ver [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#operationerror).
{% endhint %}

### Recusas são consultáveis: `404` vs `FAILED` <a href="#recusas-consultaveis" id="recusas-consultaveis"></a>

Uma operação **recusada na admissão do processamento** — averbação duplicada, recusa no gate de cancelamento/manutenção (garantia inexistente, fora de estado elegível, aprovação já pendente, operação inválida) — **não responde mais `404` permanente** no polling: ela responde `200` com `status = FAILED` já na **primeira consulta**, com o **mesmo `error.code`** do evento `FAILED` entregue por webhook — polling e webhook não se contradizem.

O `404` do polling significa apenas **`requestId` inexistente ou ainda não registrado**. Não o trate como "ainda processando" nem como sinal de recusa — **programe pelo `error.code`**.

Para os códigos de duplicidade — `ENDORSEMENT_ALREADY_SUBMITTED`, `GUARANTEE_OPERATION_DUPLICATE` e `GUARANTEE_APPROVAL_ALREADY_PENDING` — o `error` traz também **`originalRequestId`**: o `requestId` da operação original em andamento (ou concluída). Consulte-o para acompanhar o desfecho real. Ver [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#originalrequestid).

### Exemplo de resposta de polling

```json
{
  "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "QUEUED",
  "source": "NA",
  "estimatedWaitSeconds": 18
}
```

Quando concluída com sucesso:

```json
{
  "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "COMPLETED",
  "source": "CAIXA_CALL",
  "result": {
    "protocolNumber": "123456789",
    "protocolStatus": "ENDORSED",
    "detail": { "href": "/fgts/v1/protocolos/123456789", "rel": "self" }
  }
}
```

O campo `estimatedWaitSeconds` é uma estimativa **best-effort** e **não é garantia de prazo**; é `null` em estados terminais ou quando indisponível. O formato do `result` varia por operação — ver [Operações FGTS](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/operacoes-fgts.md).

Quando a operação tem reserva associada (`ENDORSEMENT`, `CANCEL_RESERVE`, `MAINTAIN_GUARANTEE`) e o identificador é conhecido, a resposta traz também **`reserveIdentifier`** no nível superior — o mesmo identificador entregue nos eventos de webhook, nos dois canais. Ver [Consultar Status da Operação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md).

***

## Webhook é o caminho preferido; polling é fallback

Sempre que possível, **prefira receber o resultado por webhook**: a Giro.Tech envia um `POST` para a URL cadastrada assim que a operação conclui, sem que você precise consultar repetidamente. O polling deve ser usado como **fallback** (quando o webhook não chegou) ou para **reconciliação** (auditar o estado de uma operação específica).

Quando usar polling, siga estas orientações:

1. **Consulte até um estado terminal.** Pare ao receber `COMPLETED`, `FAILED`, `FAILED_NEEDS_MANUAL` ou `EXPIRED`. Estados não-terminais (`PENDING_MANUAL_APPROVAL`, `QUEUED`, `DISPATCHING`, `IN_FLIGHT`, `AWAITING_PROVIDER`, `NEEDS_VERIFICATION`, `RETRYING`) indicam que a operação ainda está em andamento.
2. **Respeite o `Retry-After` em `503`.** Se o serviço estiver temporariamente indisponível, o polling responde `503` com o header `Retry-After` (segundos). Aguarde esse intervalo antes de tentar novamente. Ver [Serviço indisponível](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#upstream-unavailable).
3. **Use intervalos espaçados.** Evite polling agressivo; o `estimatedWaitSeconds`, quando presente, é uma boa referência para o intervalo da próxima consulta.
4. **Não programe timeout curto para averbação.** Erro transitório da Caixa é retentado automaticamente **a cada 15 minutos por até 72 horas** antes de virar `FAILED`. Uma averbação legitimamente em andamento pode passar dias em estado não-terminal, sem gerar evento nenhum. Desistir antes disso descarta operação viva — e, se você resubmeter por conta própria, esbarra na recusa por `reserveIdentifier` duplicado. Ver [Retentativa de averbação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/retentar-averbacao.md#antes-de-retentar). Enquanto a janela está aberta, `status` é `RETRYING` e o bloco `retry` diz em que tentativa está, quando é a próxima e **por que** está esperando — em `retry.lastProviderError`. É ali que se vê se a espera depende de uma ação do trabalhador (código `7`: autorizar no app do FGTS) ou é só instabilidade da Caixa. Ver [Consultar Status](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md#campo-retry-retryprogress).

{% hint style="warning" %}
Cada `requestId` pertence ao originator que o submeteu. Consultar um `requestId` de outro originator retorna `403 ORIGINATOR_OWNERSHIP_VIOLATION`.
{% endhint %}

***

## Status da operação vs. status do protocolo <a href="#protocolo-vs-operacao" id="protocolo-vs-operacao"></a>

A API oferece **duas formas de consultar status diferentes**, para situações diferentes. Ambas são **assíncronas** e o resultado é acompanhado pelo mesmo polling por `requestId` (ou por webhook) — o que muda é **como você identifica** o que quer consultar. Não as confunda:

|                           | Status da operação                                                             | Status por protocolo                                                                                                            |
| ------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| **Como acionar**          | Você **já tem** o `requestId` da sua submissão                                 | Você **submete** `POST /api/v1/fgts/protocol-status-queries` (informando o número do protocolo) e recebe um `requestId`         |
| **Acompanhamento**        | `GET /api/v1/fgts/operations/{requestId}` ou webhook                           | `GET /api/v1/fgts/operations/{requestId}` ou webhook (do `requestId` retornado pela submissão)                                  |
| **Você parte de**         | `requestId` (o que veio no `202` da sua submissão original)                    | número do **protocolo** (emitido pela Caixa)                                                                                    |
| **Quando usar**           | Acompanhar uma operação que **você** submeteu, do enfileiramento ao desfecho   | Consultar a situação atual de um protocolo que você já tem em mãos (sem o `requestId` original)                                 |
| **O que o `result` traz** | O `result` da operação submetida (saldo, protocolo, etc.), conforme a operação | O `protocolStatus` atual do protocolo (`ENDORSED`, `PROCESSING`, `REJECTED`, `NOT_FOUND`, `RATE_LIMITED`) e os dados de detalhe |

**O caminho normal é o status da operação.** Ao submeter uma averbação (ou manutenção de garantia), acompanhe pelo `requestId`; quando o `status` chega a `COMPLETED`, o `result` já traz o número do **protocolo** da Caixa. A consulta de status por protocolo é útil **depois**, quando você tem apenas o número do protocolo (sem o `requestId` original) e quer saber a situação atual dele — você a **submete** como qualquer outra operação e acompanha o desfecho pelo novo `requestId`.

{% hint style="info" %}
Como no polling por `requestId`, a consulta de status por protocolo é restrita ao **dono**: apenas o originator que originou o protocolo pode consultá-lo (caso contrário, a submissão é rejeitada com `403`).
{% endhint %}

Referência: [Consultar Status por Protocolo](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/consultar-status-protocolo.md).

***

## Resposta em cache da consulta de saldo <a href="#fast-path" id="fast-path"></a>

A consulta de saldo (`POST /api/v1/fgts/balance-queries`) é a **única exceção** ao modelo assíncrono:

* **Quando já há um valor recente aproveitável** → **pode** responder `200 OK` síncrono, com `status: COMPLETED`, `source: CAIXA_CALL` e o `result` com o saldo já disponível. **Não é necessário polling.**
* **Caso contrário** → responde `202 Accepted` com `status: QUEUED`, seguindo o fluxo assíncrono normal.

> O `200` síncrono é uma **otimização oportunista e não garantida**: a mesma consulta pode retornar `202` mesmo havendo saldo recente. Trate sempre o `202` (assíncrono) como o caminho padrão e o `200` como atalho quando disponível.

```json
{
  "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "COMPLETED",
  "source": "CAIXA_CALL",
  "result": {
    "workerCpf": "12345678901",
    "balanceDate": "2026-05-20",
    "hasDisregardedBalance": false,
    "activeRequestCount": 2,
    "periods": [
      { "transferDate": "2026-05-01", "amount": 1250.50 }
    ]
  }
}
```

Detalhes da consulta de saldo em [Operações FGTS](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/operacoes-fgts.md).

***

## Próximos passos

* [Operações FGTS](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/operacoes-fgts.md) — o catálogo de operações e os formatos de `result`.
* [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md) — a estrutura do `WebhookEnvelope` entregue ao seu endpoint.
* [Prioridades e rate limit](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/prioridades-e-rate-limit.md) — como `NORMAL`/`DEFERRED` e o `429` afetam a admissão.

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