GS1-identifikaatorid ja liitumine

qr3.app põhineb BYO-GTIN/BYO-GLN mudelil (Bring Your Own): Sina tood oma olemasolevad GS1-identifikaatorid — qr3 pakub nende kohale digitaalset tootekihitust (Product-Layer).

Mida teeb GS1?

GS1 väljastab globaalselt kordumatuid identifikaatoreid toodetele ja asukohtadele:

Identifikaator	Kirjeldus	Näide
GTIN-14	Global Trade Item Number (toote ID)	`04012345678901`
GLN-13	Global Location Number (asukoht/ettevõte)	`4012345000009`
Company Prefix	Ettevõtte eesliide (7–12 kohta), millest tuletatakse GTIN-id	`4012345`

GTIN-ide saamiseks on sul vaja GS1 liikmelisust oma riiklikus GS1 organisatsioonis (nt GS1 Austria, GS1 Germany).

Mida teeb qr3.app?

qr3.app kasutab sinu olemasolevaid GS1-identifikaatoreid ja pakub:

GS1-ühilduv lahendaja (Resolver) — /01/{GTIN}/21/{Serial} koos sisuläbirääkimisega (Content-Negotiation)
ELi digitaalne tootepass (DPP) — DPP loomine, valideerimine, tarbijavaade
Trükivalmis QR-failid — SVG, PNG, vektor-PDF, EPS
JSON-LD, DCAT-AP — masinloetavad tooteandmed

Liitumisprotsess (Onboarding-Flow)

1. Registreeri GS1-identifikaatorid

Enne kui saad DPP-sid luua, pead registreerima oma GTIN-id (või oma ettevõtte eesliite / Company Prefix):

API kaudu:

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

Töölaua (Dashboard) kaudu:

Navigeeri valikusse Dashboard → GS1
Vali tüüp (GTIN, GLN või Company Prefix)
Sisesta väärtus — kontrollarvu (Check-Digit) valideerimine toimub automaatselt
Klõpsa Lisa identifikaator

Sinu organisatsioonil on iga identifikaator ainult üks kord, ühes tema Workspace’idest. Kui registreerid eemaldatud identifikaatori uuesti, tuleb see tagasi (201, sama id) omadeklaratsioonina ja kinnitamata, isegi kui see oli enne eemaldamist kinnitatud; kui see oli teises Workspace’is, kolib see siia. Kui see on endiselt registreeritud, on vastus 409, mille reason on already_registered (selles Workspace’is) või registered_in_other_workspace (teises; workspace nimetab selle, kui sul on lubatud seda avada). Kui Workspace vahepeal arhiveeritakse, on reason workspace_archived; midagi ei registreerita.

2. Loo DPP-d

Niipea kui GTIN on registreeritud (otse või ettevõtte eesliite kaudu), saad sellega luua DPP-sid:

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. Omanikuõiguse kontroll

qr3.app kontrollib iga DPP loomise ajal, kas kasutatud GTIN kuulub sinu organisatsioonile:

Otsene registreerimine — GTIN on registreeritud väärtusega identifier_type: "gtin"
Eesliite kattuvus (Prefix-Match) — GTIN algab registreeritud ettevõtte eesliitega (GTIN-14 positsioonid 2..N)

Ilma sobiva registreeringuta tagastatakse viga 422 koos juhisega GTIN esmalt registreerida.

Sama kontroll kehtib päringutele POST /v1/dpp/batch ja POST /v1/dpp/import, sünkroonselt ja järjekorda pandud tööna: üks registreerimata GTIN lükkab kogu päringu tagasi veaga 422 (pealkiri GTIN Not Registered, tagasi lükatud GTIN-id väljal gtins, nende arv väljal total); midagi ei looda ega panda järjekorda. Olemasolevaid passe see ei mõjuta. Passi esitamine EL-i tooteregistrisse (POST /v1/dpp/:id/register) nõuab lisaks, et passi organisatsioon omab GTIN-i (vt jaotist 4); muidu on vastus 409 (pealkiri GTIN Held by Another Organization).

4. Kinnitamine

Registreerimine API või juhtpaneeli kaudu on enda deklaratsioon (verified_by: "self", verified_at: null). Kinnitatud identifikaatoril on verified_at (verified_by: "gs1_registry" või "admin"); selle määrab qr3 pärast tõendiga taotluse kontrollimist (vt allpool). Kinnitatud GTIN või ettevõtte eesliide:

seob avaliku GS1-lahendaja nende GTIN-ide puhul sinu organisatsiooniga, isegi kui teine organisatsioon lõi passi varem;
blokeerib kõik teised organisatsioonid: sellise GTIN-i jaoks DPP loomine, ka partii või impordi kaudu, tagastab 409 (errors/conflict, pealkiri GTIN Verified by Another Organization, tagasi lükatud GTIN-id väljal gtins). Partii ja import lükatakse tagasi tervikuna.

Ilma kinnituseta kuulub GTIN organisatsioonile, kellel see on olnud kõige kauem katkestuseta (üksikasjad: GS1-lahendaja). Kui sinu GTIN lahendatakse teise organisatsiooni passiks, taotle selle kinnitamist.

Kinnitamise taotlemine

Juhtpaneelil jaotises GS1, osas Taotle kinnitamist: sisesta tüüp (GTIN või ettevõtte eesliide) ja väärtus, laadi üles tõend ja esita taotlus. Tõend näitab, et sinu organisatsioonil on GS1-lt saadud GTIN või ettevõtte eesliide, näiteks sinu GS1 organisatsiooni litsentsi kinnitus (PDF, PNG, JPEG või WebP). See salvestatakse privaatselt; seda näevad ainult sinu organisatsioon ja qr3 meeskond. Automaatset päringut GS1-sse ei ole.

qr3 meeskond kontrollib tõendit ning kiidab taotluse heaks või lükkab selle põhjendusega tagasi. Pärast heakskiitu on identifikaator kinnitatud (verified_by: "admin") ja toimib, nagu eespool kirjeldatud. Iga otsuse kohta saad e-kirja oma organisatsiooni teavitusaadressile, selle puudumisel omaniku aadressile.

Kes: ainult organisatsiooni administraatorid (org_admin või omanik). Teised rollid ja otsesed API-võtmed saavad 403. Ka qr3 tugi ei saa sinu nimel taotlust esitada.
Olek: pending (kontrollimisel), approved, rejected, withdrawn (sinu poolt tagasi võetud) või revoked (kinnitus hiljem tühistatud). Kontrollimisel oleva taotluse saad tagasi võtta.
409: reason on request_pending (sinu organisatsioonil on selle identifikaatori kohta juba taotlus), already_verified või verified_elsewhere (teine organisatsioon on selle kinnitanud; teda ei nimetata). Kui sinu organisatsioonil on selle GS1 litsents, kirjuta aadressile [email protected]: qr3 kontrollib mõlemat poolt ja võib kinnituse tühistada. Kui tõend muutub taotluse esitamise ajal, on reason proof_changed; esita taotlus uuesti.
Teine Workspace: request_pending korral nimetavad workspace (id, name) ja request_id avatud taotluse, kui sul on lubatud selle Workspace’i avada; võta see seal tagasi. Muidu on mõlemad null. Kui Workspace arhiveeritakse taotluse esitamise ajal, on reason workspace_archived; midagi ei esitata.
Arhiveerimine: kui Workspace arhiveeritakse, võetakse selle kontrollimisel olevad taotlused tagasi (withdrawn, auditilogis põhjusega workspace archived). Tõend on seejärel jälle vaba ja saad identifikaatorit teisest Workspace’ist uuesti taotleda.
Tõend: kuni taotlus on kontrollimisel või heaks kiidetud, ei saa faili asendada ega kustutada (409, reason: "gs1_verification_proof"). Pärast tagasilükkamist, tagasivõtmist või tühistamist on see jälle vaba.
Eemaldamine: kinnitatud identifikaatorit ei saa eemaldada (409, reason: "verified"). Kinnituse tühistab ainult qr3.

Millal on mul vaja mõlemat?

Ülesanne	GS1	qr3.app
Oma GTIN-ide/GLN-ide hankimine	✅ Liikmelisus vajalik	—
GTIN-i kontrollarvu (Check-Digit) valideerimine	—	✅ API + töölaud
Tootele QR-koodi genereerimine	—	✅
DPP loomine vastavalt EL-i määrusele	—	✅
GS1 Digital Linki lahendamine	—	✅ Resolver + `/.well-known/gs1resolver`
EL-i registris (EU-Registry) registreerimine	Planeeritud (Q4 2026)	Planeeritud (faas 4c)

API viited

POST /v1/gs1/identifiers — Registreerimine
GET /v1/gs1/identifiers — Nimekirja kuvamine
DELETE /v1/gs1/identifiers/:id — Eemaldamine
POST /v1/gs1/validate — Valideerimine (ilma registreerimiseta, autentimist pole vaja)
POST /v1/gs1/verifications — Kinnitamise taotlemine (organisatsiooni administraatorid)
GET /v1/gs1/verifications — Taotluste loend
GET /v1/gs1/verifications/:id — Taotluse pärimine
POST /v1/gs1/verifications/:id/withdraw — Taotluse tagasivõtmine

Üksikasju vaata API dokumentatsioonist.