Zum Inhalt springen
qr3.app Docs

GS1-Identifikatoren & Onboarding

GS1-Identifikatoren & Onboarding

qr3.app setzt auf ein BYO-GTIN/BYO-GLN-Modell (Bring Your Own): Du bringst deine bestehenden GS1-Identifikatoren mit — qr3 übernimmt den digitalen Product-Layer darüber.

Was macht GS1?

GS1 vergibt weltweit eindeutige Identifikatoren für Produkte und Standorte:

IdentifikatorBeschreibungBeispiel
GTIN-14Global Trade Item Number (Produkt-ID)04012345678901
GLN-13Global Location Number (Standort/Firma)4012345000009
Company PrefixFirmen-Präfix (7-12 Stellen), aus dem GTINs abgeleitet werden4012345

Um GTINs zu erhalten, brauchst du eine GS1-Mitgliedschaft bei deiner nationalen GS1-Organisation (z. B. GS1 Austria, GS1 Germany).

Was macht qr3.app?

qr3.app nutzt deine vorhandenen GS1-Identifikatoren und bietet:

  • GS1-konformer Resolver — /01/{GTIN}/21/{Serial} mit Content-Negotiation
  • EU Digital Product Passport — DPP-Erstellung, Validierung, Consumer-Ansicht
  • Druckfertige QR-Assets — SVG, PNG, Vektor-PDF, EPS
  • JSON-LD, DCAT-AP — Maschinenlesbare Produktdaten

Onboarding-Flow

1. GS1-Identifikatoren registrieren

Bevor du DPPs erstellen kannst, musst du deine GTINs (oder deinen Company Prefix) registrieren:

Per API:

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

Per Dashboard:

  1. Navigiere zu Dashboard → GS1
  2. Wähle den Typ (GTIN, GLN oder Company Prefix)
  3. Gib den Wert ein — die Check-Digit-Validierung erfolgt automatisch
  4. Klicke Identifikator hinzufügen

Deine Organisation hält jeden Identifikator nur einmal, in einem ihrer Workspaces. Registrierst du einen entfernten Identifikator erneut, kommt er zurück (201, dieselbe id), als Selbstauskunft und nicht verifiziert, auch wenn er vor dem Entfernen verifiziert war; lag er in einem anderen Workspace, zieht er in diesen um. Ist er noch registriert, lautet die Antwort 409 mit reason already_registered (in diesem Workspace) oder registered_in_other_workspace (in einem anderen; workspace nennt ihn, wenn du ihn öffnen darfst). Wird der Workspace währenddessen archiviert, lautet reason workspace_archived; registriert wird nichts.

2. DPPs erstellen

Sobald eine GTIN registriert ist (direkt oder über einen Company Prefix), kannst du DPPs damit anlegen:

Terminal-Fenster
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. Ownership-Prüfung

qr3.app prüft bei jeder DPP-Erstellung, ob die verwendete GTIN zu deiner Organisation gehört:

  1. Direkte Registrierung — Die GTIN ist als identifier_type: "gtin" registriert
  2. Prefix-Match — Die GTIN beginnt mit einem registrierten Company Prefix (Position 2..N der GTIN-14)

Ohne passende Registrierung gibt es einen 422-Fehler mit dem Hinweis, die GTIN zuerst zu registrieren.

Dieselbe Prüfung gilt für POST /v1/dpp/batch und POST /v1/dpp/import, synchron und als eingereihter Job: Eine GTIN ohne Registrierung weist die ganze Anfrage mit 422 ab (Titel GTIN Not Registered, die abgewiesenen GTINs in gtins, ihre Zahl in total); angelegt oder eingereiht wird nichts. Bestehende Pässe bleiben unberührt. Die Meldung eines Passes ans EU-Produktregister (POST /v1/dpp/:id/register) verlangt zusätzlich, dass die Organisation des Passes die GTIN hält (siehe Abschnitt 4); sonst lautet die Antwort 409 (Titel GTIN Held by Another Organization).

4. Verifizierung

Eine Registrierung über API oder Dashboard ist eine Selbstauskunft (verified_by: "self", verified_at: null). Ein verifizierter Identifikator trägt verified_at (verified_by: "gs1_registry" oder "admin"); qr3 setzt das, nachdem es einen Antrag mit Nachweis geprüft hat (siehe unten). Eine verifizierte GTIN oder ein verifizierter Company Prefix:

  • bindet den öffentlichen GS1-Resolver für diese GTINs an deine Organisation, auch wenn eine andere Organisation früher einen Pass angelegt hat;
  • sperrt jede andere Organisation: Ein DPP für eine solche GTIN, auch per Batch oder Import, ergibt 409 (errors/conflict, Titel GTIN Verified by Another Organization, die abgewiesenen GTINs in gtins). Batch und Import werden als Ganzes abgewiesen.

Ohne Verifizierung gehört eine GTIN der Organisation, die sie am längsten ohne Unterbrechung hält (Details: GS1-Resolver). Löst deine GTIN zum Pass einer anderen Organisation auf, beantrage ihre Verifizierung.

Verifizierung beantragen

Im Dashboard unter GS1, Abschnitt Verifizierung beantragen: Typ (GTIN oder Company Prefix) und Wert eingeben, einen Nachweis hochladen und den Antrag stellen. Der Nachweis zeigt, dass deine Organisation die GTIN oder den Company Prefix von GS1 hat, zum Beispiel die Lizenzbestätigung deiner GS1-Organisation (PDF, PNG, JPEG oder WebP). Er wird privat gespeichert; nur deine Organisation und das qr3-Team sehen ihn. Eine automatische Abfrage bei GS1 gibt es nicht.

Das qr3-Team prüft den Nachweis und gibt frei oder lehnt mit Begründung ab. Nach der Freigabe ist der Identifikator verifiziert (verified_by: "admin") und wirkt wie oben beschrieben. Über jede Entscheidung bekommst du eine E-Mail an die Benachrichtigungsadresse deiner Organisation, sonst an die Adresse des Eigentümers.

  • Wer: nur Organisations-Admins (org_admin oder der Eigentümer). Andere Rollen und direkte API-Keys erhalten 403. Auch der qr3-Support kann keinen Antrag in deinem Namen stellen.
  • Status: pending (in Prüfung), approved, rejected, withdrawn (von dir zurückgezogen) oder revoked (Verifizierung später widerrufen). Einen Antrag in Prüfung kannst du zurückziehen.
  • 409: reason ist request_pending (für diesen Identifikator läuft schon ein Antrag deiner Organisation), already_verified oder verified_elsewhere (eine andere Organisation hat ihn verifiziert; sie wird nicht genannt). Hält deine Organisation die GS1-Lizenz dafür, schreib an [email protected]: qr3 prüft beide Seiten und kann eine Verifizierung widerrufen. Ändert sich der Nachweis, während der Antrag eingereicht wird, lautet reason proof_changed; dann den Antrag erneut stellen.
  • Anderer Workspace: Bei request_pending nennen workspace (id, name) und request_id den offenen Antrag, wenn du seinen Workspace öffnen darfst; zieh ihn dort zurück. Sonst sind beide null. Wird der Workspace archiviert, während du den Antrag stellst, lautet reason workspace_archived; gestellt wird nichts.
  • Archivieren: Wird ein Workspace archiviert, werden seine Anträge in Prüfung zurückgezogen (withdrawn, im Audit-Log mit dem Grund workspace archived). Der Nachweis ist danach wieder frei, und du kannst den Identifikator aus einem anderen Workspace erneut beantragen.
  • Nachweis: Solange der Antrag in Prüfung oder freigegeben ist, lässt sich die Datei weder ersetzen noch löschen (409, reason: "gs1_verification_proof"). Nach Ablehnung, Rückzug oder Widerruf ist sie wieder frei.
  • Entfernen: Ein verifizierter Identifikator lässt sich nicht entfernen (409, reason: "verified"). Die Verifizierung hebt nur qr3 per Widerruf auf.

Wann brauche ich beides?

AufgabeGS1qr3.app
Eigene GTINs/GLNs erhalten✅ Mitgliedschaft nötig—
GTIN-Check-Digit validieren—✅ API + Dashboard
QR-Code für Produkt erzeugen—✅
DPP nach EU-Verordnung erstellen—✅
GS1 Digital Link auflösen—✅ Resolver + /.well-known/gs1resolver
In der EU-Registry registrierenGeplant (Q4 2026)Geplant (Phase 4c)

API-Referenz

  • POST /v1/gs1/identifiers — Registrieren
  • GET /v1/gs1/identifiers — Auflisten
  • DELETE /v1/gs1/identifiers/:id — Entfernen
  • POST /v1/gs1/validate — Validieren (ohne Registrierung, kein Auth)
  • POST /v1/gs1/verifications — Verifizierung beantragen (Organisations-Admins)
  • GET /v1/gs1/verifications — Anträge auflisten
  • GET /v1/gs1/verifications/:id — Antrag abrufen
  • POST /v1/gs1/verifications/:id/withdraw — Antrag zurückziehen

Siehe API-Dokumentation für Details.