---
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 da V3 das APIs. Suas integrações V1/V2 atuais continuam funcionando sem qualquer alteração."
source_url: https://nfe.io/docs/release-notes/2026-3-cnpj-alfanumerico
last_updated: 2026-06-14
---

# 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"`).

:::warning 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 API | Comportamento |
|---|---|
| **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ário | Antes (hoje) | Depois (V2 mantida) | Depois (V3 nova) |
|---|---|---|---|
| Cadastrar empresa com CNPJ numérico | ✅ funciona | ✅ funciona igual | ✅ funciona |
| Cadastrar empresa com CNPJ alfa | n/a | ❌ **404 Not Found** | ✅ aceita e devolve `string` |
| Emitir NF-e/NFS-e com emissor alfa | n/a | ❌ **400 Bad Request** ("Use V3 for alphanumeric CNPJ") | ✅ emite e devolve `string` |
| Receber documento fiscal (Distribuição de Documentos Fiscais) com CNPJ alfa | n/a | 🔇 **ignorado silenciosamente** (não chega no seu V2) | ✅ aparece, com `string` |
| Webhook de nota com CNPJ alfa | n/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

| Data | O 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**](./documentacao-tecnica) 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.**