Saldo FGTS (private-payroll-fgts-balances)

Rota base v5/private-payroll-fgts-balances. Ver visão geral do módulo.

Para um vínculo específico, consulta na Dataprev (consultar-saldo-fgts, com o token do termo no header tokenAutorizacao) o saldo do FGTS e a multa rescisória disponíveis para servir como garantia do consignado privado. O resultado é gravado como consulta persistida, sem listas filhas.

Processamento assíncrono

O POST não aguarda a Dataprev. A API valida o que não depende do provedor, grava a consulta com status pending ("Consultando") e responde imediatamente com esse registro. Em segundo plano, a consulta é feita na Dataprev e o mesmo registro é atualizado para success ou error. Acompanhe o resultado assinando os eventos private_payroll_fgts_balance.completed e private_payroll_fgts_balance.failed, cujo payload é a própria consulta, no mesmo formato da resposta do POST. Esta API não expõe GET /{id} para este recurso: o webhook é a forma de receber o resultado.

Autorização do trabalhador no aplicativo da Carteira de Trabalho

A Dataprev só libera o saldo se o trabalhador tiver autorizado a consulta ao FGTS no aplicativo da Carteira de Trabalho Digital. Essa autorização expira em 30 dias. Sem ela, o provedor recusa (código Dataprev IV) e a consulta termina com status = error, com o motivo em status.note.

Autenticação

API Key. Exige permissão de consulta de saldo FGTS.

Rotas implementadas

Rota	Verbo	Resumo
/v5/private-payroll-fgts-balances	POST	Registra a consulta do saldo FGTS para um vínculo e processa em segundo plano.

Leitura por id, busca e filtros deste recurso ficam no portal da Semear e não são expostos na API de integração.

Campos da entidade

Campo	Tipo	Aceita nulo	Descrição
id / code	string (uuid) / integer	Não	Identificadores da consulta gravada.
authorizationTermId	string (uuid)	Não	Termo usado.
employmentRelationshipId	string (uuid)	Não	Vínculo consultado.
provider	object (code/key/name)	Não	Sempre dataprev.
status	object (Status)	Não	pending (1, Consultando), success (2, Sucesso) ou error (3, Erro). Em erro, note traz o motivo retornado pela Dataprev. Pode ser usado como filtro na busca. Ver PrivatePayrollFgtsBalanceStatus.
queriedAt	string (date-time)	Não	Momento em que a API registrou a consulta (UTC).
documentNumber, name	string	Não	CPF e nome do trabalhador (do termo).
registrationNumber, employerDocumentType, employerDocumentNumber	string / CodeName / string	Não	Chave do vínculo consultado.
providerQueriedAt	string (date-time)	Sim	Momento de referência do saldo, informado pelo provedor (horário local do provedor, sem sufixo Z). Nulo enquanto a consulta está pending.
availableBalanceAmount	decimal	Sim	Saldo do FGTS disponível para garantia. Preenchido quando a consulta termina com success.
severanceFineAmount	decimal	Sim	Multa rescisória disponível.
totalAvailableAmount	decimal	Sim	Total disponível como garantia, reunindo o saldo do FGTS e a multa rescisória.

---

POST /v5/private-payroll-fgts-balances

Registra a consulta do saldo FGTS de um vínculo e processa em segundo plano.

Autenticação: API Key. Exige permissão de consulta de saldo FGTS.

Comportamento

1. Carrega o termo e valida active + token (4053003–4053005).
2. Carrega o vínculo (4053008) e valida CPF (4053009) e completude (4053010).
3. Grava a consulta com status pending e responde 201 com o registro, sem aguardar a Dataprev.
4. Em segundo plano, chama a Dataprev com matrícula e documento do empregador do vínculo. Falhas temporárias do provedor (tempo esgotado, indisponibilidade) são repetidas automaticamente algumas vezes, com espera crescente; quando a cota da Dataprev é excedida, o processamento é adiado até o horário indicado pelo provedor. Erros de negócio (como IV ou TS) encerram a consulta na hora.
5. Atualiza o mesmo registro: success com os valores do saldo, ou error com o motivo da Dataprev em status.note. A falha no provedor também é gravada, e o evento correspondente (private_payroll_fgts_balance.completed ou .failed) é publicado.

Payload de entrada

Campos enviados pela requisição Consulta de garantias FGTS da collection, na mesma ordem.

Visualizar parâmetros

Campo	Tipo	Obrigatório	Descrição
authorizationTermId	string (uuid)	Sim	Termo active com token. Ausente → 4053002.
employmentRelationshipId	string (uuid)	Sim	items[].id de um vínculo devolvido em Vínculos. Ausente → 4053007.

Exemplo de Requisição e Resposta

Body

Visualizar Body

{
  "authorizationTermId": "{{termId}}",
  "employmentRelationshipId": "{{employmentRelationshipId}}"
}

cURL

curl --request POST \
  --url '{{baseUrl}}/v5/private-payroll-fgts-balances' \
  --header 'X-Api-Key: {{x_api_key}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "authorizationTermId": "{{termId}}",
    "employmentRelationshipId": "{{employmentRelationshipId}}"
  }'

201 - Created

A consulta volta com status pending e sem os valores do saldo, que são preenchidos quando o processamento termina. O exemplo segue a estrutura do contrato.

Visualizar Response

{
  "id": "00000000-0000-7000-8000-000000000501",
  "code": 1,
  "authorizationTermId": "00000000-0000-7000-8000-000000000101",
  "employmentRelationshipId": "00000000-0000-7000-8000-000000000311",
  "provider": { "code": 100, "key": "dataprev", "name": "Dataprev" },
  "status": { "code": 1, "key": "pending", "name": "Consultando", "date": "2026-09-15T12:00Z", "color": "#FFEB3B", "note": null },
  "queriedAt": "2026-09-15T12:00:00Z",
  "documentNumber": "00000000000",
  "name": "Nome do Trabalhador",
  "registrationNumber": "000",
  "employerDocumentType": { "code": 1, "name": "CNPJ" },
  "employerDocumentNumber": "00000000000000",
  "providerQueriedAt": null,
  "availableBalanceAmount": null,
  "severanceFineAmount": null,
  "totalAvailableAmount": null
}

400 - Erro

Termo ausente/não encontrado/não ativo/sem token (4053002–4053005); vínculo ausente/não encontrado/de outro CPF/incompleto (4053007–4053010); ou exceção não tratada (9999999). A recusa da Dataprev não volta no POST: ela chega depois, com a consulta em status = error e o motivo em status.note.

Visualizar Response

{ "messages": [ { "code": "4053009", "text": "O vínculo informado não pertence ao trabalhador do termo de autorização" } ] }

Motivos comuns de recusa do provedor (registrados em status.note da consulta):

Código Dataprev	Significado	O que fazer
IV	Trabalhador não autorizou a consulta ao saldo FGTS no aplicativo da Carteira de Trabalho, ou a autorização expirou (30 dias).	Orientar o trabalhador a autorizar no aplicativo e repetir a consulta.
TS	Vínculo encerrado.	Escolher outro vínculo ativo.

401 - Não autorizado

API Key ausente, inválida ou expirada.

403 - Proibido

Usuário autenticado sem permissão de consulta de saldo FGTS. Corpo vazio.