CaaS Massificados · FGTS

FGTS — Consultas e acompanhamento

Dado pessoal ou sensível deve ser mascarado em outputs, logs e exemplos. Todos os valores desta página são fictícios. Formatos de data e de valor: Convenções de dados.

O que é

Depois do envio para aprovação a operação sai das suas mãos e percorre a esteira da UY3. Esta página reúne as consultas que respondem "onde está a operação, o que falta e o que já foi pago".

O acompanhamento do FGTS é por consulta: você pergunta, a API responde com o status atual. O que cada transição de status significa, e o que fazer em cada uma, está em 4.1 Eventos e notificações.

Quando usar

Entre o submitapproval e a liquidação, para saber em que etapa a operação está.
Depois da liquidação, para obter o comprovante de transferência.
Ao longo do contrato, para consultar o cronograma de parcelas anuais e o saldo.
Em rotina de reconciliação diária ou semanal da sua carteira.

Pré-requisitos

id da operação — devolvido em 3. Operação.
Token válido — ver Autenticação.

Endpoints de consulta

Status e dados da operação

GET /v1/CreditNote/{id}
GET /v1/CreditNote

GET /v1/CreditNote/{id} devolve a operação completa: status, cálculo, documentos, assinaturas e cronograma. É a consulta que responde "e agora?".

GET /v1/CreditNote lista operações com filtros. Os que interessam ao acompanhamento do FGTS:

Parâmetro	Local	Obrigatório	Como preencher	Exemplo
`status`	query	Não	Status a filtrar. Combine com paginação para varrer a fila de uma etapa.	`Warranty`
`personId`	query	Não	Todas as operações de um titular — é a consulta que confere o limite anual de contratos.	`11111111-1111-1111-1111-111111111111`
`productId`	query	Não	Todas as operações de um produto contratado.	`33333333-3333-3333-3333-333333333333`
`creditNoteNo`	query	Não	Número da operação, quando você tem o número e não o `id`.	`2026/000456`
`initialDate` / `finalDate`	`data civil` (query)	Não	Janela de criação. Use para varredura incremental.	`2026-08-01` / `2026-08-31`
`initialPaymentDate` / `finalPaymentDate`	`data civil` (query)	Não	Janela de vencimento de parcela — no FGTS, o mês do saque-aniversário.	`2027-08-01` / `2027-08-31`
`minValue` / `maxValue`	`inteiro em centavos` (query)	Não	Faixa de valor contratado.	`50000` / `1000000`
`isDeleted`	query	Não	`true` para incluir operações excluídas logicamente.	`false`
`page` / `size`	query	Não	Paginação. Mantenha `size` moderado em varredura.	`1` / `50`
`orderBy`	query	Não	Campo de ordenação.	`createDate desc`

curl --location --request GET '{{baseUrl}}/v1/CreditNote/55555555-5555-5555-5555-555555555555' \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Accept: application/json'

Assinatura

GET /v1/CreditNote/{id}/SignUrl

Devolve as URLs de coleta de assinatura, para entregar ao titular. Disponíveis a partir do status Signatures. O andamento da coleta é lido no próprio GET /v1/CreditNote/{id}.

Liquidação e comprovante

GET /v1/CreditNote/{id}/transferReceipt

Devolve o comprovante da transferência (Pix ou TED) feita ao titular. Disponível a partir da liquidação.

Cronograma de parcelas e quitação

POST /v1/CreditNote/{id}/DuePaymentSchedule
GET  /v1/CreditNote/{id}/LiquidationScheduleCreditNote

DuePaymentSchedule calcula o calendário de quitação da operação — o que o titular deve para liquidar antecipadamente em uma data, antes do próximo saque-aniversário.

Consultas dos cadastros

GET /v1/NaturalPerson/{id}
GET /v1/NaturalPerson

Confirmam os dados do titular e os documentos anexados. É a consulta que verifica se o termo de consentimento está no dossiê — como o FGTS não tem registro de autorização com status próprio, essa conferência substitui a listagem de autorizações do consignado. Ver 2.1 Consentimento de consulta.

Extração em lote

GET /v1/CreditNote/Export/excel
GET /v1/CreditNote/related-operations

Export/excel exporta a carteira filtrada em planilha — use para conciliação periódica, não para acompanhamento de operação individual.

Webhooks

O acompanhamento hoje é por consulta. O ciclo de vida completo — quais eventos existem, quando cada um acontece, quais exigem ação sua e o padrão de varredura recomendado — está na página dedicada:

→ 4.1 Eventos e notificações

O que acontece depois

Com a operação em Finished, o ciclo de integração se encerra: a cada ano o saque-aniversário é debitado na origem e amortiza o contrato. O que resta do seu lado é a conciliação periódica e, quando o titular quiser antecipar de novo, conferir o limite anual de contratos antes de abrir nova operação.

Antes desta etapa

3. Operação — é de lá que vem o id consultado aqui.

Próxima etapa

4.1 Eventos e notificações — o significado de cada status e o que fazer em cada um.
5. Erros e troubleshooting — quando uma consulta revelar reprovação, revisão ou erro.

Downloads

Contexto para LLM deste módulo: llms-fgts.txt
Collection Postman do módulo: uy3-fgts.postman_collection.json
Documentação consolidada para LLM: llms.txt