Consulta cadastral

Visão geral

Consulte dados cadastrais oficiais brasileiros pelo número de identificação do contribuinte:

Os dois endpoints são GET: o corpo assinado é a string vazia e todas as variáveis de caminho (CNPJ / CPF / data de nascimento) fazem parte do caminho assinado, veja Autenticação. As respostas são objetos simples (sem envelope da plataforma); erros de negócio são um objeto simples {code, message}.

Por que o CPF exige data de nascimento

A fonte upstream valida CPF e data de nascimento como um par (semântica da Receita Federal); o CPF sozinho não devolve nada. Um par divergente e um CPF inexistente devolvem o mesmo código de erro: são propositalmente indistinguíveis, caso contrário o endpoint se tornaria uma ferramenta para descobrir a data de nascimento de terceiros.

Pré-requisitos (uma única vez)

1. Credencial da aplicação: solicite uma aplicação e receba o app_secret. Ele é exibido apenas uma vez; guarde-o com segurança.
2. Assinatura da API: a plataforma concede à sua aplicação acesso aos endpoints necessários (a chave de escopo é o caminho do endpoint).

Endpoints

Modelo de erros

Duas formas de erro

Erros de negócio, de requisição e da fonte upstream (HTTP 400 / 422 / 428 / 451 / 503) são devolvidos como objeto simples:

{ "code": 10016003, "message": "CPF not found" }

Erros da camada de autenticação (HTTP 401 / 403 / 429) são produzidos pelo gateway da plataforma antes de a requisição chegar à API e usam o envelope da plataforma:

{ "success": false, "errorType": 1, "code": 10009005, "message": "API not subscribed, please subscribe before calling" }

Nota: seu tratamento de erros precisa aceitar as duas formas. Uma regra robusta: interprete o corpo como JSON, leia code de qualquer uma das formas e trate success=false ou HTTP >= 400 como falha.

Códigos de erro de negócio

Erros de formato e de dígito verificador são rejeitados localmente pela plataforma e nunca chegam à fonte upstream: não consomem cota nem são cobrados.

Convenção de responsabilidade: 10016000 a 10016003 e 10016010 a 10016012 são problemas do chamador; 10016004 a 10016006 são bloqueios legais de terceiros; 10016020 é indisponibilidade de terceiro; HTTP 500 + 10001000 é falha da plataforma.

Cobrança: 10016003 (não encontrado / data de nascimento divergente), 10016004 (menos de 16 anos) e 10016005 (16 a 17 anos) são cobrados por chamada; 10016006 (idade não verificável), 10016020 (upstream indisponível) e os erros de formato / dígito verificador rejeitados localmente não são cobrados. As faixas etárias estão detalhadas na página Consulta de CPF.

Erros de autenticação e autorização

Orientação de repetição: 401 e 403 são erros de configuração; repetir sem corrigir é inútil e pode disparar o limite de taxa. 429 e 503 (10016020) podem ser repetidos com backoff. 422 / 428 / 451 são bloqueios legais; repetir é inútil. Para 500, contate a plataforma com o timestamp e o caminho da requisição que falhou.

Referência rápida de status HTTP

Proteção de dados

O CPF é dado pessoal de pessoa natural e está sujeito à LGPD (Lei 13.709/2018):

• A plataforma não persiste os resultados das consultas de CPF; toda consulta vai à fonte em tempo real.
• Valores completos de CPF nunca entram nos logs da aplicação; são mascarados.
• As variáveis de caminho no log de chamadas passam por HMAC antes do armazenamento; nenhum texto em claro é retido.
• A fonte upstream retém legalmente os dados de menores de idade; a plataforma repassa os status 451 / 422 / 428 sem alteração e não armazena nada. 451 / 422 são cobrados por chamada, 428 não; veja Menores de idade e verificação de idade na página Consulta de CPF.

Espera-se que os chamadores observem o mesmo princípio da necessidade mínima: consulte apenas quando houver base legal de negócio (como a emissão de notas) e não retenha dados pessoais além do que o negócio exige.

Localização das respostas

O campo message segue o idioma da requisição: o cabeçalho Language (en / pt / es / zh) tem precedência, depois Accept-Language (aceita pt-BR e valores q). Sem cabeçalho de idioma, as respostas usam português (pt) por padrão.

Para decisões programáticas use sempre o code numérico e valores enumerados como situacao.codigo; nunca compare textos descritivos. O message das faixas de bloqueio da LGPD é o texto legal em português e não é traduzido.

Checklist de integração

1. Obtenha o app_secret e confirme que os dois endpoints estão assinados.
2. Chame com um CNPJ real: HTTP 200, ni ecoa a entrada, situacaoCadastral.codigo é 2.
3. Chame com um CPF real + data de nascimento: HTTP 200, nascimento ecoa a entrada.
4. Caso negativo: CPF correto com data de nascimento errada devolve 400 + 10016003 (mesmo código de não encontrado).
5. Caso negativo: CNPJ / CPF com dígitos verificadores errados devolve 400 + 10016011 / 10016001 (rejeitado localmente, não cobrado).
6. Caso negativo: data de nascimento como 1997-01-09 ou 31021997 devolve 400 + 10016002.
7. Caminhos de falha: chame com sign errado (401 + 10009003); chame um endpoint não assinado (403 + 10009005).
8. Compatibilidade do parser: garanta que seu cliente trata 422 / 428 / 451 / 503 como falha e lê o corpo simples {code, message} (esses status não podem ser disparados com dados de teste; só aparecem em produção com CPFs reais de menores).

Solução de problemas

1. Uma requisição GET não concatenou o corpo como a string vazia "" (usou um objeto vazio ou texto de espaço reservado);
2. path sem o prefixo /openapi, ou incluindo a query string;
3. O segmento da data de nascimento ficou de fora da assinatura do CPF; as duas variáveis de caminho precisam ser assinadas;
4. sign enviado em maiúsculas (deve ser hex minúsculo);
5. O timestamp usado na concatenação difere do cabeçalho (gerado de novo entre os dois);
6. Um CNPJ formatado cuja / dividiu o caminho.

Recalcule primeiro os valores fixos do exemplo de assinatura em Autenticação; quando sua implementação local conferir, passe a inspecionar os parâmetros da requisição real.