Chave de acesso NFS-e

Verifica se a chave de acesso de uma NFS-e nacional, a Nota Fiscal de Serviço eletrônica do Sistema Nacional NFS-e, é válida.

• A chave é um bloco único de 50 caracteres, Cód.Mun.(7) Amb.Ger.(1) Tipo de Inscrição Federal(1) Inscrição Federal(14) nNFSe(13) AAMM(4) Cód.Num.(9) DV(1), todos dígitos exceto um CNPJ alfanumérico na Inscrição Federal.
• O literal NFS que o atributo Id de infNFSe coloca antes da chave é retirado, junto com os espaços nas extremidades.
• O DANFSe imprime a chave em um único bloco, então ela não tem máscara impressa. As fronteiras entre os 8 campos aceitam os caracteres de máscara que o isValidCpf lê (espaço, ., - ou /, isolados ou em sequência), enquanto um separador dentro de um campo invalida o valor.
• O código do município precisa começar com um código IBGE de UF; ele não é consultado na tabela do IBGE.
• O ambGer precisa ser 1 (o sistema do município) ou 2 (o Sistema Nacional NFS-e), e o tipo de inscrição 1 (um CPF, preenchido com 000 à esquerda) ou 2 (um CNPJ, numérico ou alfanumérico), com um CPF ou CNPJ cujos próprios dígitos verificadores sejam válidos. Letras só são aceitas em um CNPJ, e minúsculas são lidas como maiúsculas, como o isValidCnpj com { version: 2 } as lê.
• O nNFSe não pode ser todo de zeros e o mês precisa estar entre 01 e 12.
• O dígito verificador é um módulo 11 sobre os 49 primeiros caracteres, pesos de 2 a 9 ciclando a partir da direita, em que resto 0 ou 1 dá 0. Uma letra vale o seu código ASCII menos 48 (A vale 17). Nenhum documento oficial diz isso: as notas técnicas 001 a 009 da NFS-e, o Anexo I e as Perguntas e Respostas de 08/09/2026 são omissos, e a Nota Técnica Conjunta 2025.001, cuja regra do ASCII menos 48 vale para a chave dos DF-e, lista os documentos que abrange (NF-e, NFC-e, CT-e, CT-e OS, GTV-e, MDF-e, BP-e, BP-e TM, NF3e e NFCom) sem a NFS-e. A regra vem por analogia com essa NT e com os próprios dígitos verificadores do CNPJ.
• As letras seguem o TSIdNFSe do pacote de esquemas de 27/07/2026, nas posições da Inscrição Federal (10 a 23). O pacote de produção de 09/02/2026 ainda tipa a chave como [0-9]{50}.
• Os modelos municipais de NFS-e que não são o padrão nacional estão fora do escopo.

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

isValidNfseKey('35503082258716523000119000000000001226011357924683'); // true (emitente com CNPJ, SP)
isValidNfseKey('NFS35503082258716523000119000000000001226011357924683'); // true (prefixo Id do XML)
isValidNfseKey('43149021100040364478829000000000105725120484407255'); // true (emitente com CPF, RS)
isValidNfseKey('35503082212ABC34501DE35000000000001226091357924682'); // true (emitente com CNPJ alfanumérico)
isValidNfseKey('35503082258716523000119000000000001226011357924684'); // false (dígito verificador)
isValidNfseKey('3550308 2 2 58716523000119 0000000000012 2601 135792468 3'); // true (separadores entre os campos)

Remove tudo o que não é dígito ou letra de um CNPJ alfanumérico da chave de acesso de uma NFS-e nacional e limita o resultado a 50 caracteres.

• As letras ficam em maiúsculas, como faz o parseCnpj com { version: 2 }, e as letras antes do primeiro dígito são descartadas, inclusive o prefixo NFS do atributo Id do XML, já que a chave começa com dígitos. O isValidNfseKey verifica se as letras que restam estão em um CNPJ.

• Essa é a forma em que o leiaute guarda a chave e a que o DANFSe imprime, um bloco único, e por isso não existe formatNfseKey.

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

parseNfseKey('NFS35503082258716523000119000000000001226011357924683');
// '35503082258716523000119000000000001226011357924683'

parseNfseKey('3550308 2 2 58716523000119 0000000000012 2601 135792468 3');
// '35503082258716523000119000000000001226011357924683'

parseNfseKey('nfs3550308 2 2 12.abc.345/01de-35 0000000000012 2609 135792468 2');
// '35503082212ABC34501DE35000000000001226091357924682'

Interpreta a chave de acesso de uma NFS-e nacional e retorna seus campos, como um NfseKeyInfo. Aceita as mesmas formas de entrada do isValidNfseKey.

• Retorna municipalityCode, stateCode, generatorEnvironment, taxIdType, taxId, number, year, month, code e checkDigit.
• O generatorEnvironment é um NfseKeyGeneratorEnvironment: 1 o sistema do município, 2 o Sistema Nacional NFS-e.
• O taxIdType é um NfseKeyTaxIdType, 'cpf' ou 'cnpj', e o taxId é o CPF de 11 dígitos, sem o 000 que o preenche na chave, ou o CNPJ de 14 caracteres, numérico ou alfanumérico, em maiúsculas.
• Retorna null quando a chave não é válida.

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

getNfseKeyInfo('35503082258716523000119000000000001226011357924683');
// { municipalityCode: '3550308', stateCode: 'SP', generatorEnvironment: 2, taxIdType: 'cnpj',
//   taxId: '58716523000119', number: 12, year: 2026, month: 1, code: '135792468', checkDigit: 3 }

getNfseKeyInfo('43149021100040364478829000000000105725120484407255');
// { municipalityCode: '4314902', stateCode: 'RS', generatorEnvironment: 1, taxIdType: 'cpf',
//   taxId: '40364478829', number: 1057, year: 2025, month: 12, code: '048440725', checkDigit: 5 }

getNfseKeyInfo('35503082212ABC34501DE35000000000001226091357924682');
// { municipalityCode: '3550308', stateCode: 'SP', generatorEnvironment: 2, taxIdType: 'cnpj',
//   taxId: '12ABC34501DE35', number: 12, year: 2026, month: 9, code: '135792468', checkDigit: 2 }

getNfseKeyInfo('invalid'); // null

Fonte: a documentação técnica do Sistema Nacional NFS-e, cujos tipos de esquema TSIdNFSe e TSChaveNFSe e o campo NFSe/infNFSe/id do ANEXO I definem o leiaute e as regras E1280 e E1284, o manual da emissão por decisão administrativa ou judicial, que nomeia o dígito verificador de módulo 11, a Nota Técnica SE/CGNFS-e 008 (item 2.1.1), que imprime a chave em bloco único, os esquemas atualizados para o CNPJ alfanumérico (o pacote de produção restrita v1.01-20260727; o serviço trata o CNPJ alfanumérico em produção desde 10/08/2026, enquanto o pacote de produção de 09/02/2026 ainda só tem dígitos) e a Nota Técnica Conjunta 2025.001, cuja regra de ASCII menos 48 da chave da NF-e o dígito verificador empresta.