Consulta de Saldo FGTS

Como esta etapa entra no fluxo

Use esta página para iniciar a consulta de saldo FGTS, aguardar o retorno assíncrono e buscar o resultado final depois do webhook.

entender por que o retorno imediato do POST é null;
tratar os eventos de sucesso e falha da consulta;
buscar o saldo final com GET /fgts/balance?search=.

Regra prática: envie o POST, aguarde o webhook e só depois consulte o resultado com GET.

Ordem recomendada

POST /fgts/balance
    -&gt; webhook de saldo
    -&gt; GET /fgts/balance?search=&lt;CPF&gt;

O que guardar

id da consulta;
balanceId, quando retornado pelo webhook;
amount;
periods;
provider;
status;
updatedAt.

A consulta de saldo disponível permite verificar o valor disponível para o Saque Aniversário FGTS de um cliente. Este processo é assíncrono, e a resposta à requisição inicial será sempre null, indicando que o processamento está em andamento. O resultado final será enviado através de um webhook, que notificará o sistema quando a consulta estiver concluída. Após receber a notificação via webhook, você pode fazer uma nova requisição GET para obter os dados da consulta.

Endpoint para Consulta de Saldo

URL: https://bff.v8sistema.com/fgts/balance
Método HTTP para Iniciar Consulta: POST
Método HTTP para Consultar Retorno: GET
Autenticação: A requisição deve incluir um token de autenticação válido no header.

Parâmetros de Entrada para POST (Iniciar Consulta)

A solicitação para iniciar a consulta deve conter os seguintes parâmetros no corpo (payload) da requisição:

documentNumber: string
O número do documento do cliente (CPF ou CNPJ), utilizado para identificar o cliente no sistema.
provider: string
Identificador do provedor de dados. Pode ser enviado com os seguintes valores:
- "bms"
- "girotech"

Exemplo de Requisição (POST)

POST /fgts/balance HTTP/1.1 Host: bff.v8sistema.com Authorization: Bearer &lt;access_token&gt; Content-Type: application/json  {   "documentNumber": "12345678900",   "provider": "BMS" }

Resposta Inicial

Devido à natureza assíncrona do processo, a resposta imediata do endpoint será sempre null. Isso indica que a requisição foi recebida com sucesso, mas o processamento da consulta de saldo está em andamento.

Exemplo de Resposta Inicial

{
"solicitacao_id": "01a03fbc-7ba1-7aa2-96e8-228a4ee8c2bc"
}

Notificação via Webhook

Após o processamento da consulta, o sistema enviará uma notificação via webhook contendo o resultado da consulta de saldo. O retorno será enviado para o endpoint de webhook configurado no seu sistema, com as informações detalhadas sobre o status da consulta.

Exemplo de Webhook: Falha na Consulta

{
"type": "balance.status.received.fail",
"timestamp": "2025-09-26T18:53:11.553Z",
"documentNumber": "02634598706",
"provider": "cartos",
"balanceId": "5f1ddfb2-9eda-4571-ac8b-aac801739a84",
"errorMessage": "Instituição Fiduciária não possui autorização do Trabalhador para Operação Fiduciária."
}

Exemplo de Webhook: Sucesso na Consulta

{
"type": "balance.status.received.success",
"documentNumber": "02634598706",
"provider": "cartos",
"balance": "1638.65",
"balanceId": "326166dc-c823-4921-bdae-7b7acd43ba5e",
"installments": [
{
"dueDate": "2026-09-01",
"amount": 210.16
},
{
"dueDate": "2027-09-01",
"amount": 178.79
},
{
"dueDate": "2028-09-01",
"amount": 202.49
}],
"timestamp": "2025-09-26T18:47:06.278Z"
}

Consultar Status Final da Consulta (Método GET)

Após receber a notificação do webhook, você pode fazer uma requisição GET ao mesmo endpoint para obter os dados completos da consulta realizada.

URL: https://bff.v8sistema.com/fgts/balance
Método HTTP: GET
Autenticação: A requisição deve incluir um token de autenticação válido no header.
Parâmetros de Entrada: Para fazer a consulta dos dados da consulta realizada, a requisição GET deve incluir o número do documento do cliente.

Exemplo de Requisição (GET)

GET /fgts/balance?search=&lt;CPF&gt; HTTP/1.1
Host: bff.v8sistema.com
Authorization: Bearer &lt;access_token&gt;
Content-Type: application/json

Resposta da Consulta Final (GET)

A resposta retornada ao fazer a requisição GET após o processamento será os dados completos da consulta de saldo. Caso a consulta tenha sido bem-sucedida, os dados retornados serão como no exemplo a seguir:

{
"data": [
		{
			"id": "5fac9c6f-b21f-4e24-b9cc-f148ab5549b9",
			"documentNumber": "00100200304",
			"partnerId": "0001",
			"status": "success",
			"statusInfo": null,
			"createdAt": "2025-04-24T20:39:51.911Z",
			"updatedAt": "2025-04-24T20:39:51.911Z",
			"amount": 216.92,
			"provider": "bms",
			"periods": [
				{
					"amount": 66.42,
					"dueDate": "2026-04-01"
				},
				{
					"amount": 46.5,
					"dueDate": "2027-04-01"
				},
				{
					"amount": 43.4,
					"dueDate": "2028-04-01"
				},
				{
					"amount": 28.33,
					"dueDate": "2029-04-01"
				},
				{
					"amount": 18.38,
					"dueDate": "2030-04-01"
				},
				{
					"amount": 13.89,
					"dueDate": "2032-04-01"
				}
			]
		}
	],
	"pages": {
		"limit": 10,
		"total": 1,
		"current": 1,
		"hasNext": false,
		"hasPrev": false,
		"totalPages": 1
	}
}

Campos da Resposta

id: id unico de indentificação da consulta.

documentNumber: O número do documento do cliente consultado.
partnerId: Codigo referente ao usuario que iniciou a consulta.
statusInfo será exibido erros como "Institution isn't authorized by the client".
createdAt: Data da criação da consulta.
updatedAt: Data quando o saldo teve o retorno do saldo da consulta.
provider: O provedor de dados utilizado para a consulta.
status: Status da consulta (success ou fail).
amount: valor disponivel na conta FGTS do cliente.
periods: periodos que estão disponiveis para contratação compostos por data de desconto de cada parcela (dueDate) e valor disponivel em cada parcela (amount).

Atenção

O parâmetro provider pode ser enviado com um dos seguintes valores válidos:
- "BMS"
- "GIROTECH"
A resposta null após a requisição POST indica que o processo está em andamento. O status final será fornecido via webhook assim que a consulta for concluída.
A requisição GET deve ser feita somente após receber a notificação do webhook, confirmando que a consulta foi processada.
Certifique-se de configurar corretamente o seu endpoint de webhook para receber as notificações de status da consulta.

Considerações Importantes

A requisição POST deve incluir um token de autenticação válido no cabeçalho Authorization para garantir a segurança da consulta.
A requisição GET é usada para obter os dados da consulta após o processamento. Não é necessário realizar uma novo POST para consultar novamente o saldo.
A consulta pode levar algum tempo para ser processada. Não é necessário fazer novas requisições POST enquanto o status final não for retornado via webhook.

Webhooks

Limpando a consulta de saldo