GS1 azonosítók & Onboarding

A qr3.app a BYO-GTIN/BYO-GLN (Bring Your Own) modellre épül: te hozod a meglévő GS1 azonosítóidat — a qr3 pedig biztosítja a felettük lévő digitális termékréteget (Product-Layer).

Mit csinál a GS1?

A GS1 világszerte egyedi azonosítókat bocsát ki termékekhez és helyszínekhez:

Azonosító	Leírás	Példa
GTIN-14	Global Trade Item Number (termékazonosító)	`04012345678901`
GLN-13	Global Location Number (helyszín/cég)	`4012345000009`
Company Prefix	Vállalati előtag (7-12 számjegy), amelyből a GTIN-ek származnak	`4012345`

A GTIN-ek beszerzéséhez GS1-tagságra van szükséged a helyi nemzeti GS1-szervezetnél (pl. GS1 Austria, GS1 Germany).

Mit csinál a qr3.app?

A qr3.app a meglévő GS1 azonosítóidat használja, és az alábbiakat kínálja:

GS1-konform Resolver — /01/{GTIN}/21/{Serial} Content-Negotiation támogatással
EU Digitális Termékútlevél — DPP létrehozása, validálása és fogyasztói nézet
Nyomtatásra kész QR-eszközök — SVG, PNG, vektoros PDF, EPS
JSON-LD, DCAT-AP — Gépileg olvasható termékadatok

Onboarding folyamat

1. GS1 azonosítók regisztrálása

Mielőtt DPP-ket hozhatnál létre, regisztrálnod kell a GTIN-jeidet (vagy a Company Prefix előtagodat):

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

Irányítópulton (Dashboard) keresztül:

Navigálj a Dashboard → GS1 menüponthoz
Válaszd ki a típust (GTIN, GLN vagy Company Prefix)
Add meg az értéket — az ellenőrző számjegy (Check-Digit) ellenőrzése automatikusan megtörténik
Kattints az Azonosító hozzáadása gombra

A szervezeted minden azonosítót csak egyszer birtokol, valamelyik Workspace-ében. Ha egy eltávolított azonosítót újra regisztrálsz, visszatér (201, ugyanaz az id) saját nyilatkozatként és hitelesítés nélkül, akkor is, ha az eltávolítás előtt hitelesített volt; ha egy másik Workspace-ben volt, átkerül ebbe. Ha még regisztrálva van, a válasz 409, a reason értéke already_registered (ebben a Workspace-ben) vagy registered_in_other_workspace (egy másikban; a workspace megnevezi, ha megnyithatod). Ha a Workspace-t közben archiválják, a reason értéke workspace_archived; semmi sem kerül regisztrálásra.

2. DPP-k létrehozása

Amint egy GTIN regisztrálva van (közvetlenül vagy egy Company Prefix-en keresztül), létrehozhatsz hozzá DPP-ket:

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. Tulajdonjog-ellenőrzés

A qr3.app minden DPP létrehozásakor ellenőrzi, hogy a használt GTIN a te szervezetedhez tartozik-e:

Közvetlen regisztráció — A GTIN identifier_type: "gtin" típusként van regisztrálva
Előtag-egyezés (Prefix-Match) — A GTIN egy regisztrált Company Prefix előtaggal kezdődik (a GTIN-14 2..N pozíciója)

Megfelelő regisztráció nélkül egy 422-es hibaüzenetet kapsz, amely arra figyelmeztet, hogy először regisztráld a GTIN-t.

Ugyanez az ellenőrzés érvényes a POST /v1/dpp/batch és a POST /v1/dpp/import hívásra, szinkron módon és sorba állított feladatként is: egyetlen regisztráció nélküli GTIN az egész kérést elutasítja 422-vel (cím GTIN Not Registered, az elutasított GTIN-ek a gtins mezőben, számuk a total mezőben); semmi nem jön létre, és semmi nem kerül sorba. A meglévő útlevelek nem érintettek. Egy útlevél bejelentése az EU-termékregiszterbe (POST /v1/dpp/:id/register) ezenfelül megköveteli, hogy az útlevél szervezete birtokolja a GTIN-t (lásd a 4. szakaszt); különben a válasz 409 (cím GTIN Held by Another Organization).

4. Hitelesítés

Az API-n vagy a dashboardon keresztüli regisztráció saját nyilatkozat (verified_by: "self", verified_at: null). A hitelesített azonosító verified_at értéket hordoz (verified_by: "gs1_registry" vagy "admin"); ezt a qr3 állítja be, miután ellenőrizte a bizonyítékkal beküldött kérelmet (lásd lent). Egy hitelesített GTIN vagy Company Prefix:

a nyilvános GS1 resolvert ezeknél a GTIN-eknél a te szervezetedhez köti, akkor is, ha egy másik szervezet korábban hozott létre útlevelet;
minden más szervezetet letilt: DPP létrehozása egy ilyen GTIN-hez, kötegben vagy importtal is, 409-et ad (errors/conflict, cím GTIN Verified by Another Organization, az elutasított GTIN-ek a gtins mezőben). A köteg és az import egészében elutasításra kerül.

Hitelesítés nélkül a GTIN ahhoz a szervezethez tartozik, amelynél a legrégebben, megszakítás nélkül van (részletek: GS1-Resolver). Ha a GTIN-ed egy másik szervezet útlevelére oldódik fel, kérd a hitelesítését.

Hitelesítés kérése

A dashboardon a GS1 alatt, a Hitelesítés kérése részben: add meg a típust (GTIN vagy Company Prefix) és az értéket, tölts fel egy bizonyítékot, és küldd be a kérelmet. A bizonyíték azt mutatja, hogy a szervezeted a GS1-től kapta a GTIN-t vagy a Company Prefixet, például a GS1-szervezeted licencvisszaigazolása (PDF, PNG, JPEG vagy WebP). Privát módon tároljuk; csak a szervezeted és a qr3 csapata látja. Automatikus GS1-lekérdezés nincs.

A qr3 csapata ellenőrzi a bizonyítékot, és jóváhagyja a kérelmet, vagy indoklással elutasítja. Jóváhagyás után az azonosító hitelesített (verified_by: "admin"), és a fent leírt módon hat. Minden döntésről e-mailt kapsz a szervezeted értesítési címére, ennek hiányában a tulajdonos címére.

Ki: csak a szervezet adminisztrátorai (org_admin vagy a tulajdonos). Más szerepkörök és a közvetlen API-kulcsok 403-at kapnak. A qr3 ügyfélszolgálata sem küldhet be kérelmet a nevedben.
Állapot: pending (ellenőrzés alatt), approved, rejected, withdrawn (általad visszavonva) vagy revoked (a hitelesítést később érvénytelenítették). Ellenőrzés alatt álló kérelmet visszavonhatsz.
409: a reason értéke request_pending (a szervezetednek már van kérelme ehhez az azonosítóhoz), already_verified vagy verified_elsewhere (egy másik szervezet hitelesítette; nem nevezzük meg). Ha a szervezetednél van hozzá a GS1-licenc, írj az [email protected] címre: a qr3 mindkét felet megvizsgálja, és érvénytelenítheti a hitelesítést. Ha a bizonyíték a kérelem beküldése közben megváltozik, a reason értéke proof_changed; küldd be újra a kérelmet.
Másik Workspace: request_pending esetén a workspace (id, name) és a request_id megnevezi a nyitott kérelmet, ha megnyithatod a Workspace-ét; ott vond vissza. Különben mindkettő null. Ha a Workspace-t a kérelem beküldése közben archiválják, a reason értéke workspace_archived; semmi sem kerül beküldésre.
Archiválás: ha egy Workspace-t archiválnak, az ellenőrzés alatt álló kérelmeit visszavonjuk (withdrawn, az auditnaplóban workspace archived indokkal). A bizonyíték ezután ismét szabad, és az azonosítót egy másik Workspace-ből újra kérelmezheted.
Bizonyíték: amíg a kérelem ellenőrzés alatt áll vagy jóvá van hagyva, a fájl nem cserélhető le és nem törölhető (409, reason: "gs1_verification_proof"). Elutasítás, visszavonás vagy érvénytelenítés után újra szabad.
Eltávolítás: hitelesített azonosító nem távolítható el (409, reason: "verified"). A hitelesítést csak a qr3 szüntetheti meg, érvénytelenítéssel.

Mikor van szükségem mindkettőre?

Feladat	GS1	qr3.app
Saját GTIN/GLN azonosítók beszerzése	✅ Tagság szükséges	—
GTIN ellenőrző számjegy validálása	—	✅ API + Dashboard
QR-kód generálása termékhez	—	✅
DPP létrehozása az EU-rendeletnek megfelelően	—	✅
GS1 Digital Link feloldása	—	✅ Resolver + `/.well-known/gs1resolver`
Regisztráció az EU-Registry-ben	Tervezve (2026 Q4)	Tervezve (4c fázis)

API-referencia

POST /v1/gs1/identifiers — Regisztráció
GET /v1/gs1/identifiers — Listázás
DELETE /v1/gs1/identifiers/:id — Eltávolítás
POST /v1/gs1/validate — Validálás (regisztráció és hitelesítés nélkül)
POST /v1/gs1/verifications — Hitelesítés kérése (a szervezet adminisztrátorai)
GET /v1/gs1/verifications — Kérelmek listázása
GET /v1/gs1/verifications/:id — Kérelem lekérése
POST /v1/gs1/verifications/:id/withdraw — Kérelem visszavonása

A részletekért lásd az API-dokumentációt.