Consulta cadastral

Consulta de CPF

Dados cadastrais oficiais de uma pessoa física a partir do CPF e da data de nascimento.

GET/openapi/v3/consultas/cpf/{cpf}/{nascimento}

Requer os cabeçalhos de assinatura token, timestamp e sign, veja Autenticação.

Devolve os dados cadastrais de um CPF de 11 dígitos mais a data de nascimento: nome, situação cadastral e data de nascimento. A fonte upstream valida CPF e data de nascimento como um par; um par divergente e um CPF inexistente devolvem o mesmo código 10016003, propositalmente indistinguíveis (veja Consulta cadastral).

Requisição GET: o corpo assinado é a string vazia e as duas variáveis de caminho fazem parte do caminho assinado. A resposta é um objeto simples, sem envelope da plataforma.

Parâmetros

Parâmetros de caminho

cpfstringobrigatório
11 dígitos, somente dígitos; não aceita caracteres de formatação.
Exemplo: 40710536828
nascimentostringobrigatório
Data de nascimento, DDMMYYYY, 8 dígitos (ex.: 09011997 = 9 de janeiro de 1997).
Exemplo: 09011997

Respostas

200

Consulta realizada; titular maior de idade. Dados cadastrais da pessoa física.

nistring
CPF, 11 dígitos.
nomestring
Nome completo da pessoa física.
situacaoobject
Situação cadastral.
nascimentostring
Data de nascimento, devolvida no formato original DDMMYYYY.

Erros

Código	HTTP
10016000	400	Formato de CPF inválido (11 dígitos obrigatórios). Verifique caracteres de formatação indevidos ou comprimento errado.
10016001	400	Dígitos verificadores do CPF inválidos. Valide localmente com o algoritmo mod-11 para evitar chamadas inúteis.
10016002	400	Data de nascimento inválida (DDMMYYYY válido obrigatório). Observe a ordem dia-mês-ano e que a data precisa existir.
10016003	400	CPF não encontrado: o CPF não existe ou o CPF e a data de nascimento não coincidem (propositalmente indistinguíveis). Cobrado por chamada.
10016005	422	`LGPD: menor de idade`: titular com 16 a 17 anos. Dados legalmente retidos pela fonte upstream, sem campos pessoais; não repita. Cobrado por chamada.
10016004	451	`LGPD: menor de 16 anos (Lei Felca)`: titular com menos de 16 anos. Dados legalmente retidos, sem campos pessoais; não repita. Cobrado por chamada.
10016006	428	`LGPD: idade nao verificavel - informe a data de nascimento para completar a verificacao`: idade não verificável. A plataforma já reverificou uma vez com a data de nascimento informada; não repita. Não cobrado.
10016020	503	Fonte de dados upstream temporariamente indisponível. Repita com backoff exponencial (inicie em 1 s, dobre até 30 s, adicione jitter); se persistir, contate a plataforma. Não cobrado.

Valores de situacao.codigo

Código	Descrição	Significado
`0`	REGULAR	Regular
`2`	SUSPENSA	Suspensa
`3`	TITULAR FALECIDO	Titular falecido
`4`	PENDENTE DE REGULARIZACAO	Pendente de regularização
`5`	CANCELADA POR MULTIPLICIDADE	Cancelada (inscrição duplicada)
`8`	NULA	Nula
`9`	CANCELADA DE OFICIO	Cancelada de ofício

Nota de negócio: quando codigo não é 0, cabe ao chamador decidir se o fluxo de negócio pode continuar. Emitir uma nota para um titular falecido (3), por exemplo, normalmente justifica um bloqueio; este endpoint informa a situação fielmente e não toma essa decisão por você.

Menores de idade e verificação de idade (LGPD / Lei Felca)

A fonte upstream responde às consultas de CPF pela faixa etária do titular. A plataforma repassa o código de status upstream sem alteração:

Resultado da verificação de idade	HTTP	code	Resposta
Adulto (18 anos ou mais)	200	(nenhum)	Nome, situação cadastral e data de nascimento, como de costume
16 a 17 anos	422	10016005	`{ "code": 10016005, "message": "LGPD: menor de idade" }`, sem nenhum campo pessoal
Menos de 16 anos	451	10016004	`{ "code": 10016004, "message": "LGPD: menor de 16 anos (Lei Felca)" }`, sem nenhum campo pessoal
Idade não verificável	428	10016006	`{ "code": 10016006, "message": "LGPD: idade nao verificavel - informe a data de nascimento para completar a verificacao" }`, sem nenhum campo pessoal

O message das três faixas de bloqueio é o texto legal definido pela fonte upstream (português) e não é traduzido pelo cabeçalho Language; ramifique por code no código.
428 significa que a base upstream não tem data de nascimento do titular e não consegue calcular a idade. A plataforma já reverificou uma vez com a data de nascimento que você informou (dentro da mesma chamada; você não precisa repetir): se a verificação tiver êxito, você recebe o resultado normal conforme a tabela; um 428 persistente significa que a fonte oficial também não conseguiu verificar, e repetir é inútil.
Cobrança: 422 (16 a 17 anos), 451 (menos de 16) e não encontrado / data de nascimento divergente (400 + 10016003) são cobrados por chamada; a fonte upstream também cobra por essas conclusões. 428 (idade não verificável) e indisponibilidade upstream (503) não são cobrados. A plataforma não armazena nada para as faixas de bloqueio. Em 422 / 451 não consulte o mesmo CPF repetidamente: a idade não muda com novas tentativas e cada tentativa é cobrada.
Erros de formato e de dígito verificador são rejeitados localmente, não chegam à fonte upstream e não são cobrados.