Un tableau qui relie « customer_id » à « code_client » ne décrit ni la source maîtresse, ni le comportement en cas de doublon, ni l’unité du prix, ni ce qui se passe lorsqu’une commande arrive deux fois.
Une intégration API ERP–e-commerce doit reposer sur un contrat métier versionné. Il décrit les objets, mais aussi leurs décisions, délais, erreurs et preuves.
La structure proposée couvre le catalogue, les clients, le stock et les commandes. Elle convient aux API, aux événements ou aux fichiers dès lors que les mêmes exigences sont rendues explicites.
Le contrat appartient conjointement aux producteurs et aux consommateurs de chaque donnée. Il devient fiable seulement lorsque les deux côtés le testent et l’utilisent réellement pendant les incidents.
Définir périmètre et responsabilité
Le document nomme flux, systèmes, entités, pays, fréquence, volumes et conséquences opérationnelles. Chaque objet possède un responsable côté producteur et un autre côté consommateur, tous deux capables d’arbitrer une évolution.
Il distingue catalogue, offre, stock, client, commande, paiement, expédition et facture. Fusionner ces notions dans un objet « produit » ou « commande » crée des ambiguïtés.
Les fonctions hors périmètre et les opérations encore manuelles sont également recensées. Le contrat ne prétend pas automatiser ce qui reste humain, mais il décrit les entrées et les preuves attendues autour de cette décision.
Un périmètre utile précise surtout les effets interdits : le catalogue ne crée pas de client, le paiement ne modifie pas le stock et l’ERP ne republie pas une commande déjà annulée. Ces frontières évitent qu’un même événement déclenche des responsabilités concurrentes.
Attribuer les sources de vérité
Pour chaque champ, la matrice indique le système maître, ses consommateurs, la fréquence et la règle de conflit. Une donnée calculée reçoit également un responsable, une formule versionnée et une politique de recalcul.
L’ERP peut maîtriser prix et client, le PIM le contenu, l’e-commerce le panier et l’OMS la commande. La répartition réelle dépend du système d’information, des responsabilités métier et de la capacité de chaque outil à prouver son état.
Une écriture provenant d’un non-maître est refusée, traitée comme demande ou gouvernée par une règle explicite.
Le signal faible apparaît souvent dans les corrections manuelles : si une équipe écrase régulièrement une donnée issue du système maître, le problème vient probablement de la responsabilité attribuée ou de son délai de mise à jour. Automatiser cet écrasement ne résout pas le conflit de responsabilité qui produit la correction.
Contractualiser les identités
Chaque objet possède un identifiant stable, des identifiants externes, une règle d’unicité et une stratégie de création. Les correspondances sont versionnées afin de reconstituer le lien valable au moment de chaque échange.
Les clés naturelles comme l’adresse électronique ou le SKU sont utilisées seulement lorsque leur stabilité est démontrée. Les changements, scissions et fusions suivent un processus qui préserve les anciennes références.
La corrélation relie commande, ligne, paiement et expédition afin de reconstituer une transaction de bout en bout.
Un test simple consiste à partir d’un colis livré et à remonter jusqu’au client, à la ligne de commande et au paiement. Si cette traversée exige une recherche approximative par date et montant, l’identité reste insuffisamment contractualisée.
Décrire schéma et sémantique
Le schéma indique type, obligation, cardinalité, format, exemple et contraintes de chaque propriété. Sa description explique le sens métier et les décisions permises, au lieu de répéter simplement le nom technique.
Valeur nulle, absence, zéro et chaîne vide représentent des états distincts dans le contrat. Chaque date indique son fuseau, son événement métier et la règle applicable aux changements d’heure.
Les exemples incluent nominal et cas difficiles : commande partielle, adresse internationale, produit sans stock et client multi-entités.
Les exemples négatifs comptent autant que le cas nominal, car ils rendent les limites opposables. Un prix sans devise, une quantité décimale interdite ou une adresse incomplète doivent produire une réponse connue avant la mise en production.
Versionner transformations et unités
Les correspondances de catégorie, taxe, unité, devise et statut deviennent des éléments versionnés, déployés et testés. Chaque valeur inconnue possède un comportement explicite : rejet, quarantaine, valeur temporaire ou demande de décision.
Les arrondis, conversions et valeurs par défaut sont documentés avec leurs conséquences métier. Toute transformation conserve sa version et la valeur source afin de permettre un nouveau calcul sans perte d’information.
Un changement est simulé sur un jeu historique pour détecter population et collisions avant publication.
Par exemple, convertir des unités de conditionnement après l’arrondi peut créer un stock vendable supérieur au stock physique. La recette compare donc l’ordre des opérations, les bornes et l’écart cumulé sur une population réaliste.
Définir statuts et transitions
Le contrat décrit les états, les transitions autorisées, l’acteur et l’effet de chaque décision. Un statut source peut rester conservé à côté du modèle commun afin de préserver la précision du canal.
Les événements tardifs ne doivent pas faire reculer silencieusement une commande déjà traitée. Les conflits entrent en exception avec le contexte, la version connue et la décision attendue.
Les commandes annulées, expédiées et remboursées possèdent des règles séparées plutôt qu’un champ générique mis à jour.
Garantir idempotence et ordre
Chaque opération à effet de bord possède une clé d’idempotence, une durée et une réponse en cas de doublon.
L’ordre des événements est garanti par le transport ou géré par une version métier. Une réponse réseau perdue ne conduit jamais à créer deux commandes, deux réservations ou deux remboursements.
La clé d’idempotence ne doit pas être un simple identifiant de requête recréé à chaque tentative. Elle représente l’intention métier durable, par exemple « rembourser telle ligne pour telle cause », et reste stable jusqu’au résultat final.
Les mises à jour concurrentes utilisent version, timestamp ou autre règle validée, sans dernier écrit arbitraire.
Classer erreurs et reprises
Les erreurs distinguent validation, conflit métier, dépassement de limite, indisponibilité et défaut permanent. Chaque catégorie possède une politique de nouvelle tentative, une temporisation et une condition d’escalade.
La quarantaine conserve une charge utile protégée, la cause, la version et l’action attendue. La reprise est contrôlée, idempotente et rapprochée afin qu’un succès technique ne masque pas un doublon fonctionnel.
Une erreur retourne code stable, message actionnable et corrélation, sans exposer de secret.
Le coût caché des erreurs mal classées vient des reprises humaines répétées et impossibles à automatiser. Mesurer leur volume, leur ancienneté et leur temps de traitement permet de prioriser la correction du contrat plutôt que d’agrandir indéfiniment l’équipe support.
Faire évoluer sans rupture
Le contrat publie compatibilité, dépréciation, préavis et date de fin pour chaque version. Ajouter un champ réellement optionnel diffère profondément de changer le sens ou l’unité d’une propriété existante.
Les tests des consommateurs vérifient leurs hypothèses réelles sur les propriétés qu’ils utilisent. Producteur et consommateurs exécutent cette recette dans leur chaîne de livraison avant de publier une version incompatible.
La coexistence de plusieurs versions possède une durée et une population explicitement bornées. Une migration sans décommissionnement entretient une dette permanente et oblige chaque incident à vérifier plusieurs comportements simultanément.
Protéger données et secrets
Le contrat indique authentification, autorisation, chiffrement, minimisation, conservation et classification des champs.
Les secrets sont tournés, les webhooks authentifiés et les environnements séparés. Les données personnelles n’entrent pas dans les logs par défaut.
Les exports et replays sensibles sont tracés et limités par rôle.
Fixer SLA et observabilité
L’engagement de service couvre la fraîcheur et le résultat métier, pas seulement la disponibilité HTTP. Les volumes nominaux, les pics admissibles et la vitesse de rattrapage sont chiffrés sur des conditions connues.
La corrélation suit chaque événement, sa transformation et son état dans le système destinataire. Les alertes indiquent la population, la conséquence, le responsable et la procédure de résolution attendue.
Le mode dégradé précise ce qui continue et quand une donnée devient trop ancienne pour être utilisée.
Prouver par rapprochement
Les contrôles comparent comptes, montants, stocks, commandes et statuts selon la nature du flux. Les agrégats détectent les dérives globales, tandis que les échantillons prouvent qu’aucune compensation ne masque deux erreurs opposées.
Chaque lot ou fenêtre possède un manifeste, des volumes, des erreurs, des reprises et un solde final. La fermeture prouve que l’état destinataire correspond à l’intention métier, pas seulement que tous les appels ont répondu.
Le cadre des API ERP relie ce contrat aux connecteurs et à leur exploitation.
Conclusion : partager une sémantique
Le contrat ERP–e-commerce constitue une convention métier réellement exécutable par les deux systèmes. Le schéma seul ne décrit ni les responsabilités, ni les transitions, ni le traitement des échecs.
Les identités, l’idempotence, les versions et les reprises protègent durablement les transactions. Les rapprochements prouvent ensuite que l’état attendu existe réellement dans le système destinataire.
Les tests consommateur gardent le contrat vivant pendant les changements et réduisent les corrections silencieuses.
Dawap conçoit ces contrats dans ses missions d’intégration API, puis les met en production avec une supervision exploitable et des procédures de reprise testées.
