Erro 400 — CNPJ alfanumérico requer a API v3
Este erro aparece na API de NFS-e (Nota Fiscal de Serviço Eletrônica) ao usar as versões legadas (V1/V2) com CNPJ alfanumérico envolvido. Há duas variantes da mensagem:
Na emissão, quando o prestador (a empresa do companyId) tem CNPJ alfanumérico:
"Prestador com CNPJ alfanumérico requer a API v3; as rotas v1/v2 não suportam CNPJ alfanumérico."
Na consulta por ID, quando a nota envolve CNPJ alfanumérico (prestador, tomador, destinatário ou intermediário):
"Esta nota fiscal contém CNPJ alfanumérico e requer a API v3; as rotas v1/v2 não suportam CNPJ alfanumérico."
Na NF-e/NFC-e o sinal é diferente: não há rejeição na emissão, mas a nota que envolve CNPJ alfanumérico fica invisível para a V2 — a consulta por ID retorna 404 Not Found e a nota não aparece nas listagens.
Causa
As versões legadas tratam federalTaxNumber como número. Um CNPJ alfanumérico (IN RFB 2.229/2024, em vigor desde julho de 2026) contém letras nas 12 primeiras posições e não pode ser representado como número.
Para não quebrar integrações existentes, as rotas legadas não expõem dados alfanuméricos: a NFS-e responde 400 explicando a causa (a nota existe, mas exige a V3); a NF-e/NFC-e responde 404, como se a nota não existisse para aquela versão.
Como resolver
- Confirme o formato: verifique se há letra em alguma das 12 primeiras posições do CNPJ. Os 2 dígitos finais são sempre numéricos.
- Cadastre a empresa pela V3, se ainda não existir:
POST /v3/companies. Empresas alfanuméricas são invisíveis para as versões legadas. - Troque o endpoint de
/v1/ou/v2/para/v3/(mesmo path nos demais segmentos, mesmas credenciais):
curl -X POST "https://api.nfe.io/v3/companies/{companyId}/serviceinvoices" \
-H "Authorization: SUA_API_KEY" \
-d '{ ... }'
- Prepare o consumidor da resposta: na V3,
federalTaxNumberé semprestring, inclusive para CNPJ numérico. - Consultas e listagens dessas notas também devem migrar para a V3 — as rotas legadas não as entregam.
Não procure flag, whitelist ou liberação manual: não existem. Se a SEFAZ ou a prefeitura ainda não aceitar o formato, a rejeição da autoridade é repassada como veio.
Como prevenir
Detecte o formato antes de escolher a versão. Se o CNPJ tiver letra nas 12 primeiras posições, direcione o fluxo para a V3:
function isAlphanumericCnpj(cnpj) {
return /[A-Z]/.test(String(cnpj).substring(0, 12));
}
Para novas integrações, use a V3 desde o início e trate federalTaxNumber como string em modelos, banco (VARCHAR(14)) e parsers. Isso elimina esta classe de erro.