GTIN (EAN/UPC)

Check if a GTIN (Global Trade Item Number, the number under an EAN/UPC barcode) is valid.

• Covers the four structures of the GS1 General Specifications, the same four the NF-e accepts in cEAN and cEANTrib: GTIN-8, GTIN-12 (UPC), GTIN-13 (EAN) and GTIN-14 (DUN-14).
• Options (IsValidGtinOptions): lengths accepts only some of the four lengths, and defaults to all four.
• The value must be a string of 8, 12, 13 or 14 digits, surrounding whitespace aside, whose last digit is the GS1 modulo 10 check digit: weights 3 and 1 alternating from the right, the sum subtracted from the nearest equal or higher multiple of ten. That is what rules I03-10 and I12-10 of SEFAZ Nota Técnica 2021.003 check (rejections 611 and 612).
• Leading zeros count, so a number is never accepted, and a masked value ('7 890000 000017') is rejected instead of having its digits picked out.
• The 'SEM GTIN' literal the NF-e uses for a product without a GTIN is not a GTIN, so it is not valid here: test for it before calling.
• A value of zeros only is rejected, although its check digit is valid. That is a rule of this library, not of the NF-e or GS1: rejection 611 is only the check digit, and the GS1 General Specifications (release 26.0, table 1-4) reserve the GS1 Prefix 0000000 for Restricted Circulation Numbers within a company rather than forbid it. Zeros are rejected as the usual placeholder for a missing GTIN.
• The prefix does not change the verdict. Restricted Circulation Numbers (prefixes 02, 04 and 20 to 29, the codes a shop prints on its own scale labels) and the ISSN, ISBN and coupon ranges share the structure and the check digit, and the "Tabela Prefixo GS1" SEFAZ validates cEAN against lists them as valid; use getGtinInfo to tell them apart.
• The prefix is not checked against the list of GS1 Member Organisations either: GS1 keeps assigning ranges, so a copy of that list would turn down valid numbers as it ages. Whether the number is registered (the Cadastro Centralizado de GTIN lookup SEFAZ runs for the 789 and 790 prefixes) cannot be checked offline.

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

isValidGtin('7890000000017'); // true (GTIN-13, GS1 Brasil prefix)
isValidGtin('6291041500213'); // true (the example of the GS1 check digit page)
isValidGtin('78912342'); // true (GTIN-8)
isValidGtin('061414112345'); // true (GTIN-12)
isValidGtin('17890000000014'); // true (GTIN-14)
isValidGtin('7890000000018'); // false (wrong check digit)
isValidGtin('17890000000014', { lengths: [8, 12, 13] }); // false (GTIN-14 not accepted)
isValidGtin('7 890000 000017'); // false (digits only)
isValidGtin('SEM GTIN'); // false
isValidGtin('0000000000000'); // false (zeros only, a rule of this library)

Parse a GTIN into its fields, as a GtinInfo.

• Returns null when the value is not a valid GTIN, under the same rules as isValidGtin.
• The prefix is read as the GS1 General Specifications (tables 1-4, 1-5 and 1-9) lay the numbers out: the value is left padded with zeros to 14 digits, and the prefix is positions 7 to 9 when positions 2 to 6 are zeros (a GTIN-8, or a GTIN-14 that packs one) and positions 2 to 4 otherwise. The first digit, the padding zero or the indicator digit, is never part of the prefix, so a GTIN-12 has a prefix that starts with 0, and a GTIN-14 has the prefix of the GTIN it packs.

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

getGtinInfo('7890000000017');
// { type: 'GTIN-13', length: 13, prefix: '789', isBrazilian: true,
//   isRestrictedCirculation: false, checkDigit: 7 }

getGtinInfo('17890000000014');
// { type: 'GTIN-14', length: 14, prefix: '789', isBrazilian: true,
//   isRestrictedCirculation: false, checkDigit: 4 }

getGtinInfo('061414112345');
// { type: 'GTIN-12', length: 12, prefix: '006', isBrazilian: false,
//   isRestrictedCirculation: false, checkDigit: 5 }

getGtinInfo('2000000000015')?.isRestrictedCirculation; // true (in-store number)
getGtinInfo('7890000000018'); // null (wrong check digit)

Source: GS1 General Specifications, GS1 check digit calculator, SEFAZ Nota Técnica 2021.003 and the Tabela Prefixo GS1 of the Portal da NF-e.