Identificatori GS1 & Onboarding

qr3.app se bazează pe un model BYO-GTIN/BYO-GLN (Bring Your Own): aduci propriii identificatori GS1 existenți — qr3 se ocupă de stratul digital de produs (Product-Layer) de deasupra acestora.

Ce face GS1?

GS1 emite identificatori unici la nivel global pentru produse și locații:

Identificator	Descriere	Exemplu
GTIN-14	Global Trade Item Number (ID produs)	`04012345678901`
GLN-13	Global Location Number (Locație/Companie)	`4012345000009`
Company Prefix	Prefix de companie (7-12 cifre), din care sunt derivate codurile GTIN	`4012345`

Pentru a obține coduri GTIN, ai nevoie de calitatea de membru GS1 în cadrul organizației tale naționale GS1 (de ex. GS1 Austria, GS1 Germany).

Ce face qr3.app?

qr3.app utilizează identificatorii tăi GS1 existenți și oferă:

Resolver conform cu GS1 — /01/{GTIN}/21/{Serial} cu Content-Negotiation
EU Digital Product Passport — creare DPP, validare, vizualizare pentru consumatori
Asset-uri QR gata de tipărit — SVG, PNG, PDF vectorial, EPS
JSON-LD, DCAT-AP — date de produs lizibile de către echipamente (machine-readable)

Fluxul de onboarding

1. Înregistrarea identificatorilor GS1

Înainte de a putea crea DPP-uri, trebuie să îți înregistrezi codurile GTIN (sau prefixul de companie - Company Prefix):

Prin 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"}'

Prin Dashboard:

Navighează la Dashboard → GS1
Selectează tipul (GTIN, GLN sau Company Prefix)
Introdu valoarea — validarea cifrei de control (Check-Digit) se realizează automat
Dă clic pe Adăugare identificator

Organizația ta deține fiecare identificator o singură dată, într-unul dintre Workspace-urile sale. Dacă înregistrezi din nou un identificator eliminat, acesta revine (201, același id) ca declarație proprie și neverificat, chiar dacă era verificat înainte de eliminare; dacă era în alt Workspace, se mută în acesta. Dacă este încă înregistrat, răspunsul este 409 cu reason already_registered (în acest Workspace) sau registered_in_other_workspace (în altul; workspace îl numește dacă îl poți deschide). Dacă Workspace-ul este arhivat între timp, reason este workspace_archived; nu se înregistrează nimic.

2. Crearea DPP-urilor

De îndată ce un cod GTIN este înregistrat (direct sau prin intermediul unui Company Prefix), poți crea DPP-uri cu acesta:

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. Verificarea proprietății (Ownership)

qr3.app verifică la fiecare creare de DPP dacă codul GTIN utilizat aparține organizației tale:

Înregistrare directă — Codul GTIN este înregistrat ca identifier_type: "gtin"
Potrivire prefix (Prefix-Match) — Codul GTIN începe cu un Company Prefix înregistrat (pozițiile 2..N din GTIN-14)

Fără o înregistrare corespunzătoare, se va returna o eroare 422 cu indicația de a înregistra mai întâi codul GTIN.

Aceeași verificare se aplică pentru POST /v1/dpp/batch și POST /v1/dpp/import, sincron și ca job în coadă: un cod GTIN fără înregistrare face ca întreaga cerere să fie refuzată cu 422 (titlu GTIN Not Registered, codurile GTIN refuzate în gtins, numărul lor în total); nu se creează și nu se pune nimic în coadă. Pașapoartele existente nu sunt afectate. Trimiterea unui pașaport către Registrul de produse al UE (POST /v1/dpp/:id/register) cere în plus ca organizația pașaportului să dețină codul GTIN (vezi secțiunea 4); altfel răspunsul este 409 (titlu GTIN Held by Another Organization).

4. Verificare

O înregistrare prin API sau dashboard este o autodeclarare (verified_by: "self", verified_at: null). Un identificator verificat are verified_at (verified_by: "gs1_registry" sau "admin"); îl setează qr3 după ce verifică o cerere cu dovadă (vezi mai jos). Un cod GTIN sau un Company Prefix verificat:

leagă resolverul GS1 public pentru aceste coduri GTIN de organizația ta, chiar dacă o altă organizație a creat mai devreme un pașaport;
blochează orice altă organizație: crearea unui DPP pentru un astfel de cod GTIN, inclusiv prin lot sau import, returnează 409 (errors/conflict, titlu GTIN Verified by Another Organization, codurile GTIN refuzate în gtins). Lotul și importul sunt refuzate în întregime.

Fără verificare, un cod GTIN aparține organizației care îl deține de cel mai mult timp fără întrerupere (detalii: GS1-Resolver). Dacă codul tău GTIN se rezolvă la pașaportul altei organizații, solicită verificarea lui.

Solicitarea verificării

În dashboard, la GS1, secțiunea Solicită verificarea: introdu tipul (GTIN sau Company Prefix) și valoarea, încarcă o dovadă și trimite cererea. Dovada arată că organizația ta are codul GTIN sau Company Prefix de la GS1, de exemplu confirmarea licenței de la organizația ta GS1 (PDF, PNG, JPEG sau WebP). Este stocată privat; o văd doar organizația ta și echipa qr3. Nu există o interogare automată la GS1.

Echipa qr3 verifică dovada și aprobă cererea sau o respinge cu o motivare. După aprobare, identificatorul este verificat (verified_by: "admin") și are efectul descris mai sus. Primești un e-mail despre fiecare decizie la adresa de notificare a organizației tale, altfel la adresa proprietarului.

Cine: doar administratorii organizației (org_admin sau proprietarul). Celelalte roluri și cheile API directe primesc 403. Nici suportul qr3 nu poate trimite o cerere în numele tău.
Status: pending (în verificare), approved, rejected, withdrawn (retrasă de tine) sau revoked (verificare revocată ulterior). O cerere în verificare o poți retrage.
409: reason este request_pending (organizația ta are deja o cerere pentru acest identificator), already_verified sau verified_elsewhere (altă organizație l-a verificat; nu este numită). Dacă organizația ta deține licența GS1 pentru el, scrie la [email protected]: qr3 verifică ambele părți și poate revoca o verificare. Dacă dovada se schimbă în timp ce cererea este trimisă, reason este proof_changed; trimite cererea din nou.
Alt Workspace: la request_pending, workspace (id, name) și request_id indică cererea deschisă dacă îi poți deschide Workspace-ul; retrage-o de acolo. Altfel, ambele sunt null. Dacă Workspace-ul este arhivat în timp ce trimiți cererea, reason este workspace_archived; nu se trimite nimic.
Arhivare: când un Workspace este arhivat, cererile lui aflate în verificare sunt retrase (withdrawn, în jurnalul de audit cu motivul workspace archived). Dovada devine din nou liberă și poți solicita din nou identificatorul dintr-un alt Workspace.
Dovadă: cât timp cererea este în verificare sau aprobată, fișierul nu poate fi nici înlocuit, nici șters (409, reason: "gs1_verification_proof"). După respingere, retragere sau revocare este din nou liber.
Eliminare: un identificator verificat nu poate fi eliminat (409, reason: "verified"). Doar qr3 anulează verificarea, revocând-o.

Când am nevoie de ambele?

Sarcină	GS1	qr3.app
Obținerea propriilor coduri GTIN/GLN	✅ Calitate de membru necesară	—
Validarea cifrei de control GTIN	—	✅ API + Dashboard
Generarea codului QR pentru produs	—	✅
Crearea DPP conform Regulamentului UE	—	✅
Rezoluția GS1 Digital Link	—	✅ Resolver + `/.well-known/gs1resolver`
Înregistrarea în Registrul UE	Planificat (Q4 2026)	Planificat (Faza 4c)

Referință API

POST /v1/gs1/identifiers — Înregistrare
GET /v1/gs1/identifiers — Listare
DELETE /v1/gs1/identifiers/:id — Ștergere
POST /v1/gs1/validate — Validare (fără înregistrare, fără autentificare)
POST /v1/gs1/verifications — Solicitarea verificării (administratorii organizației)
GET /v1/gs1/verifications — Listarea cererilor
GET /v1/gs1/verifications/:id — Obținerea unei cereri
POST /v1/gs1/verifications/:id/withdraw — Retragerea unei cereri

Consultă Documentația API pentru detalii.