Referência de status e webhooks FGTS
Esta página resume os eventos e status usados no acompanhamento do fluxo FGTS.
Webhook de saldo
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 |
Webhook de proposta
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 |
Status da consulta de saldo
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.
Status de operação
A listagem de operações FGTS permite filtrar por status. A documentação atual apresenta exemplos como:
-
formalization -
pending -
pending_endorsement- Averbação pendente -
canceled
Use a página Consultando Operações FGTS para detalhes da consulta e filtros disponíveis.
Boa prática de acompanhamento
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.
