--- title: "2026.3 - CNPJ Alfanumérico para Emissões Fiscais" description: "A NFE.io passa a suportar o CNPJ alfanumérico (IN RFB 2.229/2024) por meio de um novo versionamento das suas APIs (próprio de cada produto). Suas versões atuais continuam funcionando sem qualquer alteração." source_url: https://nfe.io/docs/release-notes/2026-3-cnpj-alfanumerico last_updated: 2026-07-03 --- # 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"`). :::warning 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**](/release-notes/2026-3-cnpj-alfanumerico/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**](./documentacao-tecnica) 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.**