---
title: "Consulta de CNPJ V3 - NFE.io | Docs"
description: "Referência da API de Consulta de CNPJ V3: endpoints, parâmetros e contrato alfanumérico pós IN RFB nº 2.229/2024."
source_url: https://nfe.io/docs/documentacao/consultas/pessoa-juridica/consulta-cnpj-v3
last_updated: 2026-07-22
---

# 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](/documentacao/nossa-plataforma/chaves-de-autenticacao).

## 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](./migracao-v2-para-v3).

## 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)](/desenvolvedores/rest-api/consulta-de-cnpj-v3).