Preskočiť na obsah
qr3.app Docs

GS1 identifikátory & onboarding

GS1 identifikátory & onboarding

qr3.app stavia na modeli BYO-GTIN/BYO-GLN (Bring Your Own): prinesiete si svoje existujúce GS1 identifikátory — qr3 prevezme digitálnu produktovú vrstvu nad nimi.

Čo robí GS1?

GS1 prideľuje celosvetovo jedinečné identifikátory pre produkty a lokality:

IdentifikátorPopisPríklad
GTIN-14Global Trade Item Number (ID produktu)04012345678901
GLN-13Global Location Number (lokalita/firma)4012345000009
Company PrefixFiremný prefix (7-12 miest), z ktorého sa odvodzujú GTIN4012345

Na získanie GTIN potrebujete členstvo v GS1 u vašej národnej organizácie GS1 (napr. GS1 Austria, GS1 Germany).

Čo robí qr3.app?

qr3.app využíva vaše existujúce GS1 identifikátory a ponúka:

  • Resolver kompatibilný s GS1 — /01/{GTIN}/21/{Serial} s Content-Negotiation
  • Digitálny pas produktu EÚ — tvorba DPP, validácia, zobrazenie pre spotrebiteľa
  • QR podklady pripravené na tlač — SVG, PNG, vektorové PDF, EPS
  • JSON-LD, DCAT-AP — strojovo čitateľné údaje o produkte

Onboarding proces

1. Registrácia GS1 identifikátorov

Predtým, ako budete môcť vytvárať DPP, musíte zaregistrovať svoje GTIN (alebo váš Company Prefix):

Cez API:

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

Cez dashboard:

  1. Prejdite na Dashboard → GS1
  2. Vyberte typ (GTIN, GLN alebo Company Prefix)
  3. Zadajte hodnotu — overenie kontrolnej číslice (Check-Digit) prebehne automaticky
  4. Kliknite na Pridať identifikátor

Vaša organizácia má každý identifikátor len raz, v jednom zo svojich Workspace. Ak odstránený identifikátor zaregistrujete znova, vráti sa (201, rovnaké id) ako vlastné vyhlásenie a neoverený, aj keď bol pred odstránením overený; ak bol v inom Workspace, presunie sa do tohto. Ak je stále zaregistrovaný, odpoveď je 409 s reason already_registered (v tomto Workspace) alebo registered_in_other_workspace (v inom; workspace ho uvedie, ak ho smiete otvoriť). Ak sa Workspace medzitým archivuje, reason je workspace_archived; nič sa nezaregistruje.

2. Vytvorenie DPP

Akonáhle je GTIN zaregistrovaná (priamo alebo prostredníctvom Company Prefix), môžete pomocou nej vytvárať DPP:

Terminal window
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. Overenie vlastníctva

qr3.app pri každom vytvorení DPP kontroluje, či použitá GTIN patrí vašej organizácii:

  1. Priama registrácia — GTIN je zaregistrovaná ako identifier_type: "gtin"
  2. Zhoda prefixu — GTIN začína registrovaným Company Prefix (pozícia 2..N v GTIN-14)

Bez zodpovedajúcej registrácie dôjde k chybe 422 s upozornením, že GTIN je potrebné najprv zaregistrovať.

Rovnaká kontrola platí pre POST /v1/dpp/batch a POST /v1/dpp/import, synchrónne aj ako zaradenú úlohu: jedna GTIN bez registrácie odmietne celú požiadavku s 422 (titulok GTIN Not Registered, odmietnuté GTIN v gtins, ich počet v total); nič sa nevytvorí ani nezaradí. Existujúce pasy zostávajú bez zmeny. Prihlásenie pasu do registra produktov EÚ (POST /v1/dpp/:id/register) navyše vyžaduje, aby organizácia pasu GTIN držala (pozri oddiel 4); inak je odpoveď 409 (titulok GTIN Held by Another Organization).

4. Overenie

Registrácia cez API alebo dashboard je vlastné vyhlásenie (verified_by: "self", verified_at: null). Overený identifikátor nesie verified_at (verified_by: "gs1_registry" alebo "admin"); nastavuje ho qr3 po kontrole žiadosti s dokladom (pozri nižšie). Overená GTIN alebo Company Prefix:

  • viaže verejný GS1 resolver pre tieto GTIN na vašu organizáciu, aj keď iná organizácia vytvorila pas skôr;
  • blokuje každú inú organizáciu: vytvorenie DPP pre takú GTIN, aj dávkou alebo importom, vracia 409 (errors/conflict, titulok GTIN Verified by Another Organization, odmietnuté GTIN v gtins). Dávka a import sa odmietnu ako celok.

Bez overenia patrí GTIN organizácii, ktorá ju drží najdlhšie bez prerušenia (podrobnosti: GS1 resolver). Ak sa vaša GTIN preloží na pas inej organizácie, požiadajte o jej overenie.

Žiadosť o overenie

V dashboarde v časti GS1, oddiel Požiadať o overenie: zadajte typ (GTIN alebo Company Prefix) a hodnotu, nahrajte doklad a podajte žiadosť. Doklad ukazuje, že vaša organizácia má GTIN alebo Company Prefix od GS1, napríklad potvrdenie licencie od vašej organizácie GS1 (PDF, PNG, JPEG alebo WebP). Ukladá sa súkromne; vidí ho len vaša organizácia a tím qr3. Automatický dopyt v GS1 neexistuje.

Tím qr3 doklad skontroluje a žiadosť schváli, alebo ju s odôvodnením zamietne. Po schválení je identifikátor overený (verified_by: "admin") a pôsobí, ako je opísané vyššie. O každom rozhodnutí dostanete e-mail na adresu pre oznámenia vašej organizácie, inak na adresu vlastníka.

  • Kto: len administrátori organizácie (org_admin alebo vlastník). Ostatné roly a priame API kľúče dostanú 403. Ani podpora qr3 nemôže podať žiadosť vaším menom.
  • Stav: pending (v posudzovaní), approved, rejected, withdrawn (stiahnutá vami) alebo revoked (overenie neskôr odvolané). Žiadosť v posudzovaní môžete stiahnuť.
  • 409: reason je request_pending (pre tento identifikátor už existuje žiadosť vašej organizácie), already_verified alebo verified_elsewhere (overila ho iná organizácia; nie je uvedená). Ak má vaša organizácia preň licenciu GS1, napíšte na [email protected]: qr3 preverí obe strany a môže overenie odvolať. Ak sa doklad zmení počas podávania žiadosti, reason je proof_changed; podajte žiadosť znova.
  • Iný Workspace: pri request_pending uvádzajú workspace (id, name) a request_id otvorenú žiadosť, ak smiete otvoriť jej Workspace; tam ju stiahnite. Inak sú obe null. Ak sa Workspace počas podávania žiadosti archivuje, reason je workspace_archived; nič sa nepodá.
  • Archivácia: pri archivácii Workspace sa jeho žiadosti v posudzovaní stiahnu (withdrawn, v audit logu s dôvodom workspace archived). Doklad je potom opäť voľný a o identifikátor môžete znova požiadať z iného Workspace.
  • Doklad: kým je žiadosť v posudzovaní alebo schválená, súbor nemožno nahradiť ani zmazať (409, reason: "gs1_verification_proof"). Po zamietnutí, stiahnutí alebo odvolaní je opäť voľný.
  • Odstránenie: overený identifikátor nemožno odstrániť (409, reason: "verified"). Overenie ruší len qr3 odvolaním.

Kedy potrebujem oboje?

ÚlohaGS1qr3.app
Získanie vlastných GTIN/GLN✅ Vyžaduje sa členstvo—
Validácia kontrolnej číslice GTIN—✅ API + Dashboard
Generovanie QR kódu pre produkt—✅
Vytvorenie DPP podľa nariadenia EÚ—✅
Rozlíšenie GS1 Digital Link—✅ Resolver + /.well-known/gs1resolver
Registrácia v registri EÚPlánované (Q4 2026)Plánované (Fáza 4c)

API referencia

  • POST /v1/gs1/identifiers — Registrácia
  • GET /v1/gs1/identifiers — Zoznam
  • DELETE /v1/gs1/identifiers/:id — Odstránenie
  • POST /v1/gs1/validate — Validácia (bez registrácie, bez autentifikácie)
  • POST /v1/gs1/verifications — Žiadosť o overenie (administrátori organizácie)
  • GET /v1/gs1/verifications — Zoznam žiadostí
  • GET /v1/gs1/verifications/:id — Načítanie žiadosti
  • POST /v1/gs1/verifications/:id/withdraw — Stiahnutie žiadosti

Podrobnosti nájdete v API dokumentácii.