E-Social

O aplicativo de Consulta Qualificação Cadastral permite ao usuário verificar se o Cadastro de Pessoa Física (CPF) e o Número de Identificação Social (NIS, também NIT/PIS/PASEP) estão aptos para serem utilizados no eSocial.

A consulta confere os quatro dados juntos — CPF, NIS, nome e data de nascimento — e devolve a divergência encontrada, quando há alguma.

🚧 O corpo é repassado do provedor, sem transformação

O conteúdo de data é o que o provedor devolve, entregue como está dentro do envelope padrão. Três consequências práticas:

• Os nomes dos campos estão em português, no vocabulário do provedor (nome, mensagem, orientacao), e não no camelCase em inglês do resto da API.
• Todo bloco é opcional. Um bloco só aparece quando o provedor tem dado para ele. Nunca assuma que uma chave existe: teste antes de acessar.
• Não há garantia de tipo. Como não há conversão no caminho, o mesmo campo pode chegar como número ou como texto conforme a origem do dado.

Request

GET /esocial-qualificacao-cadastral/v1

Parâmetros

Parâmetro	Descrição	Obrigatório
taxId	CPF	Sim
birthdate	Data de Nascimento	Sim
nis	NIS	Sim
name	Nome	Sim

Os quatro são obrigatórios de verdade: faltando qualquer um deles, a chamada é recusada com 422 e a mensagem Required params: taxId, birthdate, nis and name, antes de qualquer consulta.

TIP

O CPF pode ser passado com ou sem máscara (12345678909 ou 123.456.789-09) e devem ser passados todos os chars, incluindo os zeros à esquerda.

Só o taxId é validado pela API — um CPF que não passa na validação do dígito verificador devolve 422. birthdate, nis e name são repassados ao provedor exatamente como chegaram, sem validação de formato deste lado.

Headers

Authorization: ApiKey <sua-chave-de-api>

Parâmetro de query desconhecido é ignorado

Um parâmetro que não esteja entre taxId, birthdate, nis e name não gera erro: ele é simplesmente ignorado.

Exemplo Request

GET /esocial-qualificacao-cadastral/v1?taxId=12345678909&name=Maria da Silva&birthdate=01/01/2001&nis=00000000000

curl -i -G 'https://api.nxcd.app/esocial-qualificacao-cadastral/v1' \
  --header 'Authorization: ApiKey SUA_CHAVE_AQUI' \
  --data-urlencode 'taxId=12345678909' \
  --data-urlencode 'name=Maria da Silva' \
  --data-urlencode 'birthdate=01/01/2001' \
  --data-urlencode 'nis=00000000000'

Response

Campo	Descrição	Tipo
id	ID único da requisição	String
version	Versão da API	String
data	Objeto com o resultado da busca	Object
data.cpf	CPF consultado	String
data.eSocialQualificacaoCadastral	Objeto com o resultado da busca	Object
data.eSocialQualificacaoCadastral.nome	Nome da pessoa consultada	String
data.eSocialQualificacaoCadastral.dataNascimento	Data de nascimento da pessoa consultada	String
data.eSocialQualificacaoCadastral.cpf	CPF da pessoa consultada	String
data.eSocialQualificacaoCadastral.nis	NIS da pessoa consultada	String
data.eSocialQualificacaoCadastral.mensagem	Mensagem retornada na consulta	String
data.eSocialQualificacaoCadastral.orientacao	Orientação retornada na consulta	String
data.eSocialQualificacaoCadastral.urlComprovante	URL do comprovante da consulta realizada	String
metadata	Objeto com os metadados da requisição	Object
metadata.timeSpent	Tempo da requisição, em milissegundos	Number

A divergência vem em mensagem e orientacao

Não há um campo booleano de "apto" ou "não apto". Quando algum dos quatro dados diverge do cadastro, o provedor descreve a divergência em mensagem e o que fazer a respeito em orientacao.

Exemplos JSON

Veja alguns exemplos em JSON da resposta.

1. Exemplo quando dados encontrados

Status Code: 200

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "version": "v1",
  "data": {
    "cpf": "12345678909",
    "eSocialQualificacaoCadastral": {
      "nome": "Maria da Silva",
      "dataNascimento": "01/01/2001",
      "cpf": "12345678909",
      "nis": "00000000000",
      "mensagem": "O nome existente no cadastro do CPF é : MARIA DA SILVA SANTOS",
      "orientacao": " Verifique os dados digitados. Se estiverem corretos, dirija-se a uma agência do Banco do Brasil ou Correios, entidades autorizadas pela RFB, para regularização do CPF.",
      "urlComprovante": "https://..."
    }
  },
  "metadata": {
    "timeSpent": 10000
  }
}

Headers de resposta

Header	Quando aparece
Nextid-ReqId	Em todas as respostas. Traz o identificador da requisição, o mesmo do campo id do corpo.

Erros

Código	Quando ocorre
401 Unauthorized	Chave de API ausente, inválida, ou sem a permissão nextid.bureaus.eSocial.
404 Not Found	A versão informada na URL não existe. Só v1 é aceita.
422 Unprocessable Entity	Falta taxId, birthdate, nis ou name, ou o CPF não passa na validação do dígito verificador.
500 Internal Server Error	Falha inesperada durante o processamento.

As duas causas de 422 têm mensagens distintas, e a checagem de parâmetro ausente vem primeiro:

Situação	Mensagem
Falta um ou mais dos quatro parâmetros	Required params: taxId, birthdate, nis and name
Os quatro vieram, mas o CPF é inválido	Invalid taxId (CPF)

Exemplo de resposta com parâmetro ausente:

Status Code: 422

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "error": {
    "statusCode": 422,
    "error": "Unprocessable Entity",
    "message": "Required params: taxId, birthdate, nis and name"
  }
}

O formato das respostas de erro está descrito em Códigos HTTP das respostas.

Versões

A única versão é a v1, e ela é a que atende quando a versão é omitida na URL. /esocial-qualificacao-cadastral e /esocial-qualificacao-cadastral/v1 são equivalentes.

Versão	Situação	O que muda
v1	Recomendada	Única versão. É o que responde quando a versão é omitida na URL.

Qualquer outro valor no lugar de v1 devolve 404 com a mensagem API version not found.

Endpoint relacionado

Para conferir nome, nome da mãe e data de nascimento de um CPF direto na Receita Federal, veja o Bureau PF.