Pular para o conteúdo principal
Ver como Markdown

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 julho de 2026, conforme a IN RFB 2.229/2024. Para suportar essa mudança sem quebrar nenhuma integração existente, a NFE.io disponibiliza a V3 das suas APIs.

A regra é única e previsível em toda a plataforma: suas integrações V1/V2 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 julho/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 julho/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), seu sistema vai quebrar ao encontrar uma empresa com CNPJ alfanumérico. A V2 protege você disso (nunca devolve alfa), mas, para suportar o formato novo, será necessário tratar o campo como texto (string).

Como a NFE.io resolveu — princípio "V2 nunca vê 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 APIComportamento
V1 e V2 (suas integrações atuais)Congeladas. Continuam funcionando exatamente como hoje. Recebem e devolvem CNPJ apenas como número. Nunca vão expor um CNPJ alfanumérico.
V3 (nova)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árioAntes (hoje)Depois (V2 mantida)Depois (V3 nova)
Cadastrar empresa com CNPJ numérico✅ funciona✅ funciona igual✅ funciona
Cadastrar empresa com CNPJ alfan/a❌ 404 Not Found✅ aceita e devolve string
Emitir NF-e/NFS-e com emissor alfan/a❌ 400 Bad Request ("Use V3 for alphanumeric CNPJ")✅ emite e devolve string
Receber documento fiscal (Distribuição de Documentos Fiscais) com CNPJ alfan/a🔇 ignorado silenciosamente (não chega no seu V2)✅ aparece, com string
Webhook de nota com CNPJ alfan/a🔇 não é enviado para assinantes V2✅ 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á na V2 e nunca enxerga alfa, ou você migrou para a V3 e tudo vem como texto, de forma consistente.

Datas que você precisa anotar​

DataO que acontece
06/04/2026✅ Ambiente de homologação SEFAZ já aceita CNPJ alfanumérico — você pode testar.
Maio–Junho/2026🚀 NFE.io disponibiliza a V3 das APIs em homologação e produção.
Julho/2026⚠️ Receita Federal começa a emitir CNPJs alfanuméricos em produção. 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. A V2 continua funcionando exatamente como hoje.
  2. Só fique atento se um cliente seu abrir uma empresa nova após julho/2026 — pode ser que o CNPJ dela seja alfanumérico, e nesse caso a V2 vai rejeitar.
  3. Quando precisar suportar esse cliente, migre o fluxo dele para a V3.

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

  1. Migre para a V3 dos endpoints que você usa (cadastro, emissão, distribuição, consulta).
  2. Mude o tipo de federalTaxNumber no seu código de número (long, int64) para texto (string).
  3. Revise armazenamento e índices: se seu banco guarda CNPJ como BIGINT ou NUMERIC(14), troque por VARCHAR(14) (ou tipo equivalente).
  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 a versão V3 (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 SEFAZ ainda não autoriza CNPJ alfa em produção, sua emissão V3 com CNPJ alfa vai chegar até a SEFAZ e ser rejeitada pela própria SEFAZ (você recebe a resposta real, cStat=215).
  • Quando a SEFAZ liberar o XSD alfa em produção, o sistema passa a autorizar (cStat=100) automaticamente — 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 clientes V1/V2 — 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 com mensagem clara explicando que você precisa usar a V3.

✅ Sem prazo forçado de migração — V1/V2 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 à V3 em homologação se quiser testar antes de julho/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 julho/2026.
  2. Sua integração atual (V1/V2) continua funcionando — só não enxerga CNPJ alfa.
  3. Quando precisar suportar CNPJ alfa, migre para a V3 e troque number por string.
  4. Sem flag, sem espera, sem regressão.

NFE.io

A NFE.io é uma empresa de tecnologia que fornece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas. Com suas ferramentas, as empresas podem economizar tempo e reduzir erros, aumentando a eficiência e precisão do processo de emissão de notas fiscais.

Um dos principais cases de sucesso da NFE.io é a implementação da solução na empresa de transporte Rodonaves. Com a automatização da emissão e gestão de notas fiscais eletrônicas, a Rodonaves conseguiu reduzir em até 80% o tempo gasto nesse processo, o que se traduziu em uma significativa melhoria na eficiência operacional. Além disso, a empresa também conseguiu eliminar erros e atrasos na emissão de notas fiscais, o que melhorou a relação com seus clientes e aumentou a confiança dos órgãos fiscais.

Outro exemplo é a implementação da NFE.io na empresa de comércio eletrônico, a Loja Integrada. Com a automatização da emissão de notas fiscais, a Loja Integrada conseguiu aumentar a velocidade de emissão de notas em até 10 vezes, o que permitiu que a empresa atendesse a uma maior quantidade de clientes e, consequentemente, aumentar as suas vendas.

Além desses exemplos, a NFE.io também tem outros cases de sucesso com empresas de setores como indústria, construção, varejo e serviços, mostrando a versatilidade e eficácia da sua solução.

Em resumo, a NFE.io é uma empresa de tecnologia que oferece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas, ajudando as empresas a economizar tempo e reduzir erros, melhorando a eficiência e precisão do processo. Com cases de sucesso em diferentes setores, a NFE.io tem se destacado como uma empresa líder em automação fiscal.