Visão geral do fluxo FGTS
Esta página mostra a ordem recomendada para integrar o produto Saque Aniversário FGTS. Use este fluxo como mapa de implementação antes de consultar os detalhes de cada endpoint.
Fluxo recomendado
1. Autenticar
2. Configurar webhooks
3. Iniciar consulta de saldo
4. Aguardar webhook de saldo
5. Buscar o resultado da consulta
6. Consultar tabelas de taxas
7. Criar simulação
8. Criar proposta
9. Acompanhar a operação
10. Resolver pendências ou cancelar, quando necessário
Antes de começar
-
Obtenha um token válido em
POST /oauth/token. -
Cadastre o webhook de saldo antes de iniciar consultas em
POST /fgts/balance. -
Cadastre o webhook de proposta para acompanhar mudanças de status.
-
Defina o provedor que será usado na operação.
-
Prepare sua aplicação para tratar respostas assíncronas.
Passo a passo da integração
| Etapa | O que fazer | Endpoint principal | O que guardar |
|---|---|---|---|
| Autenticação | Gerar token de acesso | POST /oauth/token |
access_token |
| Webhooks | Registrar URLs de retorno | POST /user/webhook/balance e POST /user/webhook/proposal |
URLs validadas |
| Saldo | Iniciar consulta de saldo | POST /fgts/balance |
documentNumber, provider |
| Retorno do saldo | Aguardar evento de conclusão | Webhook de saldo | balanceId, amount, periods |
| Consulta final | Buscar saldo processado | GET /fgts/balance?search= |
id, amount, periods, status |
| Tabelas | Escolher tabela ativa | GET /fgts/simulations/fees/new |
simulationFeesId |
| Simulação | Calcular condições da operação | POST /fgts/simulations |
id da simulação |
| Proposta | Criar proposta para formalização | POST /fgts/proposal |
id, contractNumber, formalizationLink |
| Acompanhamento | Listar ou detalhar operações | GET /fgts/proposal e GET /fgts/proposal/{id} |
Status atual |
| Pendências | Reapresentar dados ou documentos | Páginas de pendências | ID da proposta |
| Cancelamento | Cancelar proposta elegível | PATCH /fgts/proposal/{id}/cancel |
Status final |
Regra mais importante do saldo FGTS
A consulta de saldo é assíncrona. O POST /fgts/balance inicia o processamento e a resposta imediata esperada é null.
Depois disso:
-
Aguarde o webhook de saldo.
-
Use
GET /fgts/balance?search=para recuperar o resultado. -
Não envie novos
POST /fgts/balanceenquanto a consulta anterior ainda estiver em processamento.
Quando limpar o cache de saldo
Use a limpeza de cache somente quando precisar forçar uma nova consulta para o mesmo CPF e provedor.
O fluxo recomendado é:
DELETE /fgts/balance/cache/{documentNumber}
POST /fgts/balance
Aguardar webhook
GET /fgts/balance?search=<CPF>
Próximas páginas
-
Para implementar a autenticação, consulte Autenticação.
-
Para preparar callbacks, consulte Webhooks.
-
Para iniciar o fluxo operacional, siga para Consulta de Saldo FGTS.
