--- title: "CNPJ Alfanumérico — Consultas" description: "Comportamento do CNPJ alfanumérico nas APIs de Consulta da NFE.io: Consulta de Notas (NF-e) e Consulta de Pessoa Jurídica (CNPJ / legalentities). Estado atual em homologação e o que será implementado." source_url: https://nfe.io/docs/release-notes/2026-3-cnpj-alfanumerico/consultas last_updated: 2026-07-03 --- # 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](/release-notes/2026-3-cnpj-alfanumerico/documentacao-tecnica). Para as APIs de **emissão** e **distribuição**, veja [Emissões / DF-e](/release-notes/2026-3-cnpj-alfanumerico/emissoes-dfe). ## 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. :::warning 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](#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) :::info 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. :::warning 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 ```http 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`. :::warning `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](/release-notes/2026-3-cnpj-alfanumerico/documentacao-tecnica#8-checklist-de-preparação). ### Massa de testes em homologação Host: `https://data.api.legalentities-homolog.nfe.one` `basicInfo` — `GET /v2/legalentities/basicInfo/{federalTaxNumber}`: ```text 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 ```bash # Produção (numérico) — segue funcionando normalmente curl --location 'https://legalentity.api.nfe.io/v2/legalentities/basicInfo/14380200000121' \ --header 'Authorization: ' # 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: ' curl --location 'https://data.api.legalentities-homolog.nfe.one/v2/legalentities/stateTaxInfo/SP/KGKG99WE000159' \ --header 'Authorization: ' ``` > **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.