GS1-Resolver

Der GS1-Resolver ist die öffentliche Leseschicht für einen DPP. Die kanonische URL sieht so aus:

https://qr3.app/01/{GTIN}
https://qr3.app/01/{GTIN}/10/{LOT}
https://qr3.app/01/{GTIN}/21/{SERIAL}
https://qr3.app/01/{GTIN}/10/{LOT}/21/{SERIAL}

Beim Anlegen eines DPP (POST /v1/dpp) gilt: serial und lot müssen sichere GS1-Pfadsegmente verwenden: nur A-Z, a-z, 0-9, ., _, ~, - und eine Länge von 1 bis 20 Zeichen. Reservierte URL-Trennzeichen werden abgelehnt, damit der kanonische Link auflösbar bleibt.

Content Negotiation

Der gleiche Resolver liefert je nach Accept-Header verschiedene Darstellungen:

Accept	Antwort
`text/html`	Consumer-HTML
`application/ld+json`	JSON-LD
`application/json`	Rohes DPP-JSON
`application/linkset+json`	Linkset mit Alternativen

Die JSON-Darstellung (application/json, ?format=json) ist der öffentliche Produktpass: Produktdaten, Links und Registrierungsstand, ohne interne Kennungen. workspace_id, organization_id, code_id und created_by (die ID des API-Keys, der den Produktpass angelegt hat) gehören nicht dazu; der angemeldete Abruf GET /v1/dpp/:id liefert sie. Auch das interne Prüfergebnis des Produktpasses, is_valid und validation_errors, gehört nicht dazu; der angemeldete Abruf GET /v1/dpp/:id liefert es.

Öffentlich sichtbare Routen

GET /01/... ist der kanonische Resolver
GET /dpp/:gtin/:serial?lot=... ist ein HTML-Alias
GET /v1/dpp/:id/qr.svg liefert das SVG
GET /v1/dpp/:id/qr.png liefert das PNG
GET /v1/dpp/:id/qr.pdf liefert das PDF
GET /v1/dpp/:id/qr.eps liefert das EPS

Die Sichtbarkeit der QR-Assets richtet sich nach dem DPP-Status:

live ist ohne Authentifizierung öffentlich abrufbar
draft und archived brauchen einen gültigen Auth-Kontext plus Workspace-Zugriff
Ungültige Authentifizierung liefert 401
Nicht sichtbare oder fremde Workspaces liefern 404

Zu welcher Organisation eine GTIN auflöst

Mehrere Organisationen können Pässe mit derselben GTIN haben. Der Resolver liefert nur Pässe der Organisation, der die GTIN gehört:

Verifiziert: die Organisation, die die GTIN verifiziert hat, oder ein GS1 Company Prefix, mit dem die GTIN beginnt. Ein selbst registrierter Identifikator (POST /v1/gs1/identifiers) ist keine Verifizierung.
Sonst die erste: die Organisation, die die GTIN am längsten ohne Unterbrechung hält. Eine Organisation hält eine GTIN, solange sie mindestens einen nicht gelöschten Pass dafür hat, gleich welchen Status; ihr Anspruch zählt ab dem ersten Pass dieses Zeitraums, Bearbeiten oder Löschen einzelner Pässe ändert daran nichts. Hat sie keinen Pass mehr, endet der Anspruch; ein später angelegter Pass beginnt einen neuen.

Eine gelöschte Organisation zählt für keine der beiden Regeln.

Innerhalb dieser Organisation kommt der zuletzt geänderte live-Pass mit der angefragten GTIN, Seriennummer und Charge. Hat sie keinen, leitet der Resolver an GS1 weiter (siehe Fallback), auch wenn eine andere Organisation einen passenden Pass hat. Dasselbe gilt für /dpp/…, /dpp/dpp_… und ohne Authentifizierung für die QR-Assets und die Bilderliste eines Passes: Der Pass einer anderen Organisation liefert 404. Mit deinem eigenen Key siehst du deine Pässe immer.

Fallback

Ohne lokalen Treffer leitet der GS1-Resolver mit 307 zu https://id.gs1.org weiter. Beim GTIN-Alias /dpp/:gtin/:serial?lot=... gilt das auch für eine ungültige GTIN-Prüfziffer: gtin, lot und serial werden einzeln als URL-Pfadsegmente kodiert, einschließlich reservierter Trennzeichen. Der Redirect bestätigt weder die Gültigkeit der GTIN noch verfügbare Daten bei GS1.

Ausnahme: Ist ein dekodierter Bezeichner ausschließlich . oder .., antwortet der Alias ohne lokalen Treffer mit 422, application/problem+json, Typ https://docs.qr3.app/errors/validation und dem betroffenen Feld in errors[], ohne Redirect. URL-Parser normalisieren diese Segmente auch in kodierter Form. Werte wie LOT.1 oder ... bleiben delegierbar. Die Ausnahme betrifft nur diesen Alias ohne Treffer; Erstellungsvalidierung, kanonischer Resolver und bestehende Treffer bleiben unverändert.

GET /dpp/{GTIN}/UNKNOWN?lot=LOT%2F1
307 Location: https://id.gs1.org/01/{GTIN}/10/LOT%2F1/21/UNKNOWN

GET /dpp/{GTIN}/UNKNOWN?lot=.
422 Content-Type: application/problem+json

Praxis

DPP im Dashboard anlegen.
Die GS1-URI als QR-Ziel verwenden.
Verbrauchende Systeme über Accept auf das gewünschte Format leiten.