Consulta de CNPJ — V3 (recomendada)

A V3 é a versão recomendada e atual da API de Consulta de CNPJ. Ela aceita CNPJ tanto no formato numérico quanto no formato alfanumérico — padrão da IN RFB nº 2.229/2024, em vigor desde julho de 2026, o que significa que CNPJs com letras já podem existir em operações reais.

Endpoints

A V3 tem dois endpoints, ambos sob a tag LegalEntities.

Dados básicos do CNPJ

Método	URL
GET	https://legalentity.api.nfe.io/v3/legalentities/basicInfo/{federalTaxNumber}

Parâmetros:

Nome	Local	Obrigatório	Descrição
federalTaxNumber	path	Sim	CNPJ, numérico ou alfanumérico.
updateAddress	query	Não	Atualiza o endereço com base nos Correios. Padrão: true.
updateCityCode	query	Não	Quando updateAddress=false, atualiza apenas o código da cidade. Padrão: false.

Inscrição Estadual por CNPJ

Método	URL
GET	https://legalentity.api.nfe.io/v3/legalentities/stateTaxInfo/{state}/{federalTaxNumber}

Parâmetros:

Nome	Local	Obrigatório	Descrição
state	path	Sim	Código do IBGE do estado a consultar.
federalTaxNumber	path	Sim	CNPJ, numérico ou alfanumérico.

Formatos de entrada aceitos

A V3 normaliza o CNPJ recebido automaticamente — você não precisa higienizar a entrada:

• Pontuação (., /, -) é aceita e removida.
• Letras minúsculas são convertidas para maiúsculas.
• CNPJs numéricos com menos de 14 posições são completados com zeros à esquerda (ex.: 9665359000152 vira 09665359000152).

Autenticação

Mesma autenticação por API Key das demais APIs de consulta da NFE.io — HTTP Header (Authorization ou X-NFEIO-APIKEY) ou query string (api_key). Veja chaves de autenticação.

Códigos de status

Status	Significado
200	Sucesso na requisição
400	Algum parâmetro informado não é válido
401	API Key da conta não é válida
403	API Key não tem permissão para acesso
404	Empresa não encontrada para o CNPJ informado (apenas em basicInfo)
500	Erro no processamento

Contrato de resposta

Na V3, o campo federalTaxNumber é retornado como texto (string), não como número — é esse ajuste de tipo que permite acomodar CNPJ alfanumérico. O valor vem sempre na forma canônica de 14 posições, com zeros à esquerda preservados (ex.: "09665359000152").

Se você vem da V2, veja as diferenças de contrato no guia de migração.

Documentação completa da API

A referência completa de campos, schemas e exemplos da V3 está na documentação da API de Consulta de CNPJ (V3).