Zum Inhalt springen
qr3.app Docs

GS1-Resolver

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:

AcceptAntwort
text/htmlConsumer-HTML
application/ld+jsonJSON-LD
application/jsonRohes DPP-JSON
application/linkset+jsonLinkset mit Alternativen

Ö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

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

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