v1

latestOpenAPI 3.0.02026-08-049274312.1 KB

API Beneficiário Final

Consulta API Beneficiário Final

Esta API retorna os beneficiários finais associados a um CNPJ, incluindo dados cadastrais, endereço residencial ou comercial, faixa de renda estimada e status na Receita Federal de cada beneficiário identificado.

TABELA DE CAMPOS DE REQUISIÇÃO

Campo	Descrição	Formato	Obrigatório
IdConsulta	Identificador da consulta. Valor fixo: 635.	string	Sim
CpfCnpj	CNPJ da empresa a ser consultada.	string	Sim

TABELA DE CAMPOS DE RETORNO

Campo	Descrição	Formato
CONSULTA.CODIGORESPOSTA	Código interno da transação.	string
CONSULTA.DATAHORA	Data e hora da consulta.	DD/MM/YYYY HH:MM:SS
CONSULTA.LOGON	Identificador da conta que realizou a consulta.	string
CONSULTA.IDCONSULTA	IdConsulta enviado na requisição.	string
RESPOSTA.CODIGO	Código do resultado: 1 sucesso, 2 não encontrado, 3 erro.	string
RESPOSTA.BENEFICIARIO_FINAL.REGISTRO_N.CNPJ	CNPJ da empresa consultada.	string
RESPOSTA.BENEFICIARIO_FINAL.REGISTRO_N.TIPO_DOCUMENTO	Tipo de documento do beneficiário (F = física, J = jurídica).	string
RESPOSTA.BENEFICIARIO_FINAL.REGISTRO_N.RAZAO_SOCIAL	Razão social da empresa consultada.	string
RESPOSTA.BENEFICIARIO_FINAL.REGISTRO_N.CPF	CPF do beneficiário final.	string
RESPOSTA.BENEFICIARIO_FINAL.REGISTRO_N.NOME	Nome completo do beneficiário final.	string
RESPOSTA.BENEFICIARIO_FINAL.REGISTRO_N.TP_ENDERECO	Tipo de endereço (RESIDENCIAL ou COMERCIAL).	string
RESPOSTA.BENEFICIARIO_FINAL.REGISTRO_N.TP_LOGRADOURO	Tipo de logradouro (ex: RUA, AV).	string
RESPOSTA.BENEFICIARIO_FINAL.REGISTRO_N.LOGRADOURO	Nome do logradouro.	string
RESPOSTA.BENEFICIARIO_FINAL.REGISTRO_N.NUMERO	Número do endereço.	string
RESPOSTA.BENEFICIARIO_FINAL.REGISTRO_N.COMPLEMENTO	Complemento do endereço.	string
RESPOSTA.BENEFICIARIO_FINAL.REGISTRO_N.BAIRRO	Bairro do endereço.	string
RESPOSTA.BENEFICIARIO_FINAL.REGISTRO_N.CIDADE	Cidade do endereço.	string
RESPOSTA.BENEFICIARIO_FINAL.REGISTRO_N.UF	UF do endereço.	string
RESPOSTA.BENEFICIARIO_FINAL.REGISTRO_N.CEP	CEP do endereço.	string
RESPOSTA.BENEFICIARIO_FINAL.REGISTRO_N.FAIXA_RENDA_ESTIMADA	Faixa de renda estimada do beneficiário.	string
RESPOSTA.BENEFICIARIO_FINAL.REGISTRO_N.STATUS_RECEITA	Situação cadastral do beneficiário na Receita Federal.	string

post/beneficiariofinalendrs

Request body

Example request

{
  "Consulta": {
    "IdConsulta": "635",
    "CpfCnpj": "00000000000000"
  }
}

Response

Resposta da consulta.

Código 1: Sucesso.
Código 2: Registro não encontrado.
Código 3: Erro na consulta.

Example response

{
  "CONSULTA": {
    "CODIGORESPOSTA": "83924662",
    "DATAHORA": "16/06/2026 13:22:36",
    "LOGON": "28784",
    "IDCONSULTA": "635"
  },
  "RESPOSTA": {
    "CODIGO": "1",
    "BENEFICIARIO_FINAL": {
      "REGISTRO_1": {
        "CNPJ": "00000000000000",
        "TIPO_DOCUMENTO": "J",
        "RAZAO_SOCIAL": "EMPRESA EXEMPLO LTDA",
        "CPF": "00000000000",
        "NOME": "NOME EXEMPLO",
        "TP_ENDERECO": "COMERCIAL",
        "TP_LOGRADOURO": "RUA",
        "LOGRADOURO": "AVENIDA BRASIL",
        "NUMERO": "100",
        "BAIRRO": "CENTRO",
        "CIDADE": "SAO PAULO",
        "UF": "SP",
        "CEP": "00000000",
        "FAIXA_RENDA_ESTIMADA": "DE 5 A 6 SALARIOS MINIMOS",
        "STATUS_RECEITA": "REGULAR"
      }
    }
  }
}