En réalité, la liberté modulaire de Medusa devient un risque lorsque chaque intégration invente sa propre vérité sur le produit, le paiement ou la commande. Cette lecture permet de décider les frontières, d’exercer les pannes et de transmettre un service sur mesure réellement exploitable.
Le parcours suit donc une intention de checkout jusqu’au paiement, à la commande, au stock et à l’expédition, sans transformer l’orchestrateur en référentiel caché. Chaque frontière nomme l’état attendu, l’équipe qui tranche et la preuve conservée après une réponse ambiguë. Le dossier garde aussi la version de schéma, la règle tarifaire, la réservation et les effets irréversibles déjà appliqués. Cette chaîne permet au support de distinguer une panne temporaire d’un refus métier, puis d’appliquer le bon runbook avant toute nouvelle mutation.
Sur modules commerce, le principe directeur est simple : « modules commerce et intégrations sur mesure » constitue un service exploitable et non une suite de requêtes vers le service source. Ce contrat attribue le client, le justificatif conservé puis l’arbitrage associé lorsque les événements arrivent en retard.
Les arbitrages relatifs à expéditions articulent conception, mapping, recette négative et reprise. Notre accompagnement API cadre le contrat et confronte la conception aux possibilités documentées.
Rendre exploitable le périmètre « intégrations sur mesure »
Le comité confronte ce cas, la mesure « SKU sans correspondance », la preuve « version tarifaire » et un exercice conduit par le responsable référentiel ; le support valide le runbook sur un dossier réel.
Traiter le webhook comme une notification, pas comme la vérité complète
Avant d’étendre modules commerce, côté exploitation, le schéma d’erreur différencie validation, conflit, indisponibilité et dépassement de quota pour guider la bonne reprise.
Étendre le pilote par décision plutôt que par volume brut
Contre-test à jouer avec la finance
En production sur intégrations sur mesure, dans les faits, le journal masque les données sensibles mais conserve « version tarifaire », la version de contrat et le résultat de la décision.
La finance part d’une commande et suit la corrélation jusqu’au paiement et à l’écriture attendue. Le runbook indique qui peut reprendre, quel effet est irréversible et quelles données doivent rester masquées pendant le diagnostic.
Stabiliser SKU, variantes et attributs avant les volumes
Pour reprendre le point modules commerce, dans les faits, chaque retry relit l’expédition, contrôle « mouvement de stock » et distingue absence de réponse, refus métier et effet déjà appliqué.
Séparer stock physique, disponible et réservé
Medusa API ne doit jamais réduire le stock à une quantité unique : dépôt, réservation, promesse et mouvement possèdent des temporalités différentes. Dans le traitement de expéditions, une fois le flux ouvert, l’exercice de passation débute par la mesure « délai de confirmation » et se termine lorsque le support applicatif retrouve « code dépôt » sans intervention du développeur.
Dans le dossier intégrations sur mesure, après un échec provoqué, la revue de production confronte l’indicateur « SKU sans correspondance » à un échantillon d’écarts compris par le support applicatif.
Préserver la logique comptable derrière chaque événement
Avant d’étendre modules commerce, dans les faits, le tableau de bord rattache la mesure « stocks divergents » à l’impact métier au lieu d’additionner des erreurs techniques sans contexte.
Pour qui ce projet est utile — et dans quels cas le différer
Pour Medusa API, le support applicatif pilote le cadrage, le responsable référentiel relit le tarif et la logistique exerce la reprise ; dans Medusa API, ces trois responsabilités doivent rester visibles entre le service source et l’environnement « ERP, commerce et logistique ». Pour cette décision, le support applicatif confronte le stock entre les deux systèmes et conserve « code dépôt » comme preuve de sortie.
Pour reprendre le point intégrations sur mesure, la logistique confronte l’expédition entre les deux systèmes avant d’autoriser la reprise décrite dans « identifiant de commande ».
La limite du dispositif apparaît quand cette partie du flux masque la métrique « stocks divergents » ou rend « un retour vise le mauvais dépôt » incompréhensible pour le support applicatif ; ce périmètre retourne alors en pilote avec une reprise manuelle. Pendant le contrôle de expéditions, la finance compare le client entre les deux systèmes puis transmet « version tarifaire » au propriétaire du run.
Écrire le contrat technique sans inventer l’API
Contrat, payload et compatibilité
Dans le dossier modules commerce, l’administration des ventes met en regard la facture entre les deux systèmes jusqu’à ce que « identifiant de commande » explique le résultat observé.
Lors de la revue de intégrations sur mesure, la finance confronte le client entre les deux systèmes et ferme l’écart seulement après lecture de « code dépôt ».
{
"eventType": "medusa.api.changed",
"businessObject": "client",
"externalId": "<source-id>",
"correlationId": "<trace-id>",
"occurredAt": "<iso-8601>",
"schemaVersion": "1"
}Idempotence, retry et preuve de reprise
Le schéma relatif à modules commerce dans cette intégration documente absence de champ, null et effacement volontaire ; une table de mapping versionnée relie chaque conversion à « mouvement de stock ». À la lecture du runbook de modules commerce, l’administration des ventes met en regard le stock entre les deux systèmes puis date la décision associée à « identifiant de commande ».
Le contrat d’entrée conserve schemaVersion, correlationId et occurredAt. Le retry relit l’état courant, l’idempotence protège l’effet métier et la queue sépare indisponibilité, conflit et rejet permanent avant toute reprise.
Erreurs fréquentes qui fragilisent l’exploitation
Confondre succès technique et état final de l’article
Au moment du verdict sur expéditions, la logistique met en regard le tarif entre les deux systèmes et joint « mouvement de stock » au compte rendu de recette.
La réponse HTTP n’est donc qu’un accusé technique. La recette exige un état terminal de commande, une balance de stock cohérente et une preuve compréhensible par le support avant de valider le module.
Relancer le traitement après « un SKU change sans correspondance » sans lire l’état courant
Pour le point modules commerce, la finance qualifie le dernier écart sur le tarif puis rattache le verdict à « identifiant de commande ».
Sur le périmètre intégrations sur mesure, le support applicatif qualifie le dernier écart sur le stock avant de consigner la décision dans « code dépôt ».
Décision de sortie du pilote : actions à valider
Dans le cas expéditions, le support applicatif qualifie le dernier écart sur le stock à partir de « version tarifaire », sans retouche hors procédure.
Pour cette décision, le responsable référentiel qualifie le dernier écart sur la commande et conserve « code dépôt » comme preuve de sortie.
- À faire d’abord sur modules commerce : confier le stock à un référentiel, un responsable et une règle de conflit testable.
- À valider ensuite sur intégrations sur mesure : jouer « une expédition ne déclenche pas la facture », puis expliquer le verdict depuis « mouvement de stock ».
- À différer pour expéditions : les exceptions qui rendent la mesure « stocks divergents » illisible pour le support applicatif.
Pour reprendre le point intégrations sur mesure, la finance qualifie le dernier écart sur le client avant d’autoriser la reprise décrite dans « mouvement de stock ».
Plan d’action avant la bascule en production
Dans Medusa API, le lot commence par cette étape, sans encore étendre à ce cas métier, le dossier de périmètre identifie la facture, la source autoritative, le responsable, la sortie attendue et le justificatif lors de « un stock réservé est publié disponible ». Pendant le contrôle de expéditions, l’administration des ventes qualifie le dernier écart sur la facture puis transmet « mouvement de stock » au propriétaire du run.
Dans le dossier modules commerce, le support applicatif qualifie le dernier écart sur l’article jusqu’à ce que « mouvement de stock » explique le résultat observé.
Enfin, pour Medusa API, le comité étend le périmètre consacré à cette étape vers ce cas métier, sur un seul sujet à chaque étape, et garde la bascule réversible tant que « identifiant de commande » ne permet pas d’expliquer tous les écarts critiques. Sur le sujet expéditions, la finance qualifie le dernier écart sur la commande avec « code dépôt » comme point de retour vérifiable.
Définir la frontière de chaque module commerce
En réalité, la modularité n’autorise pas chaque composant à redéfinir la commande. Le catalogue décrit les variantes, le pricing décide un montant dans un contexte, l’inventory confirme une disponibilité et l’order conserve l’engagement accepté. Si un module ne peut pas fournir sa décision, alors le workflow attend dans un état explicite ; dans ce cas, le service appelant connaît le motif et l’owner. En revanche, un enrichissement sans effet sur le checkout peut être repris plus tard plutôt que de bloquer la vente.
Le contrat entre modules publie les entrées obligatoires, les sorties terminales et les erreurs reconnues. Une valeur absente conserve l’existant, un null suit une règle documentée et un effacement exige une intention distincte. Chaque évolution porte schemaVersion et une période de compatibilité ; les payloads historiques sont rejoués avant activation. Cette discipline évite qu’un nouveau champ de produit casse le calcul de prix ou qu’une extension transforme silencieusement une commande déjà enregistrée.
Les dépendances externes restent derrière des adaptateurs qui traduisent sans déplacer l’autorité. Le transporteur peut enrichir un colis, le PSP confirmer un paiement et l’ERP produire une facture, mais aucun ne modifie seul l’état global de la vente. Le mapping conserve source, version, date métier et corrélation. Si l’API fournisseur évolue, alors l’adaptateur revient à la version précédente et les messages attendent ; dans ce cas, le domaine Medusa continue d’exposer un état compréhensible.
Le coût caché d’une frontière floue apparaît dans les corrections croisées : le support change le stock, la finance recrée une facture et le commerce relance la commande, sans savoir quelle action a réellement réparé le dossier. La revue d’architecture refuse donc un module qui ne nomme pas son état de référence, ses effets irréversibles et son chemin de retour. Cette décision se vérifie par un scénario de panne, pas par la seule présence d’une interface TypeScript.
Orchestrer checkout, paiement et stock sans doublon
Le checkout produit une intention qui peut encore expirer, changer de livraison ou échouer au paiement. La commande n’est créée qu’après une décision explicite, avec le snapshot des lignes, du prix, des taxes et de la réservation. Si la réponse du PSP disparaît après l’effet, alors le workflow ne débite pas une seconde fois ; dans ce cas, il relit le paiement avec la référence fonctionnelle. En revanche, un événement analytique peut attendre sans ralentir la confirmation client.
Une clé d’idempotence associe checkout, opération et version de décision. Le webhook est acquitté rapidement, puis placé dans une queue dont chaque message conserve correlationId, occurredAt et tentative. La journalisation distingue réception, décision et effet appliqué ; le monitoring suit le seuil d’événements sans état terminal. Le retry utilise un backoff et relit l’état courant, tandis que le rollback ferme les nouvelles entrées sans effacer les preuves déjà confirmées.
La recette provoque trois ambiguïtés : réponse perdue après autorisation du paiement, réservation expirée avant création de commande et remboursement reçu avant la notification initiale. Chaque scénario doit aboutir à une seule commande, un seul effet financier et une balance de stock explicable. La finance retrouve l’écriture, la logistique le mouvement et le support le checkout depuis la même corrélation. Une différence reste en quarantaine avec son propriétaire, son ancienneté et sa prochaine action.
Les retours partiels imposent une règle supplémentaire. Le remboursement ne remet pas automatiquement l’article en vente : la logistique confirme d’abord le dépôt et l’état du produit. L’avoir conserve la répartition de taxe et de remise de la commande historique, plutôt que de recalculer avec le catalogue actuel. Le test ferme le dossier seulement quand quantités commandées, expédiées, retournées et facturées se rapprochent sans mutation directe en base.
Mettre l’intégration sur mesure sous contrat de run
Le plan de déploiement commence par un canal, un moyen de paiement et une famille de produits. Une balance quotidienne confronte checkouts acceptés, commandes créées, paiements, mouvements et expéditions. Elle mesure aussi l’ancienneté des écarts et le nombre de reprises humaines, car un bon débit peut cacher quelques dossiers critiques. Si le seuil convenu dérive, alors le dernier palier est retiré ; dans ce cas, le flux précédent ou le mode lecture seule reste disponible.
La sécurité est exercée avec la même exigence. Chaque adaptateur possède une identité dédiée, des scopes minimaux et une rotation indépendante. Les logs masquent tokens, données de paiement et informations client inutiles tout en conservant les identifiants de preuve. La recette révoque un secret pendant que des messages attendent : la nouvelle identité reprend la queue sans perdre la corrélation, l’ancienne est refusée et aucun opérateur n’élargit les droits pour contourner l’incident.
Le runbook commence par la commande, pas par une classe ou une table technique. Il indique comment retrouver le checkout, le paiement, la réservation et le dernier effet terminal ; il sépare action autorisée, escalade métier et opération interdite. Pendant la passation, un opérateur reçoit un dossier ambigu, relit les sources, remet uniquement l’étape manquante en file et vérifie la balance suivante. Les zones incompréhensibles corrigent la documentation avant l’ouverture.
La décision de sortie du pilote exige enfin une reprise reproductible après évolution de schéma, rotation de secret et redémarrage des workers. Le responsable métier valide le résultat, le support la procédure et l’équipe technique le monitoring. Tant qu’un de ces rôles dépend d’une correction improvisée ou qu’un rollback détruit la piste d’audit, le module reste borné. L’excellence du sur-mesure se mesure à cette autonomie, pas au nombre de personnalisations livrées.
Recetter des exemples qui contredisent le nominal
Exemple concret : le dernier article est réservé au moment où le paiement perd sa réponse. Le workflow relit l’autorisation, conserve une seule réservation et crée au plus une commande. Si le paiement reste indémontrable, alors le checkout demeure en attente avec une échéance et un owner ; il n’est ni annulé silencieusement ni débité une seconde fois.
Autre exemple concret : un retour partiel vise un dépôt différent de celui de l’expédition. La logistique confirme d’abord le lieu et l’état du produit, puis le module de stock applique le mouvement. La finance émet l’avoir depuis la commande historique, sans recalculer taxe ou remise avec les règles actuelles. La corrélation permet au support d’expliquer les deux effets.
Le dernier contre-test modifie une variante et un prix pendant qu’un canal est indisponible. Au rétablissement, l’adaptateur publie une version cohérente, pas un assemblage des derniers champs reçus. La balance compare catalogue attendu, offres visibles et commandes acceptées ; l’écart bloque le prochain palier jusqu’à décision du responsable référentiel.
La passation réunit enfin ces exemples dans un exercice chronométré. Un opérateur reçoit le paiement ambigu, le retour multi-dépôt et la variante en conflit sans connaître leur préparation. Il retrouve chaque corrélation, lit les états de référence, applique l’action autorisée puis contrôle la balance suivante. Le compte rendu mesure les données introuvables, les décisions non attribuées et les étapes qui exigent encore un développeur. Le pilote ne sort que lorsque le runbook permet de fermer les trois dossiers, après rotation de secret et redémarrage de la queue, sans perte de preuve ni mutation directe.
Guides complémentaires pour approfondir la conception
Pour auditer modules commerce et l’autorisation associée au SKU, confrontez le cas à architecture IAM et protection des flux. Quand l’écart observé est « un retour vise le mauvais dépôt », enchaînez avec REST, webhook et synchronisation afin de fermer idempotence et rejeu.
Les patterns applicables à intégrations sur mesure aident à raisonner mais ne remplacent pas les capacités publiées. La solution doit confirmer scopes, pagination, quotas et événements, puis rattacher « code dépôt » au SKU.
Conclusion : faire de l’intégration un service explicable
Sur intégrations sur mesure, le premier jalon consiste à attribuer la commande, jouer « une commande est créée deux fois », avant de transmettre la reprise à l’administration des ventes. Le volume vient après la démonstration.
Le critère final reste la capacité des équipes commerce, finance et support à retrouver le même checkout, la même commande et chaque effet associé depuis une preuve partagée, y compris après une panne ou une évolution de module.
Pour appliquer expéditions à un SI existant, notre accompagnement en intégration API peut cadrer le flux, le mapping, la reprise et l’observabilité avec vos équipes métier et support. Le cadrage reste rattaché à Medusa API.
