> 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/submeter-operacoes/submeter-consulta-saldo.md).

# Consultar Saldo

Admite uma consulta de saldo/margem FGTS com prioridade `NORMAL`. **Pode** ter resposta síncrona: quando há um valor recente aproveitável em cache, o saldo retorna inline (`200`) e o webhook é enviado também, com o mesmo `requestId`; caso contrário, a operação é enfileirada para processamento assíncrono (`202`) e o resultado chega via webhook ou polling. O `200` síncrono é uma otimização oportunista e **não garantida** — trate o `202` como o caminho padrão.

{% hint style="info" %}
Esta operação é **assíncrona** sempre que responde `202`: a resposta confirma apenas a admissão, e o saldo chega depois via [webhook](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md) ou por [polling](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md) do `requestId`. O `200` síncrono (saldo inline) é uma otimização oportunista e **não garantida** — pode vir `202` mesmo havendo saldo recente. O webhook é enviado nos dois casos.
{% endhint %}

## Request

`POST /api/v1/fgts/balance-queries`

Autenticado: `Authorization: Bearer {originatorToken}`.

### Parâmetros

| Parâmetro         | Local  | Tipo               | Obrigatório | Descrição                                                                                                                                                                                                                      |
| ----------------- | ------ | ------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Idempotency-Key` | header | `string` (max 100) | Não         | Chave de idempotência de negócio (escopo por originator). Reenviar a mesma chave retorna o `requestId` existente sem reprocessar. Ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/idempotencia.md). |

### Corpo

| Campo | Tipo                              | Obrigatório | Descrição                                               |
| ----- | --------------------------------- | ----------- | ------------------------------------------------------- |
| `cpf` | `string` (11 dígitos, `^\d{11}$`) | Sim         | CPF do trabalhador, 11 dígitos numéricos sem pontuação. |

## Response

| Campo       | Tipo            | Descrição                                                                                                                 |
| ----------- | --------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `requestId` | `string` (uuid) | Identificador único da requisição admitida, gerado pela API. Use no polling em `GET /api/v1/fgts/operations/{requestId}`. |
| `status`    | `string`        | `QUEUED` (enfileirada, resposta `202`) ou `COMPLETED` (resultado inline em cache HIT, resposta `200`).                    |
| `source`    | `string`        | Origem do resultado — presente apenas no `200`. Valor: `CAIXA_CALL`.                                                      |
| `result`    | `object`        | Saldo disponível inline — presente apenas no `200` (cache HIT). Nulo no `202`.                                            |

* **200 OK** — cache aproveitável: saldo disponível inline em `result`. A consulta também é enfileirada com o mesmo `requestId`: o webhook é enviado e o polling desse `requestId` funciona. Oportunista e **não garantido**.
* **202 Accepted** — sem cache aproveitável: operação enfileirada para processamento assíncrono. Sob alta demanda, pode ser admitida com prioridade `DEFERRED`.

## Exemplo

### Cache MISS — `202 Accepted`

```http
POST /api/v1/fgts/balance-queries HTTP/1.1
Host: ingress.gtfgts.staging.giro.tech
Authorization: Bearer {originatorToken}
Content-Type: application/json
Idempotency-Key: 7c1e6a90-balance-001

{
  "cpf": "12345678901"
}
```

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

### Cache HIT — `200 OK`

```http
POST /api/v1/fgts/balance-queries HTTP/1.1
Host: ingress.gtfgts.staging.giro.tech
Authorization: Bearer {originatorToken}
Content-Type: application/json

{
  "cpf": "12345678901"
}
```

```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 }
    ]
  }
}
```

## Próximo passo

No cache MISS (`202`), acompanhe o resultado em [Consultar status da operação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md) usando o `requestId` retornado, ou aguarde o callback no webhook cadastrado.

No cache HIT (`200`), o saldo já está em `result` e o webhook chega também, com o mesmo `requestId` — trate a entrega de forma idempotente pelo `requestId`.

## Erros

| Código | Situação                                                                                                                                                                                                                                                                                                                                                                      |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | Validação de payload (campo obrigatório ausente, CPF fora do padrão `^\d{11}$`, etc.) — `errorCode = VALIDATION_ERROR`                                                                                                                                                                                                                                                        |
| 401    | Token ausente, inválido ou expirado — `errorCode = UNAUTHORIZED`                                                                                                                                                                                                                                                                                                              |
| 422    | `Idempotency-Key` já usada nesta rota com outro corpo — `errorCode = IDEMPOTENCY_KEY_PAYLOAD_MISMATCH`. Nada é enfileirado; para uma operação nova, use uma chave nova. Ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/idempotencia.md#payload-diferente)                                                                                         |
| 429    | Hard ceiling de rate limit de ingresso excedido — `errorCode = INGRESS_RATE_LIMIT_EXCEEDED` (header `Retry-After: 1`, sem `X-RateLimit-*`). Ver [Prioridades e rate limit](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/prioridades-e-rate-limit.md)                                                                                                               |
| 503    | Caixa em manutenção programada — `errorCode = CAIXA_MAINTENANCE_WINDOW`, com `maintenanceEndsAt` e header `Retry-After`. A consulta **não** foi enfileirada e a `Idempotency-Key` **não** foi consumida. A rota de lote continua sendo aceita. Ver [Janela de manutenção da Caixa](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#caixa-maintenance-window) |
| 503    | Indisponibilidade momentânea; nada foi registrado — `errorCode = SUBMISSION_TEMPORARILY_UNAVAILABLE` (header `Retry-After: 5`). Repita com o mesmo corpo e a mesma `Idempotency-Key`                                                                                                                                                                                          |
| 500    | Erro interno inesperado — `errorCode = INTERNAL_ERROR`                                                                                                                                                                                                                                                                                                                        |

Os erros seguem o formato `ProblemDetail` (RFC 7807), com o campo `errorCode`. Ver [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md).

Esses são os erros da **requisição**. O desfecho da operação chega depois, no `error.code` do polling e do webhook — ver [`error.code` de operação](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#catalogo-operacao) e [Códigos da Caixa](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#catalogo-caixa). Na consulta de saldo, os desfechos de falha são `CPF_NOT_OPERABLE` (códigos crus `5`, `7`, `8`, `9`, `11`, `13`, `18` e `35`), `OPERATION_NOT_YET_ALLOWED`, `PROVIDER_UNAVAILABLE` (códigos `3`, `524` e `525`), `TRANSIENT_PROVIDER_EDGE_UNAVAILABLE` e `PROVIDER_ERROR`.

## Submete consulta de saldo FGTS

> Admite uma consulta de saldo/margem FGTS com prioridade \`NORMAL\`.\
> \*\*Resposta dual:\*\*\
> \- \*\*Saldo disponível em cache\*\* (\`200\`): quando há valor recente para o CPF consultado,\
> &#x20; o saldo retorna inline com \`source: CAIXA\_CALL\`. Otimização oportunista — \*\*não garantida\*\*.\
> &#x20; O webhook é enviado também, com o mesmo \`requestId\`.\
> \- \*\*Saldo indisponível\*\* (\`202\`): operação enfileirada para processamento assíncrono;\
> &#x20; acompanhe via polling (\`GET /api/v1/fgts/operations/{requestId}\`) ou webhook.\
> \
> O webhook é enviado nos dois casos. Quando o saldo não está disponível inline, o originator não o recebe na mesma chamada.\
> \*\*Rate limiting:\*\* - Em volume normal: \`202\` com prioridade \`NORMAL\`. - Sob alto volume, a requisição pode ser admitida com prioridade reduzida \`DEFERRED\`\
> &#x20; (\`202\`) ou rejeitada com \`429 Retry-After\`.\
> \
> O header \`Idempotency-Key\` permite deduplicação de negócio: reenviar a mesma chave retorna o \`requestId\` existente sem reprocessar.\
> \*\*Deduplicação por CPF:\*\* enquanto uma consulta para o mesmo CPF e originator ainda está em andamento, uma nova chamada recebe \`202\` com o \`requestId\` daquela consulta, em vez de criar outra. Vale também para chamadas que trazem \`Idempotency-Key\` própria. A cota de rate limit é consumida normalmente. A janela é curta (90 s), de modo que reconsultar o mesmo CPF alguns minutos depois continua produzindo uma consulta nova — é assim que a autorização do trabalhador, quando pendente, é capturada.\
> Duas exceções: \`forceRefresh: true\` (quando o originator tem a capacidade habilitada) nunca é deduplicado, e a rota de lote tem janela própria — uma consulta interativa jamais recebe o \`requestId\` de uma submissão \`DEFERRED\`.

```json
{"openapi":"3.0.3","info":{"title":"gtfgts-ingress Public API","version":"0.0.1"},"tags":[{"name":"fgts-operations","description":"Submissão assíncrona de operações FGTS (balance-queries, endorsements, guarantee-maintenances, reserve-cancellations, reserve-value-queries, reserve-protocol-queries, protocol-status-queries), polling de status por `requestId` e cancelamento síncrono de operação. Todas protegidas por JWT do originator."}],"servers":[{"url":"https://ingress.gtfgts.staging.giro.tech","description":"Homologação (testes e validação da integração)"},{"url":"https://gtfgts.giro.tech","description":"Produção (operações reais)"},{"url":"http://localhost:8080","description":"Local (bootRun -Pprofiles=local)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT de originator fornecido pela GTLab no cadastro do originator. Identifica e autoriza o originator em todos os endpoints `/api/v1/**`.\nInclua no header: `Authorization: Bearer <token>`."}}},"paths":{"/api/v1/fgts/balance-queries":{"post":{"operationId":"submitBalanceQuery","tags":["fgts-operations"],"summary":"Submete consulta de saldo FGTS","description":"Admite uma consulta de saldo/margem FGTS com prioridade `NORMAL`.\n**Resposta dual:**\n- **Saldo disponível em cache** (`200`): quando há valor recente para o CPF consultado,\n  o saldo retorna inline com `source: CAIXA_CALL`. Otimização oportunista — **não garantida**.\n  O webhook é enviado também, com o mesmo `requestId`.\n- **Saldo indisponível** (`202`): operação enfileirada para processamento assíncrono;\n  acompanhe via polling (`GET /api/v1/fgts/operations/{requestId}`) ou webhook.\n\nO webhook é enviado nos dois casos. Quando o saldo não está disponível inline, o originator não o recebe na mesma chamada.\n**Rate limiting:** - Em volume normal: `202` com prioridade `NORMAL`. - Sob alto volume, a requisição pode ser admitida com prioridade reduzida `DEFERRED`\n  (`202`) ou rejeitada com `429 Retry-After`.\n\nO header `Idempotency-Key` permite deduplicação de negócio: reenviar a mesma chave retorna o `requestId` existente sem reprocessar.\n**Deduplicação por CPF:** enquanto uma consulta para o mesmo CPF e originator ainda está em andamento, uma nova chamada recebe `202` com o `requestId` daquela consulta, em vez de criar outra. Vale também para chamadas que trazem `Idempotency-Key` própria. A cota de rate limit é consumida normalmente. A janela é curta (90 s), de modo que reconsultar o mesmo CPF alguns minutos depois continua produzindo uma consulta nova — é assim que a autorização do trabalhador, quando pendente, é capturada.\nDuas exceções: `forceRefresh: true` (quando o originator tem a capacidade habilitada) nunca é deduplicado, e a rota de lote tem janela própria — uma consulta interativa jamais recebe o `requestId` de uma submissão `DEFERRED`.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Chave de idempotência de negócio (string livre, ex.: UUID do cliente). Escopo isolado por originator — a mesma chave não colide entre originators diferentes. Requisições com a mesma chave retornam o `requestId` existente sem reprocessar.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Corpo da requisição para consulta de saldo/margem FGTS. Rota normal (`/balance-queries`) admite com prioridade `NORMAL`; rota de lote (`/batch/balance-queries`) admite com prioridade `DEFERRED`. A prioridade é determinada pela rota.","required":["cpf"],"properties":{"cpf":{"type":"string","pattern":"^\\d{11}$","minLength":11,"maxLength":11,"description":"CPF do trabalhador — 11 dígitos numéricos sem pontuação. Campo PII. Formato e dígitos verificadores (mód-11) validados na entrada; sequências de dígitos repetidos são rejeitadas com `400`."}}}}}},"responses":{"200":{"description":"Saldo disponível inline. Ocorre quando há cache aproveitável para o CPF consultado. O campo `source` retorna `CAIXA_CALL`. Resposta oportunista — não garantida.\nA consulta também é enfileirada com o mesmo `requestId`: o webhook é enviado, com o mesmo saldo, e o `requestId` é consultável em `GET /api/v1/fgts/operations/{requestId}`. Não é preciso fazer polling quando `status` for `COMPLETED` — o resultado já está em `result`. Trate o webhook de forma idempotente pelo `requestId`.","content":{"application/json":{"schema":{"type":"object","description":"Confirmação de admissão assíncrona da operação FGTS (`202 Accepted`). O processamento ocorre em background; acompanhe pelo `requestId` via polling (`GET /api/v1/fgts/operations/{requestId}`) ou pelo webhook cadastrado.\n**Exceção para `balance-queries`:** quando o saldo já está disponível, a resposta é `200 OK` com `status: COMPLETED`, `source: CAIXA_CALL` e `result` com o saldo — não é necessário polling, e o webhook é enviado também. Caso contrário, retorna `202`.","required":["requestId","status"],"properties":{"requestId":{"type":"string","format":"uuid","description":"Identificador único (UUID) gerado pelo serviço para esta chamada. Em resposta `202` a requisição foi admitida no processamento assíncrono e este é o identificador de polling: use-o em `GET /api/v1/fgts/operations/{requestId}`. Em resposta `200` de `balance-queries` o resultado já vem inline em `result`, e a operação também é admitida com este `requestId`: é o mesmo do webhook e é consultável em `GET /api/v1/fgts/operations/{requestId}`. Só é preciso fazer polling quando o `status` for `QUEUED`."},"status":{"type":"string","enum":["QUEUED","COMPLETED"],"description":"Status da operação no momento da admissão. `QUEUED`: operação enfileirada para processamento assíncrono (resposta `202`). `COMPLETED`: resultado disponível inline no campo `result` — ocorre apenas quando o saldo de `balance-queries` já está disponível (resposta `200`)."},"source":{"type":"string","nullable":true,"enum":["CAIXA_CALL"],"description":"Origem do resultado. Presente apenas em resposta `200` de `balance-queries`. `CAIXA_CALL`: saldo apurado na Caixa. Nulo em respostas `202`."},"result":{"nullable":true,"description":"Resultado da operação. Presente apenas em resposta `200` de `balance-queries`. Nulo em respostas `202`.","oneOf":[{"type":"object","description":"Resultado de consulta de saldo (`BALANCE_QUERY`) com saldo disponível — saldo FGTS do trabalhador, com a lista de períodos e valores por competência.","required":["workerCpf","balanceDate"],"properties":{"workerCpf":{"type":"string","description":"CPF do trabalhador (11 dígitos, sem pontuação)."},"balanceDate":{"type":"string","format":"date","description":"Data de referência do saldo consultado (ISO-8601, ex. `2026-05-20`)."},"hasDisregardedBalance":{"type":"boolean","description":"Indica que o trabalhador possui valores de FGTS não considerados no saldo retornado, por não estarem disponíveis para uso como garantia. Pode vir ausente quando a Caixa não informa o campo."},"activeRequestCount":{"type":"integer","description":"Quantidade de pedidos de garantia ativos para o trabalhador na Caixa, considerando todas as instituições — não apenas as reservas deste originador. Reflete o momento da apuração do saldo, não o da requisição: o valor pode estar desatualizado."},"periods":{"type":"array","description":"Lista de períodos com valor disponível para averbação.","items":{"type":"object","description":"Período de competência com valor disponível para averbação.","required":["transferDate","amount"],"properties":{"transferDate":{"type":"string","format":"date","description":"Data de transferência (competência) do período (ISO-8601, ex. `2026-05-01`)."},"amount":{"type":"number","description":"Valor disponível para averbação neste período."}}}}}},{"type":"object","description":"Resultado de consulta de saldo (`BALANCE_QUERY`) sem saldo disponível para averbação.","required":["hasBalance"],"properties":{"hasBalance":{"type":"boolean","description":"Sempre `false` — indica ausência de saldo."}}}]},"reserveIdentifier":{"type":"string","nullable":true,"minLength":13,"maxLength":14,"pattern":"^GT[FD][0-9]{8}[0-9A-HJKMNP-TV-Z]{2,3}$","description":"Identificador determinístico de 13 ou 14 caracteres (`GTD{contractNumber:8}{code:2..3}`) gerado no momento da submissão de averbação — o código do originador tem 2 ou 3 caracteres. Presente apenas em respostas `202` de `POST /endorsements`. Nulo para todos os outros tipos de operação."}}}}}},"202":{"description":"Saldo não disponível inline — operação admitida para processamento assíncrono. Acompanhe pelo `requestId` via polling (`GET /api/v1/fgts/operations/{requestId}`) ou pelo webhook cadastrado. Também retornado quando, sob alto volume, a prioridade é reduzida para `DEFERRED`.\nO `requestId` pode ser o de uma consulta já em andamento para o mesmo CPF e originator — nesse caso nenhuma operação nova é criada e o polling desse `requestId` devolve o resultado daquela consulta.","content":{"application/json":{"schema":{"type":"object","description":"Confirmação de admissão assíncrona da operação FGTS (`202 Accepted`). O processamento ocorre em background; acompanhe pelo `requestId` via polling (`GET /api/v1/fgts/operations/{requestId}`) ou pelo webhook cadastrado.\n**Exceção para `balance-queries`:** quando o saldo já está disponível, a resposta é `200 OK` com `status: COMPLETED`, `source: CAIXA_CALL` e `result` com o saldo — não é necessário polling, e o webhook é enviado também. Caso contrário, retorna `202`.","required":["requestId","status"],"properties":{"requestId":{"type":"string","format":"uuid","description":"Identificador único (UUID) gerado pelo serviço para esta chamada. Em resposta `202` a requisição foi admitida no processamento assíncrono e este é o identificador de polling: use-o em `GET /api/v1/fgts/operations/{requestId}`. Em resposta `200` de `balance-queries` o resultado já vem inline em `result`, e a operação também é admitida com este `requestId`: é o mesmo do webhook e é consultável em `GET /api/v1/fgts/operations/{requestId}`. Só é preciso fazer polling quando o `status` for `QUEUED`."},"status":{"type":"string","enum":["QUEUED","COMPLETED"],"description":"Status da operação no momento da admissão. `QUEUED`: operação enfileirada para processamento assíncrono (resposta `202`). `COMPLETED`: resultado disponível inline no campo `result` — ocorre apenas quando o saldo de `balance-queries` já está disponível (resposta `200`)."},"source":{"type":"string","nullable":true,"enum":["CAIXA_CALL"],"description":"Origem do resultado. Presente apenas em resposta `200` de `balance-queries`. `CAIXA_CALL`: saldo apurado na Caixa. Nulo em respostas `202`."},"result":{"nullable":true,"description":"Resultado da operação. Presente apenas em resposta `200` de `balance-queries`. Nulo em respostas `202`.","oneOf":[{"type":"object","description":"Resultado de consulta de saldo (`BALANCE_QUERY`) com saldo disponível — saldo FGTS do trabalhador, com a lista de períodos e valores por competência.","required":["workerCpf","balanceDate"],"properties":{"workerCpf":{"type":"string","description":"CPF do trabalhador (11 dígitos, sem pontuação)."},"balanceDate":{"type":"string","format":"date","description":"Data de referência do saldo consultado (ISO-8601, ex. `2026-05-20`)."},"hasDisregardedBalance":{"type":"boolean","description":"Indica que o trabalhador possui valores de FGTS não considerados no saldo retornado, por não estarem disponíveis para uso como garantia. Pode vir ausente quando a Caixa não informa o campo."},"activeRequestCount":{"type":"integer","description":"Quantidade de pedidos de garantia ativos para o trabalhador na Caixa, considerando todas as instituições — não apenas as reservas deste originador. Reflete o momento da apuração do saldo, não o da requisição: o valor pode estar desatualizado."},"periods":{"type":"array","description":"Lista de períodos com valor disponível para averbação.","items":{"type":"object","description":"Período de competência com valor disponível para averbação.","required":["transferDate","amount"],"properties":{"transferDate":{"type":"string","format":"date","description":"Data de transferência (competência) do período (ISO-8601, ex. `2026-05-01`)."},"amount":{"type":"number","description":"Valor disponível para averbação neste período."}}}}}},{"type":"object","description":"Resultado de consulta de saldo (`BALANCE_QUERY`) sem saldo disponível para averbação.","required":["hasBalance"],"properties":{"hasBalance":{"type":"boolean","description":"Sempre `false` — indica ausência de saldo."}}}]},"reserveIdentifier":{"type":"string","nullable":true,"minLength":13,"maxLength":14,"pattern":"^GT[FD][0-9]{8}[0-9A-HJKMNP-TV-Z]{2,3}$","description":"Identificador determinístico de 13 ou 14 caracteres (`GTD{contractNumber:8}{code:2..3}`) gerado no momento da submissão de averbação — o código do originador tem 2 ou 3 caracteres. Presente apenas em respostas `202` de `POST /endorsements`. Nulo para todos os outros tipos de operação."}}}}}},"400":{"description":"Requisição inválida — falha de validação de Bean Validation (campos obrigatórios ausentes, formatos incorretos, CPF com dígitos errados, etc.). O campo `errors` contém um mapa `{ \"campo\": \"mensagem\" }` para cada campo inválido. O campo `title` é sempre `\"Bean validation error\"` e `detail` é sempre `\"One or more fields were invalid. See 'errors' for details.\"`.\nRejeições de regra de negócio também chegam como `400`, com `errorCode` próprio (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Quando a rejeição aponta um campo do request, ela traz o mesmo `errors` e o mesmo `detail`; quando não há campo associado, `errors` é omitido e `detail` é o reason phrase do status.","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro estruturado segundo RFC 7807 — Problem Details for HTTP APIs. Campos adicionais `errorCode` (código canônico GTLab estável) e `timestamp` (instante do erro no servidor) são extensões proprietárias. O campo `errors` (mapa campo→mensagem) é incluído nos erros que apontam para um campo do request: validação de Bean Validation (`errorCode: VALIDATION_ERROR`, HTTP 400) e rejeições de regra de negócio que identificam o campo culpado (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Nos erros que não têm campo associado (`401`, `403`, `404`, `429`, `500`, `503`, e rejeições de negócio sem campo) o campo `errors` está ausente.","properties":{"type":{"type":"string","format":"uri","description":"URI de referência do tipo de problema."},"title":{"type":"string","description":"Título legível do tipo de problema."},"status":{"type":"integer","format":"int32","description":"HTTP status code do problema."},"detail":{"type":"string","description":"Descrição legível específica desta ocorrência do problema."},"instance":{"type":"string","description":"URI reference (relativa ou absoluta) que identifica esta ocorrência específica do problema. Geralmente o path do endpoint que gerou o erro."},"errorCode":{"type":"string","description":"Código de erro canônico GTLab estável para uso programático."},"timestamp":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no servidor (ISO-8601 UTC)."},"errors":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Mapa de erros no formato `{ \"campo\": \"mensagem\" }`, onde cada chave nomeia um campo do **request enviado por você**. Presente quando `errorCode` é `VALIDATION_ERROR` (falha de Bean Validation — `@NotBlank`, `@NotNull`, `@Size`, `@Pattern`, etc.) e também em rejeições de regra de negócio que conseguem apontar o campo culpado, como `CONTRACT_INSTALLMENTS_MISMATCH`. Quando presente, `detail` é `\"One or more fields were invalid. See 'errors' for details.\"`. Ausente em erros sem campo associado (`401`, `403`, `404`, `429`, `500`, `503`) e em rejeições de negócio que não se referem a um campo do request."}}}}}},"401":{"description":"Não autenticado — JWT ausente, inválido ou expirado. Autentique-se e inclua o token no header `Authorization: Bearer <token>`.","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro estruturado segundo RFC 7807 — Problem Details for HTTP APIs. Campos adicionais `errorCode` (código canônico GTLab estável) e `timestamp` (instante do erro no servidor) são extensões proprietárias. O campo `errors` (mapa campo→mensagem) é incluído nos erros que apontam para um campo do request: validação de Bean Validation (`errorCode: VALIDATION_ERROR`, HTTP 400) e rejeições de regra de negócio que identificam o campo culpado (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Nos erros que não têm campo associado (`401`, `403`, `404`, `429`, `500`, `503`, e rejeições de negócio sem campo) o campo `errors` está ausente.","properties":{"type":{"type":"string","format":"uri","description":"URI de referência do tipo de problema."},"title":{"type":"string","description":"Título legível do tipo de problema."},"status":{"type":"integer","format":"int32","description":"HTTP status code do problema."},"detail":{"type":"string","description":"Descrição legível específica desta ocorrência do problema."},"instance":{"type":"string","description":"URI reference (relativa ou absoluta) que identifica esta ocorrência específica do problema. Geralmente o path do endpoint que gerou o erro."},"errorCode":{"type":"string","description":"Código de erro canônico GTLab estável para uso programático."},"timestamp":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no servidor (ISO-8601 UTC)."},"errors":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Mapa de erros no formato `{ \"campo\": \"mensagem\" }`, onde cada chave nomeia um campo do **request enviado por você**. Presente quando `errorCode` é `VALIDATION_ERROR` (falha de Bean Validation — `@NotBlank`, `@NotNull`, `@Size`, `@Pattern`, etc.) e também em rejeições de regra de negócio que conseguem apontar o campo culpado, como `CONTRACT_INSTALLMENTS_MISMATCH`. Quando presente, `detail` é `\"One or more fields were invalid. See 'errors' for details.\"`. Ausente em erros sem campo associado (`401`, `403`, `404`, `429`, `500`, `503`) e em rejeições de negócio que não se referem a um campo do request."}}}}}},"429":{"description":"Teto de vazão das submissões FGTS excedido (`INGRESS_RATE_LIMIT_EXCEEDED`) — a requisição foi rejeitada e nenhum `requestId` foi gerado. Aguarde `Retry-After` (1 segundo) e reduza a taxa. Esta resposta não traz os headers de janela. Abaixo do teto e acima da cota, a requisição é admitida com prioridade `DEFERRED` (`202`).","headers":{"Retry-After":{"description":"Segundos até a próxima janela disponível.","schema":{"type":"integer","format":"int64"}}},"content":{"application/problem+json":{"schema":{"type":"object","description":"Erro estruturado segundo RFC 7807 — Problem Details for HTTP APIs. Campos adicionais `errorCode` (código canônico GTLab estável) e `timestamp` (instante do erro no servidor) são extensões proprietárias. O campo `errors` (mapa campo→mensagem) é incluído nos erros que apontam para um campo do request: validação de Bean Validation (`errorCode: VALIDATION_ERROR`, HTTP 400) e rejeições de regra de negócio que identificam o campo culpado (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Nos erros que não têm campo associado (`401`, `403`, `404`, `429`, `500`, `503`, e rejeições de negócio sem campo) o campo `errors` está ausente.","properties":{"type":{"type":"string","format":"uri","description":"URI de referência do tipo de problema."},"title":{"type":"string","description":"Título legível do tipo de problema."},"status":{"type":"integer","format":"int32","description":"HTTP status code do problema."},"detail":{"type":"string","description":"Descrição legível específica desta ocorrência do problema."},"instance":{"type":"string","description":"URI reference (relativa ou absoluta) que identifica esta ocorrência específica do problema. Geralmente o path do endpoint que gerou o erro."},"errorCode":{"type":"string","description":"Código de erro canônico GTLab estável para uso programático."},"timestamp":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no servidor (ISO-8601 UTC)."},"errors":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Mapa de erros no formato `{ \"campo\": \"mensagem\" }`, onde cada chave nomeia um campo do **request enviado por você**. Presente quando `errorCode` é `VALIDATION_ERROR` (falha de Bean Validation — `@NotBlank`, `@NotNull`, `@Size`, `@Pattern`, etc.) e também em rejeições de regra de negócio que conseguem apontar o campo culpado, como `CONTRACT_INSTALLMENTS_MISMATCH`. Quando presente, `detail` é `\"One or more fields were invalid. See 'errors' for details.\"`. Ausente em erros sem campo associado (`401`, `403`, `404`, `429`, `500`, `503`) e em rejeições de negócio que não se referem a um campo do request."}}}}}},"500":{"description":"Erro interno inesperado no servidor.","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro estruturado segundo RFC 7807 — Problem Details for HTTP APIs. Campos adicionais `errorCode` (código canônico GTLab estável) e `timestamp` (instante do erro no servidor) são extensões proprietárias. O campo `errors` (mapa campo→mensagem) é incluído nos erros que apontam para um campo do request: validação de Bean Validation (`errorCode: VALIDATION_ERROR`, HTTP 400) e rejeições de regra de negócio que identificam o campo culpado (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Nos erros que não têm campo associado (`401`, `403`, `404`, `429`, `500`, `503`, e rejeições de negócio sem campo) o campo `errors` está ausente.","properties":{"type":{"type":"string","format":"uri","description":"URI de referência do tipo de problema."},"title":{"type":"string","description":"Título legível do tipo de problema."},"status":{"type":"integer","format":"int32","description":"HTTP status code do problema."},"detail":{"type":"string","description":"Descrição legível específica desta ocorrência do problema."},"instance":{"type":"string","description":"URI reference (relativa ou absoluta) que identifica esta ocorrência específica do problema. Geralmente o path do endpoint que gerou o erro."},"errorCode":{"type":"string","description":"Código de erro canônico GTLab estável para uso programático."},"timestamp":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no servidor (ISO-8601 UTC)."},"errors":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Mapa de erros no formato `{ \"campo\": \"mensagem\" }`, onde cada chave nomeia um campo do **request enviado por você**. Presente quando `errorCode` é `VALIDATION_ERROR` (falha de Bean Validation — `@NotBlank`, `@NotNull`, `@Size`, `@Pattern`, etc.) e também em rejeições de regra de negócio que conseguem apontar o campo culpado, como `CONTRACT_INSTALLMENTS_MISMATCH`. Quando presente, `detail` é `\"One or more fields were invalid. See 'errors' for details.\"`. Ausente em erros sem campo associado (`401`, `403`, `404`, `429`, `500`, `503`) e em rejeições de negócio que não se referem a um campo do request."}}}}}},"503":{"description":"Consulta não admitida. Dois casos, distinguidos por `errorCode`:\n- `CAIXA_MAINTENANCE_WINDOW`: a Caixa está em janela de manutenção programada.\n  A resposta traz `maintenanceEndsAt` com o fim previsto da janela (UTC), e\n  `Retry-After` com os segundos restantes até lá. A janela pode ser encerrada\n  antes do previsto, então `maintenanceEndsAt` é um limite superior, não uma\n  promessa. Só a rota interativa é recusada — `POST /api/v1/fgts/batch/balance-queries`\n  continua sendo aceita e é processada quando a janela fecha.\n- `SUBMISSION_TEMPORARILY_UNAVAILABLE`: falha transitória de infraestrutura.\nNos dois casos a requisição **não** foi enfileirada e nenhuma chave de idempotência foi consumida: reenviar o mesmo corpo com a mesma `Idempotency-Key` produz uma submissão nova, não uma duplicata.","headers":{"Retry-After":{"description":"Segundos recomendados até a próxima tentativa.","schema":{"type":"integer","format":"int64"}}},"content":{"application/problem+json":{"schema":{"type":"object","description":"Erro estruturado segundo RFC 7807 — Problem Details for HTTP APIs. Campos adicionais `errorCode` (código canônico GTLab estável) e `timestamp` (instante do erro no servidor) são extensões proprietárias. O campo `errors` (mapa campo→mensagem) é incluído nos erros que apontam para um campo do request: validação de Bean Validation (`errorCode: VALIDATION_ERROR`, HTTP 400) e rejeições de regra de negócio que identificam o campo culpado (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Nos erros que não têm campo associado (`401`, `403`, `404`, `429`, `500`, `503`, e rejeições de negócio sem campo) o campo `errors` está ausente.","properties":{"type":{"type":"string","format":"uri","description":"URI de referência do tipo de problema."},"title":{"type":"string","description":"Título legível do tipo de problema."},"status":{"type":"integer","format":"int32","description":"HTTP status code do problema."},"detail":{"type":"string","description":"Descrição legível específica desta ocorrência do problema."},"instance":{"type":"string","description":"URI reference (relativa ou absoluta) que identifica esta ocorrência específica do problema. Geralmente o path do endpoint que gerou o erro."},"errorCode":{"type":"string","description":"Código de erro canônico GTLab estável para uso programático."},"timestamp":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no servidor (ISO-8601 UTC)."},"errors":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Mapa de erros no formato `{ \"campo\": \"mensagem\" }`, onde cada chave nomeia um campo do **request enviado por você**. Presente quando `errorCode` é `VALIDATION_ERROR` (falha de Bean Validation — `@NotBlank`, `@NotNull`, `@Size`, `@Pattern`, etc.) e também em rejeições de regra de negócio que conseguem apontar o campo culpado, como `CONTRACT_INSTALLMENTS_MISMATCH`. Quando presente, `detail` é `\"One or more fields were invalid. See 'errors' for details.\"`. Ausente em erros sem campo associado (`401`, `403`, `404`, `429`, `500`, `503`) e em rejeições de negócio que não se referem a um campo do request."}}}}}}}}}}}
```

## Resultado no webhook

No fluxo assíncrono (`202`), concluída a consulta a Giro.Tech envia ao webhook cadastrado um envelope `{ source, eventType, data }`. (Em **cache HIT** a submissão já responde `200` com o saldo inline, sem webhook.) Para esta operação o `source` é **`BALANCE_QUERY`** e os `eventType` possíveis são (consulta **não** tem desfecho `*_NEEDS_VERIFICATION`):

| `eventType`                | Quando                                                      | `data`                                                               |
| -------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------- |
| `BALANCE_QUERY_COMPLETED`  | consulta concluída com saldo                                | `result` = `BalanceResult` (`workerCpf`, `balanceDate`, `periods[]`) |
| `BALANCE_QUERY_NO_BALANCE` | concluída, porém **sem saldo FGTS**                         | `result.hasBalance = false`                                          |
| `BALANCE_QUERY_FAILED`     | erro na consulta (inclui expiração, com `status = EXPIRED`) | `error` (`OperationError`)                                           |

### 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\_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
    }
  }
}
```

### 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" }
      ]
    }
  }
}
```

Catálogo completo de eventos e payloads em [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md) e [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md).

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