GS1-tunnisteet & Onboarding

qr3.app perustuu BYO-GTIN/BYO-GLN-malliin (Bring Your Own): Tuot mukanasi olemassa olevat GS1-tunnisteesi — qr3 hoitaa niiden päällä olevan digitaalisen tuotekerroksen (Product Layer).

Mitä GS1 tekee?

GS1 myöntää maailmanlaajuisesti yksilöllisiä tunnisteita tuotteille ja toimipaikoille:

Tunniste	Kuvaus	Esimerkki
GTIN-14	Global Trade Item Number (tuotetunniste)	`04012345678901`
GLN-13	Global Location Number (toimipaikka/yritys)	`4012345000009`
Company Prefix	Yritystunniste (7–12 numeroa), josta GTIN-koodit johdetaan	`4012345`

Saadaksesi GTIN-koodeja tarvitset GS1-jäsenyyden kansalliselta GS1-organisaatioltasi (esim. GS1 Finland).

Mitä qr3.app tekee?

qr3.app hyödyntää olemassa olevia GS1-tunnisteitasi ja tarjoaa:

GS1-yhteensopiva resolveri — /01/{GTIN}/21/{Serial} sisällön neuvottelulla (Content-Negotiation)
EU Digital Product Passport — DPP-luonti, validointi, kuluttajanäkymä
Tulostusvalmiit QR-tiedostot — SVG, PNG, vektori-PDF, EPS
JSON-LD, DCAT-AP — Koneellisesti luettavat tuotetiedot

Onboarding-prosessi

1. Rekisteröi GS1-tunnisteet

Ennen kuin voit luoda DPP-passeja, sinun on rekisteröitävä GTIN-koodisi (tai Company Prefix -yritystunnisteesi):

API:n kautta:

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

Hallintapaneelin kautta:

Siirry kohtaan Dashboard → GS1
Valitse tyyppi (GTIN, GLN tai Company Prefix)
Syötä arvo — tarkistusnumeron validointi tapahtuu automaattisesti
Napsauta Lisää tunniste

Organisaatiollasi on kukin tunniste vain kerran, jossakin sen työtiloista (Workspace). Jos rekisteröit poistetun tunnisteen uudelleen, se palaa (201, sama id) omana ilmoituksena ja vahvistamattomana, vaikka se olisi ollut vahvistettu ennen poistoa; jos se oli toisessa työtilassa, se siirtyy tähän. Jos se on yhä rekisteröity, vastaus on 409, jonka reason on already_registered (tässä työtilassa) tai registered_in_other_workspace (toisessa; workspace nimeää sen, jos saat avata sen). Jos työtila arkistoidaan sillä välin, reason on workspace_archived; mitään ei rekisteröidä.

2. Luo DPP-passit

Kun GTIN on rekisteröity (joko suoraan tai Company Prefix -tunnisteen kautta), voit luoda sille DPP-passeja:

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. Omistajuuden tarkistus

qr3.app tarkistaa jokaisen DPP-luonnin yhteydessä, kuuluuko käytetty GTIN organisaatiollesi:

Suora rekisteröinti — GTIN on rekisteröity tyypillä identifier_type: "gtin"
Prefix-osuma — GTIN alkaa rekisteröidyllä Company Prefix -tunnisteella (GTIN-14-koodin sijainnit 2..N)

Ilman vastaavaa rekisteröintiä palautetaan 422-virhe ja ilmoitus, että GTIN on rekisteröitävä ensin.

Sama tarkistus koskee pyyntöjä POST /v1/dpp/batch ja POST /v1/dpp/import, synkronisena ja jonoon asetettuna tehtävänä: yksikin rekisteröimätön GTIN hylkää koko pyynnön virheellä 422 (otsikko GTIN Not Registered, hylätyt GTIN-koodit kentässä gtins, niiden määrä kentässä total); mitään ei luoda eikä aseteta jonoon. Olemassa olevat passit eivät muutu. Passin ilmoittaminen EU-tuoterekisteriin (POST /v1/dpp/:id/register) edellyttää lisäksi, että passin organisaatio hallitsee GTIN-koodia (katso osio 4); muuten vastaus on 409 (otsikko GTIN Held by Another Organization).

4. Vahvistus

Rekisteröinti API:n tai hallintapaneelin kautta on oma ilmoitus (verified_by: "self", verified_at: null). Vahvistetulla tunnisteella on verified_at (verified_by: "gs1_registry" tai "admin"); sen asettaa qr3 tarkistettuaan todisteen sisältävän hakemuksen (katso alla). Vahvistettu GTIN tai Company Prefix:

sitoo julkisen GS1-selvittimen näiden GTIN-koodien osalta organisaatioosi, vaikka toinen organisaatio olisi luonut passin aiemmin;
estää kaikki muut organisaatiot: DPP:n luominen tällaiselle GTIN-koodille, myös erä- tai tuontitoiminnolla, palauttaa 409 (errors/conflict, otsikko GTIN Verified by Another Organization, hylätyt GTIN-koodit kentässä gtins). Erä ja tuonti hylätään kokonaan.

Ilman vahvistusta GTIN kuuluu organisaatiolle, jolla se on ollut pisimpään ilman katkosta (lisätiedot: GS1-selvitin). Jos GTIN-koodisi ratkeaa toisen organisaation passiin, hae sille vahvistusta.

Vahvistuksen hakeminen

Hallintapaneelissa kohdassa GS1, osiossa Hae vahvistusta: anna tyyppi (GTIN tai Company Prefix) ja arvo, lataa todiste ja lähetä hakemus. Todiste osoittaa, että organisaatiollasi on GS1:ltä saatu GTIN tai Company Prefix, esimerkiksi GS1-organisaatiosi lisenssivahvistus (PDF, PNG, JPEG tai WebP). Se tallennetaan yksityisenä; vain organisaatiosi ja qr3-tiimi näkevät sen. Automaattista kyselyä GS1:ltä ei ole.

qr3-tiimi tarkistaa todisteen ja hyväksyy hakemuksen tai hylkää sen perustellen. Hyväksynnän jälkeen tunniste on vahvistettu (verified_by: "admin") ja vaikuttaa yllä kuvatulla tavalla. Saat jokaisesta päätöksestä sähköpostin organisaatiosi ilmoitusosoitteeseen tai muuten omistajan osoitteeseen.

Kuka: vain organisaation ylläpitäjät (org_admin tai omistaja). Muut roolit ja suorat API-avaimet saavat vastauksen 403. Myöskään qr3:n tuki ei voi lähettää hakemusta puolestasi.
Tila: pending (tarkistettavana), approved, rejected, withdrawn (sinun perumasi) tai revoked (vahvistus mitätöity myöhemmin). Tarkistettavana olevan hakemuksen voit perua.
409: reason on request_pending (organisaatiollasi on jo hakemus tälle tunnisteelle), already_verified tai verified_elsewhere (toinen organisaatio on vahvistanut sen; sitä ei nimetä). Jos organisaatiollasi on sen GS1-lisenssi, kirjoita osoitteeseen [email protected]: qr3 tarkistaa molemmat osapuolet ja voi mitätöidä vahvistuksen. Jos todiste muuttuu hakemusta lähetettäessä, reason on proof_changed; lähetä hakemus uudelleen.
Toinen työtila: kun reason on request_pending, workspace (id, name) ja request_id nimeävät avoimen hakemuksen, jos saat avata sen työtilan; peru se siellä. Muuten molemmat ovat null. Jos työtila arkistoidaan hakemusta lähetettäessä, reason on workspace_archived; mitään ei lähetetä.
Arkistointi: kun työtila arkistoidaan, sen tarkistettavana olevat hakemukset perutaan (withdrawn, tarkastuslokissa syyllä workspace archived). Todiste on sen jälkeen taas vapaa, ja voit hakea tunnistetta uudelleen toisesta työtilasta.
Todiste: niin kauan kuin hakemus on tarkistettavana tai hyväksytty, tiedostoa ei voi korvata eikä poistaa (409, reason: "gs1_verification_proof"). Hylkäyksen, perumisen tai mitätöinnin jälkeen se on taas vapaa.
Poistaminen: vahvistettua tunnistetta ei voi poistaa (409, reason: "verified"). Vahvistuksen purkaa vain qr3 mitätöimällä sen.

Milloin tarvitsen molempia?

Tehtävä	GS1	qr3.app
Omien GTIN-/GLN-koodien hankkiminen	✅ Jäsenyys vaaditaan	—
GTIN-tarkistusnumeron validointi	—	✅ API + Hallintapaneeli
QR-koodin luominen tuotteelle	—	✅
DPP-passin luominen EU-asetuksen mukaisesti	—	✅
GS1 Digital Link -selvitys (resolving)	—	✅ Resolveri + `/.well-known/gs1resolver`
Rekisteröinti EU-rekisteriin	Suunniteltu (Q4 2026)	Suunniteltu (Vaihe 4c)

API-viite

POST /v1/gs1/identifiers — Rekisteröinti
GET /v1/gs1/identifiers — Listaus
DELETE /v1/gs1/identifiers/:id — Poistaminen
POST /v1/gs1/validate — Validointi (ilman rekisteröintiä, ei todennusta)
POST /v1/gs1/verifications — Hae vahvistusta (organisaation ylläpitäjät)
GET /v1/gs1/verifications — Listaa hakemukset
GET /v1/gs1/verifications/:id — Hae hakemus
POST /v1/gs1/verifications/:id/withdraw — Peru hakemus

Katso lisätietoja API-dokumentaatiosta.