{ "$schema": "../cases.schema.json", "format": 1, "domain": "nfeKey", "title": { "en": "NF-e access key", "pt-BR": "Chave de acesso NF-e" }, "functions": [ { "id": "nfeKey.format", "level": "extended", "summary": "Formats a DF-e (Documento Fiscal eletrônico) access key (chave de acesso) into groups of 4 characters separated by spaces.", "description": "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`).\n\nEvery 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.\n\n- 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\"`).\n- 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.\n- 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.\n- 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.\n- 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.", "params": [ { "name": "value", "type": "string" }, { "name": "options", "type": "FormatNfeKeyOptions", "optional": true } ], "returns": "string", "cases": [ { "id": "nfeKey.format#[\"35170458716523000119550010000000121000123458\"]", "args": [ "35170458716523000119550010000000121000123458" ], "expect": { "returns": "3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458" } }, { "id": "nfeKey.format#nfe-prefix", "args": [ "NFe35170458716523000119550010000000121000123458" ], "expect": { "returns": "3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458" } }, { "id": "nfeKey.format#partial", "args": [ "12345" ], "expect": { "returns": "1234 5" } }, { "id": "nfeKey.format#empty", "args": [ "" ], "expect": { "returns": "" } }, { "id": "nfeKey.format#[\"1\"]", "args": [ "1" ], "expect": { "returns": "1" }, "note": "JavaScript's own test: should format partial values as far as they go" }, { "id": "nfeKey.format#[\"123\"]", "args": [ "123" ], "expect": { "returns": "123" }, "note": "JavaScript's own test: should format partial values as far as they go" }, { "id": "nfeKey.format#[\"1234\"]", "args": [ "1234" ], "expect": { "returns": "1234" }, "note": "JavaScript's own test: should format partial values as far as they go" }, { "id": "nfeKey.format#[\"12345\",{\"pad\":true}]", "args": [ "12345", { "pad": true } ], "expect": { "returns": "0000 0000 0000 0000 0000 0000 0000 0000 0000 0001 2345" }, "note": "JavaScript's own test: should left pad the value when options.pad is true" }, { "id": "nfeKey.format#[\"35170458716523000119550010000000121000123458\",{\"pad\":true}]", "args": [ "35170458716523000119550010000000121000123458", { "pad": true } ], "expect": { "returns": "3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458" }, "note": "JavaScript's own test: should left pad the value keeping a complete access key untouched" }, { "id": "nfeKey.format#[\"12345\",{\"pad\":false}]", "args": [ "12345", { "pad": false } ], "expect": { "returns": "1234 5" }, "note": "JavaScript's own test: should left pad the value and nothing else when options.pad is false, undefined or the options object is missing" }, { "id": "nfeKey.format#[\"12345\",{}]", "args": [ "12345", {} ], "expect": { "returns": "1234 5" }, "note": "JavaScript's own test: should left pad the value and nothing else when options.pad is false, undefined or the options object is missing" }, { "id": "nfeKey.format#[\"3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458\"]", "args": [ "3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458" ], "expect": { "returns": "3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458" }, "note": "JavaScript's own test: should remove all non numeric characters, including the NFe prefix" }, { "id": "nfeKey.format#[\"35260712ABC34501DE35550010000001231102030403\"]", "args": [ "35260712ABC34501DE35550010000001231102030403" ], "expect": { "returns": "3526 0712 ABC3 4501 DE35 5500 1000 0001 2311 0203 0403" }, "note": "changed in 2.5.0 (#593): 2.4.0 dropped the letters. JavaScript's own test: formatNfeKey with the alphanumeric CNPJ of NT Conjunta 2025.001 should keep the letters in positions 7 to 18 instead of dropping them" }, { "id": "nfeKey.format#[\"35260712abc34501de35550010000001231102030403\"]", "args": [ "35260712abc34501de35550010000001231102030403" ], "expect": { "returns": "3526 0712 ABC3 4501 DE35 5500 1000 0001 2311 0203 0403" }, "note": "JavaScript's own test: formatNfeKey with the alphanumeric CNPJ of NT Conjunta 2025.001 should upper case them" }, { "id": "nfeKey.format#[\"352607A2ABC34501DZ35\"]", "args": [ "352607A2ABC34501DZ35" ], "expect": { "returns": "3526 07A2 ABC3 4501 DZ35" }, "note": "JavaScript's own test: formatNfeKey with the alphanumeric CNPJ of NT Conjunta 2025.001 should keep a letter in position 7 and in position 18" }, { "id": "nfeKey.format#[\"35260A\"]", "args": [ "35260A" ], "expect": { "returns": "3526 0" }, "note": "JavaScript's own test: formatNfeKey with the alphanumeric CNPJ of NT Conjunta 2025.001 should drop a letter in positions 1 to 6 and from position 19 on" }, { "id": "nfeKey.format#[\"35260712ABC34501DEA5\"]", "args": [ "35260712ABC34501DEA5" ], "expect": { "returns": "3526 0712 ABC3 4501 DE5" }, "note": "JavaScript's own test: formatNfeKey with the alphanumeric CNPJ of NT Conjunta 2025.001 should drop a letter in positions 1 to 6 and from position 19 on" }, { "id": "nfeKey.format#[\"35260712ABC34501DE3A5\"]", "args": [ "35260712ABC34501DE3A5" ], "expect": { "returns": "3526 0712 ABC3 4501 DE35" }, "note": "JavaScript's own test: formatNfeKey with the alphanumeric CNPJ of NT Conjunta 2025.001 should drop a letter in positions 1 to 6 and from position 19 on" }, { "id": "nfeKey.format#[\"NF3e35170458716523000119550010000000121000123458\"]", "args": [ "NF3e35170458716523000119550010000000121000123458" ], "expect": { "returns": "3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458" }, "note": "changed in 2.5.0 (#615): the XML Id prefix is stripped before the key is read (2.4.0 kept the 3 of NF3e). JavaScript docs example" }, { "id": "nfeKey.format#[\"CTe35170458716523000119550010000000121000123458\"]", "args": [ "CTe35170458716523000119550010000000121000123458" ], "expect": { "returns": "3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458" }, "note": "XML Id prefix" }, { "id": "nfeKey.format#[\"MDFe35170458716523000119550010000000121000123458\"]", "args": [ "MDFe35170458716523000119550010000000121000123458" ], "expect": { "returns": "3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458" }, "note": "XML Id prefix" }, { "id": "nfeKey.format#[\"BPe35170458716523000119550010000000121000123458\"]", "args": [ "BPe35170458716523000119550010000000121000123458" ], "expect": { "returns": "3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458" }, "note": "XML Id prefix" }, { "id": "nfeKey.format#[\"NFCom35170458716523000119550010000000121000123458\"]", "args": [ "NFCom35170458716523000119550010000000121000123458" ], "expect": { "returns": "3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458" }, "note": "XML Id prefix" }, { "id": "nfeKey.format#[\" NFe 35170458716523000119550010000000121000123458\"]", "args": [ " NFe 35170458716523000119550010000000121000123458" ], "expect": { "returns": "3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458" }, "note": "the prefix is stripped with the whitespace around it" }, { "id": "nfeKey.format#[\"\",{\"pad\":true}]", "args": [ "", { "pad": true } ], "expect": { "returns": "" }, "note": "changed in 2.5.0 (#615): a value with no digits gives an empty string even with pad (2.4.0 returned the zero mask)" }, { "id": "nfeKey.format#[\"abc\",{\"pad\":true}]", "args": [ "abc", { "pad": true } ], "expect": { "returns": "" }, "note": "changed in 2.5.0 (#615): a value with no digits gives an empty string even with pad" }, { "id": "nfeKey.format#[-1]", "args": [ -1 ], "expect": { "returns": "" }, "note": "changed in 2.5.0 (#615): a value that is not a non-negative safe integer gives an empty string" }, { "id": "nfeKey.format#[1.5]", "args": [ 1.5 ], "expect": { "returns": "" }, "note": "changed in 2.5.0 (#615): a value that is not a non-negative safe integer gives an empty string" }, { "id": "nfeKey.format#[12345]", "args": [ 12345 ], "expect": { "returns": "1234 5" }, "note": "a number is read as the string of its digits" }, { "id": "nfeKey.format#[null]", "args": [ null ], "expect": { "returns": "" }, "note": "a value that is not a string or a number gives an empty string" }, { "id": "nfeKey.format#[true]", "args": [ true ], "expect": { "returns": "" }, "note": "a value that is not a string or a number gives an empty string" } ] }, { "id": "nfeKey.getInfo", "level": "extended", "summary": "Splits a DF-e (Documento Fiscal eletrônico) access key (chave de acesso) into its fields.", "description": "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.\n\n- 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.\n- 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`.\n- `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.\n- It returns `null` exactly when `nfeKey.isValid` returns `false`.", "params": [ { "name": "value", "type": "string" } ], "returns": "NfeKeyInfo?", "cases": [ { "id": "nfeKey.getInfo#[\"35170458716523000119550010000000121000123458\"]", "args": [ "35170458716523000119550010000000121000123458" ], "expect": { "returns": { "stateCode": "SP", "year": 2017, "month": 4, "taxId": "58716523000119", "model": "55", "series": 1, "number": 12, "emissionType": 1, "code": "00012345", "checkDigit": 8 } } }, { "id": "nfeKey.getInfo#wrong-check-digit", "args": [ "35170458716523000119550010000000121000123459" ], "expect": { "returns": null } }, { "id": "nfeKey.getInfo#empty", "args": [ "" ], "expect": { "returns": null } }, { "id": "nfeKey.getInfo#[\"35170458716523000119990010000000121000123453\"]", "args": [ "35170458716523000119990010000000121000123453" ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null when the model is not one of the nine supported (model 99 with a matching check digit)" }, { "id": "nfeKey.getInfo#[\"35170458716523000119550010000000001000123457\"]", "args": [ "35170458716523000119550010000000001000123457" ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null when the document number is zero" }, { "id": "nfeKey.getInfo#[\"35170458716523000119550010000000128000123455\"]", "args": [ "35170458716523000119550010000000128000123455" ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null when tpEmis is 8, which the NF-e MOC does not assign, even with a matching check digit" }, { "id": "nfeKey.getInfo#[\"35170458716523000119570010000000122000123453\"]", "args": [ "35170458716523000119570010000000122000123453" ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null when tpEmis belongs to another model: 2 for a CT-e, 3 for a CT-e OS, 9 for an MDF-e, 3 for a BP-e" }, { "id": "nfeKey.getInfo#[\"35170458716523000119670010000000123000123454\"]", "args": [ "35170458716523000119670010000000123000123454" ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null when tpEmis belongs to another model: 2 for a CT-e, 3 for a CT-e OS, 9 for an MDF-e, 3 for a BP-e" }, { "id": "nfeKey.getInfo#[\"35170458716523000119580010000000129000123454\"]", "args": [ "35170458716523000119580010000000129000123454" ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null when tpEmis belongs to another model: 2 for a CT-e, 3 for a CT-e OS, 9 for an MDF-e, 3 for a BP-e" }, { "id": "nfeKey.getInfo#[\"35170458716523000119630010000000123000123450\"]", "args": [ "35170458716523000119630010000000123000123450" ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null when tpEmis belongs to another model: 2 for a CT-e, 3 for a CT-e OS, 9 for an MDF-e, 3 for a BP-e" }, { "id": "nfeKey.getInfo#[\"35170458716523000119550010000000121000000003\"]", "args": [ "35170458716523000119550010000000121000000003" ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null when the cNF of an NF-e is one rule B03-10 of the MOC forbids" }, { "id": "nfeKey.getInfo#[\"35170458716523000119550010000000121111111113\"]", "args": [ "35170458716523000119550010000000121111111113" ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null when the cNF of an NF-e is one rule B03-10 of the MOC forbids" }, { "id": "nfeKey.getInfo#[\"35170458716523000119550010000000121123456781\"]", "args": [ "35170458716523000119550010000000121123456781" ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null when the cNF of an NF-e is one rule B03-10 of the MOC forbids" }, { "id": "nfeKey.getInfo#[\"35170458716523000119550010000123451000123458\"]", "args": [ "35170458716523000119550010000123451000123458" ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null when the cNF of an NF-e equals its nNF, the second half of rule B03-10" }, { "id": "nfeKey.getInfo#[\"not-a-key\"]", "args": [ "not-a-key" ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null when the access key is otherwise invalid" }, { "id": "nfeKey.getInfo#[\"43160472202112000136550000000010571048440722\"]", "args": [ "43160472202112000136550000000010571048440722" ], "expect": { "returns": { "stateCode": "RS", "year": 2016, "month": 4, "taxId": "72202112000136", "model": "55", "series": 0, "number": 1057, "emissionType": 1, "code": "04844072", "checkDigit": 2 } }, "note": "JavaScript's own test: should return the parsed access key for a NF-e access key (RS), the NFePHP sped-cte `$infNFe->chave` example (NF-e referenced by a CT-e)" }, { "id": "nfeKey.getInfo#[\"35170458716523000119620010000000121000123450\"]", "args": [ "35170458716523000119620010000000121000123450" ], "expect": { "returns": { "stateCode": "SP", "year": 2017, "month": 4, "taxId": "58716523000119", "model": "62", "series": 1, "number": 12, "emissionType": 1, "authorizationSite": 0, "code": "0012345", "checkDigit": 0 } }, "note": "JavaScript's own test: should return the parsed access key splitting nSiteAutoriz from the 7 digit cNF of an NFCom, per its Visão Geral §2.1.3" }, { "id": "nfeKey.getInfo#[\"35170458716523000119660010000000121000123454\"]", "args": [ "35170458716523000119660010000000121000123454" ], "expect": { "returns": { "stateCode": "SP", "year": 2017, "month": 4, "taxId": "58716523000119", "model": "66", "series": 1, "number": 12, "emissionType": 1, "authorizationSite": 0, "code": "0012345", "checkDigit": 4 } }, "note": "JavaScript's own test: should return the parsed access key splitting nSiteAutoriz from the 7 digit cNF of an NF3e, per its Visão Geral" }, { "id": "nfeKey.getInfo#[\"35260712ABC34501DE35550010000001231102030403\"]", "args": [ "35260712ABC34501DE35550010000001231102030403" ], "expect": { "returns": { "stateCode": "SP", "year": 2026, "month": 7, "taxId": "12ABC34501DE35", "model": "55", "series": 1, "number": 123, "emissionType": 1, "code": "10203040", "checkDigit": 3 } }, "note": "changed in 2.5.0 (#593): alphanumeric CNPJ in positions 7 to 18 (NT Conjunta 2025.001); 2.4.0 rejected it. JavaScript's own test: should return the fields for the alphanumeric CNPJ of NT Conjunta 2025.001, reading its letters into taxId" }, { "id": "nfeKey.getInfo#[\"35260712abc34501de35550010000001231102030403\"]", "args": [ "35260712abc34501de35550010000001231102030403" ], "expect": { "returns": { "stateCode": "SP", "year": 2026, "month": 7, "taxId": "12ABC34501DE35", "model": "55", "series": 1, "number": 123, "emissionType": 1, "code": "10203040", "checkDigit": 3 } }, "note": "JavaScript's own test: should return the fields for the alphanumeric CNPJ, reading lower case letters into an upper case taxId" }, { "id": "nfeKey.getInfo#[\"35260712ABC34501DEA5550010000001231102030408\"]", "args": [ "35260712ABC34501DEA5550010000001231102030408" ], "expect": { "returns": null }, "note": "JavaScript's own test: should return null for a letter in the CNPJ check digits" }, { "id": "nfeKey.getInfo#[\"35170458716523000119640010000000127000123456\"]", "args": [ "35170458716523000119640010000000127000123456" ], "expect": { "returns": { "stateCode": "SP", "year": 2017, "month": 4, "taxId": "58716523000119", "model": "64", "series": 1, "number": 12, "emissionType": 7, "code": "00012345", "checkDigit": 6 } }, "note": "GTV-e (64) with tpEmis 7 (#593, back to the 2.4.0 behaviour)" } ] }, { "id": "nfeKey.isValid", "level": "extended", "summary": "Checks whether a DF-e (Documento Fiscal eletrônico) access key (chave de acesso) is valid.", "description": "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.\n\n- 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.\n- 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`.\n- 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.\n- 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.\n- 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.\n- 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.\n- 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.\n- 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.\n- 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`).", "params": [ { "name": "value", "type": "string" } ], "returns": "boolean", "cases": [ { "id": "nfeKey.isValid#[\"35170458716523000119550010000000121000123458\"]", "args": [ "35170458716523000119550010000000121000123458" ], "expect": { "returns": true } }, { "id": "nfeKey.isValid#masked", "args": [ "3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458" ], "expect": { "returns": true } }, { "id": "nfeKey.isValid#nfe-prefix", "args": [ "NFe35170458716523000119550010000000121000123458" ], "expect": { "returns": true } }, { "id": "nfeKey.isValid#wrong", "args": [ "35170458716523000119550010000000001000123457" ], "expect": { "returns": false } }, { "id": "nfeKey.isValid#too-short", "args": [ "3517045871652300011955001000000012100012345" ], "expect": { "returns": false } }, { "id": "nfeKey.isValid#empty", "args": [ "" ], "expect": { "returns": false } }, { "id": "nfeKey.isValid#[\"35120859597245000190550000000095831710040056\"]", "args": [ "35120859597245000190550000000095831710040056" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true for a real NF-e access key without a mask, the br-validate-dfe-access-key README/tests example (SP)" }, { "id": "nfeKey.isValid#[\"43160472202112000136550000000010571048440722\"]", "args": [ "43160472202112000136550000000010571048440722" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true for a real NF-e access key without a mask, the NFePHP sped-cte `$infNFe->chave` example (RS, NF-e referenced by a CT-e)" }, { "id": "nfeKey.isValid#[\"CTe35170458716523000119570010000000121000123455\"]", "args": [ "CTe35170458716523000119570010000000121000123455" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true when it has the XML Id prefix of one of the other covered documents" }, { "id": "nfeKey.isValid#[\"MDFe35170458716523000119580010000000121000123459\"]", "args": [ "MDFe35170458716523000119580010000000121000123459" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true when it has the XML Id prefix of one of the other covered documents" }, { "id": "nfeKey.isValid#[\"BPe35170458716523000119630010000000121000123453\"]", "args": [ "BPe35170458716523000119630010000000121000123453" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true when it has the XML Id prefix of one of the other covered documents" }, { "id": "nfeKey.isValid#[\"NF3e35170458716523000119660010000000121000123454\"]", "args": [ "NF3e35170458716523000119660010000000121000123454" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true when it has the XML Id prefix of one of the other covered documents" }, { "id": "nfeKey.isValid#[\"nfcom35170458716523000119620010000000121000123450\"]", "args": [ "nfcom35170458716523000119620010000000121000123450" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true when it has the XML Id prefix of one of the other covered documents" }, { "id": "nfeKey.isValid#[\"35170458716523000119620010000000121000123450\"]", "args": [ "35170458716523000119620010000000121000123450" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true for the four models added beside the NF-e family: NFCom (62), BP-e (63), GTV-e (64) and NF3e (66)" }, { "id": "nfeKey.isValid#[\"35170458716523000119630010000000121000123453\"]", "args": [ "35170458716523000119630010000000121000123453" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true for the four models added beside the NF-e family: NFCom (62), BP-e (63), GTV-e (64) and NF3e (66)" }, { "id": "nfeKey.isValid#[\"35170458716523000119640010000000121000123457\"]", "args": [ "35170458716523000119640010000000121000123457" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true for the four models added beside the NF-e family: NFCom (62), BP-e (63), GTV-e (64) and NF3e (66)" }, { "id": "nfeKey.isValid#[\"35170458716523000119660010000000121000123454\"]", "args": [ "35170458716523000119660010000000121000123454" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true for the four models added beside the NF-e family: NFCom (62), BP-e (63), GTV-e (64) and NF3e (66)" }, { "id": "nfeKey.isValid#[\"35170458716523000119570010000000128000123452\"]", "args": [ "35170458716523000119570010000000128000123452" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true for a CT-e, a CT-e OS and a GTV-e authorised by the SVC-SP, whose MOC assigns tpEmis 8" }, { "id": "nfeKey.isValid#[\"35170458716523000119670010000000128000123455\"]", "args": [ "35170458716523000119670010000000128000123455" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true for a CT-e, a CT-e OS and a GTV-e authorised by the SVC-SP, whose MOC assigns tpEmis 8" }, { "id": "nfeKey.isValid#[\"35170458716523000119640010000000128000123454\"]", "args": [ "35170458716523000119640010000000128000123454" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true for a CT-e, a CT-e OS and a GTV-e authorised by the SVC-SP, whose MOC assigns tpEmis 8 (GTV-e tpEmis 8, from the maintainer briefing, #593: back to the 2.4.0 behaviour)" }, { "id": "nfeKey.isValid#[\"3517.0458.7165.2300.0119.5500.1000.0000.1210.0012.3458\"]", "args": [ "3517.0458.7165.2300.0119.5500.1000.0000.1210.0012.3458" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true when the printed groups of 4 are split by any of the mask characters" }, { "id": "nfeKey.isValid#[\"3517-0458-7165-2300-0119-5500-1000-0000-1210-0012-3458\"]", "args": [ "3517-0458-7165-2300-0119-5500-1000-0000-1210-0012-3458" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true when the printed groups of 4 are split by any of the mask characters" }, { "id": "nfeKey.isValid#[\"3517/0458/7165/2300/0119/5500/1000/0000/1210/0012/3458\"]", "args": [ "3517/0458/7165/2300/0119/5500/1000/0000/1210/0012/3458" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true when the printed groups of 4 are split by any of the mask characters" }, { "id": "nfeKey.isValid#[\"3517.0458-7165/2300 0119 5500 1000 0000 1210 0012 3458\"]", "args": [ "3517.0458-7165/2300 0119 5500 1000 0000 1210 0012 3458" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true when the mask characters are mixed and a run of them separates two groups" }, { "id": "nfeKey.isValid#[\"3517 - 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458\"]", "args": [ "3517 - 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true when the mask characters are mixed and a run of them separates two groups" }, { "id": "nfeKey.isValid#[\"NFe 3512 0859 5972 4500 0190 5500 0000 0095 8317 1004 0056\"]", "args": [ "NFe 3512 0859 5972 4500 0190 5500 0000 0095 8317 1004 0056" ], "expect": { "returns": true }, "note": "JavaScript's own test: should return true when it has the NFe prefix and a whitespace mask combined" }, { "id": "nfeKey.isValid#[\"351 70458716523000119550010000000121000123458\"]", "args": [ "351 70458716523000119550010000000121000123458" ], "expect": { "returns": false }, "note": "JavaScript's own test: should return false when a separator falls inside a printed group of 4 digits" }, { "id": "nfeKey.isValid#[\"3517 0458 7165 2300 0119 5500 1000 0000 1210 00123 458\"]", "args": [ "3517 0458 7165 2300 0119 5500 1000 0000 1210 00123 458" ], "expect": { "returns": false }, "note": "JavaScript's own test: should return false when a separator falls inside a printed group of 4 digits" }, { "id": "nfeKey.isValid#[\"3517#0458#7165#2300#0119#5500#1000#0000#1210#0012#3458\"]", "args": [ "3517#0458#7165#2300#0119#5500#1000#0000#1210#0012#3458" ], "expect": { "returns": false }, "note": "JavaScript's own test: should return false when the groups are split by a character outside the mask" }, { "id": "nfeKey.isValid#[\"3517,0458,7165,2300,0119,5500,1000,0000,1210,0012,3458\"]", "args": [ "3517,0458,7165,2300,0119,5500,1000,0000,1210,0012,3458" ], "expect": { "returns": false }, "note": "JavaScript's own test: should return false when the groups are split by a character outside the mask" }, { "id": "nfeKey.isValid#[\"35170358716523000119550010000000301000000300\"]", "args": [ "35170358716523000119550010000000301000000300" ], "expect": { "returns": false }, "note": "JavaScript's own test: should return false for the NFePHP `Keys::isValid` doc example, whose cNF equals its nNF (rule B03-10)" }, { "id": "nfeKey.isValid#[\"35170458716523000119550010000000121000000003\"]", "args": [ "35170458716523000119550010000000121000000003" ], "expect": { "returns": false }, "note": "JavaScript's own test: should return false when the cNF of an NF-e is one of the codes rule B03-10 lists" }, { "id": "nfeKey.isValid#[\"35170458716523000119550010000000121123456781\"]", "args": [ "35170458716523000119550010000000121123456781" ], "expect": { "returns": false }, "note": "JavaScript's own test: should return false when the cNF of an NF-e is one of the codes rule B03-10 lists" }, { "id": "nfeKey.isValid#[\"42100484684182000157550010000000020108042108\"]", "args": [ "42100484684182000157550010000000020108042108" ], "expect": { "returns": false }, "note": "JavaScript's own test: should return false when tpEmis is not between 1 and 9, using the br-validate-dfe-access-key doc example with a valid check digit but tpEmis '0'" }, { "id": "nfeKey.isValid#[\"35260712ABC34501DE35550010000001231102030403\"]", "args": [ "35260712ABC34501DE35550010000001231102030403" ], "expect": { "returns": true }, "note": "changed in 2.5.0 (#593): alphanumeric CNPJ in positions 7 to 18 (NT Conjunta 2025.001); 2.4.0 rejected it. JavaScript's own test: with the alphanumeric CNPJ of NT Conjunta 2025.001 should accept the key of CNPJ 12ABC34501DE35" }, { "id": "nfeKey.isValid#[\"3526 0712 ABC3 4501 DE35 5500 1000 0001 2311 0203 0403\"]", "args": [ "3526 0712 ABC3 4501 DE35 5500 1000 0001 2311 0203 0403" ], "expect": { "returns": true }, "note": "JavaScript's own test: alphanumeric CNPJ: should accept it masked in groups of 4 and behind the XML Id prefix" }, { "id": "nfeKey.isValid#[\"3526.0712.ABC3.4501.DE35.5500.1000.0001.2311.0203.0403\"]", "args": [ "3526.0712.ABC3.4501.DE35.5500.1000.0001.2311.0203.0403" ], "expect": { "returns": true }, "note": "JavaScript's own test: alphanumeric CNPJ: should accept it masked in groups of 4 and behind the XML Id prefix" }, { "id": "nfeKey.isValid#[\"NFe35260712ABC34501DE35550010000001231102030403\"]", "args": [ "NFe35260712ABC34501DE35550010000001231102030403" ], "expect": { "returns": true }, "note": "JavaScript's own test: alphanumeric CNPJ: should accept it masked in groups of 4 and behind the XML Id prefix" }, { "id": "nfeKey.isValid#[\"3526 0712 AB C3 4501 DE35 5500 1000 0001 2311 0203 0403\"]", "args": [ "3526 0712 AB C3 4501 DE35 5500 1000 0001 2311 0203 0403" ], "expect": { "returns": false }, "note": "JavaScript's own test: alphanumeric CNPJ: should reject a separator inside a group of 4 of it" }, { "id": "nfeKey.isValid#[\"35260712abc34501de35550010000001231102030403\"]", "args": [ "35260712abc34501de35550010000001231102030403" ], "expect": { "returns": true }, "note": "JavaScript's own test: alphanumeric CNPJ: should read lower case letters as upper case, the case folding isValidCnpj applies to version 2" }, { "id": "nfeKey.isValid#[\"352607A2ABC34501DZ35550010000001231102030409\"]", "args": [ "352607A2ABC34501DZ35550010000001231102030409" ], "expect": { "returns": true }, "note": "JavaScript's own test: alphanumeric CNPJ: should accept a letter in position 7 and in position 18, the two ends of the CNPJ root and order" }, { "id": "nfeKey.isValid#[\"35260A12ABC34501DE35550010000001231102030400\"]", "args": [ "35260A12ABC34501DE35550010000001231102030400" ], "expect": { "returns": false }, "note": "JavaScript's own test: alphanumeric CNPJ: should reject a letter in positions 1 to 6" }, { "id": "nfeKey.isValid#[\"35A60712ABC34501DE35550010000001231102030406\"]", "args": [ "35A60712ABC34501DE35550010000001231102030406" ], "expect": { "returns": false }, "note": "JavaScript's own test: alphanumeric CNPJ: should reject a letter in positions 1 to 6" }, { "id": "nfeKey.isValid#[\"35260712ABC34501DEA5550010000001231102030408\"]", "args": [ "35260712ABC34501DEA5550010000001231102030408" ], "expect": { "returns": false }, "note": "JavaScript's own test: alphanumeric CNPJ: should reject a letter in positions 19 and 20, the CNPJ check digits" }, { "id": "nfeKey.isValid#[\"35260712ABC34501DE3A550010000001231102030405\"]", "args": [ "35260712ABC34501DE3A550010000001231102030405" ], "expect": { "returns": false }, "note": "JavaScript's own test: alphanumeric CNPJ: should reject a letter in positions 19 and 20, the CNPJ check digits" }, { "id": "nfeKey.isValid#[\"35260712ABC34501DE35A50010000001231102030406\"]", "args": [ "35260712ABC34501DE35A50010000001231102030406" ], "expect": { "returns": false }, "note": "JavaScript's own test: alphanumeric CNPJ: should reject a letter after position 20, in the model or the document number" }, { "id": "nfeKey.isValid#[\"35260712ABC34501DE355500100000A1231102030400\"]", "args": [ "35260712ABC34501DE355500100000A1231102030400" ], "expect": { "returns": false }, "note": "JavaScript's own test: alphanumeric CNPJ: should reject a letter after position 20, in the model or the document number" }, { "id": "nfeKey.isValid#[\"35260712ABC34501DE35620010000001231102030405\"]", "args": [ "35260712ABC34501DE35620010000001231102030405" ], "expect": { "returns": true }, "note": "JavaScript's own test: alphanumeric CNPJ: should accept the alphanumeric CNPJ in the key of the other models, NFCom and CT-e" }, { "id": "nfeKey.isValid#[\"35260712ABC34501DE35570010000001231102030400\"]", "args": [ "35260712ABC34501DE35570010000001231102030400" ], "expect": { "returns": true }, "note": "JavaScript's own test: alphanumeric CNPJ: should accept the alphanumeric CNPJ in the key of the other models, NFCom and CT-e" }, { "id": "nfeKey.isValid#[\"35260712ABC34501DE35550010000001231102030404\"]", "args": [ "35260712ABC34501DE35550010000001231102030404" ], "expect": { "returns": false }, "note": "JavaScript's own test: alphanumeric CNPJ: should compute the check digit with the letters valued at their ASCII code minus 48 (only 3 is accepted)" }, { "id": "nfeKey.isValid#[\"35170458716523000119640010000000127000123456\"]", "args": [ "35170458716523000119640010000000127000123456" ], "expect": { "returns": true }, "note": "from the maintainer briefing, #593: GTV-e (64) with tpEmis 7 (SVC-RS), back to the 2.4.0 behaviour (CT-e MOC field D15)" }, { "id": "nfeKey.isValid#[\"35170458716523000119640010000000122000123455\"]", "args": [ "35170458716523000119640010000000122000123455" ], "expect": { "returns": true }, "note": "GTV-e (64) with tpEmis 2 (contingência off-line)" }, { "id": "nfeKey.isValid#[\"35170458716523000119640010000000123000123453\"]", "args": [ "35170458716523000119640010000000123000123453" ], "expect": { "returns": false }, "note": "GTV-e (64) with tpEmis 3, which the CT-e MOC does not assign to the GTV-e (check digit correct)" }, { "id": "nfeKey.isValid#[\"NFe 3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458\"]", "args": [ "NFe 3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458" ], "expect": { "returns": true }, "note": "the prefix followed by whitespace and a masked key" }, { "id": "nfeKey.isValid#[\" NFe 35170458716523000119550010000000121000123458\"]", "args": [ " NFe 35170458716523000119550010000000121000123458" ], "expect": { "returns": true }, "note": "whitespace around the prefix is ignored" }, { "id": "nfeKey.isValid#[\"35170458716523000119550ß10000000121000123458\"]", "args": [ "35170458716523000119550ß10000000121000123458" ], "expect": { "returns": false }, "note": "JavaScript's own test: a non-ASCII letter that upper cases into an ASCII one is rejected" }, { "id": "nfeKey.isValid#[\"35260712ſBC34501DE35550010000001231102030403\"]", "args": [ "35260712ſBC34501DE35550010000001231102030403" ], "expect": { "returns": false }, "note": "ſ is not folded into an ASCII letter" }, { "id": "nfeKey.isValid#[\"35260712ABC34501DEß5550010000001231102030403\"]", "args": [ "35260712ABC34501DEß5550010000001231102030403" ], "expect": { "returns": false }, "note": "ß is not folded into SS" }, { "id": "nfeKey.isValid#[null]", "args": [ null ], "expect": { "returns": false }, "note": "a value that is not a string is invalid" }, { "id": "nfeKey.isValid#[3.5170458716523e+43]", "args": [ 3.5170458716523e+43 ], "expect": { "returns": false }, "note": "a number is not a valid access key: the type is a string" } ] }, { "id": "nfeKey.parse", "level": "extended", "summary": "Removes the formatting characters of a DF-e (Documento Fiscal eletrônico) access key (chave de acesso) and returns the characters of the key.", "description": "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.\n\n- 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.\n- A letter anywhere else is dropped, like any other character outside the key. 2.4.0 dropped every letter.\n- 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`).\n- 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).", "params": [ { "name": "value", "type": "string | number" } ], "returns": "string", "cases": [ { "id": "nfeKey.parse#masked", "args": [ "3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458" ], "expect": { "returns": "35170458716523000119550010000000121000123458" } }, { "id": "nfeKey.parse#nfe-prefix", "args": [ "NFe35170458716523000119550010000000121000123458" ], "expect": { "returns": "35170458716523000119550010000000121000123458" } }, { "id": "nfeKey.parse#partial", "args": [ "3517 0458" ], "expect": { "returns": "35170458" } }, { "id": "nfeKey.parse#empty", "args": [ "" ], "expect": { "returns": "" } }, { "id": "nfeKey.parse#[\"3517.0458.7165.2300.0119.5500.1000.0000.1210.0012.3458\"]", "args": [ "3517.0458.7165.2300.0119.5500.1000.0000.1210.0012.3458" ], "expect": { "returns": "35170458716523000119550010000000121000123458" }, "note": "JavaScript's own test: should remove non numeric characters" }, { "id": "nfeKey.parse#[-1]", "args": [ -1 ], "expect": { "returns": "" }, "note": "JavaScript's own test: should return an empty string when it is a negative, fractional or unsafe number (#593 number rule)" }, { "id": "nfeKey.parse#[1.5]", "args": [ 1.5 ], "expect": { "returns": "" }, "note": "JavaScript's own test: should return an empty string when it is a negative, fractional or unsafe number (#593 number rule)" }, { "id": "nfeKey.parse#[9007199254740992]", "args": [ 9007199254740992 ], "expect": { "returns": "" }, "note": "JavaScript's own test: should return an empty string when it is a negative, fractional or unsafe number (#593 number rule)" }, { "id": "nfeKey.parse#[\"3526 0712 ABC3 4501 DE35 5500 1000 0001 2311 0203 0403\"]", "args": [ "3526 0712 ABC3 4501 DE35 5500 1000 0001 2311 0203 0403" ], "expect": { "returns": "35260712ABC34501DE35550010000001231102030403" }, "note": "changed in 2.5.0 (#593): 2.4.0 dropped the letters. JavaScript's own test: parseNfeKey with the alphanumeric CNPJ of NT Conjunta 2025.001 should keep the letters in positions 7 to 18 instead of dropping them" }, { "id": "nfeKey.parse#[\"NFe35260712ABC34501DE35550010000001231102030403\"]", "args": [ "NFe35260712ABC34501DE35550010000001231102030403" ], "expect": { "returns": "35260712ABC34501DE35550010000001231102030403" }, "note": "JavaScript's own test: parseNfeKey with the alphanumeric CNPJ of NT Conjunta 2025.001 should keep the letters in positions 7 to 18 instead of dropping them" }, { "id": "nfeKey.parse#[\"35260712abc34501de35550010000001231102030403\"]", "args": [ "35260712abc34501de35550010000001231102030403" ], "expect": { "returns": "35260712ABC34501DE35550010000001231102030403" }, "note": "JavaScript's own test: parseNfeKey with the alphanumeric CNPJ of NT Conjunta 2025.001 should upper case them" }, { "id": "nfeKey.parse#[\"35260A\"]", "args": [ "35260A" ], "expect": { "returns": "35260" }, "note": "JavaScript's own test: parseNfeKey with the alphanumeric CNPJ of NT Conjunta 2025.001 should drop a letter in positions 1 to 6 and from position 19 on" }, { "id": "nfeKey.parse#[\"35260712ABC34501DEA5\"]", "args": [ "35260712ABC34501DEA5" ], "expect": { "returns": "35260712ABC34501DE5" }, "note": "JavaScript's own test: parseNfeKey with the alphanumeric CNPJ of NT Conjunta 2025.001 should drop a letter in positions 1 to 6 and from position 19 on" }, { "id": "nfeKey.parse#[\"NF3e35170458716523000119550010000000121000123458\"]", "args": [ "NF3e35170458716523000119550010000000121000123458" ], "expect": { "returns": "35170458716523000119550010000000121000123458" }, "note": "the XML Id prefix is stripped first, so the 3 of NF3e is not part of the key" }, { "id": "nfeKey.parse#[\"CTe35170458716523000119550010000000121000123458\"]", "args": [ "CTe35170458716523000119550010000000121000123458" ], "expect": { "returns": "35170458716523000119550010000000121000123458" }, "note": "XML Id prefix" }, { "id": "nfeKey.parse#[\"MDFe35170458716523000119550010000000121000123458\"]", "args": [ "MDFe35170458716523000119550010000000121000123458" ], "expect": { "returns": "35170458716523000119550010000000121000123458" }, "note": "XML Id prefix" }, { "id": "nfeKey.parse#[\"BPe35170458716523000119550010000000121000123458\"]", "args": [ "BPe35170458716523000119550010000000121000123458" ], "expect": { "returns": "35170458716523000119550010000000121000123458" }, "note": "XML Id prefix" }, { "id": "nfeKey.parse#[\"NFCom35170458716523000119550010000000121000123458\"]", "args": [ "NFCom35170458716523000119550010000000121000123458" ], "expect": { "returns": "35170458716523000119550010000000121000123458" }, "note": "XML Id prefix" }, { "id": "nfeKey.parse#[\" NFe 3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458\"]", "args": [ " NFe 3517 0458 7165 2300 0119 5500 1000 0000 1210 0012 3458" ], "expect": { "returns": "35170458716523000119550010000000121000123458" }, "note": "the prefix is stripped with the whitespace around it, mask included" }, { "id": "nfeKey.parse#[12345]", "args": [ 12345 ], "expect": { "returns": "12345" }, "note": "a number is read as the string of its digits" } ] } ] }