Le flux fournisseur contient une référence produit, mais l’import répond qu’il ne la retrouve pas. Une autre interface accepte pourtant le même GTIN. Le risque est de déclarer un produit absent alors que la valeur a changé d’écriture entre l’échange EANCOM, le champ GS1 XML et la clé de recherche du catalogue. Avant d’ouvrir une création produit, il faut vérifier le format effectivement reçu et celui que chaque étape attend.
Le scénario fictif utilise le GTIN témoin 045678912347. Sa représentation EANCOM sans zéro initial vaut 45678912347, soit 11 chiffres. Sa représentation sur 14 caractères vaut 00045678912347. Les trois chaînes ne sont pas identiques, mais notre expérience les rapproche de la même référence locale lorsque le contrat de format est connu. Ces nombres ne constituent aucune attribution GS1 à un produit réel.
Un programme original utilise Biip 4.0.0 pour observer la lecture et le formatage de GTIN. Il passe 46 contrôles et exécute 14 appels du parseur natif. La valeur EANCOM sur 11 chiffres est refusée si elle lui est transmise directement ; sa préparation sur 14 caractères permet ensuite de retrouver la référence du catalogue fictif. Ce résultat reste distinct d’une validation de message EDI, de schéma XML ou d’une recherche réellement exécutée dans un PIM.
Notre prestation d’intégration API PIM et catalogue produit peut partir de ce rejet ciblé. L’accompagnement en intégration API entre sources fournisseur et logiciels métier examine le format, le mapping et la correspondance interne. La première décision consiste à identifier la frontière qui refuse ou transforme la valeur, avant de changer la donnée de référence ou de relancer un catalogue complet.
Pour qui : une référence reconnue dans un outil et refusée dans un autre
Retrouver la valeur avant sa première transformation
Le cas concerne les échanges de références produit entre fournisseur, adaptateur EDI, middleware, PIM, ERP et destinataire du catalogue. Il faut retrouver le champ brut, le contrat qui le décrit et la valeur passée à la recherche interne. Le message « produit introuvable » peut provenir du parseur, du mapping, d’une table de correspondance ou de l’outil destinataire. Ces refus ne portent pas tous sur la même information et ne demandent pas la même correction.
Le diagnostic commence avec une seule référence et son trajet. L’équipe compare les chaînes sans les reformater pour les rendre plus lisibles à l’écran. Elle relève ensuite la largeur attendue et le type réellement transmis : chaîne, nombre dans un payload JSON ou valeur issue d’une cellule. Dans notre programme, un entier est hors contrat dès l’entrée. Cette règle locale protège le format déclaré ; elle ne prétend pas qu’un entier de 11 chiffres perd nécessairement de la précision dans tous les environnements.
Séparer GTIN, SKU et décision de création produit
Le GTIN reçu n’est pas nécessairement la clé primaire du PIM ou de l’ERP. Une recherche peut passer par une correspondance vers un identifiant produit interne. Le témoin PRODUCT-FIXTURE-47 représente seulement cette référence locale dans un dictionnaire en mémoire. Aucune API de catalogue n’est appelée. Le test montre comment une recherche sur la chaîne brute peut manquer cette entrée alors qu’une recherche sur la représentation convenue la retrouve.
Le profil doit venir du contrat de l’interface et de sa configuration, pas d’une préférence envoyée avec la donnée. Sinon, un émetteur pourrait faire passer un champ XML trop court par la branche EANCOM pour contourner le refus. Le programme teste le rejet d’un profil inconnu, mais ne fournit aucun mécanisme d’authentification de l’émetteur. En exploitation, la configuration doit rattacher chaque source autorisée à son contrat versionné. La même valeur peut donc suivre des décisions différentes selon la frontière convenue, avec un motif que le support peut expliquer.
Le coût caché apparaît si chaque échec de correspondance crée une nouvelle fiche. Les contenus, variantes et retours d’import peuvent ensuite se répartir sur deux identifiants internes. Une validation de clé ne permet pas de décider seule qu’une création est légitime. Le diagnostic doit d’abord déterminer si la référence était absente, si la recherche utilisait une autre écriture ou si le produit effectivement décrit était différent. Les règles de création restent une décision métier distincte.
EANCOM et GS1 XML ne transmettent pas toujours la même chaîne
Appliquer la règle du champ source au lieu de compter seulement les chiffres
La note officielle GS1 sur le format GTIN dans les échanges EDI distingue les deux représentations. EANCOM utilise un format numérique de longueur variable n..14 et supprime les zéros non significatifs en tête. GS1 XML attend une chaîne numérique sur 14 caractères, avec des zéros ajoutés à gauche lorsque le GTIN d’origine est plus court.
Dans notre exemple, le GTIN sur 12 chiffres commence par un zéro. Sa suppression pour l’écriture EANCOM produit donc une chaîne sur 11 chiffres. Cette largeur ne suffit pas à conclure que le fournisseur a supprimé une partie significative de l’identifiant. Il faut d’abord connaître le type de champ annoncé. Le programme choisit explicitement un profil scalaire ; il ne devine pas le protocole à partir de la valeur et ne valide pas l’enveloppe du message qui la transportait.
Conserver trois valeurs explicables dans le diagnostic
Le relevé suivant reprend les chaînes réellement calculées par l’exercice. La valeur d’origine sert à expliquer la référence témoin ; l’écriture EANCOM représente l’entrée réduite ; la chaîne sur 14 caractères prépare le rapprochement local. Ces libellés décrivent nos variables et ne sont pas les noms de champs imposés par une API fournisseur. Il faut les relier aux éléments exacts de votre interface avant d’utiliser cette préparation dans un connecteur.
{
"gtin12": "045678912347",
"eancom_numeric": "45678912347",
"gs1_xml_14": "00045678912347"
}La chaîne source doit rester disponible à côté du résultat préparé, avec la version de la règle et le profil retenu. Sinon, un journal qui ne montre que la forme finale masque l’étape où l’écart a été introduit. Cette traçabilité sert aussi lors d’un changement de contrat : elle permet de rejouer la même entrée et de comparer les sorties sans demander au support de reconstituer des zéros disparus dans une capture d’écran.
Le parseur GTIN et le contrat XML ne valident pas la même chose
Observer le refus natif de la valeur sur 11 chiffres
Dans la source installée de Biip 4.0.0, Gtin.parse retire les espaces extérieurs, puis vérifie une largeur de 8, 12, 13 ou 14 caractères. L’appel direct avec 45678912347 déclenche une ParseError qui indique la largeur 11. Ce parseur traite des représentations de GTIN ; il n’applique pas à lui seul le contrat d’un champ EANCOM à longueur variable. Notre adaptateur prépare donc cette entrée selon le profil déclaré avant d’appeler la validation native.
La même bibliothèque accepte le GTIN d’origine sur 12 chiffres et sa forme complétée sur 13 caractères. Elle produit pour ces entrées la même représentation avec as_gtin_14(). Un succès du parseur n’implique donc pas qu’un champ GS1 XML reçu sur 12 caractères respecte déjà le format attendu sur 14. Cette deuxième règle doit être contrôlée à la frontière concernée, sans attribuer au validateur GTIN une validation de schéma qu’il n’a pas réalisée.
Distinguer largeur transmise et identité du produit
Contrairement à ce que la longueur peut suggérer, préparer quatorze caractères ne crée pas ici un nouveau produit GTIN-14. Pour 00045678912347, l’objet natif conserve la classification GTIN-12 et retourne cette même chaîne sur 14 caractères. Les zéros ajoutés servent à la représentation. Le programme observe ce résultat sans attribuer de conditionnement commercial ni modifier la référence produit locale.
Le contre-exemple utilise aussi un autre identifiant fictif, 10045678912344, dont la clé est mathématiquement valide. Le parseur le classe comme GTIN-14 et refuse sa réduction en GTIN-13. Il reste différent de notre première valeur et ne trouve aucune entrée dans le catalogue local. Cet essai ne fournit aucune règle pour fabriquer ou attribuer un code réel : il montre pourquoi retirer un premier chiffre non nul ou remplacer un zéro par un indicateur changerait la question d’identité.
Exercice : retrouver une référence sans modifier le catalogue
Reproduire séparément la lecture native et le rapprochement
Le programme Python original et téléchargeable contient la référence fictive, les deux profils d’entrée et les assertions. Biip 4.0.0 est une version figée pour reproduire ce comportement ; ce choix ne constitue pas une recommandation de version pour votre production. Les modules installés ont été comparés au paquet officiel de cette version, sans remplacer le parseur ni son contrôle de clé.
Une exécution avec Python 3.14.8 donne les compteurs ci-dessous. Les premières commandes indiquent comment préparer un environnement séparé ; les compteurs correspondent à notre exécution du fichier publié. Les 46 contrôles ne représentent pas 46 échanges avec un logiciel : ils portent sur les branches du programme, les sorties natives et le dictionnaire local. Aucun service PIM, ERP ou registre GS1 n’est contacté.
python3 -m venv .venv-gtin
.venv-gtin/bin/python -m pip install biip==4.0.0
.venv-gtin/bin/python gtin_wire_reference.py
checks_passed: 46
native_parse_runs: 14
real_connection_attempts: 0
real_product_writes: 0Lire les refus au niveau qui les produit
Le tableau distingue le parseur GTIN du profil de champ que nous avons écrit autour de lui. Ce profil local exige une chaîne de chiffres ASCII, contrôle la largeur déclarée puis appelle la bibliothèque. Le seuil d’admission du profil XML est exactement de 14 caractères : une largeur inférieure ou supérieure est refusée avant cette lecture native. Il ne représente pas un validateur complet EANCOM ou XML Schema pour GS1 XML. La documentation GS1 sur les documents nécessaires à GS1 XML précise notamment que les schémas ne couvrent pas toutes les dépendances décrites dans les spécifications métier.
| Entrée et frontière testées | Résultat réellement observé |
|---|---|
| 45678912347 directement dans Gtin.parse | Refus natif : largeur de 11 caractères. |
| 45678912347 avec notre profil EANCOM | Préparation en 00045678912347, puis référence locale retrouvée. |
| 00045678912347 avec notre profil XML | Largeur déjà conforme au profil ; même référence locale retrouvée. |
| 045678912347 avec notre profil XML | Refus local de largeur, malgré l’acceptation directe par le parseur GTIN. |
| Chaîne contenant des espaces ou valeur numérique | Refus du profil local avant une nouvelle lecture native. |
| 10045678912344 après validation native | Autre clé canonique ; aucune référence dans notre catalogue fictif. |
Le traitement des espaces illustre une autre différence de périmètre. L’appel natif avec des espaces extérieurs autour du GTIN sur 12 chiffres réussit, car cette version de la bibliothèque les retire. Notre profil de champ les refuse en amont. Il ne faut donc pas présenter ce refus comme une limitation du parseur ni généraliser sa tolérance au message XML complet. Le programme observe ces deux comportements séparément. Si votre interface autorise une correction de blancs, cette transformation mérite sa propre règle et ses propres preuves ; elle n’est pas incluse discrètement dans le profil montré ici.
Le programme vérifie aussi une clé de contrôle incorrecte et un numéro de circulation restreinte. Pour ce dernier témoin, la bibliothèque retourne effectivement un objet Rcn ; notre adaptateur l’exclut de ce rapprochement généraliste. Il faut traiter son contexte séparément. Une clé mathématiquement valide n’établit ni l’attribution du numéro, ni sa propriété, ni l’existence du produit dans un référentiel réel. Le contrôle local ne remplace aucun de ces éléments.
Erreurs fréquentes : réparer le symptôme à la mauvaise frontière
Compléter toutes les valeurs sans vérifier le contrat reçu
Ajouter des zéros à toute entrée rendrait notre GTIN sur 12 chiffres acceptable pour le profil XML après transformation. Cela masquerait pourtant un émetteur qui n’a pas respecté le format déclaré. Le choix doit être explicite : accepter une représentation EANCOM dans l’adaptateur prévu pour elle, ou signaler qu’un champ annoncé GS1 XML arrive avec une autre largeur. Les deux politiques ne doivent pas se remplacer silencieusement au gré des échecs d’import. Le diagnostic d’un montant Google Sheets refusé par l’ERP montre un autre défaut de représentation, lié au mode de lecture d’une cellule. Sa correction ne fournit aucune règle de préparation des GTIN ; elle impose de vérifier le type réellement obtenu avant de modifier le mapping.
Autre signal faible : le journal affiche une valeur sur 14 caractères, mais le moteur de recherche utilise encore la chaîne brute. L’interface donne alors l’impression que le GTIN a été correctement préparé. Il faut observer l’argument réellement transmis à la recherche, pas uniquement la valeur affichée par l’écran de support. Dans notre témoin, le dictionnaire ne retourne rien pour 45678912347 et retrouve PRODUCT-FIXTURE-47 pour 00045678912347 ; aucune panne réseau n’explique cet écart.
Confondre erreur de format, clé invalide et référence absente
Un GTIN dont la clé de contrôle échoue doit conserver ce motif de refus. Une valeur valide mais inconnue du catalogue demande une vérification de correspondance ou de couverture du référentiel. Un accès distant indisponible demande encore une autre réponse. Regrouper les trois cas sous « produit introuvable » peut provoquer des créations inutiles ou des relances sans effet. Le connecteur doit garder la cause originale et la frontière qui l’a établie, sans exposer de données sensibles dans les écrans de suivi.
Une fois la référence retrouvée, un autre défaut peut subsister dans le document. L’étude des cartons rattachés à la mauvaise palette dans un DESADV examine la hiérarchie logistique : un total produit juste n’y prouve pas le bon rattachement physique annoncé. À l’inverse, le présent exercice ne reconstruit aucune palette et ne valide aucun avis d’expédition complet. Les deux diagnostics répondent à des symptômes distincts.
Plan d’action : corriger la recherche avant de rejouer les produits
Faire porter la règle par une frontière identifiée
Commencez par un exemple qui échoue et une référence attendue confirmée par l’équipe catalogue. Le responsable du flux fournisseur qualifie le format source ; l’équipe du connecteur décrit la préparation ; le responsable PIM confirme la clé de recherche et le résultat attendu. Si l’ERP possède la correspondance, son intégrateur doit également confirmer ce contrat. L’intégration du PIM avec les sources produit doit rendre cette responsabilité vérifiable pour chaque interface concernée. Dawap intervient sur l’intégration et l’application spécifique ; aucune compatibilité native d’un PIM nommé n’est déduite de notre exercice Python.
- Capturer le champ brut et le profil annoncé sans changer son type ni effacer ses caractères.
- Identifier la règle de représentation applicable à ce champ, avant d’appeler le parseur GTIN.
- Contrôler la clé puis calculer la représentation utilisée par la recherche de correspondance.
- Confirmer la référence interne attendue et distinguer absence réelle, refus structurel et incident distant.
- Rejouer l’exemple sous contrôle avant d’élargir la correction au reste du flux concerné.
La décision de refus peut être vérifiée sans ouvrir tout le catalogue : si le profil déclaré est XML et que la valeur reçue contient 12 caractères, alors notre adaptateur refuse cette entrée avant la recherche, même si le parseur GTIN l’accepterait seul. Si le profil EANCOM est explicitement configuré et que sa préparation retrouve une référence confirmée, le résultat peut être présenté au traitement suivant. Cette autorisation locale ne prouve pas qu’une écriture distante a eu lieu.
Mesurer les correspondances corrigées et garder un retour arrière
Le monitoring distingue les références reconnues après préparation, les clés incorrectes et les vraies absences de catalogue. L’observabilité relie chaque issue au profil reçu, à la version de transformation et à la recherche effectuée. Un taux global de succès masquerait une hausse des formats refusés après une modification fournisseur. La cadence de revue et les seuils d’alerte dépendent du volume et du contrat de service ; nos 46 contrôles ne fixent aucun pourcentage de rejet acceptable. Une mesure de latence porte sur la recherche réellement appelée, séparément du temps de validation locale.
Dans une synchronisation par queue, le message conserve le champ brut et le profil connu lors de sa réception. Reprendre une entrée avec la dernière configuration disponible peut produire une autre recherche : la version retenue doit être explicable. Le périmètre de reprise se limite aux références affectées par la règle modifiée. Pour les écritures déjà effectuées, l’équipe garde l’identifiant interne confirmé et l’état retourné par le destinataire. Une nouvelle représentation du GTIN ne doit pas changer la clé d’idempotence d’une opération déjà reconnue sans arbitrage métier. Notre exercice ne fournit pas ce stockage de reprise.
Le runbook distingue un refus de largeur avant tout appel, une référence réellement absente et un timeout de recherche distante. Un retry identique ne corrige pas la première situation ; la dernière nécessite la politique de reprise convenue avec le destinataire. Revenir à l’ancienne transformation ne suffit pas non plus à annuler les créations déjà réalisées dans le PIM. Conservez les deux versions, comparez les références obtenues et faites confirmer les traitements à reprendre par l’équipe catalogue. Notre témoin ne démontre aucun rollback distant : il ne valide que la préparation et la recherche locale sans écriture.
Conclusion : expliquer la représentation avant de déclarer le produit absent
Le défaut reproduit tient à une frontière précise : une écriture EANCOM sur 11 chiffres est envoyée à un parseur qui attend des largeurs de GTIN différentes. La préparation selon le format déclaré retrouve la même référence locale que le champ XML sur 14 caractères. Ni la disparition d’un produit réel, ni l’existence d’un doublon, ni la réception par un PIM ne sont établies par cette expérience.
Pour un import en difficulté, la preuve à rechercher est la chaîne complète entre champ reçu, transformation, argument de recherche et référence interne confirmée. Le contrôle du GTIN aide à la constituer, mais ne décide pas seul de la création d’une fiche. Les cas de clé invalide, de circulation restreinte et de référence valide inconnue doivent garder des sorties compréhensibles pour l’équipe qui les traitera.
Notre prestation d’intégration PIM et catalogue permet de cadrer cette correspondance avec vos équipes produit et vos intégrateurs ERP. Le périmètre doit préciser les formats acceptés, la responsabilité de la transformation et les preuves attendues avant de rejouer le flux.
Dawap peut vous accompagner pour diagnostiquer ce rejet, confronter les valeurs reçues aux contrats de vos interfaces et définir la correction de correspondance avec les responsables du catalogue. Cette intervention permet de préparer une intégration API adaptée à vos références métier.
