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`	`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/balance enquanto 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.

Inicio

Checklist de integração FGTS