Votre entreprise possède déjà un ERP pour les opérations, un PIM pour les informations produit ou une application interne pour l’atelier. Une API de traçabilité permet d’envisager la création des passeports et la préparation des supports depuis ces outils. Le projet commence par une cartographie des données et des responsabilités, avant l’écriture du premier appel.

Décider quel système fait référence pour chaque donnée

Un même produit peut avoir plusieurs descriptions et références dans votre organisation. Commencez par désigner la source de chaque champ. Le PIM peut gérer les caractéristiques validées, l’ERP les lots et le service qualité les justificatifs. Cette répartition est un choix d’organisation à confirmer avec les personnes qui produisent réellement les données.

Pour chaque information transmise, notez son nom, son format, son unité éventuelle, sa source, son responsable et sa fréquence de mise à jour. Distinguez une valeur absente d’une valeur inconnue ou non applicable. Une chaîne de synchronisation peut déplacer une erreur très efficacement ; elle ne la transforme pas en information vérifiée.

Définissez aussi ce qui peut être publié et ce qui doit rester réservé. Tous les documents fournisseurs n’ont pas vocation à figurer dans la page publique du produit. Notre guide pour préparer les données du passeport produit aide à structurer ce travail avec les équipes métier.

Séparer référence commerciale, lot et exemplaire

Le nom commercial d’un article est un mauvais identifiant d’intégration : il peut changer. Établissez une correspondance entre vos identifiants stables et ceux du service de passeport. Le contrat pilote Trace prévoit notamment external_id, votre référence interne, et identification_level, avec les valeurs model, batch ou item.

Ne confondez pas un SKU avec un numéro de série. Un SKU peut représenter une référence vendue en milliers d’exemplaires. Pour un suivi unitaire, le rapprochement doit distinguer chacun de ces exemplaires. Documentez le périmètre d’unicité et le traitement d’un changement de nomenclature ou d’une fusion de catalogues.

Si vous utilisez les identifiants GS1, leur intégration demande une syntaxe précise. Le guide GS1 Digital Link explique comment un GTIN peut être complété par un lot ou un numéro de série et pourquoi l’identifiant persistant doit rester distinct de la page qui affiche les informations. Un champ GTIN dans un contrat API ne suffit pas à garantir que toutes ces règles sont mises en œuvre.

Définir un parcours de création et de publication

Nous recommandons un parcours en plusieurs étapes, avec un contrôle métier explicite avant publication. Le contrat pilote décrit POST /products, POST /batches et POST /passports pour les ressources correspondantes. Une opération POST /passports/{passportId}/publish distingue ensuite la publication de la création.

  1. Vérifier les données dans leurs systèmes sources.
  2. Préparer une demande avec la référence interne et le niveau d’identification.
  3. Conserver la réponse et la correspondance avec l’identifiant du passeport.
  4. Faire valider le dossier par la personne désignée.
  5. Publier puis préparer les supports selon le calendrier du produit.

Définissez les contrôles attendus et leur responsable. Pour une catégorie soumise au DPP, ce calendrier dépend des textes applicables : le cadre ESPR, article 9, articule la disponibilité du passeport avec la mise sur le marché ou la mise en service. Un événement commercial tardif ne doit pas être choisi arbitrairement comme déclencheur.

Prévoir les reprises et l’idempotence dès le pilote

Imaginez que votre application envoie une création, puis perde la connexion avant de recevoir la réponse. Elle ne sait pas si le passeport existe déjà. L’idempotence vise à permettre une nouvelle tentative de la même opération sans créer un doublon. Ce comportement doit être précisément défini et testé.

Le contrat Trace exige un en-tête Idempotency-Key sur la création d’un passeport et la génération en masse. Il prévoit une réponse 409 pour un conflit de référence ou d’idempotence. La durée de conservation des clés et les détails de comparaison ne sont pas encore définis dans ce contrat : ils doivent être fixés avant une intégration opérationnelle.

Côté client, nous recommandons de conserver la clé avec la demande initiale, puis de la réutiliser pour une nouvelle tentative identique. Une demande modifiée doit suivre une règle explicite. Conservez également l’identifiant de requête renvoyé en cas d’erreur pour faciliter les investigations. Ne supposez pas que tous les autres endpoints disposent du même mécanisme.

Organiser les volumes et suivre les traitements

Pour les séries, le contrat prévoit POST /passport-batches, qui renvoie un traitement asynchrone. L’intégrateur pourra consulter son état avec GET /jobs/{jobId} et récupérer les sorties décrites, telles que le manifeste de correspondance et l’archive des QR. Une demande acceptée n’est pas encore un lot entièrement terminé.

Préparez une file de travail côté intégration, un suivi des échecs et une procédure de rapprochement. Ces éléments sont des recommandations pour votre architecture. Les limites de volume, délais et règles de reprise du service pilote restent à convenir. Les webhooks Trace sont étudiés, mais leurs événements, signatures et configuration ne sont pas définis dans le contrat publié.

À titre d’exemple externe, Shopify recommande des traitements idempotents pour ses webhooks, susceptibles d’être reçus plusieurs fois. Cette précaution illustre pourquoi une notification ne doit pas provoquer aveuglément une nouvelle création dans votre système cible.

Relier les résultats API à l’impression et à l’encodage

Le contrat prévoit une route GET /passports/{passportId}/qr.svg pour le QR et une route GET /passports/{passportId}/nfc-payload pour le lien à encoder. Votre intégration doit transmettre ces résultats au bon outil de production, avec la liste des correspondances. Une API ne pose pas l’étiquette et n’écrit pas physiquement la puce.

Le poste d’impression ou d’encodage doit vérifier la destination attendue. Le contrat prévoit un retour de résultat d’encodage via POST /carriers/{carrierId}/encoding-result ; cela ne remplace pas la relecture matérielle. Pour définir les contrôles, suivez notre méthode pour imprimer et encoder les étiquettes et comparez les supports QR, NFC ou hybrides.

Cadrer un premier pilote intégrable

Choisissez quelques références, un responsable métier et une équipe technique. Préparez un cas nominal, une donnée invalide, une reprise réseau et une unité à réétiqueter. Vérifiez l’ensemble du parcours jusqu’au scan du produit fini. Gardez les clés API dans l’application serveur, jamais dans les QR ou dans le code public du navigateur.

La documentation et le contrat OpenAPI constituent la base de cette discussion. La plateforme SaaS et l’offre Shopify restent deux alternatives indépendantes pour les équipes qui préfèrent leurs interfaces. Le choix de l’API seule permet de conserver votre propre parcours métier, sous réserve de l’activation et de la validation du pilote.