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 |
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
- Troque a URL base de
v2parav3nas suas chamadas de consulta. - Ajuste o tipo do campo
federalTaxNumberna sua integração: na V3 ele vem como texto de 14 posições, com zeros à esquerda — não converta para número. - 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.
- Teste com um CNPJ alfanumérico em homologação antes de subir para produção.
- 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. Em caso de dúvida, entre em contato com o suporte.