CNPJ Alfanumérico — Consultas

Este guia detalha o comportamento do CNPJ alfanumérico nas APIs de consulta. O princípio de versionamento, os contratos JSON, webhooks, códigos de status e o checklist de migração estão na Documentação técnica. Para as APIs de emissão e distribuição, veja Emissões / DF-e.

Visão geral das Consultas

As Consultas da NFE.io abrangem dois produtos, tratados nesta página:

• Consulta de Notas — lookup de uma NF-e emitida pela chave de acesso.
• Consulta de Pessoa Jurídica (CNPJ) — dados cadastrais de um CNPJ (basicInfo, inscrições estaduais), nos endpoints /v2/legalentities/*.

Diferente da emissão, a Consulta é um lookup read-only sobre dados que a Receita Federal e as SEFAZ já publicaram.

Versionamento das Consultas em estudo

Estamos estudando uma forma de versionar de modo uniforme todas as APIs de Consulta (CNPJ, Inscrição Estadual etc.). Hoje, em homologação, o suporte ao CNPJ alfanumérico está disponível para teste nas rotas atuais — mas isso é um ambiente de testes, não o contrato definitivo. Quando o modelo de versionamento for definido, a rota/versão que carregará o alfanumérico em produção será comunicada. Não cravamos hoje que o alfanumérico permanecerá na rota /v2/.... Veja O que será implementado abaixo.

API de Consulta de Notas (consulta de NF-e)

Endpoint base: https://api.nfe.io/v{version}/lookup

Cenário	Versões atuais	Versão própria (em estudo)
Lookup por chave de acesso numérica	✅ normal	✅ normal
Lookup por chave alfa	400 Bad Request	200 OK (string); 404 se não existir
Scan / busca por CNPJ alfa	400 Bad Request	200 OK; 404 se não existir

API de Consulta de Pessoa Jurídica (CNPJ / legalentities)

Dado de implementação em homologação (homologação aberta a partir de junho/2026)

O comportamento descrito nesta seção reflete a implementação disponível em homologação e serve para você adaptar e testar sua integração. Ele não constitui compromisso formal de produção e pode evoluir. A documentação oficial e permanente da Consulta de Pessoa Jurídica será publicada em momento posterior.

Não confunda com a 5.5. A Consulta de Notas faz lookup de uma NF-e emitida pela chave de acesso. A Consulta de Pessoa Jurídica consulta os dados cadastrais de um CNPJ (basicInfo, inscrições estaduais etc.) nos endpoints /v2/legalentities/*. Apesar do caminho conter legalentities, trata-se da consulta de CNPJ, não de um cadastro de entidades.

Versionamento das Consultas em estudo

Estamos estudando uma forma de versionar de modo uniforme todas as APIs de Consulta (CNPJ, Inscrição Estadual etc.). Por isso, não trate o caminho de versão atual (/v2/...) como o contrato definitivo do CNPJ alfanumérico: a versão/rota que carregará o alfanumérico em produção será comunicada quando o modelo de versionamento for definido. Hoje o suporte a alfa existe apenas em homologação (data.api.legalentities-homolog.nfe.one), para você preparar e testar sua integração. Em produção (legalentity.api.nfe.io), os endpoints aceitam apenas CNPJ numérico; a liberação do alfanumérico em produção ainda não tem data formal.

Endpoint base (produção): https://legalentity.api.nfe.io/v2/legalentities Endpoint base (homologação): https://data.api.legalentities-homolog.nfe.one/v2/legalentities

A autenticação usa a mesma API Key no header Authorization (ou via query param ?apiKey=).

Endpoints afetados

GET /v2/legalentities/basicInfo/{federalTaxNumber}
GET /v2/legalentities/stateTaxInfo/{state}/{federalTaxNumber}
GET /v2/legalentities/stateTaxForInvoice/{state}/{federalTaxNumber}
GET /v2/legalentities/stateTaxSuggestedForInvoice/{state}/{federalTaxNumber}
GET /v2/legalentities/stateTaxInfo/national/{state}/{federalTaxNumber}
GET /v2/legalentities/stateTaxInfo/issue/{state}/{federalTaxNumber}/onlyone

Em homologação, todos aceitam federalTaxNumber numérico ou alfanumérico. Para CNPJ alfanumérico, envie o identificador sem pontuação (apenas letras e dígitos, 14 caracteres) — o formato com máscara (##.###.###/####-##) retorna 404 para alfa. A detecção é automática: a API identifica se o identificador contém letras e seleciona o caminho de consulta apropriado.

Comportamento

Cenário (basicInfo)	Status	Observação
CNPJ numérico encontrado	200	Sem mudanças
CNPJ numérico ausente do cache	200 (após consulta real-time)	Fallback existente preservado
CNPJ alfa encontrado em cache	200	Novo — em homologação; federalTaxNumber como string
CNPJ alfa válido ausente do cache	404	Novo — sem fallback real-time (≠ numérico)
Identificador inválido (tamanho/dígito/caracteres)	400	Validação — ex.: {"errors":[{"message":"cnpj is null, white space or not valid"}]}

• Response: o campo federalTaxNumber é retornado sem caracteres especiais (apenas letras e dígitos). Trate-o sempre como string.
• Sem fallback para alfa: CNPJs alfanuméricos são indexados conforme a Receita Federal os disponibiliza. Se um CNPJ alfa válido não estiver no cache, a API retorna 404 em vez de buscar em tempo real — diferente do numérico, que faz fallback para consulta real-time.
• Correção de zeros à esquerda: CNPJs que iniciam com zero (ex.: 00730444000182) agora são processados corretamente nos endpoints basicInfo.

stateTaxInfo — limitação conhecida em homologação

Para parte dos CNPJ alfanuméricos presentes em cache, o stateTaxInfo ainda pode retornar 500 ao montar a resposta (correção em andamento). Os documentos da massa de teste de stateTaxInfo abaixo respondem 200 normalmente — use-os para validar a Inscrição Estadual e não assuma o caminho como totalmente estável até o aviso de conclusão.

A adaptação de código (tipo string/VARCHAR(14), regex ^[A-HJ-NPRT-Z0-9]{12}[0-9]{2}$, normalização para maiúsculas e tratamento do 404) é a mesma do checklist da seção 8 da Documentação técnica.

Massa de testes em homologação

Host: https://data.api.legalentities-homolog.nfe.one

basicInfo — GET /v2/legalentities/basicInfo/{federalTaxNumber}:

V8SLYY68000157   PD8R3RYW000119   4Z5NMJ68000113   6S1Y9YBN000174
5W8DZV0E000117   64687957000130   670E5Z9W000118   75BZ6PW0000135
8K9X8744000138   A74MVL9LS6GG49   D7GMJ1VJ000131   E3D674YY000165
E3D674YY1SWJ28   G9J47ZWV000155   GHB4W0HR000130   H6E5B9YE9D2309
JADKNR6L000116   XVMZLYBE000173

stateTaxInfo — GET /v2/legalentities/stateTaxInfo/{state}/{federalTaxNumber}:

CNPJ	UF
KGKG99WE000159	SP
KGKG99WE9PAG10	SE
615ZKJ37000100	SC
615ZKJ37G4TP78	RS
NH556LTV000134	RR

Exemplos cURL

# Produção (numérico) — segue funcionando normalmente
curl --location 'https://legalentity.api.nfe.io/v2/legalentities/basicInfo/14380200000121' \
  --header 'Authorization: <apiKey>'

# Homologação (alfanumérico) — disponível apenas em homologação por enquanto
curl --location 'https://data.api.legalentities-homolog.nfe.one/v2/legalentities/basicInfo/670E5Z9W000118' \
  --header 'Authorization: <apiKey>'

curl --location 'https://data.api.legalentities-homolog.nfe.one/v2/legalentities/stateTaxInfo/SP/KGKG99WE000159' \
  --header 'Authorization: <apiKey>'

Próximas etapas: o suporte completo ao alfanumérico em stateTaxInfo/* e em Regime Tributário ainda está em andamento e será comunicado quando concluído.

O que será implementado

O suporte ao CNPJ alfanumérico nas Consultas seguirá o mesmo princípio de não-quebra já adotado na emissão. O que está planejado (e ainda não vale como contrato até comunicação formal):

• Versionamento uniforme das Consultas. As versões numéricas atuais serão congeladas (resposta idêntica à de hoje, CNPJ como número), e o CNPJ alfanumérico passará a viver numa versão alfa-aware dedicada, que devolve o federalTaxNumber sempre como string.
• Fronteira de versão. Consultar um CNPJ com letras numa versão atual (numérica) retornará 400 Bad Request, orientando o uso da versão alfa-aware. Na versão alfa-aware, a consulta retorna o dado (200) ou 404 Not Found se o registro não existir.
• Garantia de não-quebra. Integrações atuais que só usam CNPJ numérico continuam funcionando sem qualquer alteração; um mecanismo de verificação de contrato impede mudanças acidentais nas versões antigas.
• Correção do stateTaxInfo alfanumérico. A limitação conhecida em homologação (alguns CNPJ alfa em cache retornando 500 no stateTaxInfo) está em correção, para responder 200 com os dados de Inscrição Estadual.

Prazo de referência: a Receita Federal cadastra o 1º CNPJ alfanumérico em 01/08/2026 (IN RFB nº 2.229/2024). Use a homologação para preparar e validar sua integração antes disso.