Přeskočit na obsah
qr3.app Docs

Identifikátory GS1 a onboarding

Identifikátory GS1 a onboarding

qr3.app sází na model BYO-GTIN/BYO-GLN (Bring Your Own): Přinesete si své stávající identifikátory GS1 — qr3 se postará o digitální produktovou vrstvu nad nimi.

Co dělá GS1?

GS1 přiděluje celosvětově unikátní identifikátory pro produkty a lokality:

IdentifikátorPopisPříklad
GTIN-14Global Trade Item Number (ID produktu)04012345678901
GLN-13Global Location Number (lokalita/firma)4012345000009
Company PrefixFiremní předpona (7–12 číslic), ze které se odvozují GTIN4012345

Chcete-li získat GTIN, potřebujete členství v GS1 u vaší národní organizace GS1 (např. GS1 Austria, GS1 Germany).

Co dělá qr3.app?

qr3.app využívá vaše stávající identifikátory GS1 a nabízí:

  • Resolver kompatibilní s GS1 — /01/{GTIN}/21/{Serial} s Content-Negotiation
  • Digitální pas produktu EU — tvorba DPP, validace, zobrazení pro spotřebitele
  • QR podklady připravené k tisku — SVG, PNG, vektorové PDF, EPS
  • JSON-LD, DCAT-AP — strojově čitelná produktová data

Postup onboardingu

1. Registrace identifikátorů GS1

Předtím než budete moci vytvářet DPP, musíte zaregistrovat své GTIN (nebo svůj Company Prefix):

Přes API:

Terminál
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"}'

Přes dashboard:

  1. Přejděte do Dashboard → GS1
  2. Vyberte typ (GTIN, GLN nebo Company Prefix)
  3. Zadejte hodnotu — validace kontrolní číslice (Check-Digit) proběhne automaticky
  4. Klikněte na Přidat identifikátor

Vaše organizace má každý identifikátor jen jednou, v jednom ze svých Workspace. Pokud odstraněný identifikátor zaregistrujete znovu, vrátí se (201, stejné id) jako vlastní prohlášení a neověřený, i když byl před odstraněním ověřený; pokud byl v jiném Workspace, přesune se do tohoto. Pokud je stále registrovaný, odpověď je 409 s reason already_registered (v tomto Workspace) nebo registered_in_other_workspace (v jiném; workspace ho uvede, pokud ho smíte otevřít). Pokud je Workspace mezitím archivován, reason je workspace_archived; nic se nezaregistruje.

2. Vytvoření DPP

Jakmile je GTIN zaregistrována (přímo nebo prostřednictvím Company Prefix), můžete s ní vytvářet DPP:

Terminál
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. Ověření vlastnictví (Ownership)

qr3.app při každém vytváření DPP kontroluje, zda použitá GTIN patří vaší organizaci:

  1. Přímá registrace — GTIN je zaregistrována jako identifier_type: "gtin"
  2. Shoda předpony (Prefix-Match) — GTIN začíná registrovaným Company Prefix (pozice 2..N v GTIN-14)

Bez odpovídající registrace dojde k chybě 422 s upozorněním, že je nejprve nutné GTIN zaregistrovat.

Stejná kontrola platí pro POST /v1/dpp/batch a POST /v1/dpp/import, synchronně i jako zařazenou úlohu: jedna GTIN bez registrace odmítne celý požadavek s 422 (titulek GTIN Not Registered, odmítnuté GTIN v gtins, jejich počet v total); nic se nevytvoří ani nezařadí. Stávající pasy zůstávají beze změny. Přihlášení pasu do registru produktů EU (POST /v1/dpp/:id/register) navíc vyžaduje, aby organizace pasu GTIN držela (viz oddíl 4); jinak je odpověď 409 (titulek GTIN Held by Another Organization).

4. Ověření

Registrace přes API nebo dashboard je vlastní prohlášení (verified_by: "self", verified_at: null). Ověřený identifikátor nese verified_at (verified_by: "gs1_registry" nebo "admin"); nastavuje ho qr3 poté, co zkontroluje žádost s dokladem (viz níže). Ověřená GTIN nebo Company Prefix:

  • váže veřejný GS1-Resolver pro tyto GTIN na vaši organizaci, i když jiná organizace vytvořila pas dříve;
  • blokuje každou jinou organizaci: vytvoření DPP pro takovou GTIN, i dávkou nebo importem, vrací 409 (errors/conflict, titulek GTIN Verified by Another Organization, odmítnuté GTIN v gtins). Dávka a import se odmítnou jako celek.

Bez ověření patří GTIN organizaci, která ji drží nejdéle bez přerušení (podrobnosti: GS1-Resolver). Pokud se vaše GTIN přeloží na pas jiné organizace, požádejte o její ověření.

Žádost o ověření

V dashboardu v části GS1, oddíl Požádat o ověření: zadejte typ (GTIN nebo Company Prefix) a hodnotu, nahrajte doklad a podejte žádost. Doklad ukazuje, že vaše organizace má GTIN nebo Company Prefix od GS1, například potvrzení licence od vaší organizace GS1 (PDF, PNG, JPEG nebo WebP). Ukládá se soukromě; vidí ho jen vaše organizace a tým qr3. Automatický dotaz u GS1 neexistuje.

Tým qr3 doklad zkontroluje a žádost schválí, nebo ji s odůvodněním zamítne. Po schválení je identifikátor ověřen (verified_by: "admin") a působí, jak je popsáno výše. O každém rozhodnutí dostanete e-mail na adresu pro oznámení vaší organizace, jinak na adresu vlastníka.

  • Kdo: jen administrátoři organizace (org_admin nebo vlastník). Ostatní role a přímé API klíče dostanou 403. Ani podpora qr3 nemůže podat žádost vaším jménem.
  • Stav: pending (ve schvalování), approved, rejected, withdrawn (stažena vámi) nebo revoked (ověření později odvoláno). Žádost ve schvalování můžete stáhnout.
  • 409: reason je request_pending (pro tento identifikátor už běží žádost vaší organizace), already_verified nebo verified_elsewhere (ověřila ho jiná organizace; není uvedena). Pokud vaše organizace drží licenci GS1 pro něj, napište na [email protected]: qr3 prověří obě strany a může ověření odvolat. Pokud se doklad změní během podávání žádosti, reason je proof_changed; podejte žádost znovu.
  • Jiný Workspace: u request_pending uvádějí workspace (id, name) a request_id otevřenou žádost, pokud smíte otevřít její Workspace; tam ji stáhněte. Jinak jsou obě null. Pokud je Workspace během podávání žádosti archivován, reason je workspace_archived; nic se nepodá.
  • Archivace: při archivaci Workspace se jeho žádosti ve schvalování stáhnou (withdrawn, v auditním logu s důvodem workspace archived). Doklad je pak opět volný a o identifikátor můžete znovu požádat z jiného Workspace.
  • Doklad: dokud je žádost ve schvalování nebo schválená, soubor nelze nahradit ani smazat (409, reason: "gs1_verification_proof"). Po zamítnutí, stažení nebo odvolání je opět volný.
  • Odstranění: ověřený identifikátor nelze odstranit (409, reason: "verified"). Ověření ruší jen qr3 odvoláním.

Kdy potřebuji obojí?

ÚkolGS1qr3.app
Získání vlastních GTIN/GLN✅ Nutné členství—
Validace kontrolní číslice GTIN—✅ API + Dashboard
Generování QR kódu pro produkt—✅
Vytvoření DPP podle nařízení EU—✅
Překlad GS1 Digital Link—✅ Resolver + /.well-known/gs1resolver
Registrace v registru EUPlánováno (Q4 2026)Plánováno (Fáze 4c)

API reference

  • POST /v1/gs1/identifiers — Registrace
  • GET /v1/gs1/identifiers — Výpis
  • DELETE /v1/gs1/identifiers/:id — Odstranění
  • POST /v1/gs1/validate — Validace (bez registrace, bez autentizace)
  • POST /v1/gs1/verifications — Žádost o ověření (administrátoři organizace)
  • GET /v1/gs1/verifications — Seznam žádostí
  • GET /v1/gs1/verifications/:id — Načtení žádosti
  • POST /v1/gs1/verifications/:id/withdraw — Stažení žádosti

Podrobnosti naleznete v dokumentaci k API.