---
title: "Erro 400 — CNPJ alfanumérico requer a API v3"
description: "A NFS-e retorna 400 quando o prestador tem CNPJ alfanumérico nas rotas v1/v2. Na NF-e/NFC-e, a nota alfanumérica responde 404 na V2. Migre para a V3."
source_url: https://nfe.io/docs/erros/400-cnpj-alfanumerico-requer-v3/
last_updated: 2026-08-19
---

# 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:

```json
"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):

```json
"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

1. 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.
2. 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.
3. Troque o endpoint de `/v1/` ou `/v2/` para `/v3/` (mesmo path nos demais segmentos, mesmas credenciais):

```bash
curl -X POST "https://api.nfe.io/v3/companies/{companyId}/serviceinvoices" \
  -H "Authorization: SUA_API_KEY" \
  -d '{ ... }'
```

4. Prepare o consumidor da resposta: na V3, `federalTaxNumber` é sempre `string`, inclusive para CNPJ numérico.
5. 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:

```javascript
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.

## Veja também

- [Migrar a emissão de notas da V2 para a V3](/documentacao/nossa-plataforma/migracao-emissao-v2-para-v3/)
- [Release note 2026.3 — CNPJ Alfanumérico](/release-notes/2026-3-cnpj-alfanumerico/)
- [CNPJ Alfanumérico — documentação técnica](/release-notes/2026-3-cnpj-alfanumerico/documentacao-tecnica/)