GS1 identifikatoriai ir integracija

qr3.app naudoja BYO-GTIN / BYO-GLN modelį (angl. Bring Your Own): jūs pateikiate savo esamus GS1 identifikatorius, o qr3 pasirūpina skaitmeniniu produkto sluoksniu virš jų.

Ką daro GS1?

GS1 suteikia unikalius identifikatorius produktams ir vietoms visame pasaulyje:

Identifikatorius	Aprašymas	Pavyzdys
GTIN-14	Global Trade Item Number (produkto ID)	`04012345678901`
GLN-13	Global Location Number (vietos / įmonės ID)	`4012345000009`
Company Prefix	Įmonės prefiksas (7–12 skaitmenų), iš kurio generuojami GTIN	`4012345`

Norėdami gauti GTIN, turite turėti GS1 narystę savo šalies GS1 organizacijoje (pvz., „GS1 Austria“, „GS1 Germany“).

Ką daro qr3.app?

qr3.app naudoja jūsų turimus GS1 identifikatorius ir siūlo:

GS1 standartus atitinkantis nukreipimo įrankis (Resolver) — /01/{GTIN}/21/{Serial} su turinio derybomis (Content-Negotiation)
ES skaitmeninis produkto pasas (DPP) — DPP kūrimas, patvirtinimas, vartotojo peržiūra
Spaudai paruošti QR failai — SVG, PNG, vektorinis PDF, EPS
JSON-LD, DCAT-AP — mašininio skaitymo produktų duomenys

Integracijos eiga (Onboarding)

1. GS1 identifikatorių registravimas

Prieš kurdami DPP, turite užregistruoti savo GTIN (arba įmonės prefiksą):

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

Naudojant valdymo skydelį (Dashboard):

Eikite į Valdymo skydelis → GS1
Pasirinkite tipą (GTIN, GLN arba Company Prefix)
Įveskite reikšmę — kontrolinio skaitmens patikra (Check-Digit) atliekama automatiškai
Spustelėkite Pridėti identifikatorių

Jūsų organizacija kiekvieną identifikatorių turi tik vieną kartą, vienoje iš savo Workspace. Jei pašalintą identifikatorių užregistruojate dar kartą, jis grįžta (201, tas pats id) kaip savideklaracija ir nepatvirtintas, net jei prieš pašalinimą buvo patvirtintas; jei jis buvo kitoje Workspace, jis perkeliamas į šią. Jei jis vis dar užregistruotas, atsakymas yra 409 su reason already_registered (šioje Workspace) arba registered_in_other_workspace (kitoje; workspace ją nurodo, jei galite ją atidaryti). Jei Workspace tuo metu archyvuojama, reason yra workspace_archived; niekas neužregistruojama.

2. DPP kūrimas

Kai tik GTIN yra užregistruotas (tiesiogiai arba per įmonės prefiksą), galite kurti DPP:

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. Nuosavybės patikra

qr3.app kiekvieno DPP kūrimo metu tikrina, ar naudojamas GTIN priklauso jūsų organizacijai:

Tiesioginė registracija — GTIN yra užregistruotas kaip identifier_type: "gtin"
Prefikso atitikimas — GTIN prasideda registruotu įmonės prefiksu (GTIN-14 2..N pozicijos)

Jei atitinkamos registracijos nėra, grąžinama 422 klaida su pranešimu, kad pirmiausia reikia užregistruoti GTIN.

Ta pati patikra galioja POST /v1/dpp/batch ir POST /v1/dpp/import, sinchroniškai ir kaip eilėje esanti užduotis: vienas neužregistruotas GTIN atmeta visą užklausą su 422 (pavadinimas GTIN Not Registered, atmesti GTIN lauke gtins, jų skaičius lauke total); nieko nesukuriama ir į eilę nededama. Esami pasai nekeičiami. Paso pateikimas ES produktų registrui (POST /v1/dpp/:id/register) papildomai reikalauja, kad paso organizacija valdytų GTIN (žr. 4 skyrių); kitu atveju atsakymas yra 409 (pavadinimas GTIN Held by Another Organization).

4. Patvirtinimas

Registracija per API ar valdymo skydelį yra savarankiška deklaracija (verified_by: "self", verified_at: null). Patvirtintas identifikatorius turi verified_at (verified_by: "gs1_registry" arba "admin"); jį nustato qr3, patikrinęs prašymą su įrodymu (žr. toliau). Patvirtintas GTIN arba įmonės prefiksas:

susieja viešą GS1 resolverį šiems GTIN su jūsų organizacija, net jei kita organizacija pasą sukūrė anksčiau;
blokuoja visas kitas organizacijas: DPP kūrimas tokiam GTIN, taip pat paketu ar importu, grąžina 409 (errors/conflict, pavadinimas GTIN Verified by Another Organization, atmesti GTIN lauke gtins). Paketas ir importas atmetami visa apimtimi.

Be patvirtinimo GTIN priklauso organizacijai, ilgiausiai be pertraukos jį turinčiai (išsamiau: GS1 Resolver). Jei jūsų GTIN išsprendžiamas į kitos organizacijos pasą, pateikite prašymą jį patvirtinti.

Patvirtinimo prašymas

Valdymo skydelyje skiltyje GS1, dalyje Prašyti patvirtinimo: įveskite tipą (GTIN arba įmonės prefiksas) ir vertę, įkelkite įrodymą ir pateikite prašymą. Įrodymas parodo, kad jūsų organizacija turi GS1 suteiktą GTIN arba įmonės prefiksą, pavyzdžiui, jūsų GS1 organizacijos licencijos patvirtinimą (PDF, PNG, JPEG arba WebP). Jis saugomas privačiai; jį mato tik jūsų organizacija ir qr3 komanda. Automatinės užklausos į GS1 nėra.

qr3 komanda patikrina įrodymą ir prašymą patvirtina arba atmeta nurodydama priežastį. Patvirtinus identifikatorius yra patvirtintas (verified_by: "admin") ir veikia, kaip aprašyta aukščiau. Apie kiekvieną sprendimą gausite el. laišką jūsų organizacijos pranešimų adresu, o jei jo nėra, savininko adresu.

Kas: tik organizacijos administratoriai (org_admin arba savininkas). Kiti vaidmenys ir tiesioginiai API raktai gauna 403. Ir qr3 pagalba negali pateikti prašymo jūsų vardu.
Būsena: pending (tikrinamas), approved, rejected, withdrawn (jūsų atšauktas) arba revoked (patvirtinimas vėliau panaikintas). Tikrinamą prašymą galite atšaukti.
409: reason yra request_pending (jūsų organizacija jau turi prašymą šiam identifikatoriui), already_verified arba verified_elsewhere (jį patvirtino kita organizacija; ji neįvardijama). Jei jūsų organizacija turi jam GS1 licenciją, rašykite adresu [email protected]: qr3 patikrina abi puses ir gali panaikinti patvirtinimą. Jei įrodymas pasikeičia teikiant prašymą, reason yra proof_changed; pateikite prašymą dar kartą.
Kita Workspace: esant request_pending, workspace (id, name) ir request_id nurodo atvirą prašymą, jei galite atidaryti jo Workspace; ten jį atšaukite. Kitu atveju abu yra null. Jei Workspace archyvuojama, kol teikiate prašymą, reason yra workspace_archived; nieko nepateikiama.
Archyvavimas: kai Workspace archyvuojama, jos tikrinami prašymai atšaukiami (withdrawn, audito žurnale su priežastimi workspace archived). Įrodymas vėl tampa laisvas, ir identifikatoriaus galite vėl prašyti iš kitos Workspace.
Įrodymas: kol prašymas tikrinamas arba patvirtintas, failo negalima nei pakeisti, nei ištrinti (409, reason: "gs1_verification_proof"). Po atmetimo, atšaukimo ar panaikinimo jis vėl laisvas.
Pašalinimas: patvirtinto identifikatoriaus pašalinti negalima (409, reason: "verified"). Patvirtinimą panaikina tik qr3.

Kada man reikia abiejų?

Užduotis	GS1	qr3.app
Gauti savo GTIN / GLN	✅ Reikalinga narystė	—
Patvirtinti GTIN kontrolinį skaitmenį	—	✅ API + valdymo skydelis
Sugeneruoti produkto QR kodą	—	✅
Sukurti DPP pagal ES reglamentą	—	✅
Iššifruoti (nukreipti) GS1 Digital Link	—	✅ Resolver + `/.well-known/gs1resolver`
Registruoti ES registre	Planuojama (2026 m. IV ketv.)	Planuojama (4c etapas)

API nuorodos

POST /v1/gs1/identifiers — Registruoti
GET /v1/gs1/identifiers — Sąrašas
DELETE /v1/gs1/identifiers/:id — Pašalinti
POST /v1/gs1/validate — Patvirtinti (be registracijos, nereikia autorizacijos)
POST /v1/gs1/verifications — Prašyti patvirtinimo (organizacijos administratoriai)
GET /v1/gs1/verifications — Prašymų sąrašas
GET /v1/gs1/verifications/:id — Gauti prašymą
POST /v1/gs1/verifications/:id/withdraw — Atšaukti prašymą

Išsamesnės informacijos ieškokite API dokumentacijoje.