Identifikaturi GS1 & Onboarding

qr3.app tibbaża fuq mudell BYO-GTIN/BYO-GLN (Bring Your Own): Inti ġġib l-identifikaturi GS1 eżistenti tiegħek — qr3 tieħu ħsieb is-saff tal-prodott diġitali (digital product layer) fuqhom.

X’tagħmel GS1?

GS1 toħroġ identifikaturi uniċi madwar id-dinja għal prodotti u postijiet:

Identifikatur	Deskrizzjoni	Eżempju
GTIN-14	Global Trade Item Number (ID tal-Prodott)	`04012345678901`
GLN-13	Global Location Number (Post/Kumpanija)	`4012345000009`
Company Prefix	Prefiss tal-Kumpanija (7-12-il ċifra), li minnu jiġu derivati l-GTINs	`4012345`

Biex tikseb GTINs, għandek bżonn sħubija f’GS1 mal-organizzazzjoni nazzjonali tiegħek ta’ GS1 (eż. GS1 Austria, GS1 Germany).

X’tagħmel qr3.app?

qr3.app tuża l-identifikaturi GS1 eżistenti tiegħek u toffri:

Resolver konformi ma’ GS1 — /01/{GTIN}/21/{Serial} b’Content-Negotiation
Passaport Diġitali tal-Prodott tal-UE — Ħolqien ta’ DPP, validazzjoni, u dehra għall-konsumatur
Assessi tal-QR lesti għall-istampar — SVG, PNG, PDF vettorjali, EPS
JSON-LD, DCAT-AP — Data tal-prodott li tista’ tinqara mill-magni

Fluss tal-Onboarding

1. Irreġistra l-Identifikaturi GS1

Qabel ma tkun tista’ toħloq DPPs, trid tirreġistra l-GTINs tiegħek (jew il-Company Prefix tiegħek):

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

Permezz tad-Dashboard:

Innaviga lejn Dashboard → GS1
Agħżel it-tip (GTIN, GLN jew Company Prefix)
Daħħal il-valur — il-validazzjoni taċ-ċifra tal-kontroll (check-digit) issir awtomatikament
Ikklikkja Żid l-Identifikatur

L-organizzazzjoni tiegħek għandha kull identifikatur darba biss, f’wieħed mill-workspaces tagħha. Jekk terġa’ tirreġistra identifikatur li tneħħa, jiġi lura (201, l-istess id) bħala awtodikjarazzjoni u mhux ivverifikat, anki jekk kien ivverifikat qabel ma tneħħa; jekk kien f’workspace ieħor, jiċċaqlaq għal dan. Jekk għadu rreġistrat, it-tweġiba hija 409 b’reason already_registered (f’dan il-workspace) jew registered_in_other_workspace (f’ieħor; workspace isemmih jekk tista’ tiftħu). Jekk il-workspace jiġi arkivjat fil-frattemp, reason huwa workspace_archived; ma jiġi rreġistrat xejn.

2. Oħloq DPPs

Ladarba GTIN tkun irreġistrata (direttament jew permezz ta’ Company Prefix), tista’ toħloq DPPs biha:

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. Verifika tas-Sjieda (Ownership)

qr3.app tivverifika ma’ kull ħolqien ta’ DPP jekk il-GTIN użata tappartjenix għall-organizzazzjoni tiegħek:

Reġistrazzjoni diretta — Il-GTIN hija rreġistrata bħala identifier_type: "gtin"
Tqabbil tal-Prefiss (Prefix-Match) — Il-GTIN tibda b’Company Prefix irreġistrat (pożizzjoni 2..N tal-GTIN-14)

Mingħajr reġistrazzjoni xierqa, ikollok żball 422 b’avviż biex tirreġistra l-GTIN l-ewwel.

L-istess verifika tapplika għal POST /v1/dpp/batch u POST /v1/dpp/import, b’mod sinkronu u bħala job fil-kju: GTIN waħda mingħajr reġistrazzjoni tirrifjuta t-talba kollha b’422 (titlu GTIN Not Registered, il-GTINs miċħuda f’gtins, l-għadd tagħhom f’total); xejn ma jinħoloq jew jitpoġġa fil-kju. Il-passaporti eżistenti ma jintlaqtux. Is-sottomissjoni ta’ passaport lir-Reġistru tal-Prodotti tal-UE (POST /v1/dpp/:id/register) teħtieġ barra minn hekk li l-organizzazzjoni tal-passaport żżomm il-GTIN (ara t-taqsima 4); inkella t-tweġiba hija 409 (titlu GTIN Held by Another Organization).

4. Verifika

Reġistrazzjoni permezz tal-API jew tad-dashboard hija dikjarazzjoni personali (verified_by: "self", verified_at: null). Identifikatur ivverifikat ikollu verified_at (verified_by: "gs1_registry" jew "admin"); jissettjah qr3 wara li jiċċekkja talba bi prova (ara hawn taħt). GTIN jew Company Prefix ivverifikat:

jorbot ir-resolver GS1 pubbliku għal dawn il-GTINs mal-organizzazzjoni tiegħek, anke jekk organizzazzjoni oħra ħolqot passaport qabel;
jimblokka kull organizzazzjoni oħra: il-ħolqien ta’ DPP għal GTIN bħal din, anke permezz ta’ batch jew importazzjoni, jirritorna 409 (errors/conflict, titlu GTIN Verified by Another Organization, il-GTINs miċħuda f’gtins). Il-batch u l-importazzjoni jiġu miċħuda kollha kemm huma.

Mingħajr verifika, GTIN tappartjeni lill-organizzazzjoni li ilha żżommha l-aktar mingħajr interruzzjoni (dettalji: Resolver tal-GS1). Jekk il-GTIN tiegħek tiġi riżolta għall-passaport ta’ organizzazzjoni oħra, itlob il-verifika tagħha.

Kif titlob verifika

Fid-dashboard taħt GS1, fit-taqsima Itlob verifika: daħħal it-tip (GTIN jew Company Prefix) u l-valur, tella’ prova u ibgħat it-talba. Il-prova turi li l-organizzazzjoni tiegħek għandha l-GTIN jew il-Company Prefix mingħand GS1, pereżempju l-konferma tal-liċenzja mill-organizzazzjoni GS1 tiegħek (PDF, PNG, JPEG jew WebP). Tinħażen b’mod privat; l-organizzazzjoni tiegħek u t-tim ta’ qr3 biss jistgħu jarawha. M’hemm l-ebda mistoqsija awtomatika lil GS1.

It-tim ta’ qr3 jiċċekkja l-prova u japprova t-talba jew jiċħadha b’raġuni. Wara l-approvazzjoni, l-identifikatur ikun ivverifikat (verified_by: "admin") u jaħdem kif deskritt hawn fuq. Tirċievi email dwar kull deċiżjoni fl-indirizz tan-notifiki tal-organizzazzjoni tiegħek, inkella fl-indirizz tas-sid.

Min: l-amministraturi tal-organizzazzjoni biss (org_admin jew is-sid). Rwoli oħra u ċwievet API diretti jirċievu 403. Lanqas l-appoġġ ta’ qr3 ma jista’ jibgħat talba f’ismek.
Status: pending (qed tiġi eżaminata), approved, rejected, withdrawn (irtirata minnek) jew revoked (verifika revokata aktar tard). Talba li qed tiġi eżaminata tista’ tirtiraha.
409: reason huwa request_pending (l-organizzazzjoni tiegħek diġà għandha talba għal dan l-identifikatur), already_verified jew verified_elsewhere (organizzazzjoni oħra vverifikatu; mhix imsemmija). Jekk l-organizzazzjoni tiegħek għandha l-liċenzja GS1 għalih, ikteb lil [email protected]: qr3 jiċċekkja ż-żewġ naħat u jista’ jirrevoka verifika. Jekk il-prova tinbidel waqt li t-talba tkun qed tintbagħat, reason huwa proof_changed; ibgħat it-talba mill-ġdid.
Workspace ieħor: b’request_pending, workspace (id, name) u request_id isemmu t-talba miftuħa jekk tista’ tiftaħ il-workspace tagħha; irtiraha minn hemm. Inkella t-tnejn huma null. Jekk il-workspace jiġi arkivjat waqt li tkun qed tibgħat it-talba, reason huwa workspace_archived; ma jintbagħat xejn.
Arkivjar: meta workspace jiġi arkivjat, it-talbiet tiegħu li qed jiġu eżaminati jiġu rtirati (withdrawn, fil-log tal-verifika bir-raġuni workspace archived). Il-prova terġa’ tkun ħielsa, u tista’ terġa’ titlob l-identifikatur minn workspace ieħor.
Prova: sakemm it-talba tkun qed tiġi eżaminata jew tkun approvata, il-fajl ma jistax jiġi sostitwit jew imħassar (409, reason: "gs1_verification_proof"). Wara ċaħda, irtirar jew revoka jerġa’ jkun ħieles.
Tneħħija: identifikatur ivverifikat ma jistax jitneħħa (409, reason: "verified"). qr3 biss ineħħi l-verifika, billi jirrevokaha.

Meta għandi bżonn it-tnejn?

Kompitu	GS1	qr3.app
Ikseb il-GTINs/GLNs tiegħek stess	✅ Sħubija meħtieġa	—
Validazzjoni taċ-ċifra tal-kontroll tal-GTIN	—	✅ API + Dashboard
Iġġenera kodiċi QR għall-prodott	—	✅
Oħloq DPP skont ir-Regolament tal-UE	—	✅
Riżoluzzjoni ta’ GS1 Digital Link	—	✅ Resolver + `/.well-known/gs1resolver`
Irreġistra fir-Reġistru tal-UE	Ippjanat (Q4 2026)	Ippjanat (Fażi 4c)

Referenza tal-API

POST /v1/gs1/identifiers — Irreġistra
GET /v1/gs1/identifiers — Elenka
DELETE /v1/gs1/identifiers/:id — Neħħi
POST /v1/gs1/validate — Validazzjoni (mingħajr reġistrazzjoni, l-ebda awtentikazzjoni)
POST /v1/gs1/verifications — Itlob verifika (amministraturi tal-organizzazzjoni)
GET /v1/gs1/verifications — Elenka t-talbiet
GET /v1/gs1/verifications/:id — Ġib talba
POST /v1/gs1/verifications/:id/withdraw — Irtira talba

Ara d-Dokumentazzjoni tal-API għal dettalji.