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

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.

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)

Vedi la documentazione API per i dettagli.