Skip to content
qr3.app Docs

GS1 identifikatori i onboarding

GS1 identifikatori i onboarding

qr3.app se oslanja na BYO-GTIN/BYO-GLN model (Bring Your Own): donosite svoje postojeće GS1 identifikatore — qr3 preuzima digitalni sloj proizvoda (Product-Layer) iznad njih.

Što radi GS1?

GS1 dodjeljuje globalno jedinstvene identifikatore za proizvode i lokacije:

IdentifikatorOpisPrimjer
GTIN-14Global Trade Item Number (ID proizvoda)04012345678901
GLN-13Global Location Number (lokacija/tvrtka)4012345000009
Company PrefixPrefiks tvrtke (7-12 znamenki) iz kojeg se izvode GTIN-ovi4012345

Kako biste dobili GTIN-ove, potrebno vam je članstvo u GS1 kod vaše nacionalne GS1 organizacije (npr. GS1 Croatia, GS1 Germany).

Što radi qr3.app?

qr3.app koristi vaše postojeće GS1 identifikatore i nudi:

  • GS1 kompatibilan resolver — /01/{GTIN}/21/{Serial} s Content-Negotiation
  • EU Digital Product Passport — izrada DPP-a, validacija, korisnički prikaz (Consumer-Ansicht)
  • QR materijali spremni za tisak — SVG, PNG, vektorski PDF, EPS
  • JSON-LD, DCAT-AP — strojno čitljivi podaci o proizvodu

Onboarding proces

1. Registracija GS1 identifikatora

Prije nego što možete izraditi DPP-ove, morate registrirati svoje GTIN-ove (ili svoj Company Prefix):

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

Putem nadzorne ploče (Dashboard):

  1. Idite na Nadzorna ploča → GS1
  2. Odaberite vrstu (GTIN, GLN ili Company Prefix)
  3. Unesite vrijednost — provjera kontrolne znamenke (Check-Digit) vrši se automatski
  4. Kliknite Dodaj identifikator

Vaša organizacija ima svaki identifikator samo jednom, u jednom od svojih radnih prostora. Ako uklonjeni identifikator ponovno registrirate, vraća se (201, isti id) kao vlastita izjava i nepotvrđen, čak i ako je prije uklanjanja bio potvrđen; ako je bio u drugom radnom prostoru, premješta se u ovaj. Ako je još registriran, odgovor je 409 s reason already_registered (u ovom radnom prostoru) ili registered_in_other_workspace (u drugom; workspace ga navodi ako ga smijete otvoriti). Ako se radni prostor u međuvremenu arhivira, reason je workspace_archived; ništa se ne registrira.

2. Izrada DPP-ova

Nakon što je GTIN registriran (izravno ili putem Company Prefixa), možete kreirati DPP-ove s njim:

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. Provjera vlasništva (Ownership)

qr3.app prilikom svake izrade DPP-a provjerava pripada li korišteni GTIN vašoj organizaciji:

  1. Izravna registracija — GTIN je registriran kao identifier_type: "gtin"
  2. Podudaranje prefiksa (Prefix-Match) — GTIN počinje s registriranim Company Prefixom (pozicija 2..N u GTIN-14)

Bez odgovarajuće registracije pojavit će se pogreška 422 s napomenom da najprije morate registrirati GTIN.

Ista provjera vrijedi za POST /v1/dpp/batch i POST /v1/dpp/import, sinkrono i kao zadatak u redu: jedan GTIN bez registracije odbija cijeli zahtjev s 422 (naslov GTIN Not Registered, odbijeni GTIN-ovi u gtins, njihov broj u total); ništa se ne izrađuje niti stavlja u red. Postojeće putovnice ostaju nepromijenjene. Prijava putovnice u EU registar proizvoda (POST /v1/dpp/:id/register) dodatno zahtijeva da organizacija putovnice drži GTIN (vidi odjeljak 4); inače je odgovor 409 (naslov GTIN Held by Another Organization).

4. Potvrda

Registracija putem API-ja ili nadzorne ploče je vlastita izjava (verified_by: "self", verified_at: null). Potvrđeni identifikator ima verified_at (verified_by: "gs1_registry" ili "admin"); postavlja ga qr3 nakon što provjeri zahtjev s dokazom (vidi dolje). Potvrđeni GTIN ili Company Prefix:

  • veže javni GS1 resolver za te GTIN-ove uz vašu organizaciju, čak i ako je druga organizacija ranije izradila putovnicu;
  • blokira svaku drugu organizaciju: izrada DPP-a za takav GTIN, i putem skupne obrade ili uvoza, vraća 409 (errors/conflict, naslov GTIN Verified by Another Organization, odbijeni GTIN-ovi u gtins). Skupna obrada i uvoz odbijaju se u cijelosti.

Bez potvrde GTIN pripada organizaciji koja ga drži najdulje bez prekida (detalji: GS1-Resolver). Ako se vaš GTIN razrješava u putovnicu druge organizacije, zatražite njegovu potvrdu.

Zatražiti potvrdu

Na nadzornoj ploči pod GS1, odjeljak Zatraži potvrdu: unesite vrstu (GTIN ili Company Prefix) i vrijednost, učitajte dokaz i pošaljite zahtjev. Dokaz pokazuje da vaša organizacija ima GTIN ili Company Prefix od GS1, na primjer potvrdu licence vaše GS1 organizacije (PDF, PNG, JPEG ili WebP). Sprema se privatno; vide ga samo vaša organizacija i tim qr3. Automatskog upita prema GS1 nema.

Tim qr3 provjerava dokaz te odobrava zahtjev ili ga odbija uz obrazloženje. Nakon odobrenja identifikator je potvrđen (verified_by: "admin") i djeluje kako je opisano gore. O svakoj odluci dobivate e-poruku na adresu za obavijesti vaše organizacije, inače na adresu vlasnika.

  • Tko: samo administratori organizacije (org_admin ili vlasnik). Ostale uloge i izravni API ključevi dobivaju 403. Ni podrška qr3 ne može poslati zahtjev u vaše ime.
  • Status: pending (u provjeri), approved, rejected, withdrawn (povukli ste ga) ili revoked (potvrda kasnije opozvana). Zahtjev u provjeri možete povući.
  • 409: reason je request_pending (vaša organizacija već ima zahtjev za ovaj identifikator), already_verified ili verified_elsewhere (potvrdila ga je druga organizacija; ne navodi se). Ako vaša organizacija ima GS1 licencu za njega, pišite na [email protected]: qr3 provjerava obje strane i može opozvati potvrdu. Ako se dokaz promijeni dok se zahtjev šalje, reason je proof_changed; pošaljite zahtjev ponovno.
  • Drugi radni prostor: kod request_pending workspace (id, name) i request_id navode otvoreni zahtjev ako smijete otvoriti njegov radni prostor; povucite ga ondje. Inače su oba null. Ako se radni prostor arhivira dok šaljete zahtjev, reason je workspace_archived; ništa se ne šalje.
  • Arhiviranje: kada se radni prostor arhivira, njegovi zahtjevi u provjeri se povlače (withdrawn, u revizijskom zapisniku s razlogom workspace archived). Dokaz je zatim ponovno slobodan i identifikator možete ponovno zatražiti iz drugog radnog prostora.
  • Dokaz: dok je zahtjev u provjeri ili odobren, datoteka se ne može ni zamijeniti ni izbrisati (409, reason: "gs1_verification_proof"). Nakon odbijanja, povlačenja ili opoziva ponovno je slobodna.
  • Uklanjanje: potvrđeni identifikator ne može se ukloniti (409, reason: "verified"). Potvrdu ukida samo qr3 opozivom.

Kada mi treba oboje?

ZadatakGS1qr3.app
Dobivanje vlastitih GTIN-ova/GLN-ova✅ Potrebno članstvo—
Validacija GTIN kontrolne znamenke—✅ API + nadzorna ploča
Generiranje QR koda za proizvod—✅
Izrada DPP-a prema EU uredbi—✅
Razlučivanje GS1 Digital Linka—✅ Resolver + /.well-known/gs1resolver
Registracija u EU registruPlanirano (Q4 2026)Planirano (Faza 4c)

API referenca

  • POST /v1/gs1/identifiers — Registracija
  • GET /v1/gs1/identifiers — Popisivanje
  • DELETE /v1/gs1/identifiers/:id — Uklanjanje
  • POST /v1/gs1/validate — Validacija (bez registracije, bez autorizacije)
  • POST /v1/gs1/verifications — Zatražiti potvrdu (administratori organizacije)
  • GET /v1/gs1/verifications — Popis zahtjeva
  • GET /v1/gs1/verifications/:id — Dohvat zahtjeva
  • POST /v1/gs1/verifications/:id/withdraw — Povlačenje zahtjeva

Pogledajte API dokumentaciju za detalje.