Validador de Chave NFe

Como funciona a chave de acesso?

São 44 dígitos na chave da NF-e, dispostos num layout fixo: UF (2) + AAMM (4) + CNPJ emitente (14) + modelo (2) + série (3) + número (9) + tipo emissão (1) + cNF (8) + DV (1).

O dígito verificador sai do algoritmo módulo 11, com pesos de 2 a 9 cíclicos aplicados sobre os 43 primeiros dígitos. Além do DV, conferimos o código de UF (lista válida do IBGE) e o modelo (55, 65, 57, 58, 67).

Validação 100% local; nenhuma chave é transmitida.

Chave de acesso NF-e: o identificador fiscal de 44 dígitos das notas eletrônicas

A chave de acesso é a sequência numérica de 44 dígitos que identifica de forma única qualquer documento sob o guarda-chuva dos Documentos Fiscais Eletrônicos brasileiros: NF-e (modelo 55), NFC-e (modelo 65), CT-e (modelo 57) e MDF-e (modelo 58). Ela é gerada pelo ERP emissor no momento da emissão, transmitida à SEFAZ para autorização, impressa como código de barras Code 128 no DANFE e embutida no XML assinado com certificado ICP-Brasil.

Validar uma chave de acesso é o primeiro sanity check antes de consumir qualquer XML de NF-e: chave corrompida implica documento corrompido. A chave carrega o CNPJ do emitente, o mês de emissão, o número do documento, a série e a UF de origem — ou seja, boa parte dos metadados do documento pode ser decodificada offline, sem nenhuma requisição HTTP.

Layout decomposto dos 44 dígitos

O layout oficial publicado pelo ENCAT e consolidado no Manual de Orientação do Contribuinte da SEFAZ divide a chave assim:

cUF (2) + AAMM (4) + CNPJ (14) + mod (2) + serie (3) + nNF (9) + tpEmis (1) + cNF (8) + cDV (1)

• cUF: código IBGE da UF emitente — 35 SP, 33 RJ, 31 MG, 43 RS, 41 PR, 29 BA, 52 GO.
• AAMM: ano e mês de emissão (ex.: 2605 = maio de 2026).
• CNPJ: CNPJ do emitente, 14 dígitos (jamais o destinatário).
• mod: modelo do documento — 55 NF-e, 65 NFC-e, 57 CT-e, 58 MDF-e.
• serie: 3 dígitos, série da nota (0 a 999).
• nNF: 9 dígitos, número sequencial da nota dentro da série.
• tpEmis: tipo de emissão — 1 normal, 2 contingência FS, 4 EPEC, 9 NFC-e offline.
• cNF: 8 dígitos aleatórios, componente anticolisão.
• cDV: 1 dígito verificador, módulo 11.

O algoritmo do dígito verificador passo a passo

O 44º dígito é calculado sobre os 43 primeiros usando módulo 11 com pesos cíclicos. Pseudo-código:

pesos = [2,3,4,5,6,7,8,9]
soma = 0
para i, digito em enumerate(reverso(primeiros43)):
    soma += int(digito) * pesos[i % 8]
resto = soma % 11
dv = 0 se resto em (0, 1) senão 11 - resto

Os pesos giram em ciclo 2,3,4,5,6,7,8,9,2,3,4,... aplicados aos 43 dígitos em ordem reversa. Se o resultado de 11 - resto for 10 ou 11, o DV é forçado a 0. Qualquer divergência entre o DV calculado e o 44º dígito basta para rejeitar a chave como malformada.

Validação offline versus consulta à SEFAZ

A validação offline responde a duas perguntas: (i) a chave é sintaticamente válida (comprimento, dígitos, layout) e (ii) o cDV está consistente. Ela não responde se o documento foi autorizado, se foi cancelado, se houve Carta de Correção (CCe) ou se o destinatário fez manifestação. Para isso, o sistema precisa chamar o web service SEFAZ NfeConsultaProtocolo via SOAP, enviando um envelope envSinc assinado com o certificado ICP-Brasil da empresa.

Para consultas somente-leitura existe um proxy público gratuito: a BrasilAPI expõe GET /api/nfe/v1/{chave} que retorna o status do protocolo sem exigir certificado. A Sefaz mantém também um painel de status em nfe.fazenda.gov.br — uma chave validada localmente pode falhar a consulta se o ambiente SEFAZ estiver fora do ar, o que acontece com frequência em janelas de manutenção noturnas.

Pipeline de validação para integrações ERP

Um pipeline robusto roda quatro etapas sequenciais:

• Comprimento e charset: exatamente 44 dígitos numéricos, sem letras, sem espaços. Rejeitar máscaras como 3526.0123.4567... no parser.
• Decompor componentes: extrair cUF, AAMM, CNPJ, mod, série, nNF, tpEmis, cNF, cDV. Rejeitar se cUF não estiver na tabela IBGE ou se mod não for 55, 65, 57 ou 58.
• Recalcular o DV: aplicar o algoritmo módulo 11 e comparar.
• Consulta SEFAZ opcional: chamar NfeConsultaProtocolo ou BrasilAPI para confirmar o status de autorização (cStat=100 = autorizada, 101 = cancelada, 110 = uso denegado).

Sandbox versus produção, CCe e cancelamento

Todo web service da SEFAZ expõe dois ambientes controlados por tpAmb: 1 = produção e 2 = homologação (sandbox). Chaves geradas em homologação têm cNF fixados pela Sefaz e nunca devem ser processadas pela contabilidade. A Carta de Correção Eletrônica (CCe), regulada pelo Ajuste SINIEF 7/2005, permite ao emitente corrigir erros leves em até 720 horas após a emissão; ela não muda a chave de acesso. O cancelamento exige um evento no RecepcaoEvento em até 24 h para NF-e (algumas UFs estendem o prazo), e só funciona antes do documento circular fisicamente.

Casos de uso e ecossistema

A validação offline é a base de toda integração ERP brasileira. Principais sistemas que usam validação de chave: TOTVS Protheus, SAP Business One, Bling, Conta Azul, Omie, eGestor e Sankhya. No lado dev, libs como node-nfe, nfephp-org e brazilian-utils já trazem validador pronto. Ferramentas de monitoramento fiscal (Receita, SPED, Sintegra) também usam a chave como chave primária de join entre XML, DANFE, livro contábil e extrato bancário.

Pegadinhas e antipadrões frequentes

Um número surpreendente de bugs em integrações fiscais cai em parsing descuidado da resposta SOAP da SEFAZ. O serviço devolve um envelope XML com retConsSitNFe; atributos aninhados podem estar vazios ou ausentes conforme o estado do documento — nunca presuma que um campo existe. Outras armadilhas recorrentes:

• Confiar no prefixo da chave para identificar o tipo de documento — sempre cheque mod, não a URL de origem.
• Concatenar a chave com hífens ou pontos antes de validar; remova não-dígitos primeiro.
• Validar a chave mas pular a verificação da assinatura digital do XML — é a assinatura que amarra a chave ao documento.
• Cachear respostas SEFAZ indefinidamente; uma NF-e pode ser cancelada dias depois, invalidando o cache.

FAQ

É possível validar uma chave NF-e totalmente offline?

Sim — sintaxe, layout e dígito verificador módulo 11 são pura aritmética. A validação offline não confirma autorização ou cancelamento na SEFAZ, mas é o filtro obrigatório de primeira camada.

Existe forma gratuita de consultar o status SEFAZ?

Sim. A BrasilAPI faz proxy do endpoint NfeConsultaProtocolo sem exigir autenticação, retornando o código do protocolo (cStat) e a mensagem da SEFAZ. Para volumes altos, prefira chamada SOAP direta assinada com seu próprio certificado ICP-Brasil.

A chave de uma NFC-e tem o mesmo formato?

Sim. NFC-e é modelo 65 e usa exatamente o mesmo layout de 44 dígitos e o mesmo algoritmo de DV. Só muda o campo mod; tudo o mais é idêntico à NF-e.

O que significa, na prática, o DV não bater?

Significa que a chave foi adulterada, digitada errada ou corrompida na transmissão. Qualquer documento com DV inválido deve ser rejeitado já no gateway: a própria SEFAZ devolve cStat=236 (chave de acesso com dígito verificador inválido).

Como descobrir a UF emitente só pela chave?

Olhe os 2 primeiros dígitos (cUF) e cruze com a tabela de códigos IBGE de UF. Esta ferramenta decodifica automaticamente o cUF para o nome do estado correspondente.