Le verdict d'abord : le dépannage d'une intégration API et EDI après le go-live ne consiste pas à réparer le lien cassé le plus vite possible. Il consiste à ne pas aggraver la situation. Les erreurs les plus coûteuses que j'ai vues n'ont pas été causées par la panne d'origine. Elles ont été causées par quelqu'un qui a paniqué, tout renvoyé, modifié l'inventaire à la main et redémarré l'interface, transformant une panne traçable en un gâchis que personne ne pouvait réconcilier. Donc, avant de toucher à quoi que ce soit, classifiez la panne. Le message n'est-il jamais arrivé ? Est-il arrivé mais n'a jamais été traité ? A-t-il été traité mais jamais accusé de réception ? Ou bien trois systèmes insistent-ils chacun que leurs propres chiffres sont corrects ? Si vous vous trompez de classification, chaque étape suivante est fausse aussi. J'ai vu cet écueil trois fois, dans trois entrepôts différents, avec le même scénario.
La première histoire date de l'automne dernier, dans un entrepôt tiers d'articles pour la maison en dehors d'Ontario, en Californie. Au cours de la troisième semaine après le go-live, un mardi matin, le détaillant a signalé que plus de quatre cents commandes n'étaient jamais parvenues à l'entrepôt. La personne de service a supposé que l'interface était en panne et l'a redémarrée deux fois. Rien n'a changé. La vérification a montré que le détaillant avait envoyé les commandes et que notre passerelle les avait reçues, mais qu'elles étaient bloquées à la validation des commandes parce que le détaillant avait changé un suffixe sur un code produit sans nous prévenir. Rien n'était cassé. Les deux parties avaient simplement supposé que l'autre n'avait rien changé. Nous avons remis les expéditions en route en mappant temporairement les anciens codes, puis nous avons fait passer le changement de code par un processus formel de notification. Depuis, je vérifie le journal des changements avant le journal système.
La deuxième histoire est plus douloureuse. Un entrepôt de petit électroménager près de Chicago a passé son premier mois après le go-live avec un inventaire décalé de plus de cent unités par jour, tantôt trop haut, tantôt trop bas, et personne n'a pu trouver le schéma pendant une semaine. Il s'agissait en fait de deux problèmes empilés. Les réceptions de retours étaient envoyées deux fois par le système du détaillant, et notre côté n'avait aucun contrôle d'idempotence, donc les mêmes retours étaient comptabilisés deux fois. En plus, les ajustements d'inventaire tournant étaient saisis directement dans le WMS et jamais renvoyés au détaillant. Chaque côté continuait à modifier ses propres chiffres, et l'écart ne cessait de croître. La solution n'était pas brillante : dédupliquer chaque message renvoyé sur le numéro de document commercial, et faire passer chaque ajustement d'inventaire par l'interface au lieu de laisser quelqu'un modifier une quantité et partir. Ces deux lignes figurent depuis sur ma checklist de la nuit du go-live.
Pannes API/EDI : classer d'abord, puis agir
La classification tient en quatre phrases, et vous devez faire correspondre votre panne à l'une d'elles avant d'ouvrir un fichier journal. Un, le message n'est jamais arrivé : non envoyé, envoyé au mauvais endpoint, certificat expiré, coupure réseau. Deux, il est arrivé mais n'a jamais été traité : bloqué sur la validation, le mapping ou un champ manquant. Trois, il a été traité mais jamais accusé de réception : le document commercial a été créé, mais la confirmation n'est jamais revenue, donc l'expéditeur a supposé que vous ne l'aviez jamais reçu et l'a renvoyé. Quatre, tout le monde est en désaccord : les systèmes de commandes, d'expéditions et d'inventaire utilisent des définitions différentes, donc chaque côté semble correct pris isolément.
Dix minutes de classification peuvent faire gagner quatre heures à chercher dans des milliers de lignes de journal sans savoir quel type de problème on cherche. Et une règle : ne redémarrez pas une interface de production sans preuve. Un redémarrage efface l'état des messages en vol, et une piste que vous auriez pu suivre devient une piste que vous ne pouvez plus suivre.
Beaucoup de problèmes post-live ont été semés pendant la sélection, quand personne n'a défini qui possède les données de référence ni qui détecte une exception en premier. Si vous revisitez ces décisions, la comparaison de sélection API contre EDI est une référence utile pour inscrire dans votre accord d'exploitation les responsabilités que vous avez omises.
Traçage des messages API/EDI : trouvez le message avant d'en débattre
Ma routine de traçage des messages comporte cinq étapes, et elles fonctionnent dans cet ordre. Étape un, prenez le numéro de document commercial, allez dans le système de l'expéditeur et confirmez l'enregistrement d'envoi : a-t-il été envoyé, vers quel endpoint, et quel code de réponse est revenu ? Étape deux, vérifiez l'enregistrement de réception de votre propre passerelle et confirmez que le message d'origine a été stocké. Étape trois, validez le message d'origine : s'agit-il d'un problème de format, d'un problème d'encodage, ou d'une règle métier qui le bloque ? Étape quatre, lisez le journal de traitement métier pour voir exactement où il s'est arrêté, et s'il s'est arrêté sur une erreur système ou une retenue manuelle. Étape cinq, vérifiez l'enregistrement d'accusé de réception : une confirmation a-t-elle été envoyée, et l'autre partie l'a-t-elle acceptée ?
Voici la partie contre-intuitive : une réponse de succès ne signifie pas un succès métier. Beaucoup d'interfaces renvoient un 200 juste pour dire « reçu », et non pour dire que la commande a été créée ou que l'inventaire a été correctement déduit. J'ai déjà vu deux équipes se brandir des journaux 200 pendant deux jours alors que les commandes attendaient dans une file middleware. Jugez d'après le statut du document commercial, jamais d'après le seul code de réponse. Le code de réponse prouve seulement que la transmission n'a pas cassé. Il ne prouve pas que le travail métier a été bien fait.
Autre panne classique : l'équipe n'a testé que le parcours nominal dans l'environnement de test et n'a jamais testé un renvoi, un message hors ordre ou un champ vide. Ces trois cas appartiennent à la checklist de la nuit du go-live en tant que tests distincts. Un renvoi teste l'idempotence, un message hors ordre teste la machine à états du document, et un champ vide teste si le système signale bruyamment l'erreur ou abandonne le document en silence. Les abandons silencieux sont les pires des trois, car une erreur au moins prévient quelqu'un, tandis qu'un abandon silencieux n'est découvert que lorsqu'un client se plaint.
Commandes bloquées : suivez cette checklist, case par case
Quand des commandes se bloquent, le dépannage d'intégration API et EDI commence par une règle : ne les créez pas à la main pour sauver la journée. Une commande créée à la main résout l'expédition du jour et garantit un problème de réconciliation le lendemain, soit un doublon, soit une commande manquante. Suivez plutôt cette checklist, et exigez une preuve pour chaque case, une entrée de journal ou un statut de document, et non « je pense que cela a été envoyé ». Le numéro de document existe-t-il dans le système de l'expéditeur ? Le message a-t-il atteint la passerelle ? A-t-il passé la validation ? Les codes produit et emplacement ont-ils été mappés ? Y a-t-il assez d'inventaire ? Le document est-il en retenue manuelle ?
Une fois la cause racine trouvée, l'ordre de réparation compte. Protégez d'abord les expéditions, corrigez ensuite les données, et discutez de la responsabilité en dernier. S'il s'agit d'un problème de mapping, mettez en place un mapping temporaire pour protéger les expéditions du jour pendant que le changement formel suit son cours. S'il s'agit d'une rupture de stock, confirmez si la rupture est réelle ou seulement des données d'inventaire obsolètes avant de libérer la commande ; un décalage de données appelle une réconciliation, une vraie rupture appelle le processus de rupture, et forcer la commande n'aide personne. Après avoir réparé une commande, vérifiez si le reste du lot partage la même cause.
Faites le calcul pour comprendre pourquoi les contournements manuels ne passent pas à l'échelle. Supposez que quatre cents commandes se bloquent en une journée, et que chacune demande huit minutes de vérification et de traitement manuels. Cela fait 3,200 minutes, plus de cinquante heures, et deux personnes en heures supplémentaires ne finiront toujours pas. Une fois que les commandes bloquées dépassent un certain volume, la bonne réponse est de réparer le lien et le processus en masse, et non d'ajouter des personnes. Ajouter des personnes transforme un problème de système en problème de main-d'œuvre, et cela ne fait que coûter plus cher.
Écarts d'inventaire : la réconciliation en trois étapes
Pour les écarts d'inventaire, le dépannage d'intégration API et EDI se résume à trois étapes. Étape un, réconciliez les totaux : la quantité disponible dans le WMS, la quantité disponible dans l'autre système, et la dernière quantité sur laquelle les deux côtés se sont mis d'accord, puis indiquez l'ampleur de l'écart et la date de sa première apparition. Étape deux, réconciliez les flux : de la date de référence à aujourd'hui, comparez les réceptions, les expéditions, les retours et les ajustements en quatre catégories distinctes, et trouvez quelle catégorie présente un écart cumulé égal à l'écart total. Étape trois, réconciliez les documents : prenez la catégorie présentant le plus grand écart, échantillonnez quelques transactions, et vérifiez-les une par une pour y déceler des doublons, des omissions ou des différences de définition.
Les différences de définition sont la cause la plus négligée : un côté peut compter le stock en transit comme disponible alors que l'autre ne le fait pas. Les chiffres peuvent diverger sans que personne n'ait tort, parce que les deux côtés ne comptent pas la même chose. Avant de réconcilier, écrivez ce que signifient disponible, disponible à la vente et en transit, et mettez les deux côtés d'accord. Sans définitions convenues, la réconciliation se termine avec chaque côté qui insiste sur le fait qu'il a raison.
Une dernière règle d'exploitation. Une interface n'est pas terminée le jour du go-live. Les trente premiers jours sont la période la plus risquée, quand l'autre partie peut changer un code, faire tourner un certificat ou modifier une fréquence d'envoi sans vous prévenir. Ma pratique actuelle est une réconciliation hebdomadaire pendant le premier mois, plus la rotation des certificats deux semaines avant leur expiration. Les opérations d'interface se gagnent en respectant ces routines peu glorieuses.
Par Lin Xiao, Consultant en mise en œuvre WMS
Traduit de l'anglais. En cas de divergence, la version anglaise fait foi.
