Pular para o conteúdo principal
Ver como MarkdownDocs para agentes

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 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.
atenção

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)TipoObservação
issuer.federalTaxNumberissuer.federalTaxNumbernumber → stringEmitente. V3 aceita number na entrada, devolve string.
buyer.federalTaxNumberbuyer.federalTaxNumbernumber → stringDestinatário da NF-e/NFC-e. Mesma regra do emitente.
borrower.federalTaxNumberborrower.federalTaxNumbernumber → stringTomador da NFS-e. Tomador alfanumérico não é bloqueado na emissão legada, mas a nota resultante só é entregue pela V3.
accessKeyaccessKeystring → stringJá 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):

curl -X POST "https://api.nfe.io/v1/companies/{companyId}/serviceinvoices" \
  -H "Authorization: SUA_API_KEY" \
  -d '{ "borrower": { "federalTaxNumber": 12345678000199 }, ... }'

Resposta 400 Bad Request:

"Prestador com CNPJ alfanumérico requer a API v3; as rotas v1/v2 não suportam CNPJ alfanumérico."

Depois (V3) — aceito:

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):

{
  "id": "5f9...",
  "issuer": {
    "federalTaxNumber": 12345678000199
  },
  "status": "Authorized"
}

Depois (V3):

{
  "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​

DataMarco
06/04/2026Homologação SEFAZ aceita CNPJ alfanumérico de teste.
Julho/2026Receita 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​

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.