---
title: "Migrar da Consulta de CNPJ V2 para V3 - NFE.io | Docs"
description: "Checklist para migrar da Consulta de CNPJ V2 (legada) para a V3 (recomendada), com suporte a CNPJ alfanumérico."
source_url: https://nfe.io/docs/documentacao/consultas/pessoa-juridica/migracao-v2-para-v3
last_updated: 2026-07-22
---

# Migrar da V2 para a V3

A V3 substitui a V2 como versão recomendada da Consulta de CNPJ. O motivo principal para migrar é o suporte a **CNPJ alfanumérico** (IN RFB nº 2.229/2024, **em vigor desde julho de 2026** — CNPJs com letras já podem existir em operações reais). Na V2, qualquer consulta com CNPJ alfanumérico é rejeitada com **HTTP `400`** e o código de erro **`40001`**.

## Antes (V2) e depois (V3)

| | V2 | V3 |
| --- | --- | --- |
| URL base | `https://legalentity.api.nfe.io/v2/legalentities/basicInfo/{federalTaxNumber}` | `https://legalentity.api.nfe.io/v3/legalentities/basicInfo/{federalTaxNumber}` |
| CNPJ alfanumérico | Rejeitado com `400` (código `40001`) | Suportado |
| Campo `federalTaxNumber` na resposta | Numérico | Texto (`string`), 14 posições, **zeros à esquerda preservados** |
| Autenticação | Igual | Igual |

:::warning Atenção à comparação de CNPJ na sua aplicação
Na V3, `federalTaxNumber` volta como `"09665359000152"` (string canônica de 14 posições). Se sua aplicação converte esse campo para número, ou compara com valores numéricos vindos da V2 (`9665359000152`, sem zero à esquerda), a comparação passa a falhar silenciosamente. Compare sempre como texto de 14 posições.
:::

## Checklist

1. **Troque a URL base** de `v2` para `v3` nas suas chamadas de consulta.
2. **Ajuste o tipo do campo `federalTaxNumber`** na sua integração: na V3 ele vem como texto de 14 posições, com zeros à esquerda — não converta para número.
3. **Revise comparações e chaves de lookup** que usam o CNPJ: valores vindos da V2 como número não batem com a string canônica da V3 sem normalização.
4. **Teste com um CNPJ alfanumérico** em homologação antes de subir para produção.
5. Nenhuma mudança de autenticação é necessária — a mesma API Key funciona nas duas versões.

## Dúvidas

O restante do contrato de resposta (demais campos, schemas e exemplos) está documentado na [referência da API V3](/desenvolvedores/rest-api/consulta-de-cnpj-v3). Em caso de dúvida, [entre em contato com o suporte](/documentacao/conceitos/introducao#Contato).