---
title: "CNPJ Alfanumérico — Emissões e DF-e"
description: "Comportamento do CNPJ alfanumérico nas APIs de emissão e distribuição: cadastro de empresas, NF-e/NFC-e, NFS-e e Distribuição de DF-e (versões atuais numéricas / novo versionamento alfa-aware, próprio de cada produto)."
source_url: https://nfe.io/docs/release-notes/2026-3-cnpj-alfanumerico/emissoes-dfe
last_updated: 2026-07-03
---

# CNPJ Alfanumérico — Emissões e DF-e

> Este guia detalha o comportamento do CNPJ alfanumérico nos produtos de **emissão** e **distribuição**. O princípio de versionamento ("as versões atuais nunca veem CNPJ alfa; o novo versionamento é quem entende" — lembrando que cada produto tem o seu próprio versionamento), os contratos JSON, webhooks, códigos de status e o checklist de migração estão na [Documentação técnica](/release-notes/2026-3-cnpj-alfanumerico/documentacao-tecnica). Para as APIs de **consulta**, veja [Consultas](/release-notes/2026-3-cnpj-alfanumerico/consultas).

## Mudanças por produto

A regra geral é sempre a mesma, mas cada produto tem suas particularidades. Veja a sua abaixo.

## API de Empresas (cadastro)

**Endpoint base:** `https://api.nfe.io/v{version}/companies`

| Operação | Versão atual (legado) | Novo versionamento (alfa-aware) |
|---|---|---|
| `POST /companies` com CNPJ numérico | `201 Created`, response `number` | `201 Created`, response `string` |
| `POST /companies` com CNPJ alfa | n/a — não pode mandar `string` com letras (`400`) | `201 Created`, response `string` |
| `GET /companies/{id}` de empresa numérica | `200 OK`, `federalTaxNumber: number` | `200 OK`, `federalTaxNumber: string` |
| `GET /companies/{id}` de empresa alfa | **`400 Bad Request`** (requer o novo versionamento) | `200 OK`, `federalTaxNumber: string` |
| `GET /companies?federalTaxNumber=12ABC...` | `400` | `200 OK` |

> **Importante:** uma empresa alfa cadastrada pelo novo versionamento **continua existindo no banco** — ela só é **invisível** para as versões atuais. Se o cliente em uma versão atual tentar consultá-la, recebe `400` (mensagem orientando o novo versionamento). Isso não é bug: é exatamente o princípio "as versões atuais nunca veem alfa" em ação.

## API de NF-e / NFC-e

**Endpoint base:** `https://api.nfe.io/v{version}/companies/{companyId}/productinvoices`

| Cenário | Versão atual | Novo versionamento |
|---|---|---|
| Emissão com `issuer.federalTaxNumber` numérico | ✅ normal | ✅ normal, response `string` |
| Emissão com `issuer.federalTaxNumber` alfa | **rejeitada** na versão atual (a empresa alfa não resolve na V2) | ✅ chave de acesso gerada com DV ASCII−48, XML enviado à SEFAZ |
| Consulta de NF-e emitida no novo versionamento (CNPJ alfa) via endpoint de versão atual | **`404`** | `200 OK`, response `string` |

Alguns pontos que costumam gerar dúvida:

- **Chave de acesso (44 chars)** — quando o emissor tem letras no CNPJ, a chave passa a usar **Módulo 11 com ASCII−48**. Você não precisa se preocupar com isso: a NFE.io gera a chave correta automaticamente.
- **DANFE (PDF)** — foi atualizado para imprimir o barcode da chave alfa. Se você só consome o PDF, não precisa mudar nada.
- **GNRE (PE/ES)** — sem nenhuma mudança de contrato para o cliente.

## API de NFS-e

**Endpoint base:** `https://api.nfe.io/v{version}/companies/{companyId}/serviceinvoices`

| Cenário | Versão atual | Novo versionamento |
|---|---|---|
| Emissão de NFS-e com emissor numérico | ✅ normal | ✅ normal, response `string` |
| Emissão de NFS-e com emissor alfa | **`400 Bad Request`** (orienta o novo versionamento) | ✅ depende da prefeitura aceitar (gate natural) |
| Consulta de NFS-e emitida no novo versionamento (alfa) via versão atual | **`404`** | `200 OK`, response `string` |

> **Atenção, prefeituras:** a adoção do CNPJ alfa varia bastante de um município para outro. Algumas prefeituras já atualizaram seus webservices; outras ainda não. A NFE.io **não filtra** essa resposta — manda a nota para a prefeitura e devolve exatamente o que ela responder. Se a prefeitura ainda rejeita, você recebe o erro como ele vem, sem mascaramento.

## Distribuição de Documentos Fiscais (recebimento de DF-e)

**Endpoint base:** `https://api.nfe.io/v{version}/dfe/inbound`

| Cenário | Versão atual | Novo versionamento |
|---|---|---|
| Nota inbound recebida com CNPJ emissor numérico | ✅ entregue, `number` | ✅ entregue, `string` |
| Nota inbound recebida com CNPJ emissor alfa | documento **processado**; `federalTaxNumber` tratado como **texto** | entregue como `string` |
| Webhook de nota numérica | ✅ disparado, `number` | ✅ disparado, `string` |
| Webhook de nota alfa | **formato do payload** segue a versão da assinatura/webhook | entregue como `string` |

> Vale esclarecer: no fluxo de Distribuição o `federalTaxNumber` passou a ser tratado como **texto** — a nota com CNPJ alfanumérico é **processada normalmente**. O **formato e a visibilidade** do que cada assinante recebe seguem a **versão da assinatura/webhook** (não há um número de versão fixo para a Distribuição).