Debitado do seu saldo a cada chamada cobrada. Autenticação pelo header X-API-Key. Veja como obter a chave.
Este endpoint permite consultar informações sobre as parcelas do Bolsa Família de um beneficiário. Usando o Número de Identificação Social (NIS) como chave, você obtém detalhes sobre os valores recebidos e movimentações associadas ao benefício, com flexibilidade para especificar períodos de referência e competência distintos.
A consulta é útil para validar identidades, estruturar análises de risco e crédito, verificar conformidade em processos de onboarding, além de fundamentar decisões de abertura de conta e prevenção a fraudes.
A resposta é estruturada em duas seções principais:
Metadados da Consulta
Incluem identificadores únicos da requisição, versão da API, timestamp de execução e informações sobre o processamento.
Dados do Beneficiário
NIS e CPF: Identificadores do titular
Nome: Nome registrado do beneficiário
Lista de Benefícios: Matriz com detalhes de cada parcela
Cada benefício contém:
Número do registro
Data de competência (mês e ano)
Data de referência (mês e ano)
Valor da parcela
Município e unidade federativa da localização
Também são fornecidos dados complementares como código IBGE do município, região geográfica, país e demais atributos cadastrais.
Schema da resposta (JSON Schema)
JSON Schema
{
"type": "object",
"properties": {
"retorno": {
"type": [
"object",
"null"
],
"properties": {
"cpf": {
"type": [
"string",
"null"
],
"description": "CPF do indivíduo."
},
"nis": {
"type": [
"string",
"null"
],
"description": "Número de Identificação Social."
},
"nome": {
"type": [
"string",
"null"
],
"description": "Nome do indivíduo."
},
"beneficios": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"properties": {
"uf": {
"type": [
"string",
"null"
],
"description": "Unidade Federativa do registro."
},
"valor": {
"type": [
"string",
"null"
],
"description": "Valor da parcela."
},
"municipio": {
"type": [
"string",
"null"
],
"description": "Município referente ao registro."
},
"numeroRegistro": {
"type": [
"integer",
"null"
],
"description": "Número do registro."
},
"dataMesReferencia": {
"type": [
"string",
"null"
],
"description": "Data do mês de referência."
},
"dataMesCompetencia": {
"type": [
"string",
"null"
],
"description": "Data do mês de competência."
}
}
},
"description": "Lista de benefícios consultados."
}
},
"description": "Dados do retorno da consulta."
},
"metaDados": {
"type": [
"object",
"null"
],
"properties": {
"ip": {
"type": [
"string",
"null"
],
"description": "Endereço IP da requisição."
},
"data": {
"type": [
"string",
"null"
],
"description": "Data e hora da consulta."
},
"chave": {
"type": [
"string",
"null"
],
"description": "Chave de acesso da consulta."
},
"usuario": {
"type": [
"string",
"null"
],
"description": "Usuário que realizou a consulta."
},
"mensagem": {
"type": [
"string",
"null"
],
"description": "Mensagem de retorno da consulta."
},
"apiVersao": {
"type": [
"string",
"null"
],
"description": "Versão da API utilizada."
},
"resultado": {
"type": [
"string",
"null"
],
"description": "Status do resultado da consulta."
},
"assincrono": {
"type": [
"boolean",
"null"
],
"description": "Indica se a consulta foi assíncrona."
},
"consultaUid": {
"type": [
"string",
"null"
],
"description": "Identificador único da consulta."
},
"resultadoId": {
"type": [
"integer",
"null"
],
"description": "Identificador do resultado."
},
"consultaNome": {
"type": [
"string",
"null"
],
"description": "Nome da consulta realizada."
},
"enviarCallback": {
"type": [
"boolean",
"null"
],
"description": "Indica se deve enviar callback."
},
"urlComprovante": {
"type": [
"string",
"null"
],
"description": "URL do comprovante gerado."
},
"tempoExecucaoMs": {
"type": [
"integer",
"null"
],
"description": "Tempo de execução em milissegundos."
},
"gerarComprovante": {
"type": [
"boolean",
"null"
],
"description": "Indica se deve gerar comprovante."
}
},
"description": "Metadados da consulta."
}
}
}
Códigos de erro
Código
Mensagem
Quando acontece
400
Requisição Inválida
a requisição está incorreta ou os parâmetros são inválidos.
401
Não Autenticado
o usuário não forneceu as credenciais corretas para acessar o recurso.
403
Não Autorizado
o servidor recebeu a requisição, mas se negou a autorizá-la por conta de saldo indisponível.
404
Não Encontrado
o servidor não encontrou uma representação atual do recurso solicitado.
408
Tempo Esgotado
o servidor não conseguiu retornar a requisição no prazo estabelecido.
500
Falha ao Realizar Consulta
o servidor não conseguiu processar a requisição com sucesso. Por favor, entre em contato com o nosso suporte.
503
Consulta em Manutenção
a consulta requisitada está em manutenção. Por favor, entre em contato com o nosso suporte.
Observações
Uma consulta por requisição: Envie apenas um NIS por chamada de API.
Precisão de datas: Os parâmetros de mês devem ser números entre 01 e 12; anos devem conter exatamente 4 dígitos.
Sem comprovantes: Esta consulta retorna dados informativos e não gera documentos de comprovação.
Formatos de NIS: O sistema aceita o número com ou sem formatação; nenhum ajuste prévio é necessário.
Integração com fluxos internos: O endpoint se integra a rotinas de validação de identidade, análise de risco, decisões de crédito e conformidade regulatória (incluindo LGPD).
Para dúvidas ou suporte técnico, consulte a equipe responsável pelo gateway.
Integrar
OpenAPI (JSON) ↗ — importe a URL
no Postman ou no Insomnia para gerar a coleção com todos os endpoints. Também dá para consultar
pelo chat: conecte via MCP. Esta página em Markdown.