NF-e access key

Validate

• JavaScript library
• Python library
• Go library13 cases fail
• Ruby library12 cases fail
• Rust library14 cases fail
• .NET library13 cases fail
• Erlang library

Validates a 44-character DF-e access key: NF-e (55), NFC-e (65), CT-e (57), MDF-e (58), CT-e OS (67), GTV-e (64), BP-e (63), NF3e (66) and NFCom (62). The CF-e-SAT (59) is not accepted.

• The cUF must be a state and the month (AAMM) must be 01 to 12. The model must be one of the above. The emission type (tpEmis) must be one that the MOC of that model assigns: 1 to 7 and 9 for NF-e and NFC-e; 1, 3, 4, 5, 7 and 8 for CT-e; 1, 5, 7 and 8 for CT-e OS; 1, 2, 7 and 8 for GTV-e; 1, 2 and 3 for MDF-e; 1 and 2 for BP-e, NF3e and NFCom.
• The key is cUF(2) AAMM(4) CNPJ/CPF(14) mod(2) serie(3) nNF(9) tpEmis(1) cNF(8) cDV(1). NFCom and NF3e spend position 36 on nSiteAutoriz and leave 7 digits for cNF.
• For NF-e and NFC-e, the numeric code (cNF) must pass rule B03-10 of the MOC (no repeated or sequential values from the list of 20 the rule gives, and not equal to the document number). The rule applies to the documents sent after NT 2019.001, and NF-e software commonly used a cNF equal to the document number before it, so a key authorized earlier can be rejected.
• The function rejects a document number of all zeros. The check digit is a modulus 11 over the first 43 characters, with weights 2 to 9 cycling from the right; a remainder of 0 or 1 gives check digit 0.
• The 44 characters may be grouped in 4 by whitespace, ., - or /, alone or in a run ("3517 - 0458 ..."). A separator inside a group of 4, or any other character, makes the key invalid. The function first strips the XML Id prefixes (NFe, CTe, MDFe, BPe, NF3e, NFCom, in any letter case), with any whitespace between the prefix and the first group.
• Positions 7 to 18 (the root and order of the issuer's CNPJ) may hold the letters of an alphanumeric CNPJ. The current schemas type the key as [0-9]{6}[0-9A-Z]{12}[0-9]{26} (NT Conjunta 2025.001, NF-e package PL_010), where older ones had 44 digits. A letter anywhere else, including the CNPJ check digits in positions 19 and 20, is rejected. Lowercase is read as uppercase, but a non-ASCII letter that upper-cases into an ASCII one (ſ, ß) is rejected. A CPF issuer is always 11 digits left-padded with zeros, so a letter there always belongs to an alphanumeric CNPJ. 2.4.0 accepted digits only.
• In the check digit, each character counts as its ASCII code minus 48: the digit itself for 0 to 9, and 17 to 42 for A to Z, as in the alphanumeric CNPJ.
• GTV-e (64) accepts tpEmis 1, 2, 7 and 8 (CT-e MOC, field D15). The current package PL_CTe_400_RTC lists only 1 and 2, but 7 (SVC-RS) and 8 (SVC-SP) are kept so keys authorized under PL_CTe_400 still validate, since a key carries no schema version. This is the 2.4.0 behavior.
• A value that is not a string returns false. The CPF or CNPJ check digits of the issuer are not checked, only the check digit of the key (read the key with nfeKey.getInfo and check its taxId with cnpj.isValid, or the last 11 digits of a zero-padded taxId with cpf.isValid).

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

isValidNfeKey('35170458716523000119550010000000121000123458'); // true (NF-e, SP)
isValidNfeKey('NFe35170458716523000119550010000000121000123458'); // true (XML Id prefix)
isValidNfeKey('CTe35170458716523000119570010000000128000123452'); // true (CT-e authorised by the SVC-SP)
isValidNfeKey('3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458'); // true (masked)
isValidNfeKey('3517.0458.7165.2300.0119.5500.1000.0000.1210.0012.3458'); // true (any of the mask characters)
isValidNfeKey('35260712ABC34501DE35550010000001231102030403'); // true (alphanumeric CNPJ 12ABC34501DE35)
isValidNfeKey('35260712ABC34501DEA5550010000001231102030408'); // false (a letter in position 19, a CNPJ check digit)
isValidNfeKey('351 70458716523000119550010000000121000123458'); // false (a separator inside a group of 4)
isValidNfeKey('99170458716523000119550010000000121000123458'); // false (invalid cUF)
isValidNfeKey('35170458716523000119010010000000121000123450'); // false (invalid mod)
isValidNfeKey('35170458716523000119550010000000128000123455'); // false (the NF-e MOC does not assign tpEmis 8)
isValidNfeKey('35170458716523000119550010000000121000000003'); // false (cNF 00000000, rule B03-10)

Format

• JavaScript library
• Python library
• Go library5 cases fail
• Ruby library9 cases fail
• Rust library5 cases fail
• .NET library5 cases fail
• Erlang library

Formats a DF-e access key into groups of 4 characters separated by spaces, as the DANFE and the other auxiliary documents print it. It does not validate the key (use nfeKey.isValid).

Every auxiliary document prints the key in this form: the DANFE of the NF-e and the NFC-e, the DACTE of the CT-e, the CT-e OS and the GTV-e, the DAMDFE of the MDF-e, the DABPE of the BP-e, the DANF3E of the NF3e and the DANFE-COM of the NFCom.

• The function groups a masked or partial key as far as its characters go. options.pad first left-pads the key with zeros to 44 characters ("12345" gives "0000 0000 0000 0000 0000 0000 0000 0000 0000 0001 2345").
• The XML Id prefixes (NFe, CTe, MDFe, BPe, NF3e, NFCom) are stripped first, with the whitespace around them, the way nfeKey.parse reads them. Until 2.4.0 the prefix was not stripped, so the digit of NF3e ended up in the key.
• The upper-cased letters of an alphanumeric CNPJ are kept in positions 7 to 18. A letter anywhere else is dropped, and the positions are counted on the characters kept. 2.4.0 dropped every letter.
• A value that is neither a string nor a safe non-negative integer (an object, true, -1, 1.5, a bigint) returns an empty string instead of throwing. A number is read as the string of its digits. Characters after the 44th are dropped.
• Returns an empty string when there is nothing to format. Until 2.4.0 a value with no digits and pad: true returned the full zero mask.

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' (alphanumeric CNPJ)

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

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

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

Parse

• JavaScript library
• Python library
• Go library4 cases fail
• Ruby library6 cases fail
• Rust library4 cases fail
• .NET library4 cases fail
• Erlang library

Removes the formatting of a DF-e access key and keeps only the characters of the key, capped at 44: digits, plus the upper-cased letters of an alphanumeric CNPJ in positions 7 to 18.

• The function first strips the XML Id prefixes (NFe, CTe, MDFe, BPe, NF3e, NFCom), with any whitespace around them. The prefix has to go first because NF3e carries a digit of its own that is not part of the key.
• A letter anywhere else is dropped, like any other character outside the key. 2.4.0 dropped every letter.
• A shorter value passes through as far as it goes, so the grouping of a key still being typed can be stripped with it. It does not check the key (use nfeKey.isValid).
• A number is read only when it is a safe non-negative integer. A negative, fractional, non-finite or unsafe number gives an empty string (2.4.0 read the digits of any number, sign and decimal point dropped).

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' (alphanumeric CNPJ)

Decode

• JavaScript library
• Python library
• Go library9 cases fail
• Ruby library9 cases fail
• Rust library
• .NET library9 cases fail
• Erlang library

Parses a DF-e access key into its fields. It accepts the same input as nfeKey.isValid and returns null when the key is not valid.

• Fields: stateCode (the 2-letter UF read from the cUF), year (4 digits), month (1 to 12), taxId (issuer tax id), model (the 2-digit model as a string, such as "55"), series (0 to 999) and number (1 to 999999999) as numbers, emissionType (the tpEmis code, a number), code (the numeric code as a string, keeping its leading zeros) and checkDigit (a number). An alphanumeric CNPJ keeps its uppercase letters.
• For NFCom and NF3e (models 62 and 66), code has 7 digits and the result also carries authorizationSite (nSiteAutoriz, a number from 0 to 9). The other models have no authorizationSite.
• taxId is the 14 characters of positions 7 to 20 as written: a numeric CNPJ, an alphanumeric CNPJ (upper-cased) or a CPF left-padded with zeros. A taxId with a letter is always an alphanumeric CNPJ. A padded CPF and a CNPJ that starts with 000 look alike, so check it with cpf.isValid (on the last 11 digits) or cnpj.isValid when the type matters.
• It returns null exactly when nfeKey.isValid returns 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