GS1-identificatoren & onboarding

qr3.app maakt gebruik van een BYO-GTIN/BYO-GLN-model (Bring Your Own): je brengt je bestaande GS1-identificatoren mee — qr3 verzorgt de digitale productlaag daarbovenop.

Wat doet GS1?

GS1 kent wereldwijd unieke identificatoren toe voor producten en locaties:

Identificator	Beschrijving	Voorbeeld
GTIN-14	Global Trade Item Number (product-ID)	`04012345678901`
GLN-13	Global Location Number (locatie/bedrijf)	`4012345000009`
Company Prefix	Bedrijfsprefix (7-12 cijfers), waarvan GTIN’s worden afgeleid	`4012345`

Om GTIN’s te verkrijgen, heb je een GS1-lidmaatschap nodig bij je nationale GS1-organisatie (bijv. GS1 Austria, GS1 Germany).

Wat doet qr3.app?

qr3.app gebruikt je bestaande GS1-identificatoren en biedt:

GS1-conforme resolver — /01/{GTIN}/21/{Serial} met content-negotiation
EU Digital Product Passport — DPP-creatie, validatie, consumentenweergave
Drukklare QR-assets — SVG, PNG, vector-PDF, EPS
JSON-LD, DCAT-AP — Machineleesbare productgegevens

Onboarding-flow

1. GS1-identificatoren registreren

Voordat je DPP’s kunt maken, moet je je GTIN’s (of je Company Prefix) registreren:

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

Via het dashboard:

Navigeer naar Dashboard → GS1
Kies het type (GTIN, GLN of Company Prefix)
Voer de waarde in — de controlecijfervalidatie (check-digit) gebeurt automatisch
Klik op Identificator toevoegen

Je organisatie heeft elke identificator maar één keer, in een van haar Workspaces. Registreer je een verwijderde identificator opnieuw, dan komt hij terug (201, dezelfde id) als eigen verklaring en niet geverifieerd, ook als hij vóór het verwijderen geverifieerd was; stond hij in een andere Workspace, dan verhuist hij naar deze. Is hij nog geregistreerd, dan is het antwoord 409 met reason already_registered (in deze Workspace) of registered_in_other_workspace (in een andere; workspace noemt die als je hem mag openen). Wordt de Workspace intussen gearchiveerd, dan is reason workspace_archived; er wordt niets geregistreerd.

2. DPP’s maken

Zodra een GTIN is geregistreerd (direct of via een Company Prefix), kun je hiermee DPP’s aanmaken:

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. Eigendomscontrole

qr3.app controleert bij elke DPP-creatie of de gebruikte GTIN bij jouw organisatie hoort:

Directe registratie — De GTIN is geregistreerd als identifier_type: "gtin"
Prefix-match — De GTIN begint met een geregistreerde Company Prefix (positie 2..N van de GTIN-14)

Zonder geldige registratie treedt er een 422-fout op met de melding om de GTIN eerst te registreren.

Dezelfde controle geldt voor POST /v1/dpp/batch en POST /v1/dpp/import, synchroon en als job in de wachtrij: één GTIN zonder registratie weigert het hele verzoek met 422 (titel GTIN Not Registered, de geweigerde GTINs in gtins, hun aantal in total); er wordt niets aangemaakt of in de wachtrij gezet. Bestaande paspoorten blijven ongemoeid. Het indienen van een paspoort bij het EU-productregister (POST /v1/dpp/:id/register) vereist bovendien dat de organisatie van het paspoort de GTIN houdt (zie sectie 4); anders is het antwoord 409 (titel GTIN Held by Another Organization).

4. Verificatie

Een registratie via de API of het dashboard is een eigen verklaring (verified_by: "self", verified_at: null). Een geverifieerde identificator draagt verified_at (verified_by: "gs1_registry" of "admin"); qr3 stelt dit in nadat het een aanvraag met bewijs heeft gecontroleerd (zie hieronder). Een geverifieerde GTIN of Company Prefix:

bindt de openbare GS1-resolver voor deze GTINs aan jouw organisatie, ook als een andere organisatie eerder een paspoort heeft aangemaakt;
blokkeert elke andere organisatie: een DPP voor zo’n GTIN aanmaken, ook via batch of import, geeft 409 (errors/conflict, titel GTIN Verified by Another Organization, de geweigerde GTINs in gtins). Batch en import worden in hun geheel geweigerd.

Zonder verificatie behoort een GTIN tot de organisatie die hem het langst zonder onderbreking heeft (details: GS1-resolver). Verwijst jouw GTIN naar het paspoort van een andere organisatie, vraag dan de verificatie ervan aan.

Verificatie aanvragen

In het dashboard onder GS1, onderdeel Verificatie aanvragen: vul het type (GTIN of Company Prefix) en de waarde in, upload een bewijs en dien de aanvraag in. Het bewijs toont aan dat je organisatie de GTIN of de Company Prefix van GS1 heeft, bijvoorbeeld de licentiebevestiging van je GS1-organisatie (PDF, PNG, JPEG of WebP). Het wordt privé opgeslagen; alleen je organisatie en het qr3-team kunnen het zien. Er is geen automatische opvraging bij GS1.

Het qr3-team controleert het bewijs en keurt de aanvraag goed of wijst hem met een reden af. Na goedkeuring is de identificator geverifieerd (verified_by: "admin") en werkt hij zoals hierboven beschreven. Over elke beslissing krijg je een e-mail op het meldingsadres van je organisatie, anders op het adres van de eigenaar.

Wie: alleen organisatiebeheerders (org_admin of de eigenaar). Andere rollen en directe API-keys krijgen 403. Ook qr3-support kan geen aanvraag namens jou indienen.
Status: pending (in behandeling), approved, rejected, withdrawn (door jou ingetrokken) of revoked (verificatie later herroepen). Een aanvraag in behandeling kun je intrekken.
409: reason is request_pending (je organisatie heeft al een aanvraag voor deze identificator), already_verified of verified_elsewhere (een andere organisatie heeft hem geverifieerd; die wordt niet genoemd). Heeft je organisatie de GS1-licentie ervoor, mail dan naar [email protected]: qr3 bekijkt beide kanten en kan een verificatie herroepen. Verandert het bewijs terwijl de aanvraag wordt ingediend, dan is reason proof_changed; dien de aanvraag opnieuw in.
Andere Workspace: bij request_pending noemen workspace (id, name) en request_id de openstaande aanvraag als je de Workspace ervan mag openen; trek hem daar in. Anders zijn beide null. Wordt de Workspace gearchiveerd terwijl je de aanvraag indient, dan is reason workspace_archived; er wordt niets ingediend.
Archiveren: wordt een Workspace gearchiveerd, dan worden de aanvragen in behandeling ervan ingetrokken (withdrawn, in het auditlog met de reden workspace archived). Het bewijs is daarna weer vrij, en je kunt de identificator vanuit een andere Workspace opnieuw aanvragen.
Bewijs: zolang de aanvraag in behandeling of goedgekeurd is, kan het bestand niet worden vervangen of verwijderd (409, reason: "gs1_verification_proof"). Na een afwijzing, intrekking of herroeping is het weer vrij.
Verwijderen: een geverifieerde identificator kan niet worden verwijderd (409, reason: "verified"). Alleen qr3 heft de verificatie op, door haar te herroepen.

Wanneer heb ik beide nodig?

Taak	GS1	qr3.app
Eigen GTIN’s/GLN’s verkrijgen	✅ Lidmaatschap vereist	—
GTIN-controlecijfer valideren	—	✅ API + dashboard
QR-code voor product genereren	—	✅
DPP conform EU-verordening maken	—	✅
GS1 Digital Link resolven	—	✅ Resolver + `/.well-known/gs1resolver`
Registreren in de EU-registry	Gepland (Q4 2026)	Gepland (Fase 4c)

API-referentie

POST /v1/gs1/identifiers — Registreren
GET /v1/gs1/identifiers — Weergeven
DELETE /v1/gs1/identifiers/:id — Verwijderen
POST /v1/gs1/validate — Valideren (zonder registratie, geen auth)
POST /v1/gs1/verifications — Verificatie aanvragen (organisatiebeheerders)
GET /v1/gs1/verifications — Aanvragen opvragen
GET /v1/gs1/verifications/:id — Een aanvraag ophalen
POST /v1/gs1/verifications/:id/withdraw — Een aanvraag intrekken

Zie de API-documentatie voor details.