--- title: "Migrar a emissão da V2 para a V3 (CNPJ alfanumérico)" description: "Migre a emissão de NF-e, NFC-e e NFS-e da V2 para a V3 para suportar CNPJ alfanumérico. Contratos antes/depois, mapeamento de campos e checklist." source_url: https://nfe.io/docs/documentacao/nossa-plataforma/migracao-emissao-v2-para-v3/ last_updated: 2026-08-19 --- # Migrar a emissão da V2 para a V3 (CNPJ alfanumérico) A V3 das APIs de emissão aceita CNPJ alfanumérico (IN RFB 2.229/2024) e devolve `federalTaxNumber` sempre como `string`. Migre se você emite NF-e (Nota Fiscal Eletrônica de produto), NFC-e (Nota Fiscal de Consumidor Eletrônica) ou NFS-e (Nota Fiscal de Serviço Eletrônica) e precisa atender empresas com CNPJ contendo letras. A Receita Federal emite CNPJs nesse formato desde julho de 2026. Se você trabalha apenas com CNPJs numéricos, não precisa migrar: as versões legadas (V1/V2) continuam congeladas e funcionando como hoje. ## Por que migrar As versões legadas não trabalham com CNPJ alfanumérico, e cada API sinaliza isso de um jeito: - **NFS-e**: emitir pela V1/V2 quando o **prestador** (a empresa do `companyId`) tem CNPJ alfanumérico retorna [`400 Bad Request`](/erros/400-cnpj-alfanumerico-requer-v3/) com a mensagem `Prestador com CNPJ alfanumérico requer a API v3; as rotas v1/v2 não suportam CNPJ alfanumérico.` Consultar por ID uma nota que envolva CNPJ alfanumérico também retorna `400`, indicando que a nota existe e exige a V3. - **NF-e/NFC-e**: uma nota que envolva CNPJ alfanumérico (emitente ou destinatário) é **invisível para a V2** — a consulta por ID retorna `404 Not Found` e a nota não aparece nas listagens. O risco de não migrar é operacional: qualquer cliente seu que abra uma empresa a partir de julho de 2026 pode receber um CNPJ alfanumérico. Sem a V3, você não emite para essa empresa nem acessa as notas dela pelas rotas legadas. ## Antes de começar - Cadastre a empresa emitente pela **V3 da API de Empresas** (`POST /v3/companies`). Empresa com CNPJ alfanumérico só existe para consumidores V3. - Use as mesmas credenciais de API. Não há chave nova, flag ou liberação manual. - Valide em homologação: a SEFAZ aceita CNPJ alfanumérico de teste desde 06/04/2026. ## Diferenças em alto nível - **Path da URL**: troque `/v2/` (ou `/v1/`, na NFS-e) por `/v3/` nos endpoints de emissão. - **Tipo do `federalTaxNumber` na resposta**: sempre `string` na V3, mesmo para CNPJ numérico. Nas versões legadas, valores numéricos são `number`. - **Tipo na requisição**: a V3 aceita `string` (recomendado) ou `number` (compatibilidade na entrada). - **Chave de acesso da NF-e**: com emitente alfanumérico, o dígito verificador usa Módulo 11 com ASCII−48 (NT Conjunta ENCAT 2025.001). A NFE.io gera a chave automaticamente — nenhuma ação sua. - **Webhooks**: o payload acompanha a versão da API em que a nota foi **emitida** — nota emitida pela V3 chega com `federalTaxNumber` como `string`; nota emitida pelas versões legadas mantém `number` quando o valor é numérico. - **Consultas e listagens legadas**: notas com CNPJ alfanumérico não são entregues pela V1/V2 — na NFS-e o GET por ID responde `400` (com mensagem explicando a causa) e as listagens omitem essas notas; na NF-e/NFC-e o GET responde `404` e as listagens também omitem. Elas existem e aparecem normalmente na V3. :::warning Não há gate na NFE.io: a emissão V3 com CNPJ alfanumérico vai até a SEFAZ ou prefeitura, e a resposta da autoridade é repassada sem mascaramento. Se a autoridade ainda rejeita o formato, você recebe o erro real. ::: ## Mapeamento de campos | Campo (legado) | Campo (V3) | Tipo | Observação | |---|---|---|---| | `issuer.federalTaxNumber` | `issuer.federalTaxNumber` | `number` → `string` | Emitente. V3 aceita `number` na entrada, devolve `string`. | | `buyer.federalTaxNumber` | `buyer.federalTaxNumber` | `number` → `string` | Destinatário da NF-e/NFC-e. Mesma regra do emitente. | | `borrower.federalTaxNumber` | `borrower.federalTaxNumber` | `number` → `string` | Tomador da NFS-e. Tomador alfanumérico não é bloqueado na emissão legada, mas a nota resultante só é entregue pela V3. | | `accessKey` | `accessKey` | `string` → `string` | Já era texto. Passa a poder conter letras nas posições 7–20. | | — (endpoint) | — (endpoint) | path | `/v2/companies/{id}/productinvoices` → `/v3/...` (idem `serviceinvoices` e `consumerinvoices`). | Os demais campos do payload de emissão não mudam entre as versões. ## Exemplos lado-a-lado ### Cenário 1: emitir NFS-e com prestador de CNPJ alfanumérico **Antes (V1/V2) — rejeitado** (a empresa do `companyId` tem CNPJ alfanumérico): ```bash curl -X POST "https://api.nfe.io/v1/companies/{companyId}/serviceinvoices" \ -H "Authorization: SUA_API_KEY" \ -d '{ "borrower": { "federalTaxNumber": 12345678000199 }, ... }' ``` Resposta `400 Bad Request`: ```json "Prestador com CNPJ alfanumérico requer a API v3; as rotas v1/v2 não suportam CNPJ alfanumérico." ``` **Depois (V3) — aceito:** ```bash curl -X POST "https://api.nfe.io/v3/companies/{companyId}/serviceinvoices" \ -H "Authorization: SUA_API_KEY" \ -d '{ "borrower": { "federalTaxNumber": 12345678000199 }, ... }' ``` Na NF-e/NFC-e não há rejeição equivalente na emissão: a nota que envolve CNPJ alfanumérico simplesmente não é exposta pelas rotas V2 (`404` na consulta) — emita e consulte pela V3. ### Cenário 2: parse da resposta **Antes (V2):** ```json { "id": "5f9...", "issuer": { "federalTaxNumber": 12345678000199 }, "status": "Authorized" } ``` **Depois (V3):** ```json { "id": "5f9...", "issuer": { "federalTaxNumber": "12ABC345000A92" }, "accessKey": "35260712ABC345000A92550010000000101000000155", "status": "Authorized" } ``` Ajuste o parser para tratar `federalTaxNumber` como texto. A V3 nunca devolve `number` — o tipo é determinístico, sem union types. ## Checklist de migração - [ ] Trocar o tipo de `federalTaxNumber` em modelos e DTOs de `long`/`int64` para `string`. - [ ] Trocar coluna de banco de `BIGINT`/`NUMERIC(14)` para `VARCHAR(14)`. - [ ] Remover `parseInt`, `padStart(14, '0')` e comparações numéricas aplicadas ao CNPJ antes de saber o formato. - [ ] Atualizar a validação de formato para `[A-HJ-NPRT-Z0-9]{12}[0-9]{2}` ou usar biblioteca oficial de CNPJ da sua linguagem. - [ ] Cadastrar o emitente alfanumérico via `POST /v3/companies`. - [ ] Trocar os endpoints de emissão de `/v2/` (ou `/v1/`) para `/v3/`. - [ ] Preparar o consumidor de webhooks para `federalTaxNumber` como `string` nas notas emitidas pela V3. - [ ] Testar em homologação: emissão alfanumérica na V3; na NFS-e legada, confirmar o `400` na emissão com prestador alfanumérico; na NF-e/NFC-e legada, confirmar o `404` na consulta de nota alfanumérica. ## Cronograma e suporte | Data | Marco | |---|---| | 06/04/2026 | Homologação SEFAZ aceita CNPJ alfanumérico de teste. | | Julho/2026 | Receita Federal emite CNPJs alfanuméricos em produção. **Já vigente.** | | — | V1/V2 continuam suportadas, sem data de descontinuação por esta mudança. | Migre de forma incremental: consulta primeiro, depois cadastro e, por último, emissão. Dúvidas: portal de integradores NFE.io. ## FAQ **Preciso migrar tudo de uma vez?** Não. As versões convivem. Migre fluxo a fluxo, começando pelo que precisa de CNPJ alfanumérico. **Posso mandar `federalTaxNumber` como `number` na V3?** Sim, para CNPJ numérico. A entrada aceita os dois tipos; a resposta é sempre `string`. **Minhas notas antigas mudam?** Não. CNPJs já emitidos continuam numéricos e os dados históricos não são reescritos. Na V3, eles apenas passam a ser expostos como `string`. **A NFS-e alfanumérica funciona em toda prefeitura?** Depende da prefeitura. A NFE.io envia a nota e repassa a resposta real do webservice municipal, sem filtro. ## Veja também - [Release note 2026.3 — comunicado](/release-notes/2026-3-cnpj-alfanumerico/) - [CNPJ Alfanumérico — documentação técnica](/release-notes/2026-3-cnpj-alfanumerico/documentacao-tecnica/) - [Erro 400 — CNPJ alfanumérico requer a API v3](/erros/400-cnpj-alfanumerico-requer-v3/)