Aller au contenu
qr3.app Docs

Identifiants GS1 & Onboarding

Identifiants GS1 & Onboarding

qr3.app repose sur un modèle BYO-GTIN/BYO-GLN (Bring Your Own) : vous apportez vos identifiants GS1 existants — qr3 s’occupe de la couche produit numérique (Product-Layer) supérieure.

Que fait GS1 ?

GS1 attribue des identifiants uniques au niveau mondial pour les produits et les sites :

IdentifiantDescriptionExemple
GTIN-14Global Trade Item Number (ID produit)04012345678901
GLN-13Global Location Number (Site/Entreprise)4012345000009
Company PrefixPréfixe d’entreprise (7 à 12 chiffres), à partir duquel les GTIN sont dérivés4012345

Pour obtenir des GTIN, vous devez adhérer à une organisation nationale GS1 (par ex. GS1 France, GS1 Belgique).

Que fait qr3.app ?

qr3.app utilise vos identifiants GS1 existants et propose :

  • Résolveur conforme GS1 — /01/{GTIN}/21/{Serial} avec négociation de contenu (Content-Negotiation)
  • EU Digital Product Passport — Création de DPP, validation, vue consommateur
  • Ressources QR prêtes à l’impression — SVG, PNG, PDF vectoriel, EPS
  • JSON-LD, DCAT-AP — Données de produit lisibles par machine

Flux d’onboarding

1. Enregistrer les identifiants GS1

Avant de pouvoir créer des DPP, vous devez enregistrer vos GTIN (ou votre Company Prefix) :

Via l’API :

Fenêtre de terminal
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 le tableau de bord :

  1. Accédez à Tableau de bord → GS1
  2. Sélectionnez le type (GTIN, GLN ou Company Prefix)
  3. Saisissez la valeur — la validation du chiffre de contrôle (Check-Digit) s’effectue automatiquement
  4. Cliquez sur Ajouter l’identifiant

Votre organisation ne détient chaque identifiant qu’une seule fois, dans l’un de ses Workspaces. Si vous enregistrez à nouveau un identifiant supprimé, il revient (201, le même id) comme déclaration propre et non vérifié, même s’il était vérifié avant sa suppression ; s’il se trouvait dans un autre Workspace, il est déplacé dans celui-ci. S’il est encore enregistré, la réponse est 409 avec reason already_registered (dans ce Workspace) ou registered_in_other_workspace (dans un autre ; workspace le nomme si vous pouvez l’ouvrir). Si le Workspace est archivé entre-temps, reason vaut workspace_archived ; rien n’est enregistré.

2. Créer des DPP

Dès qu’un GTIN est enregistré (directement ou via un Company Prefix), vous pouvez créer des DPP avec celui-ci :

Fenêtre de terminal
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. Vérification de propriété

qr3.app vérifie lors de chaque création de DPP si le GTIN utilisé appartient à votre organisation :

  1. Enregistrement direct — Le GTIN est enregistré en tant que identifier_type: "gtin"
  2. Correspondance de préfixe (Prefix-Match) — Le GTIN commence par un Company Prefix enregistré (positions 2 à N du GTIN-14)

Sans enregistrement correspondant, une erreur 422 est renvoyée avec l’indication d’enregistrer d’abord le GTIN.

La même vérification s’applique à POST /v1/dpp/batch et à POST /v1/dpp/import, en mode synchrone et comme tâche en file d’attente : un GTIN sans enregistrement fait refuser toute la requête avec 422 (titre GTIN Not Registered, les GTIN refusés dans gtins, leur nombre dans total) ; rien n’est créé ni mis en file. Les passeports existants ne sont pas concernés. L’inscription d’un passeport au Registre des produits de l’UE (POST /v1/dpp/:id/register) exige en plus que l’organisation du passeport détienne le GTIN (voir la section 4) ; sinon la réponse est 409 (titre GTIN Held by Another Organization).

4. Vérification

Un enregistrement via l’API ou le tableau de bord est une auto-déclaration (verified_by: "self", verified_at: null). Un identifiant vérifié porte verified_at (verified_by: "gs1_registry" ou "admin") ; c’est qr3 qui le définit, après avoir examiné une demande accompagnée d’une preuve (voir ci-dessous). Un GTIN ou un Company Prefix vérifié :

  • lie le résolveur GS1 public pour ces GTIN à votre organisation, même si une autre organisation a créé un passeport plus tôt ;
  • bloque toute autre organisation : la création d’un DPP pour un tel GTIN, y compris par lot ou par import, renvoie 409 (errors/conflict, titre GTIN Verified by Another Organization, les GTIN refusés dans gtins). Le lot et l’import sont refusés dans leur ensemble.

Sans vérification, un GTIN appartient à l’organisation qui le détient depuis le plus longtemps sans interruption (détails : Résolveur GS1). Si votre GTIN est résolu vers le passeport d’une autre organisation, demandez sa vérification.

Demander la vérification

Dans le tableau de bord, sous GS1, section Demander une vérification : saisissez le type (GTIN ou Company Prefix) et la valeur, téléversez une preuve et envoyez la demande. La preuve montre que votre organisation détient le GTIN ou le Company Prefix de GS1, par exemple la confirmation de licence de votre organisation GS1 (PDF, PNG, JPEG ou WebP). Elle est stockée de manière privée ; seules votre organisation et l’équipe qr3 peuvent la voir. Il n’y a pas d’interrogation automatique de GS1.

L’équipe qr3 examine la preuve et approuve la demande ou la refuse avec un motif. Une fois approuvé, l’identifiant est vérifié (verified_by: "admin") et produit les effets décrits ci-dessus. Vous recevez un e-mail pour chaque décision, à l’adresse de notification de votre organisation ou, à défaut, à celle du propriétaire.

  • Qui : uniquement les administrateurs de l’organisation (org_admin ou le propriétaire). Les autres rôles et les clés API directes reçoivent 403. Le support qr3 ne peut pas non plus envoyer de demande en votre nom.
  • Statut : pending (en cours d’examen), approved, rejected, withdrawn (retirée par vous) ou revoked (vérification révoquée par la suite). Vous pouvez retirer une demande en cours d’examen.
  • 409 : reason vaut request_pending (votre organisation a déjà une demande pour cet identifiant), already_verified ou verified_elsewhere (une autre organisation l’a vérifié ; elle n’est pas nommée). Si votre organisation détient la licence GS1 correspondante, écrivez à [email protected] : qr3 examine les deux parties et peut révoquer une vérification. Si la preuve change pendant l’envoi de la demande, reason vaut proof_changed ; envoyez la demande à nouveau.
  • Autre Workspace : avec request_pending, workspace (id, name) et request_id désignent la demande en cours si vous pouvez ouvrir son Workspace ; retirez-la là-bas. Sinon, les deux valent null. Si le Workspace est archivé pendant l’envoi de la demande, reason vaut workspace_archived ; rien n’est envoyé.
  • Archivage : lorsqu’un Workspace est archivé, ses demandes en cours d’examen sont retirées (withdrawn, dans le journal d’audit avec le motif workspace archived). La preuve est ensuite de nouveau libre, et vous pouvez redemander l’identifiant depuis un autre Workspace.
  • Preuve : tant que la demande est en cours d’examen ou approuvée, le fichier ne peut être ni remplacé ni supprimé (409, reason: "gs1_verification_proof"). Après un refus, un retrait ou une révocation, il est de nouveau libre.
  • Suppression : un identifiant vérifié ne peut pas être supprimé (409, reason: "verified"). Seul qr3 lève la vérification, en la révoquant.

Quand ai-je besoin des deux ?

TâcheGS1qr3.app
Obtenir ses propres GTIN/GLN✅ Adhésion requise—
Valider le chiffre de contrôle GTIN—✅ API + Tableau de bord
Générer un code QR pour le produit—✅
Créer un DPP selon le règlement UE—✅
Résoudre un GS1 Digital Link—✅ Résolveur + /.well-known/gs1resolver
S’enregistrer dans le registre de l’UEPrévu (T4 2026)Prévu (Phase 4c)

Référence API

  • POST /v1/gs1/identifiers — Enregistrer
  • GET /v1/gs1/identifiers — Lister
  • DELETE /v1/gs1/identifiers/:id — Supprimer
  • POST /v1/gs1/validate — Valider (sans enregistrement, pas d’authentification)
  • POST /v1/gs1/verifications — Demander une vérification (administrateurs de l’organisation)
  • GET /v1/gs1/verifications — Lister les demandes
  • GET /v1/gs1/verifications/:id — Obtenir une demande
  • POST /v1/gs1/verifications/:id/withdraw — Retirer une demande

Voir la documentation de l’API pour plus de détails.