Bureau PF Online

Este endpoint consulta os dados cadastrais de um CPF em tempo real, direto na origem, e devolve também a situação cadastral do CPF na Receita Federal.

É a versão online do Bureau PF. Os dois entregam o mesmo envelope e os mesmos campos de identificação; a diferença está em de onde vem o dado e no campo status, que só existe aqui.

Qual dos dois usar

	Bureau PF	Bureau PF Online
Rota	/bureau/natural-person/{CPF}	/bureau-pf-online/{CPF}
Origem do dado	Base consultada pela nossa infraestrutura	Consulta feita na hora, na origem
Campo status	Não devolve	Devolve
Versão na URL	Aceita /bureau/v2/natural-person/{CPF}	Não aceita versão na URL
Parâmetros de query	Aceita	Nenhum — qualquer um devolve 422
Permissão	nextid.bureaus.naturalPersonBureau	nextid.bureaus.naturalPersonBureau.online
Tarifação	Chave própria	Chave própria, separada

Use o Bureau PF Online quando precisar da situação cadastral do CPF, ou quando o dado precisa refletir o estado da origem no momento da chamada. Para as demais consultas de identificação, o Bureau PF atende com custo menor.

🚧 Esta consulta é tarifada à parte

A consulta em tempo real tem custo próprio e é registrada com uma chave de tarifação separada da do Bureau PF. Veja Tarifação.

Request

GET /bureau-pf-online/{CPF}

Parâmetros

Parâmetro	Descrição	Obrigatório
CPF	CPF da pessoa consultada	Sim

O CPF pode ser enviado com ou sem máscara (123.456.789-09 ou 12345678909), sempre com os 11 dígitos, incluindo os zeros à esquerda. Um CPF que não passa na validação do dígito verificador devolve 422 antes de qualquer consulta.

Headers

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

Este endpoint não aceita parâmetros de query

Diferente do Bureau PF, aqui qualquer parâmetro de query devolve 422 — inclusive um nome desconhecido, escrito por engano.

GET /bureau-pf-online/12345678909?legacy=true   → 422
GET /bureau-pf-online/12345678909?qualquer=1    → 422

A recusa é proposital: cada um dos parâmetros aceitos pelo Bureau PF desviaria a chamada para um caminho que não faz a consulta em tempo real, e ela continuaria sendo tarifada como online.

Não há versão na URL

/bureau-pf-online/v2/{CPF} não existe e devolve 404. O campo version do corpo continua respondendo v2, porque descreve o formato do payload entregue, não a versão da rota.

Exemplo Request

curl -i 'https://api.nxcd.app/bureau-pf-online/12345678909' \
  --header 'Authorization: ApiKey SUA_CHAVE_AQUI'

Response

Campo	Descrição	Tipo
id	Identificador único da requisição	String
version	Formato do payload entregue. Sempre v2	String
data	Objeto com o resultado da consulta	Object
data.federalRevenueNumber	CPF consultado, sem máscara	String
data.name	Nome da pessoa	String
data.mothersName	Nome da mãe	String
data.birthdate	Data de nascimento, no formato AAAAMMDD	Number
data.status	Situação cadastral do CPF	String
metadata	Metadados da requisição	Object
metadata.timeSpent	Tempo de processamento da requisição, em milissegundos	Number

data.status

É o campo que distingue este endpoint do Bureau PF: traz a situação cadastral do CPF na Receita Federal, como ela está no momento da consulta.

O valor observado em produção para um cadastro em ordem é "REGULAR".

🚧 Os demais valores ainda não estão documentados

REGULAR é o único valor que confirmamos até aqui. A Receita Federal usa outras situações cadastrais, e elas podem chegar neste campo — a lista completa será publicada nesta página assim que estiver confirmada.

Enquanto isso, não escreva código que dependa da lista de valores. Trate "REGULAR" como o caso em ordem e qualquer outro valor como situação a conferir, em vez de comparar contra uma lista fechada.

Exemplo JSON

Status Code: 200

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "version": "v2",
  "data": {
    "federalRevenueNumber": "12345678909",
    "name": "JOAO DA SILVA",
    "mothersName": "MARIA DA SILVA",
    "birthdate": 19900201,
    "status": "REGULAR"
  },
  "metadata": {
    "timeSpent": 312
  }
}

Quando o CPF não é encontrado

O data vem vazio. A resposta continua sendo 200.

Status Code: 200

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "version": "v2",
  "data": {},
  "metadata": {
    "timeSpent": 240
  }
}

Quando o CPF é de menor de idade

Os dados pessoais vêm mascarados: name vira menor de idade, e mothersName e birthdate viram ****. Atenção ao tipo: mascarado, o birthdate vem como texto, não como número.

Este endpoint aplica o mascaramento sempre — não há como desligá-lo.

Status Code: 200

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "version": "v2",
  "data": {
    "federalRevenueNumber": "12345678909",
    "name": "menor de idade",
    "mothersName": "****",
    "birthdate": "****",
    "status": "REGULAR"
  },
  "metadata": {
    "timeSpent": 298
  }
}

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.naturalPersonBureau.online.
404 Not Found	Foi usada uma versão na URL, como /bureau-pf-online/v2/{CPF}. Esta rota não tem versão.
422 Unprocessable Entity	CPF que não passa na validação do dígito verificador, ou qualquer parâmetro de query na URL.
500 Internal Server Error	Falha inesperada durante o processamento.

‼️ A permissão do Bureau PF não vale aqui

nextid.bureaus.naturalPersonBureau.online é uma permissão própria. Quem tem apenas nextid.bureaus.naturalPersonBureau recebe 401 neste endpoint, mesmo conseguindo chamar o Bureau PF normalmente.

Exemplo de resposta com CPF inválido:

Status Code: 422

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "error": {
    "statusCode": 422,
    "error": "Unprocessable Entity",
    "message": "Invalid Federal Revenue Number"
  }
}

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