Sage API : reprendre les commandes e-commerce bloquées

Une commande e-commerce payée mais absente de Sage crée immédiatement trois risques : le client attend une livraison, le stock peut rester disponible à tort et la finance ignore si elle doit facturer ou rembourser. Cliquer sur « rejouer » sans connaître l’état réel de l’ERP peut ensuite créer le doublon que l’équipe cherchait précisément à éviter.

La reprise commence donc par une enquête bornée. Pour chaque commande, il faut rapprocher la référence boutique, l’identifiant de paiement, la réservation de stock, la tentative d’écriture Sage et les éventuelles corrections manuelles. Ce dossier permet de décider entre création, simple rattachement, correction, remboursement ou abandon.

Contre-intuitivement, la première action n’est pas de rétablir le débit maximal : c’est de stopper ce qui peut encore modifier le périmètre. Une file gelée et expliquée protège mieux le chiffre d’affaires qu’un flux relancé trop vite dont les effets deviennent impossibles à distinguer.

L’offre d’intégration API de Dawap transforme cette discipline en mécanismes concrets : idempotence, réconciliation, observabilité, tableau de reprise et runbook partagé avec les équipes métier.

Identifier le vrai symptôme côté commerce

« Les commandes ne descendent plus » recouvre plusieurs réalités : webhook non reçu, message bloqué dans une queue, token OAuth expiré, timeout après écriture, client inconnu, référence fermée, prix refusé ou réponse Sage mal interprétée. Le diagnostic part des commandes touchées, pas du premier message d’erreur trouvé dans les logs.

La priorité dépend de l’impact. Une commande capturée et non visible dans l’ERP expose un engagement client ; un panier non payé peut attendre ; une commande marketplace proche de son délai d’expédition menace aussi la qualité de service du canal. La liste d’incident doit donc afficher montant, paiement, promesse d’expédition et ancienneté.

Distinguer absence, refus et confirmation perdue

Une commande absente de Sage peut être créée après correction. Une commande refusée exige de traiter sa cause. Une commande existante dont l’accusé a été perdu doit seulement être rattachée à sa référence ERP. Ces trois cas produisent le même symptôme côté boutique, mais aucune procédure commune n’est sûre.

Le test décisif recherche la clé externe dans Sage avant toute nouvelle écriture. Si la recherche n’est pas fiable, le dossier passe en contrôle humain. Une minute gagnée par un retry aveugle ne compense jamais plusieurs heures de dédoublonnage entre commande, livraison et facture.

Geler les écritures avant d’aggraver l’incident

Le gel vise seulement les opérations à risque. Il peut suspendre la création de commandes tout en laissant fonctionner le catalogue, ou isoler un site, une boutique et une période. Couper toute l’intégration sans comprendre ses dépendances peut masquer l’incident sous une nouvelle accumulation.

Chaque worker arrêté, message déplacé ou tâche planifiée désactivée est inscrit dans le journal d’incident avec son heure et son responsable. Cette chronologie évite qu’une relance oubliée réinjecte des messages pendant le rapprochement.

Prendre un instantané du périmètre

L’équipe exporte les références boutique, dates, montants, statuts de paiement, tentatives, réponses API et identifiants Sage connus. Elle note aussi les actions manuelles réalisées par l’ADV ou la finance. L’instantané devient la population de contrôle ; il ne change plus pendant l’analyse.

Scénario illustratif : 184 commandes sont en attente après un timeout Sage. La recherche retrouve 161 écritures déjà créées, 12 refus métier et 11 absences réelles. Sans instantané, les 161 confirmations perdues auraient pu être renvoyées avec le lot restant.

Séparer commandes, paiements, clients et factures

Une commande e-commerce agrège plusieurs objets dont le cycle de vie diffère. Le paiement peut être capturé alors que l’ordre est refusé ; le client peut exister sous une autre clé ; le stock peut être réservé sans livraison ; la facture peut être créée plus tard. Le plan de reprise doit suivre chaque objet séparément avant de reconstituer leur cohérence.

La table de rapprochement comporte au minimum la référence boutique, la référence Sage, l’identifiant de transaction, le client, le total TTC, la devise, le statut de réservation, le numéro de facture et l’éventuel avoir. Les cellules inconnues restent explicitement inconnues : elles ne sont jamais déduites d’un statut voisin.

Nommer le système propriétaire de chaque état

La boutique prouve l’intention et le parcours de paiement. Le prestataire de paiement prouve la capture ou le remboursement. Sage prouve l’exécution commerciale et comptable. Le WMS ou l’ERP prouve la préparation. Un tableau support peut agréger ces preuves, mais ne doit pas devenir leur source.

Cette séparation évite une erreur classique : marquer une commande remboursée parce qu’un avoir Sage existe, sans vérifier que le remboursement monétique a réellement été exécuté. Une pièce comptable et un mouvement financier sont liés ; ils ne sont pas interchangeables.

Reconstruire des statuts actionnables

Les statuts techniques comme « failed », « timeout » ou « HTTP 500 » n’indiquent pas quoi faire. Le poste de reprise a besoin d’états métier : à rechercher dans Sage, à corriger côté boutique, à valider par l’ADV, à rembourser, à rattacher ou prêt à rejouer.

Chaque état possède une condition d’entrée, une action autorisée, un propriétaire et une preuve de sortie. « Prêt à rejouer » signifie par exemple que la commande est absente de Sage, que son paiement est valide, que sa donnée a été corrigée et que sa clé d’idempotence sera contrôlée.

Interdire les catégories sans échéance

Un statut « à analyser » devient rapidement un parking. S’il reste nécessaire, il doit porter une cause provisoire, une personne assignée et une heure d’escalade. Au-delà, le dossier bascule vers une décision explicite : corriger, rembourser, accepter le risque ou solliciter l’équipe Sage.

Le tableau expose aussi l’âge de la plus vieille commande dans chaque état. Ce signal est plus utile qu’un taux global de succès : trois commandes payées bloquées depuis deux jours méritent plus d’attention que cinquante erreurs récentes sur des paniers de test.

Rejouer sans créer de doublons dans Sage

La clé d’idempotence associe la boutique, la commande, la société et, si nécessaire, la version de l’opération. Elle est persistée avant l’appel API puis complétée avec la référence Sage. Un index unique protège cette relation contre deux workers ou deux actions support simultanés.

Le rejeu ne repose pas uniquement sur cette base locale. Il relit l’état cible avec la référence externe lorsque Sage le permet, compare montant, client et nombre de lignes, puis choisit entre rattachement et création. Une base restaurée ou un cache perdu ne doit pas suffire à contourner la protection.

Traiter le timeout comme un état inconnu

Après un timeout, le middleware ignore si Sage a reçu la requête. Le retry automatique est donc suspendu jusqu’à la recherche de l’écriture. Si elle existe et correspond au payload attendu, le flux enregistre son identifiant et reprend après cette étape.

Si plusieurs écritures correspondent, aucune suppression automatique n’est lancée. L’ADV vérifie livraisons, factures et réservations avant de choisir l’ordre à conserver. Le doublon est alors résolu comme un incident métier, pas comme une simple ligne technique à effacer.

Transformer les traces en preuves métier

Une trace exploitable relie le correlation ID, la référence boutique, l’identifiant de paiement, la clé d’idempotence, la tentative, l’endpoint REST ou SOAP appelé, le statut reçu et la référence Sage. Les payloads sensibles sont filtrés ; les valeurs utiles au rapprochement restent consultables.

Les logs techniques expirent souvent plus vite que le cycle d’un litige. Les décisions de reprise doivent donc être persistées dans un audit trail : qui a classé la commande, sur quelle preuve, quelle correction a été appliquée et quel résultat a été vérifié.

Rendre les erreurs lisibles sans ouvrir la console

Le support doit voir « client Sage introuvable pour le compte 4832 » ou « commande déjà rattachée à SOH-21984 », pas seulement un code d’exception. Le détail technique reste accessible pour l’équipe d’intégration, mais l’action métier apparaît au premier niveau.

La supervision regroupe les incidents par cause racine. Cent messages refusés après la fermeture d’une référence constituent un problème de catalogue, pas cent incidents isolés. Cette agrégation oriente la correction vers la source et évite une campagne de reprises inutiles.

Organiser le poste de reprise

Le support a besoin d’un écran limité aux décisions autorisées : corriger une donnée, rattacher une référence Sage, demander une validation, déclencher un remboursement ou rejouer un dossier éligible. Les commandes SQL et les réinjections manuelles de payload restent hors du parcours normal.

Les droits sont séparés. Une personne peut préparer une correction ; une autre valide le rejeu lorsque le montant ou l’impact le justifie. Le journal conserve les deux identités et la différence entre valeur initiale et valeur corrigée.

Écrire le runbook depuis un dossier réel

Le runbook décrit les gestes dans l’ordre : retrouver la commande, vérifier le paiement, rechercher l’écriture Sage, qualifier le stock, choisir l’action, exécuter puis contrôler. Pour chaque étape, il nomme les entrées, la sortie attendue, les responsabilités, le seuil d’escalade et le repli autorisé.

Une personne qui n’a pas développé le connecteur doit réussir l’exercice sur un environnement de test. Si elle doit demander quel script lancer ou quelle table modifier, la procédure de reprise n’est pas encore industrialisée.

Protéger facturation, avoirs et paiements

Le rapprochement financier vérifie le total commandé, le montant capturé, la facture émise, les avoirs et les remboursements. Une égalité globale ne suffit pas : chaque mouvement doit être rattaché à une commande et à une décision documentée.

Les écarts sont traités avant la relance lorsque celle-ci peut créer une pièce comptable. Une commande déjà facturée ne repasse pas dans un flux de création ; une commande remboursée ne doit pas être libérée pour préparation ; un avoir sans remboursement doit rester visible jusqu’à l’action monétique.

Utiliser un ledger de rapprochement temporaire

Pendant l’incident, un registre peut aligner débit client, commande Sage, expédition, facture, avoir et remboursement. Ce registre sert de preuve et de liste de travail ; il ne remplace ni Sage ni le prestataire de paiement.

La finance valide le solde du périmètre avant sa clôture : commandes encaissées sans ordre, ordres sans paiement, factures dupliquées et remboursements en attente doivent être à zéro ou explicitement acceptés avec un responsable et une date.

Relancer le flux par paliers

La relance commence par un échantillon représentatif : une commande simple, une remise, plusieurs taux de TVA, une rupture et un cas déjà traité. Une queue dédiée impose le seuil de débit, conserve l’idempotence et déclenche le rollback si le monitoring détecte un nouvel écart.

La file historique et les nouvelles commandes sont séparées. Les nouveaux achats ne doivent pas attendre derrière plusieurs milliers de reprises, tandis que le backlog ancien reçoit une cadence compatible avec l’ERP et le contrôle support.

Définir les seuils d’arrêt avant d’ouvrir la vanne

Le go/no-go retient des limites simples : aucun doublon, aucun écart de montant, moins de cinq dossiers sans statut et une latence sous le seuil convenu. Deux erreurs identiques consécutives peuvent suffire à regeler le lot si elles révèlent une cause non corrigée.

Une hausse du taux de succès n’autorise pas seule l’accélération. L’équipe contrôle aussi l’âge du backlog, les corrections manuelles, le nombre de remboursements et le temps moyen de diagnostic. Le flux n’est rétabli que lorsque sa reprise reste soutenable.

Pour qui préparer ce plan de reprise

Ce dispositif est utile aux e-commerçants et distributeurs dont Sage reçoit commandes, clients, stocks ou pièces financières, en particulier lorsque plusieurs boutiques et canaux partagent le même ERP. Il devient indispensable si un retry peut créer une écriture irréversible ou si le paiement précède la validation Sage.

Réunir support, ADV, logistique, finance et intégration

Le support qualifie l’impact client ; l’ADV décide du sort commercial ; la logistique vérifie réservation et préparation ; la finance rapproche capture, facture et remboursement ; l’équipe d’intégration apporte la chronologie technique. Aucun de ces acteurs ne détient seul la preuve complète.

Un incident mineur peut rester dans le circuit standard si la clé de recherche, la correction et le contrôle final sont connus. En revanche, un périmètre non borné, des actions manuelles non tracées ou une recherche Sage ambiguë imposent une cellule de reprise dédiée.

Savoir différer la relance

Il faut différer si la population touchée n’est pas stabilisée, si l’état de paiement est incertain ou si une même référence externe retrouve plusieurs commandes Sage. Le chiffre d’affaires apparent ne justifie pas d’ajouter des écritures qui devront ensuite être annulées.

La relance devient raisonnable quand chaque dossier possède un état, une prochaine action et un propriétaire, que le cas du timeout a été testé et que le rapprochement financier peut détecter toute nouvelle divergence.

Plan d’action des premières trente heures

Heures 0 à 4 : contenir et mesurer

Nommer un pilote d’incident, horodater le début, isoler les workers concernés et capturer les files avant toute manipulation. L’équipe délimite ensuite boutique, site Sage, première et dernière commande touchées, nombre de paiements capturés et existence d’actions manuelles. Les nouvelles commandes sont routées vers un mode dégradé décidé avec le commerce.

Un échantillon de dix dossiers suffit pour distinguer défaut de transport, rejet métier et confirmation perdue. Chaque dossier reçoit une référence d’incident commune. Les hypothèses restent séparées des faits : une erreur de token observée à 9 h ne prouve pas que toutes les commandes suivantes sont absentes de Sage.

Heures 4 à 30 : rapprocher, corriger et rouvrir

La population complète est recherchée dans Sage et rapprochée des paiements. Les causes sont regroupées, les données sources corrigées et les dossiers éligibles préparés. Le pilote commence par quelques commandes contrôlées de bout en bout, puis augmente le batch tant que les seuils restent verts.

Après résorption du backlog, la surveillance renforcée reste active pendant un cycle commercial complet. Le bilan chiffre les commandes touchées, les doublons évités, les remboursements, le temps de reprise et la cause racine. Une action préventive est attribuée à chaque faiblesse révélée.

• Geler les écritures risquées tout en préservant les flux indépendants.
• Conserver un instantané immuable du périmètre et de ses preuves.
• Rechercher l’état cible après tout timeout avant d’autoriser un retry.
• Rapprocher commande, stock, paiement, facture, avoir et remboursement.
• Tester la reprise avec une personne autre que l’auteur du connecteur.

Erreurs fréquentes pendant une reprise Sage

Les erreurs les plus coûteuses cherchent à gagner du temps : vider la queue sans inventaire, réinjecter tous les messages, modifier directement une table de correspondance ou déclarer l’incident clos sur la seule baisse du backlog.

Rejouer le lot entier après une correction locale

Une correction de client ou de référence ne rend pas automatiquement toutes les commandes éligibles. Certaines existent déjà dans Sage, d’autres ont été remboursées ou modifiées. Le lot doit être reclassé dossier par dossier selon la nouvelle preuve.

Le batch de reprise ne reçoit que les identifiants validés et sa taille reste bornée. Cette sélection rend possible un rollback commercial et empêche une nouvelle erreur de se propager sur tout l’historique.

Confondre backlog nul et incident résolu

Une queue vide peut signifier que les messages ont été supprimés, déplacés ou déclarés réussis sans contrôle de l’ERP. La fermeture exige une réconciliation indépendante et le solde des écarts financiers.

Le dernier dossier mérite le même niveau de preuve que le premier. Les cas abandonnés restent documentés avec leur remboursement, leur correction manuelle ou leur acceptation de risque ; ils ne disparaissent pas dans une colonne « exceptionnel ».

• Ne jamais relancer une création après timeout sans recherche dans Sage.
• Ne pas déduire un remboursement depuis la seule présence d’un avoir.
• Ne pas mélanger nouvelles commandes et reprise historique dans la même priorité.
• Ne pas masquer la cause métier derrière un taux global de réponses HTTP.

Ressources pour fiabiliser la suite

La reprise révèle souvent une faiblesse plus ancienne de contrat, d’idempotence ou de supervision. Ces lectures permettent de traiter la cause racine après le retour au nominal, sans transformer l’incident en chantier sans fin.

La page intégrateur Sage API aide à cadrer les objets exposés, les responsabilités et le premier flux à sécuriser avant une évolution plus large.

Relier reprise, contrat et exploitation

Le contrat précise ce qui rend une opération rejouable. L’observabilité apporte les identifiants et les états. Le runbook convertit ces informations en décision support. Si l’un des trois manque, la reprise dépend encore d’une investigation artisanale.

Les ressources suivantes couvrent les limites Sage, les contrats de données et la fiabilité des webhooks :

• API Sage : repères pour cadrer l’ERP
• Contrats de données API durables
• Webhooks fiables : signature, rejeu et reprise

Conclusion : reprendre sans perdre la preuve

Une reprise réussie ne se juge pas au nombre de messages renvoyés. Elle rétablit la cohérence entre intention d’achat, commande Sage, stock, paiement et comptabilité, sans ajouter de doublon ni effacer la chronologie.

Le geste décisif consiste à traiter le timeout comme un état inconnu : rechercher, comparer, puis seulement rattacher ou recréer. Cette discipline protège le client autant que l’équipe qui devra expliquer l’incident plusieurs semaines plus tard.

Après le retour au nominal, les preuves récoltées doivent améliorer la clé d’idempotence, les statuts, les alertes et le runbook. Sinon, le prochain incident reproduira le même travail manuel sous un autre nom.

Dawap accompagne les équipes avec son offre d’intégration API pour auditer le flux Sage, construire la réconciliation, tester les interruptions et mettre en production une reprise que le support peut réellement piloter.