Come funzionano i codici a barre: validazione GS1, quorum e conflitti

Validazione: solo codici GS1 corretti

Ogni codice inviato viene controllato prima di qualsiasi altra cosa:

solo cifre, lunghezza 8, 12, 13, 14 (EAN-8, UPC-A, EAN-13, GTIN-14);
cifra di controllo GS1 valida (pesi 3 e 1 da destra);
per i codici a 13 cifre sono esclusi i prefissi che non identificano un prodotto da banco: editoria (977, 978, 979), uso interno e peso variabile (2), buoni e rimborsi (98, 99);
il codice AAMS deve esistere nella tariffa.

Un codice che non passa viene rifiutato con un motivo esplicito (invalid_barcode, invalid_checksum, unsupported_barcode, unknown_adm_code); l'elenco completo è nel riferimento API. Spazi iniziali e finali vengono ignorati.

Pacchetto o stecca

Un abbinamento è la terna codice AAMS + tipo + pezzi. Il tipo è pack (confezione singola, units = 1) o carton (stecca o cartone, units da 2 a 1000). Lo stesso prodotto ha quindi di norma due codici diversi, uno per il pacchetto e uno per la stecca, e due abbinamenti distinti.

Chi può segnalare

Qualunque utente registrato, con POST /v1/barcodes (fino a 500 elementi per chiamata, 100 all'ora). Ogni account ha un solo voto per codice a barre: una nuova segnalazione sostituisce la precedente, anche se cambia l'abbinamento proposto. Un software che serve più punti vendita può essere abilitato come integrazione e segnalare a nome di ciascun negozio con un contributorRef: ogni negozio conta come un contributore distinto.

Gli stati

Stato	Significato	Nel dataset
to_confirm	Segnalato, in attesa di altre conferme. Lo vedono solo gli account che lo hanno inviato, in `/v1/my-submissions`.	No
approved	Abbinamento pubblico, approvato per quorum, da un produttore verificato o dall'amministratore.	Sì
conflict	Proposte diverse per lo stesso codice a barre, o un produttore che contraddice un abbinamento già approvato. Lo risolve l'amministratore.	No
revoked	Revocato dall'amministratore: non accetta più segnalazioni ed è tolto dalla prima release successiva.	No

Il quorum: tre contributori d'accordo

Un codice a barre segnalato dagli utenti diventa approved quando 3 contributori distinti hanno proposto lo stesso abbinamento (stesso codice AAMS, tipo e numero di pezzi) e nessuno ne ha proposto uno diverso. Finché le conferme non bastano resta to_confirm: il tuo software può comunque usare in locale l'abbinamento che ha inviato, ma non lo troverà nel dataset.

Primo invio
Il codice entra come to_confirm con la tua proposta.
Seconda e terza conferma
Altri due account (o due negozi di un'integrazione) inviano la stessa terna.
Approvazione automatica
Il codice passa ad approved con approvedBy = quorum e viene incluso nella release successiva, pubblicata dopo qualche minuto di attesa per raccogliere altre modifiche.

Conflitti

Se per lo stesso codice a barre arrivano proposte diverse prima dell'approvazione, lo stato diventa conflict e nessuna delle proposte viene pubblicata finché l'amministratore non sceglie. Se invece un codice è già approved per quorum e arriva una proposta diversa, resta approvato ma viene marcato come contestato per una revisione; il tuo invio risulterà outvoted in /v1/my-submissions.

Produttori verificati

Un produttore verificato (vedi Registrarsi come produttore) ha un perimetro: marchi o intervalli di codici AAMS. Per un prodotto nel perimetro la sua segnalazione è autorevole: il codice viene approvato subito con approvedBy = supplier, anche se altri utenti hanno proposto abbinamenti diversi (che restano registrati come contestazione). Fuori perimetro il produttore vale come un utente qualunque. Due produttori autorevoli in disaccordo, o un produttore che contraddice un abbinamento già approvato, aprono un conflitto che decide l'amministratore.

L'amministratore

Può approvare una delle proposte, revocare un codice o riaprirlo per rifare il calcolo sui voti. Le sue decisioni non vengono cambiate da nuove segnalazioni: un codice approvato dall'amministratore resta tale (le proposte diverse lo marcano come contestato), un codice revocato rifiuta ogni invio. Le decisioni sono registrate in un registro di audit.

Cosa significa per il tuo software

Risolvi i codici a barre dal dataset locale; se un codice manca, chiedi all'operatore di scegliere il prodotto e invia l'abbinamento: il tuo contributo aiuta altri due utenti a renderlo pubblico.
Gli abbinamenti nascono da segnalazioni e possono contenere errori: mostra sempre all'operatore il prodotto riconosciuto prima di confermare la vendita, come richiesto dai termini d'uso.
Un codice può sparire dal dataset (revoca) o cambiare abbinamento (decisione dell'amministratore): a ogni importazione sostituisci l'intera tabella dei codici a barre, non aggiornarla in modo incrementale.
Invia solo codici letti davvero sulla confezione. Le segnalazioni inattendibili comportano il blocco dell'account.