CNPJ Alfanumérico para Emissões Fiscais

Para quem é este comunicado: clientes NFE.io que emitem NF-e, NFC-e ou NFS-e, ou que consomem nossas APIs de cadastro, distribuição e consulta.

Base regulatória: Instrução Normativa RFB 2.229/2024.

Visão geral

A Receita Federal começará a emitir CNPJs em um novo formato a partir de 01/08/2026 (data do 1º CNPJ alfanumérico cadastrado), conforme a IN RFB 2.229/2024. Para suportar essa mudança sem quebrar nenhuma integração existente, a NFE.io disponibiliza um novo versionamento das suas APIs — próprio de cada produto.

A regra é única e previsível em toda a plataforma: suas versões atuais continuam funcionando exatamente como hoje — elas nunca enxergam um CNPJ alfanumérico. Você só precisa agir se quiser cadastrar, emitir ou receber notas de empresas com CNPJ alfanumérico.

---

O que está mudando

A diferença prática é simples:

• Hoje, um CNPJ é só números (ex.: 12.345.678/0001-99).
• A partir de 01/08/2026, um CNPJ pode conter letras nas primeiras 12 posições (ex.: 12.ABC.345/000A-BC — exemplo ilustrativo).

Os dois últimos dígitos (verificadores) continuam sendo numéricos. As letras I, O, U, Q e F não são usadas, para evitar confusão visual com os dígitos 0 e 1.

Importante: os CNPJs já existentes não mudam. Quem tem CNPJ hoje continua com o mesmo CNPJ. O novo formato vale apenas para empresas que serão cadastradas pela Receita Federal a partir de 01/08/2026 (e, em alguns casos, para inscrições secundárias).

---

Por que isso importa para você

Se a sua aplicação:

• Emite notas fiscais (NF-e, NFC-e, NFS-e) pela NFE.io,
• Cadastra empresas pela nossa API,
• Recebe documentos fiscais (Distribuição de Documentos Fiscais),
• Consulta notas (API de Consulta de Notas),
• Recebe webhooks da NFE.io,

…então o tipo do campo federalTaxNumber muda. Hoje ele chega como número inteiro (12345678000199). Para CNPJs alfanuméricos, ele precisa chegar como texto ("12ABC345000ABC").

Atenção — possível quebra de integração

Se você armazena ou exibe o campo federalTaxNumber como número (long, int64, bigint, etc. — qualquer tipo de armazenamento numérico), seu sistema vai quebrar ao encontrar uma empresa com CNPJ alfanumérico. Suas versões atuais protegem você disso (nunca devolvem alfa), mas, para suportar o formato novo, será necessário tratar o campo como texto (string).

---

Como a NFE.io resolveu — princípio "as versões atuais nunca veem CNPJ alfa"

Para não quebrar nenhum cliente atual, criamos uma regra única, simples e previsível em todas as nossas APIs:

Versão da API	Comportamento
Suas versões atuais	Congeladas. Continuam funcionando exatamente como hoje. Recebem e devolvem CNPJ apenas como número. Nunca vão expor um CNPJ alfanumérico.
Novo versionamento (próprio de cada produto)	Alfa-aware. Aceita CNPJ numérico e alfanumérico. Devolve sempre como texto (string).

Em outras palavras:

Você só precisa fazer alguma coisa se quiser cadastrar, emitir ou receber notas de empresas com CNPJ alfanumérico. Se você só trabalha com CNPJs numéricos legados, nada muda no seu lado.

---

O que muda na prática, por endpoint

Cenário	Antes (hoje)	Depois (versão atual mantida)	Depois (novo versionamento)
Cadastrar empresa com CNPJ numérico	✅ funciona	✅ funciona igual	✅ funciona
Cadastrar empresa com CNPJ alfa	n/a	❌ 400 Bad Request (requer o novo versionamento)	✅ aceita e devolve string
Emitir NF-e/NFS-e com emissor alfa	n/a	❌ rejeitada na versão atual (o erro orienta o novo versionamento; o formato varia por produto)	✅ emite e devolve string
Receber documento fiscal (Distribuição de Documentos Fiscais) com CNPJ alfa	n/a	documento processado; federalTaxNumber tratado como texto	entregue como string
Webhook de nota com CNPJ alfa	n/a	formato do payload segue a versão da assinatura/webhook	entregue como string
Webhook de nota com CNPJ numérico	✅ number	✅ number (igual)	✅ string

Resumo em uma frase: ninguém recebe surpresa. Ou você está nas suas versões atuais e nunca enxerga alfa, ou você migrou para o novo versionamento e tudo vem como texto, de forma consistente.

Consultas (versionamento próprio em estudo)

As APIs de Consulta seguem em trilha própria: o versionamento ainda está em estudo (compatibilização entre as versões), e haverá um versionamento próprio para essa mudança, comunicado quando definido.

Cenário	Versões atuais (mantidas)	Em homologação (versão própria em estudo)
Consultar Pessoa Jurídica (CNPJ) com CNPJ alfa	404 Not Found	aceita e devolve string (apenas para teste)
Consultar nota (NF-e) com chave/CNPJ alfa	404 Not Found	aceita e devolve string

Detalhes e roadmap no guia Consultas.

---

Datas que você precisa anotar

Data	O que acontece
Junho/2026 (sem data definida)	✅ Sefaz / Emissor Nacional abrem o ambiente de homologação para CNPJ alfanumérico — você poderá testar.
1ª quinzena de julho/2026	🚀 NFE.io disponibiliza o serviço (novo versionamento, próprio de cada produto) para CNPJ alfanumérico.
01/08/2026	⚠️ 1º CNPJ alfanumérico cadastrado pela Receita Federal. A partir desse momento, qualquer fluxo de cadastro novo pode trazer um CNPJ com letras.

---

Como você deve se preparar

✅ Se sua integração só lida com CNPJs numéricos (90% dos casos)

1. Você não precisa fazer nada agora. Suas versões atuais continuam funcionando exatamente como hoje.
2. Só fique atento se um cliente seu abrir uma empresa nova a partir de 01/08/2026 — pode ser que o CNPJ dela seja alfanumérico, e nesse caso as suas versões atuais vão rejeitar.
3. Quando precisar suportar esse cliente, migre o fluxo dele para o novo versionamento do produto utilizado.

⚠️ Se você quer estar pronto para CNPJ alfanumérico desde o dia 1

1. Migre para o novo versionamento do produto utilizado nos endpoints que você usa (cadastro, emissão, distribuição, consulta) — lembrando que cada produto tem o seu próprio versionamento.
2. Mude o tipo de federalTaxNumber no seu código de número (long, int64, etc. — qualquer tipo de armazenamento numérico) para texto (string).
3. Analise como o federalTaxNumber é armazenado no seu banco de dados: se hoje ele é guardado como tipo numérico (ex.: BIGINT, NUMERIC(14)), será necessário acomodar texto (ex.: VARCHAR(14) ou equivalente). A decisão de modelagem é sua.
4. Revise comparações e máscaras: CNPJ.padStart(14, '0') ou conversões implícitas para número vão quebrar.
5. Teste em homologação SEFAZ (já disponível) usando os CNPJs alfa de teste publicados pela própria Receita.
6. Atualize seus webhooks para o novo versionamento do produto (resposta sempre string) quando estiver pronto.

💡 Se você não tem certeza

Fale com a equipe de suporte da NFE.io — vamos te ajudar a entender qual versão da API você está usando hoje, e qual é o caminho mais curto para você ficar pronto.

---

Sem flags, sem espera — quando estiver liberado, está liberado

Não temos nenhuma flag interna, whitelist ou liberação manual. A SEFAZ e as prefeituras são o gate natural:

• Enquanto a origem do dado (SEFAZ, no caso de NF-e/NFC-e; a prefeitura, no caso de NFS-e) ainda não autoriza CNPJ alfa em produção, sua emissão com CNPJ alfa pelo novo versionamento chega até a autoridade e é rejeitada por ela — você recebe a resposta real, com o erro definido pela origem do dado (ex.: cStat=215 na NF-e).
• Quando a autoridade competente liberar o formato alfa em produção, a emissão passa a ser autorizada automaticamente (ex.: cStat=100 na NF-e) — sem ninguém apertar nenhum botão na NFE.io.

Isso quer dizer que você não precisa avisar a NFE.io para "liberar" sua conta. Quando o regulador permitir, funciona.

---

Garantias

✅ Zero regressão para suas versões atuais — não tocamos no contrato dessas versões.

✅ CNPJs numéricos existentes continuam funcionando para sempre — em todas as versões.

✅ Você não vai receber erro 500 sem contexto — quando algo for incompatível, a resposta é 400/404 (ou o erro definido pela origem do dado) com mensagem clara explicando que você precisa usar o novo versionamento do produto.

✅ Sem prazo forçado de migração — suas versões atuais não têm data de descontinuação por causa dessa mudança.

---

Próximos passos

1. 📩 Compartilhe este comunicado com os devs e arquitetos que mantêm a integração com a NFE.io.
2. 📖 Consulte a Documentação técnica detalhada para ver os contratos JSON antes/depois, exemplos curl e checklist de migração.
3. 🧪 Solicite acesso ao novo versionamento em homologação se quiser testar antes de 01/08/2026.
4. 💬 Dúvidas: nosso canal de suporte e o time de Customer Success estão preparados para responder. Para discussões técnicas mais profundas, abra ticket no portal de integradores.

---

Em resumo:

1. A Receita Federal vai emitir CNPJ com letras a partir de 01/08/2026.
2. Sua integração atual continua funcionando — só não enxerga CNPJ alfa.
3. Quando precisar suportar CNPJ alfa, migre para o novo versionamento do produto e troque number por string.
4. Sem flag, sem espera, sem regressão.