Guide

Consulta de Saldo FGTS

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"

    • "qi"

    • "cartos"

Exemplo de Requisição (POST) 


POST /fgts/balance HTTP/1.1 Host: bff.v8sistema.com Authorization: Bearer <access_token> 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

null

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",   
"documentNumber": "00000000002",   
"provider": "bms",   
"errorMessage": "Não foi possível consultar o saldo no momento! - Instituição Fiduciária não possui autorização do Trabalhador para Operação Fiduciária.",   
"timestamp": "2025-01-30T13:06:38.656Z" 
}

Exemplo de Webhook: Sucesso na Consulta

{
  "type": "balance.status.received.success",
  "documentNumber": "00000000001",
  "provider": "bms",
  "balance": "585.73",
  "timestamp": "2025-01-30T13:29:15.183Z"
}

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=<CPF> HTTP/1.1
Host: bff.v8sistema.com
Authorization: Bearer <access_token>
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:Onde 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"

    • "QI"

    • "CARTOS"

  • 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.