Aller au contenu
qr3.app Docs

Résolveur GS1

Résolveur GS1

Le résolveur GS1 est la couche de lecture publique pour un DPP. L’URL canonique ressemble à ceci :

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}

Lors de la création d’un DPP (POST /v1/dpp), les règles suivantes s’appliquent : serial et lot doivent utiliser des segments de chemin GS1 sécurisés : uniquement A-Z, a-z, 0-9, ., _, ~, - et une longueur de 1 à 20 caractères. Les séparateurs d’URL réservés sont rejetés afin que le lien canonique reste résoluble.

Négociation de contenu

Le même résolveur fournit différentes représentations en fonction de l’en-tête Accept :

AcceptRéponse
text/htmlHTML consommateur
application/ld+jsonJSON-LD
application/jsonJSON DPP brut
application/linkset+jsonLinkset avec alternatives

Routes publiques

  • GET /01/... est le résolveur canonique
  • GET /dpp/:gtin/:serial?lot=... est un alias HTML
  • GET /v1/dpp/:id/qr.svg fournit le SVG
  • GET /v1/dpp/:id/qr.png fournit le PNG
  • GET /v1/dpp/:id/qr.pdf fournit le PDF
  • GET /v1/dpp/:id/qr.eps fournit l’EPS

La visibilité des ressources QR dépend du statut du DPP :

  • live est accessible publiquement sans authentification
  • draft et archived nécessitent un contexte d’authentification valide ainsi qu’un accès à l’espace de travail (Workspace)
  • Une authentification invalide renvoie 401
  • Les espaces de travail non visibles ou tiers renvoient 404

Comportement de repli

Sans correspondance locale, le résolveur GS1 redirige avec 307 vers https://id.gs1.org. Pour l’alias GTIN /dpp/:gtin/:serial?lot=..., cela s’applique aussi à un chiffre de contrôle GTIN invalide : gtin, lot et serial sont encodés séparément comme segments de chemin URL, y compris les séparateurs réservés. La redirection ne confirme ni la validité du GTIN ni la disponibilité de données chez GS1.

Exception : si un identifiant décodé est uniquement . ou .., l’alias sans correspondance locale répond avec 422, application/problem+json, le type https://docs.qr3.app/errors/validation et le champ concerné dans errors[], sans redirection. Les analyseurs d’URL normalisent ces segments même sous forme encodée. Les valeurs comme LOT.1 et ... restent transmissibles. L’exception concerne uniquement cet alias sans correspondance ; la validation à la création, le résolveur canonique et les correspondances existantes restent inchangés.

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

En pratique

  1. Créer le DPP dans le tableau de bord.
  2. Utiliser l’URI GS1 comme cible du QR code.
  3. Rediriger les systèmes clients vers le format souhaité via l’en-tête Accept.