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

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. Para as APIs de consulta, veja 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çãoVersão atual (legado)Novo versionamento (alfa-aware)
POST /companies com CNPJ numérico201 Created, response number201 Created, response string
POST /companies com CNPJ alfan/a — não pode mandar string com letras (400)201 Created, response string
GET /companies/{id} de empresa numérica200 OK, federalTaxNumber: number200 OK, federalTaxNumber: string
GET /companies/{id} de empresa alfa400 Bad Request (requer o novo versionamento)200 OK, federalTaxNumber: string
GET /companies?federalTaxNumber=12ABC...400200 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árioVersão atualNovo versionamento
Emissão com issuer.federalTaxNumber numérico✅ normal✅ normal, response string
Emissão com issuer.federalTaxNumber alfarejeitada 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 atual404200 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árioVersão atualNovo versionamento
Emissão de NFS-e com emissor numérico✅ normal✅ normal, response string
Emissão de NFS-e com emissor alfa400 Bad Request (orienta o novo versionamento)✅ depende da prefeitura aceitar (gate natural)
Consulta de NFS-e emitida no novo versionamento (alfa) via versão atual404200 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árioVersão atualNovo versionamento
Nota inbound recebida com CNPJ emissor numérico✅ entregue, number✅ entregue, string
Nota inbound recebida com CNPJ emissor alfadocumento processado; federalTaxNumber tratado como textoentregue como string
Webhook de nota numérica✅ disparado, number✅ disparado, string
Webhook de nota alfaformato do payload segue a versão da assinatura/webhookentregue 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).

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.