Identificatori GS1 & Onboarding

qr3.app si basa su un modello BYO-GTIN/BYO-GLN (Bring Your Own): porti i tuoi identificatori GS1 esistenti — qr3 si occupa del livello digitale del prodotto (Product-Layer) sovrastante.

Cosa fa GS1?

GS1 assegna identificatori univoci a livello globale per prodotti e sedi:

Identificatore	Descrizione	Esempio
GTIN-14	Global Trade Item Number (ID prodotto)	`04012345678901`
GLN-13	Global Location Number (Sede/Azienda)	`4012345000009`
Company Prefix	Prefisso aziendale (7-12 cifre), da cui derivano i GTIN	`4012345`

Per ottenere i GTIN, è necessaria un’adesione a GS1 presso la propria organizzazione nazionale GS1 (ad es. GS1 Austria, GS1 Germany).

Cosa fa qr3.app?

qr3.app utilizza i tuoi identificatori GS1 esistenti e offre:

Resolver conforme a GS1 — /01/{GTIN}/21/{Serial} con Content-Negotiation
EU Digital Product Passport — Creazione DPP, validazione, vista consumatore
Asset QR pronti per la stampa — SVG, PNG, PDF vettoriale, EPS
JSON-LD, DCAT-AP — Dati di prodotto leggibili da dispositivi automatici

Flusso di onboarding

1. Registrare gli identificatori GS1

Prima di poter creare i DPP, devi registrare i tuoi GTIN (o il tuo Company Prefix):

Per API:

curl -X POST https://qr3.app/v1/gs1/identifiers \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"identifier_type": "company_prefix", "value": "4012345", "label": "GreenPower GmbH"}'

Tramite Dashboard:

Naviga su Dashboard → GS1
Seleziona il tipo (GTIN, GLN o Company Prefix)
Inserisci il valore — la validazione della cifra di controllo (Check-Digit) avviene automaticamente
Fai clic su Aggiungi identificatore

La tua organizzazione detiene ogni identificatore una sola volta, in uno dei suoi Workspace. Se registri di nuovo un identificatore rimosso, torna (201, lo stesso id) come autodichiarazione e non verificato, anche se prima della rimozione era verificato; se si trovava in un altro Workspace, viene spostato in questo. Se è ancora registrato, la risposta è 409 con reason already_registered (in questo Workspace) o registered_in_other_workspace (in un altro; workspace lo nomina se puoi aprirlo). Se nel frattempo il Workspace viene archiviato, reason è workspace_archived; non viene registrato nulla.

2. Creare i DPP

Non appena un GTIN è registrato (direttamente o tramite un Company Prefix), puoi creare i DPP associati:

curl -X POST https://qr3.app/v1/dpp \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"gtin": "04012345678901", "product_name": "EcoMax Battery", ...}'

3. Verifica della proprietà

qr3.app verifica a ogni creazione di un DPP se il GTIN utilizzato appartiene alla tua organizzazione:

Registrazione diretta — Il GTIN è registrato come identifier_type: "gtin"
Corrispondenza del prefisso — Il GTIN inizia con un Company Prefix registrato (posizioni 2..N del GTIN-14)

Senza una registrazione corrispondente, viene restituito un errore 422 con l’indicazione di registrare prima il GTIN.

La stessa verifica vale per POST /v1/dpp/batch e POST /v1/dpp/import, in modo sincrono e come job in coda: un GTIN senza registrazione fa rifiutare l’intera richiesta con 422 (titolo GTIN Not Registered, i GTIN rifiutati in gtins, il loro numero in total); non viene creato né accodato nulla. I passaporti esistenti non sono interessati. L’invio di un passaporto al Registro dei prodotti UE (POST /v1/dpp/:id/register) richiede inoltre che l’organizzazione del passaporto sia titolare del GTIN (vedi la sezione 4); altrimenti la risposta è 409 (titolo GTIN Held by Another Organization).

4. Verifica

Una registrazione tramite API o dashboard è un’autodichiarazione (verified_by: "self", verified_at: null). Un identificatore verificato porta verified_at (verified_by: "gs1_registry" o "admin"); lo imposta qr3 dopo aver controllato una richiesta con prova (vedi sotto). Un GTIN o Company Prefix verificato:

vincola il resolver GS1 pubblico per questi GTIN alla tua organizzazione, anche se un’altra organizzazione ha creato prima un passaporte;
blocca ogni altra organizzazione: creare un DPP per un GTIN di questo tipo, anche tramite batch o importazione, restituisce 409 (errors/conflict, titolo GTIN Verified by Another Organization, i GTIN rifiutati in gtins). Batch e importazione vengono rifiutati per intero.

Senza verifica, un GTIN appartiene all’organizzazione che lo detiene da più tempo senza interruzioni (dettagli: GS1-Resolver). Se il tuo GTIN si risolve nel passaporte di un’altra organizzazione, richiedine la verifica.

Richiedere la verifica

Nella dashboard, in GS1, sezione Richiedi la verifica: inserisci il tipo (GTIN o Company Prefix) e il valore, carica una prova e invia la richiesta. La prova mostra che la tua organizzazione ha ottenuto il GTIN o il Company Prefix da GS1, per esempio la conferma di licenza della tua organizzazione GS1 (PDF, PNG, JPEG o WebP). Viene salvata in modo privato; solo la tua organizzazione e il team di qr3 possono vederla. Non c’è alcuna interrogazione automatica a GS1.

Il team di qr3 controlla la prova e approva la richiesta oppure la respinge con una motivazione. Dopo l’approvazione l’identificatore è verificato (verified_by: "admin") e ha gli effetti descritti sopra. Per ogni decisione ricevi un’e-mail all’indirizzo di notifica della tua organizzazione o, in mancanza, a quello del proprietario.

Chi: solo gli amministratori dell’organizzazione (org_admin o il proprietario). Gli altri ruoli e le chiavi API dirette ricevono 403. Neanche il supporto di qr3 può inviare una richiesta a tuo nome.
Stato: pending (in verifica), approved, rejected, withdrawn (ritirata da te) o revoked (verifica revocata in seguito). Puoi ritirare una richiesta in verifica.
409: reason è request_pending (la tua organizzazione ha già una richiesta per questo identificatore), already_verified o verified_elsewhere (un’altra organizzazione l’ha verificato; non viene nominata). Se la tua organizzazione detiene la licenza GS1 corrispondente, scrivi a [email protected]: qr3 esamina entrambe le parti e può revocare una verifica. Se la prova cambia mentre la richiesta viene inviata, reason è proof_changed; invia di nuovo la richiesta.
Altro Workspace: con request_pending, workspace (id, name) e request_id indicano la richiesta aperta se puoi aprire il suo Workspace; ritirala lì. Altrimenti entrambi sono null. Se il Workspace viene archiviato mentre invii la richiesta, reason è workspace_archived; non viene inviato nulla.
Archiviazione: quando un Workspace viene archiviato, le sue richieste in verifica vengono ritirate (withdrawn, nel registro di audit con il motivo workspace archived). La prova torna libera e puoi richiedere di nuovo l’identificatore da un altro Workspace.
Prova: finché la richiesta è in verifica o approvata, il file non può essere né sostituito né eliminato (409, reason: "gs1_verification_proof"). Dopo un rifiuto, un ritiro o una revoca torna libero.
Rimozione: un identificatore verificato non può essere rimosso (409, reason: "verified"). Solo qr3 toglie la verifica, revocandola.

Quando ho bisogno di entrambi?

Attività	GS1	qr3.app
Ottenere i propri GTIN/GLN	✅ Richiesta adesione	—
Validare la cifra di controllo del GTIN	—	✅ API + Dashboard
Generare il codice QR per il prodotto	—	✅
Creare il DPP secondo il regolamento UE	—	✅
Risolvere il GS1 Digital Link	—	✅ Resolver + `/.well-known/gs1resolver`
Registrare nel registro UE	Pianificato (Q4 2026)	Pianificato (Fase 4c)

Riferimento API

POST /v1/gs1/identifiers — Registrazione
GET /v1/gs1/identifiers — Elenco
DELETE /v1/gs1/identifiers/:id — Rimozione
POST /v1/gs1/validate — Validazione (senza registrazione, senza autenticazione)
POST /v1/gs1/verifications — Richiedere la verifica (amministratori dell’organizzazione)
GET /v1/gs1/verifications — Elencare le richieste
GET /v1/gs1/verifications/:id — Leggere una richiesta
POST /v1/gs1/verifications/:id/withdraw — Ritirare una richiesta

Vedi la documentazione API per i dettagli.