> 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-gtpayroll/api-reference/margem/consultas-dataprev/consultar-fgts-disponivel.md).

# Consultar FGTS Disponível

Consulta na Dataprev o **saldo de FGTS disponível** do trabalhador como garantia de consignado e a parcela de **multa rescisória** disponível. São os valores da **garantia FGTS** na averbação.

* Duas entradas, mesmo vínculo e mesmo processamento: por **lastro** (`bondPublicId`, entrada primária, obtido em [Consultar Vínculos Autorizados](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-vinculos-autorizados.md)) ou por **vínculo** (`relationshipPublicId`, obtido em [Consultar Margem por Vínculo](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-margem-por-vinculo.md)). O identificador precisa ser do employee informado. Nenhuma das duas cria vínculo.
* O employee precisa estar com a [autorização Dataprev](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao.md) em `AUTHORIZED`.
* Assíncrono: o `POST` devolve um `requestId` (`202`); o resultado sai no `GET` por `requestId`, sinalizado pelo webhook `FGTS_AVAILABILITY_QUERY_COMPLETED`. Ver [o padrão assíncrono](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev.md#o-padrao-assincrono).

{% hint style="warning" %}
**Autorização específica de FGTS:** o trabalhador também precisa ter autorizado "Consultar Informações do FGTS" no app **Carteira de Trabalho Digital** (validade de 30 dias). A API não consegue verificar isso; sem essa autorização, a Dataprev recusa e a consulta fica `FAILED`.
{% endhint %}

## Request

Por lastro (primária):

`POST /api/v1/originator/employees/{publicId}/authorized-bonds/{bondPublicId}/fgts-availability-queries`

Por vínculo:

`POST /api/v1/originator/employees/{publicId}/employment-relationships/{relationshipPublicId}/fgts-availability-queries`

Sem corpo.

### Parâmetros

| Parâmetro              | Local  | Tipo            | Obrigatório               | Descrição                                                                                                                                                                                         |
| ---------------------- | ------ | --------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `publicId`             | path   | `string`        | Sim                       | Identificador público do employee (16 caracteres)                                                                                                                                                 |
| `bondPublicId`         | path   | `string (uuid)` | Sim (entrada por lastro)  | Identificador público do lastro, obtido na [listagem de vínculos](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-vinculos-autorizados.md) |
| `relationshipPublicId` | path   | `string (uuid)` | Sim (entrada por vínculo) | Identificador público do vínculo empregatício                                                                                                                                                     |
| `Idempotency-Key`      | header | `string`        | Não                       | Reenvios com a mesma chave retornam o mesmo `requestId`. Ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/idempotencia.md)                                           |

## Response

O `POST` retorna `202 Accepted`:

| Campo       | Tipo     | Descrição                                                                                                                                   |
| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `requestId` | `string` | Identificador da requisição: UUID v7 (36 caracteres) nas novas, 16 caracteres nas antigas. Aceite qualquer string entre 16 e 36 caracteres. |
| `status`    | `string` | Estado inicial (`PROCESSING`).                                                                                                              |

O resultado sai em `GET /api/v1/originator/fgts-availability-queries/{requestId}`:

| Campo                            | Tipo                      | Descrição                                                                 |
| -------------------------------- | ------------------------- | ------------------------------------------------------------------------- |
| `requestId`                      | `string`                  | Identificador da requisição.                                              |
| `status`                         | `string`                  | `PENDING`, `PROCESSING`, `COMPLETED` ou `FAILED`.                         |
| `bondPublicId`                   | `string (uuid)`           | Lastro, quando a consulta foi iniciada por lastro; `null` caso contrário. |
| `employmentRelationshipPublicId` | `string (uuid)` \| `null` | Identificador público do vínculo.                                         |
| `availableBalance`               | `number`                  | Saldo de FGTS disponível como garantia. Preenchido quando `COMPLETED`.    |
| `severanceFine`                  | `number`                  | Multa rescisória disponível como garantia. Preenchido quando `COMPLETED`. |
| `referenceAt`                    | `string` (date-time)      | Data/hora da consulta na Dataprev. Preenchido quando `COMPLETED`.         |
| `errorCode`                      | `string`                  | Código do erro quando `FAILED`; `null` caso contrário.                    |
| `reason`                         | `string`                  | Descrição do erro quando `FAILED`; `null` caso contrário.                 |

O último resultado `COMPLETED` de um vínculo também aparece como `fgtsAvailability { availableBalance, severanceFine, referenceAt }` (ou `null`) na [Consultar Margem por Vínculo](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-margem-por-vinculo.md), no [`GET /margin`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md) e na [listagem de vínculos](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-vinculos-autorizados.md), sem nova consulta à Dataprev.

### Códigos de status

**POST** `.../fgts-availability-queries`:

| Código | Significado                                                   |
| ------ | ------------------------------------------------------------- |
| `202`  | Consulta iniciada. Guarde o `requestId`                       |
| `404`  | Employee/lastro/vínculo inexistente ou de outro originador    |
| `422`  | Employee não autorizado (`errorCode=EMPLOYEE_NOT_AUTHORIZED`) |

**GET** `/fgts-availability-queries/{requestId}`:

| Código | Significado                                                                                                         |
| ------ | ------------------------------------------------------------------------------------------------------------------- |
| `200`  | Consulta `COMPLETED` (use `availableBalance`/`severanceFine`/`referenceAt`) ou `FAILED` (veja `errorCode`/`reason`) |
| `202`  | Em processamento (`PENDING`/`PROCESSING`). Consulte de novo                                                         |
| `404`  | `requestId` inexistente ou de outro originador                                                                      |

## Exemplo

```http
POST /api/v1/originator/employees/abcd1234efgh5678/authorized-bonds/0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b04/fgts-availability-queries
Authorization: Bearer {originatorToken}
Idempotency-Key: 7d9f3a1c-5b2e-4c8a-9f1d-2e6b8c0a4d31
```

Resposta `202` (consulta iniciada):

```json
{
  "requestId": "0198f2d5-8b13-7e26-ac4f-7b9e2d5a3f18",
  "status": "PROCESSING"
}
```

## Request async FGTS availability query from an authorized bond (primary)

> Initiates an asynchronous query to fetch the worker's available FGTS balance\
> (\`valorSaldoDisponivelConsignado\`) and severance fine (\`valorMultaRescisoriaConsignado\`) from\
> Dataprev (\`consultar-saldo-fgts\`), resolved from an authorized bond (\`bondPublicId\`, which accepts either the opaque \`publicId\` or\
> the legacy numeric id). This is the\
> \*\*primary\*\* entry point: the bond is self-sufficient (it already carries the registration number\
> and the employer tax id).\
> \
> Processed asynchronously. On completion an \`FGTS\_AVAILABILITY\_QUERY\_COMPLETED\` webhook is\
> dispatched (or \`FGTS\_AVAILABILITY\_QUERY\_FAILED\` on a permanent Dataprev error). Poll the result via\
> \`GET /fgts-availability-queries/{requestId}\`.\
> \
> Requires the employee to be in \`AUTHORIZED\` status. The FGTS-specific consent (granted in the CTPS\
> app, 30-day validity) is not verifiable locally — if absent, Dataprev refuses and the query ends\
> \`FAILED\`.<br>

```json
{"openapi":"3.0.0","info":{"title":"GT Payroll Originator API","version":"1.1.0"},"tags":[{"name":"Dataprev","description":"Dados Dataprev (transferências de pagamento e lançamentos contábeis)"}],"servers":[{"url":"https://ingress.gtpayroll.staging.giro.tech","description":"Ambiente de Staging"},{"url":"https://ingress.gtpayroll.giro.tech","description":"Ambiente de Produção"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token fornecido pelo administrador"}}},"paths":{"/api/v1/originator/employees/{publicId}/authorized-bonds/{bondPublicId}/fgts-availability-queries":{"post":{"operationId":"requestFgtsAvailabilityByBond","summary":"Request async FGTS availability query from an authorized bond (primary)","description":"Initiates an asynchronous query to fetch the worker's available FGTS balance\n(`valorSaldoDisponivelConsignado`) and severance fine (`valorMultaRescisoriaConsignado`) from\nDataprev (`consultar-saldo-fgts`), resolved from an authorized bond (`bondPublicId`, which accepts either the opaque `publicId` or\nthe legacy numeric id). This is the\n**primary** entry point: the bond is self-sufficient (it already carries the registration number\nand the employer tax id).\n\nProcessed asynchronously. On completion an `FGTS_AVAILABILITY_QUERY_COMPLETED` webhook is\ndispatched (or `FGTS_AVAILABILITY_QUERY_FAILED` on a permanent Dataprev error). Poll the result via\n`GET /fgts-availability-queries/{requestId}`.\n\nRequires the employee to be in `AUTHORIZED` status. The FGTS-specific consent (granted in the CTPS\napp, 30-day validity) is not verifiable locally — if absent, Dataprev refuses and the query ends\n`FAILED`.\n","tags":["Dataprev"],"parameters":[{"name":"publicId","in":"path","required":true,"description":"Identificador público do employee (16 caracteres)","schema":{"type":"string"}},{"name":"bondPublicId","in":"path","required":true,"description":"Identificador público do vínculo autorizado (UUID)","schema":{"type":"string","maxLength":36}}],"responses":{"202":{"description":"Query request accepted and enqueued for processing","content":{"application/json":{"schema":{"type":"object","required":["requestId","status"],"properties":{"requestId":{"type":"string","minLength":16,"maxLength":36,"description":"Unique identifier for the async query request. UUID v7 (36 chars) for requests\ncreated after the migration; legacy requests keep their original 16-char id.\n"},"status":{"type":"string","enum":["PENDING","PROCESSING","COMPLETED","FAILED"],"description":"Current status of the async query"}}}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro de autenticação (HTTP 401). Token ausente, com prefixo diferente de `Bearer `, expirado, revogado ou inválido.","required":["type","title","status"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"403":{"description":"Insufficient permission","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro de autorização (HTTP 403). Token válido de outro perfil, sem permissão de originador.\nRecusas de permissão por regra de negócio (ex.: `ORIGINATOR_OPT_IN_NOT_ENABLED`) usam\n`#business-rule-violation` com `properties.errorCode`.\n","required":["type","title","status"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"404":{"description":"Employee (`#resource-not-found`) ou vínculo (`#business-rule-violation`) não encontrado.","content":{"application/problem+json":{"schema":{"type":"object","description":"Resposta de erro no formato RFC 7807 (Problem Details). Os campos extras **não** vêm na raiz:\nficam dentro de `properties` (`message`, `errorCode`, `errors`, `retryAfter`…).\n\nIdentifique o erro por `status` + `properties.errorCode`. O `type` agrupa famílias e sozinho não\nidentifica o erro: `#business-rule-violation` aparece com 400, 403, 404, 409, 413, 422 e 503.\nCatálogo completo em https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.\n","required":["type","title","status"],"properties":{"type":{"type":"string","description":"URL do guia de erros com o fragmento da família: `validation-error`, `not-authenticated`,\n`forbidden`, `resource-not-found`, `conflict`, `business-rule-violation`,\n`dataprev-suspension-window`, `rate-limit-exceeded`, `internal-error`, `upstream-error`,\n`service-unavailable`. Corpo ilegível, parâmetro de tipo errado, rota inexistente, `405` e\n`415` vêm como `about:blank`, sem `properties`.\n"},"title":{"type":"string","description":"Resumo curto. Na maioria dos casos é a frase padrão do status HTTP."},"status":{"type":"integer","description":"Código HTTP do erro"},"detail":{"type":"string","description":"Mensagem legível desta ocorrência. Pode mudar de texto; use `properties.errorCode` para automação."},"instance":{"type":"string","description":"Path da requisição que falhou"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"422":{"description":"Employee não autorizado na Dataprev. Checado antes do vínculo.","content":{"application/problem+json":{"schema":{"type":"object","description":"Resposta de erro no formato RFC 7807 (Problem Details). Os campos extras **não** vêm na raiz:\nficam dentro de `properties` (`message`, `errorCode`, `errors`, `retryAfter`…).\n\nIdentifique o erro por `status` + `properties.errorCode`. O `type` agrupa famílias e sozinho não\nidentifica o erro: `#business-rule-violation` aparece com 400, 403, 404, 409, 413, 422 e 503.\nCatálogo completo em https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.\n","required":["type","title","status"],"properties":{"type":{"type":"string","description":"URL do guia de erros com o fragmento da família: `validation-error`, `not-authenticated`,\n`forbidden`, `resource-not-found`, `conflict`, `business-rule-violation`,\n`dataprev-suspension-window`, `rate-limit-exceeded`, `internal-error`, `upstream-error`,\n`service-unavailable`. Corpo ilegível, parâmetro de tipo errado, rota inexistente, `405` e\n`415` vêm como `about:blank`, sem `properties`.\n"},"title":{"type":"string","description":"Resumo curto. Na maioria dos casos é a frase padrão do status HTTP."},"status":{"type":"integer","description":"Código HTTP do erro"},"detail":{"type":"string","description":"Mensagem legível desta ocorrência. Pode mudar de texto; use `properties.errorCode` para automação."},"instance":{"type":"string","description":"Path da requisição que falhou"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"423":{"description":"Janela de suspensão da Dataprev aberta (virada de competência). A operação **não** foi\nregistrada — reenvie depois de `windowEnd`.\n\nOnde olhar para reagendar: o header `Retry-After` traz os **segundos** que faltam (é sempre\ndelta-seconds, nunca HTTP-date) e o corpo traz `windowEnd` como `date-time`. Use um dos dois —\n**não** faça backoff exponencial, a volta tem hora marcada.\n","headers":{"Retry-After":{"description":"Segundos até o fim previsto da janela.","schema":{"type":"integer","format":"int32"}}},"content":{"application/problem+json":{"schema":{"type":"object","description":"Recusa por janela de suspensão da Dataprev (virada de competência). A Dataprev suspende as\noperações mensalmente, por volta do dia 21 ao dia 23, e nesse período o GTPayroll recusa de\nimediato em vez de aceitar um pedido que ficaria dias sem resposta.\n\nUse o header `Retry-After` para reagendar: **não** faça backoff exponencial, a volta tem hora\nmarcada. A recusa fica gravada na `Idempotency-Key` — reenvie com chave nova. Simulação,\npropostas e webhooks continuam disponíveis durante a janela; o webhook `DATAPREV_WINDOW_CLOSED`\navisa quando as demais rotas voltam.\n","required":["type","title","status","properties"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"properties":{"type":"object","required":["errorCode"],"properties":{"message":{"type":"string"},"errorCode":{"type":"string"},"windowEnd":{"type":"string","description":"Fim previsto da janela, em data/hora **sem fuso** (`yyyy-MM-ddTHH:mm:ss`). Ausente quando a Dataprev não informou a data."}}}}}}}},"429":{"description":"Mais de 20 requisições por segundo. Aguarde o header `Retry-After` e reenvie com **nova** `Idempotency-Key` — com a mesma chave, o `429` gravado é repetido.","content":{"application/problem+json":{"schema":{"type":"object","description":"Resposta de erro no formato RFC 7807 (Problem Details). Os campos extras **não** vêm na raiz:\nficam dentro de `properties` (`message`, `errorCode`, `errors`, `retryAfter`…).\n\nIdentifique o erro por `status` + `properties.errorCode`. O `type` agrupa famílias e sozinho não\nidentifica o erro: `#business-rule-violation` aparece com 400, 403, 404, 409, 413, 422 e 503.\nCatálogo completo em https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.\n","required":["type","title","status"],"properties":{"type":{"type":"string","description":"URL do guia de erros com o fragmento da família: `validation-error`, `not-authenticated`,\n`forbidden`, `resource-not-found`, `conflict`, `business-rule-violation`,\n`dataprev-suspension-window`, `rate-limit-exceeded`, `internal-error`, `upstream-error`,\n`service-unavailable`. Corpo ilegível, parâmetro de tipo errado, rota inexistente, `405` e\n`415` vêm como `about:blank`, sem `properties`.\n"},"title":{"type":"string","description":"Resumo curto. Na maioria dos casos é a frase padrão do status HTTP."},"status":{"type":"integer","description":"Código HTTP do erro"},"detail":{"type":"string","description":"Mensagem legível desta ocorrência. Pode mudar de texto; use `properties.errorCode` para automação."},"instance":{"type":"string","description":"Path da requisição que falhou"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}}}}}}}
```

Depois, consulte o resultado por `requestId`:

```http
GET /api/v1/originator/fgts-availability-queries/0198f2d5-8b13-7e26-ac4f-7b9e2d5a3f18
Authorization: Bearer {originatorToken}
```

Resposta `200` (consulta concluída):

```json
{
  "requestId": "0198f2d5-8b13-7e26-ac4f-7b9e2d5a3f18",
  "status": "COMPLETED",
  "bondPublicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b04",
  "employmentRelationshipPublicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02",
  "availableBalance": 1234.56,
  "severanceFine": 789.00,
  "referenceAt": "2026-06-12T09:30:15",
  "errorCode": null,
  "reason": null
}
```

Resposta `200` (consulta encerrada com falha permanente):

```json
{
  "requestId": "0198f2d5-8b13-7e26-ac4f-7b9e2d5a3f18",
  "status": "FAILED",
  "bondPublicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b04",
  "employmentRelationshipPublicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02",
  "availableBalance": null,
  "severanceFine": null,
  "referenceAt": null,
  "errorCode": "CB",
  "reason": "CPF não encontrado na base ou CPF do trabalhador inelegível"
}
```

## Retrieve FGTS availability query result by requestId

> Polls the result of a previously submitted FGTS availability query.\
> \
> \- Returns 202 (with AsyncQueryAcceptedResponse) while the query is PENDING or PROCESSING\
> \- Returns 200 (with FgtsAvailabilityQueryResultResponse) when the query is COMPLETED or FAILED<br>

```json
{"openapi":"3.0.0","info":{"title":"GT Payroll Originator API","version":"1.1.0"},"tags":[{"name":"Dataprev","description":"Dados Dataprev (transferências de pagamento e lançamentos contábeis)"}],"servers":[{"url":"https://ingress.gtpayroll.staging.giro.tech","description":"Ambiente de Staging"},{"url":"https://ingress.gtpayroll.giro.tech","description":"Ambiente de Produção"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token fornecido pelo administrador"}}},"paths":{"/api/v1/originator/fgts-availability-queries/{requestId}":{"get":{"operationId":"getFgtsAvailabilityQuery","summary":"Retrieve FGTS availability query result by requestId","description":"Polls the result of a previously submitted FGTS availability query.\n\n- Returns 202 (with AsyncQueryAcceptedResponse) while the query is PENDING or PROCESSING\n- Returns 200 (with FgtsAvailabilityQueryResultResponse) when the query is COMPLETED or FAILED\n","tags":["Dataprev"],"parameters":[{"name":"requestId","in":"path","required":true,"description":"The requestId returned by one of the POST .../fgts-availability-queries endpoints","schema":{"type":"string","maxLength":36}}],"responses":{"200":{"description":"Query completed (successfully or with failure)","content":{"application/json":{"schema":{"type":"object","required":["requestId","status"],"properties":{"requestId":{"type":"string","minLength":16,"maxLength":36,"description":"Unique identifier for the async query request. UUID v7 (36 chars) for requests\ncreated after the migration; legacy requests keep their original 16-char id.\n"},"status":{"type":"string","enum":["PENDING","PROCESSING","COMPLETED","FAILED"],"description":"Current status of the query"},"bondPublicId":{"type":"string","format":"uuid","nullable":true,"description":"Identificador público opaco do bond."},"employmentRelationshipPublicId":{"type":"string","format":"uuid","nullable":true,"description":"Identificador público opaco do vínculo."},"availableBalance":{"type":"number","format":"double","nullable":true,"description":"Available FGTS balance (present for COMPLETED)"},"severanceFine":{"type":"number","format":"double","nullable":true,"description":"Available severance fine portion (present for COMPLETED)"},"referenceAt":{"type":"string","format":"date-time","nullable":true,"description":"Dataprev consultation timestamp (present for COMPLETED)"},"errorCode":{"type":"string","nullable":true,"description":"Dataprev error code (sigla, e.g. CB) when status is FAILED"},"reason":{"type":"string","nullable":true,"description":"Failure reason when status is FAILED"}}}}}},"202":{"description":"Query still in progress","content":{"application/json":{"schema":{"type":"object","required":["requestId","status"],"properties":{"requestId":{"type":"string","minLength":16,"maxLength":36,"description":"Unique identifier for the async query request. UUID v7 (36 chars) for requests\ncreated after the migration; legacy requests keep their original 16-char id.\n"},"status":{"type":"string","enum":["PENDING","PROCESSING","COMPLETED","FAILED"],"description":"Current status of the async query"}}}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro de autenticação (HTTP 401). Token ausente, com prefixo diferente de `Bearer `, expirado, revogado ou inválido.","required":["type","title","status"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"403":{"description":"Insufficient permission","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro de autorização (HTTP 403). Token válido de outro perfil, sem permissão de originador.\nRecusas de permissão por regra de negócio (ex.: `ORIGINATOR_OPT_IN_NOT_ENABLED`) usam\n`#business-rule-violation` com `properties.errorCode`.\n","required":["type","title","status"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"404":{"description":"`requestId` não encontrado ou de outro originador.","content":{"application/problem+json":{"schema":{"type":"object","description":"Resposta de erro no formato RFC 7807 (Problem Details). Os campos extras **não** vêm na raiz:\nficam dentro de `properties` (`message`, `errorCode`, `errors`, `retryAfter`…).\n\nIdentifique o erro por `status` + `properties.errorCode`. O `type` agrupa famílias e sozinho não\nidentifica o erro: `#business-rule-violation` aparece com 400, 403, 404, 409, 413, 422 e 503.\nCatálogo completo em https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.\n","required":["type","title","status"],"properties":{"type":{"type":"string","description":"URL do guia de erros com o fragmento da família: `validation-error`, `not-authenticated`,\n`forbidden`, `resource-not-found`, `conflict`, `business-rule-violation`,\n`dataprev-suspension-window`, `rate-limit-exceeded`, `internal-error`, `upstream-error`,\n`service-unavailable`. Corpo ilegível, parâmetro de tipo errado, rota inexistente, `405` e\n`415` vêm como `about:blank`, sem `properties`.\n"},"title":{"type":"string","description":"Resumo curto. Na maioria dos casos é a frase padrão do status HTTP."},"status":{"type":"integer","description":"Código HTTP do erro"},"detail":{"type":"string","description":"Mensagem legível desta ocorrência. Pode mudar de texto; use `properties.errorCode` para automação."},"instance":{"type":"string","description":"Path da requisição que falhou"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"429":{"description":"Mais de 100 requisições por segundo. Aguarde o header `Retry-After` e reenvie com **nova** `Idempotency-Key` — com a mesma chave, o `429` gravado é repetido.","content":{"application/problem+json":{"schema":{"type":"object","description":"Resposta de erro no formato RFC 7807 (Problem Details). Os campos extras **não** vêm na raiz:\nficam dentro de `properties` (`message`, `errorCode`, `errors`, `retryAfter`…).\n\nIdentifique o erro por `status` + `properties.errorCode`. O `type` agrupa famílias e sozinho não\nidentifica o erro: `#business-rule-violation` aparece com 400, 403, 404, 409, 413, 422 e 503.\nCatálogo completo em https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.\n","required":["type","title","status"],"properties":{"type":{"type":"string","description":"URL do guia de erros com o fragmento da família: `validation-error`, `not-authenticated`,\n`forbidden`, `resource-not-found`, `conflict`, `business-rule-violation`,\n`dataprev-suspension-window`, `rate-limit-exceeded`, `internal-error`, `upstream-error`,\n`service-unavailable`. Corpo ilegível, parâmetro de tipo errado, rota inexistente, `405` e\n`415` vêm como `about:blank`, sem `properties`.\n"},"title":{"type":"string","description":"Resumo curto. Na maioria dos casos é a frase padrão do status HTTP."},"status":{"type":"integer","description":"Código HTTP do erro"},"detail":{"type":"string","description":"Mensagem legível desta ocorrência. Pode mudar de texto; use `properties.errorCode` para automação."},"instance":{"type":"string","description":"Path da requisição que falhou"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}}}}}}}
```

## Erros

| Código | `errorCode`                  | Situação                                                                                                 |
| ------ | ---------------------------- | -------------------------------------------------------------------------------------------------------- |
| 404    | —                            | Employee não encontrado ou de outro originador (`#resource-not-found`)                                   |
| 404    | —                            | `Bond não encontrado` / `Vínculo não encontrado` / `Request não encontrado` (`#business-rule-violation`) |
| 422    | `EMPLOYEE_NOT_AUTHORIZED`    | Employee não autorizado na Dataprev. Checado antes do vínculo                                            |
| 423    | `DATAPREV_SUSPENSION_WINDOW` | `POST`: janela de suspensão da Dataprev                                                                  |
| 429    | —                            | `POST`: mais de 20 requisições por segundo; `GET`: mais de 100                                           |

Erros comuns a todos os endpoints — `401`, `403` de token, `409` de `Idempotency-Key` em processamento, `500` e `503` — e o formato `ProblemDetail` estão em [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.md).

Quando a consulta falha, ela fica `FAILED` e sai `FGTS_AVAILABILITY_QUERY_FAILED`. O `errorCode` traz:

* a sigla da Dataprev (`CB`, `TA`, `GE`, `SF`, `OT`, `SI`, `ON`, `EX`, `IV`, `BC`, `CA`) — recusa permanente;
* um código `Cxx` da Caixa — `C02`, `C18`, `C25` e `C32` são transitórios ("Tente novamente mais tarde"); os demais, permanentes;
* `PROVIDER_ERROR` — a Dataprev rejeitou a consulta sem informar código;
* `RETRY_EXHAUSTED`, `DATAPREV_SUSPENSION_WINDOW` ou `UNKNOWN` — transitórios: refaça a consulta.

## Webhook `FGTS_AVAILABILITY_QUERY_COMPLETED`

Disparado (source `EMPLOYEE`) ao concluir, com `cpf`, `publicId`, `requestId`, `bondPublicId`, `employmentRelationshipPublicId`, `availableBalance`, `severanceFine` e `referenceAt`. Em falha permanente é disparado `FGTS_AVAILABILITY_QUERY_FAILED`, com `errorCode`/`reason`. Payloads em [Eventos e Payloads](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md).

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