Referência de status e webhooks FGTS

Esta página resume os eventos e status usados no acompanhamento do fluxo FGTS.

Cadastre a URL de retorno na página Webhooks usando:

POST /user/webhook/balance

Eventos documentados:

Evento	Quando ocorre	Como tratar
`balance.status.received.success`	A consulta de saldo foi concluída com sucesso	Buscar ou armazenar saldo, `balanceId` e parcelas
`balance.status.received.fail`	A consulta de saldo falhou	Exibir motivo, registrar falha e orientar nova tentativa quando aplicável

Cadastre a URL de retorno usando:

POST /user/webhook/proposal

Evento documentado:

Evento	Quando ocorre	Como tratar
`proposal.status.update`	O status da proposta foi atualizado	Consultar o detalhe da proposta quando precisar do estado completo

Na consulta final de saldo, o campo status pode indicar:

Status	Significado
`success`	Saldo retornado com sucesso
`fail`	Consulta encerrada com falha

Quando houver falha, consulte statusInfo ou a mensagem retornada no webhook.

A listagem de operações FGTS permite filtrar por status. A documentação atual apresenta exemplos como:

Use a página Consultando Operações FGTS para detalhes da consulta e filtros disponíveis.

Para manter sua base sincronizada:

Receba e registre o webhook.
Consulte o detalhe da proposta pelo ID quando precisar confirmar o estado completo.
Atualize sua operação interna apenas depois de tratar o evento recebido.