Chave de acesso NF-e

Validar

• JavaScript, biblioteca
• Python, biblioteca
• Go, biblioteca13 casos falham
• Ruby, biblioteca12 casos falham
• Rust, biblioteca14 casos falham
• .NET, biblioteca13 casos falham
• Erlang, biblioteca

Valida uma chave de acesso de DF-e com 44 caracteres: NF-e (55), NFC-e (65), CT-e (57), MDF-e (58), CT-e OS (67), GTV-e (64), BP-e (63), NF3e (66) e NFCom (62). O CF-e-SAT (59) não é aceito.

• O cUF deve ser uma UF e o mês (AAMM) deve ser de 01 a 12. O modelo deve ser um dos acima. O tipo de emissão (tpEmis) deve ser um dos que o MOC desse modelo atribui: 1 a 7 e 9 para NF-e e NFC-e; 1, 3, 4, 5, 7 e 8 para CT-e; 1, 5, 7 e 8 para CT-e OS; 1, 2, 7 e 8 para GTV-e; 1, 2 e 3 para MDF-e; 1 e 2 para BP-e, NF3e e NFCom.
• A chave é cUF(2) AAMM(4) CNPJ/CPF(14) mod(2) serie(3) nNF(9) tpEmis(1) cNF(8) cDV(1). A NFCom e a NF3e usam a posição 36 para o nSiteAutoriz e deixam 7 dígitos para o cNF.
• Na NF-e e na NFC-e, o código numérico (cNF) deve passar na regra B03-10 do MOC (sem valores repetidos ou sequenciais da lista de 20 que a regra traz, e diferente do número do documento). A regra vale para os documentos enviados depois da NT 2019.001, e os programas de NF-e costumavam usar um cNF igual ao número do documento antes dela, então uma chave autorizada antes pode ser rejeitada.
• A função rejeita um número de documento com todos os dígitos zero. O dígito verificador é um módulo 11 sobre os primeiros 43 caracteres, com pesos de 2 a 9 repetidos da direita para a esquerda; um resto 0 ou 1 dá dígito verificador 0.
• Os 44 caracteres podem vir agrupados de 4 em 4 por espaço em branco, ., - ou /, sozinhos ou em sequência ("3517 - 0458 ..."). Um separador dentro de um grupo de 4, ou qualquer outro caractere, torna a chave inválida. A função primeiro remove os prefixos Id do XML (NFe, CTe, MDFe, BPe, NF3e, NFCom, em qualquer caixa), com os espaços entre o prefixo e o primeiro grupo.
• As posições 7 a 18 (raiz e ordem do CNPJ do emitente) podem ter as letras de um CNPJ alfanumérico. Os schemas atuais tipam a chave como [0-9]{6}[0-9A-Z]{12}[0-9]{26} (NT Conjunta 2025.001, pacote PL_010 da NF-e), onde os antigos tinham 44 dígitos. Uma letra em qualquer outra posição, inclusive nos dígitos verificadores do CNPJ nas posições 19 e 20, é rejeitada. Minúsculas são lidas como maiúsculas, mas uma letra não ASCII que vira uma letra ASCII em maiúsculas (ſ, ß) é rejeitada. Um emitente CPF tem sempre 11 dígitos completados com zeros à esquerda, então uma letra ali sempre pertence a um CNPJ alfanumérico. A 2.4.0 só aceitava dígitos.
• No dígito verificador, cada caractere vale o seu código ASCII menos 48: o próprio dígito para 0 a 9, e 17 a 42 para A a Z, como no CNPJ alfanumérico.
• A GTV-e (64) aceita tpEmis 1, 2, 7 e 8 (MOC do CT-e, campo D15). O pacote atual PL_CTe_400_RTC só lista 1 e 2, mas 7 (SVC-RS) e 8 (SVC-SP) são mantidos para que chaves autorizadas sob o PL_CTe_400 continuem válidas, já que a chave não carrega versão de schema. É o comportamento da 2.4.0.
• Um valor que não é string retorna false. Os dígitos verificadores do CPF ou CNPJ do emitente não são conferidos, só o dígito verificador da chave (leia a chave com nfeKey.getInfo e confira o taxId com cnpj.isValid, ou os 11 últimos dígitos de um taxId completado com zeros com cpf.isValid).

import { isValidNfeKey } from '@brazilian-utils/brazilian-utils';

isValidNfeKey('35170458716523000119550010000000121000123458'); // true (NF-e, SP)
isValidNfeKey('NFe35170458716523000119550010000000121000123458'); // true (prefixo Id do XML)
isValidNfeKey('CTe35170458716523000119570010000000128000123452'); // true (CT-e autorizado pela SVC-SP)
isValidNfeKey('3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458'); // true (com máscara)
isValidNfeKey('3517.0458.7165.2300.0119.5500.1000.0000.1210.0012.3458'); // true (qualquer um dos caracteres de máscara)
isValidNfeKey('35260712ABC34501DE35550010000001231102030403'); // true (CNPJ alfanumérico 12ABC34501DE35)
isValidNfeKey('35260712ABC34501DEA5550010000001231102030408'); // false (letra na posição 19, dígito verificador do CNPJ)
isValidNfeKey('351 70458716523000119550010000000121000123458'); // false (separador dentro de um grupo de 4)
isValidNfeKey('99170458716523000119550010000000121000123458'); // false (cUF inválido)
isValidNfeKey('35170458716523000119010010000000121000123450'); // false (modelo inválido)
isValidNfeKey('35170458716523000119550010000000128000123455'); // false (o MOC da NF-e não atribui tpEmis 8)
isValidNfeKey('35170458716523000119550010000000121000000003'); // false (cNF 00000000, regra B03-10)

Formatar

• JavaScript, biblioteca
• Python, biblioteca
• Go, biblioteca5 casos falham
• Ruby, biblioteca9 casos falham
• Rust, biblioteca5 casos falham
• .NET, biblioteca5 casos falham
• Erlang, biblioteca

Formata uma chave de acesso de DF-e em grupos de 4 caracteres separados por espaços, como o DANFE e os outros documentos auxiliares a imprimem. Não valida a chave (use nfeKey.isValid).

Todo documento auxiliar imprime a chave nessa forma: o DANFE da NF-e e da NFC-e, o DACTE do CT-e, do CT-e OS e da GTV-e, o DAMDFE do MDF-e, o DABPE do BP-e, o DANF3E da NF3e e o DANFE-COM da NFCom.

• A função agrupa uma chave com máscara ou parcial até onde vão os seus caracteres. options.pad primeiro completa a chave com zeros à esquerda até 44 caracteres ("12345" dá "0000 0000 0000 0000 0000 0000 0000 0000 0000 0001 2345").
• Os prefixos Id do XML (NFe, CTe, MDFe, BPe, NF3e, NFCom) são removidos primeiro, com os espaços nas pontas, do jeito que nfeKey.parse os lê. Até a 2.4.0 o prefixo não era removido, então o dígito de NF3e entrava na chave.
• As letras de um CNPJ alfanumérico são mantidas em maiúsculas nas posições 7 a 18. Uma letra em qualquer outra posição é descartada, e as posições são contadas sobre os caracteres mantidos. A 2.4.0 descartava toda letra.
• Um valor que não é string nem inteiro seguro não negativo (um objeto, true, -1, 1.5, um bigint) retorna uma string vazia em vez de lançar erro. Um número é lido como a string dos seus dígitos. Os caracteres depois do 44º são descartados.
• Retorna uma string vazia quando não há nada para formatar. Até a 2.4.0, um valor sem dígitos com pad: true retornava a máscara toda de zeros.

import { formatNfeKey } from '@brazilian-utils/brazilian-utils';

formatNfeKey('35170458716523000119550010000000121000123458');
// '3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458'

formatNfeKey('35260712abc34501de35550010000001231102030403');
// '3526 0712 ABC3 4501 DE35 5500 1000 0001 2311 0203 0403' (CNPJ alfanumérico)

formatNfeKey('NF3e35170458716523000119550010000000121000123458');
// '3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458' (prefixo do Id do XML)

formatNfeKey('12345'); // '1234 5'

formatNfeKey('12345', { pad: true });
// '0000 0000 0000 0000 0000 0000 0000 0000 0000 0001 2345'

Interpretar

• JavaScript, biblioteca
• Python, biblioteca
• Go, biblioteca4 casos falham
• Ruby, biblioteca6 casos falham
• Rust, biblioteca4 casos falham
• .NET, biblioteca4 casos falham
• Erlang, biblioteca

Remove a formatação de uma chave de acesso de DF-e e mantém só os caracteres da chave, limitados a 44: dígitos, mais as letras de um CNPJ alfanumérico em maiúsculas nas posições 7 a 18.

• A função primeiro remove os prefixos Id do XML (NFe, CTe, MDFe, BPe, NF3e, NFCom), com os espaços nas pontas. O prefixo sai primeiro porque NF3e traz um dígito próprio que não faz parte da chave.
• Uma letra em qualquer outra posição é descartada, como qualquer outro caractere fora da chave. A 2.4.0 descartava toda letra.
• Um valor mais curto passa até onde vai, então o agrupamento de uma chave ainda em digitação também é removido. Não confere a chave (use nfeKey.isValid).
• Um número só é lido se for um inteiro seguro não negativo. Número negativo, fracionário, não finito ou inseguro retorna uma string vazia (a 2.4.0 lia os dígitos de qualquer número, descartando sinal e ponto decimal).

import { parseNfeKey } from '@brazilian-utils/brazilian-utils';

parseNfeKey('3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458');
// '35170458716523000119550010000000121000123458'

parseNfeKey('NFe35170458716523000119550010000000121000123458');
// '35170458716523000119550010000000121000123458'

parseNfeKey('3526 0712 abc3 4501 de35 5500 1000 0001 2311 0203 0403');
// '35260712ABC34501DE35550010000001231102030403' (CNPJ alfanumérico)

Decodificar

• JavaScript, biblioteca
• Python, biblioteca
• Go, biblioteca9 casos falham
• Ruby, biblioteca9 casos falham
• Rust, biblioteca
• .NET, biblioteca9 casos falham
• Erlang, biblioteca

Decompõe uma chave de acesso de DF-e em seus campos. Aceita a mesma entrada que nfeKey.isValid e retorna null quando a chave não é válida.

• Campos: stateCode (a sigla da UF, lida do cUF), year (4 dígitos), month (1 a 12), taxId (inscrição federal do emitente), model (o modelo de 2 dígitos como string, como "55"), series (0 a 999) e number (1 a 999999999) como números, emissionType (o código tpEmis, um número), code (o código numérico como string, mantendo os zeros à esquerda) e checkDigit (um número). Um CNPJ alfanumérico mantém as letras em maiúsculas.
• Na NFCom e na NF3e (modelos 62 e 66), code tem 7 dígitos e o resultado também traz authorizationSite (nSiteAutoriz, um número de 0 a 9). Os outros modelos não têm authorizationSite.
• taxId são os 14 caracteres das posições 7 a 20 como estão escritos: um CNPJ numérico, um CNPJ alfanumérico (em maiúsculas) ou um CPF completado com zeros à esquerda. Um taxId com letra é sempre um CNPJ alfanumérico. Um CPF completado e um CNPJ que começa com 000 se parecem, então confira com cpf.isValid (sobre os 11 últimos dígitos) ou cnpj.isValid quando o tipo importar.
• Retorna null exatamente quando nfeKey.isValid retorna false.

import { getNfeKeyInfo } from '@brazilian-utils/brazilian-utils';

getNfeKeyInfo('35170458716523000119550010000000121000123458');
// { stateCode: 'SP', year: 2017, month: 4, taxId: '58716523000119', model: '55',
//   series: 1, number: 12, emissionType: 1, code: '00012345', checkDigit: 8 }

getNfeKeyInfo('35170458716523000119620010000000121000123450');
// { stateCode: 'SP', year: 2017, month: 4, taxId: '58716523000119', model: '62',
//   series: 1, number: 12, emissionType: 1, code: '0012345', checkDigit: 0, authorizationSite: 0 }

getNfeKeyInfo('35260712ABC34501DE35550010000001231102030403');
// { stateCode: 'SP', year: 2026, month: 7, taxId: '12ABC34501DE35', model: '55',
//   series: 1, number: 123, emissionType: 1, code: '10203040', checkDigit: 3 }

getNfeKeyInfo('invalid'); // null