Votre cliente renvoie une veste en taille M et demande la même en L. Shopify affiche l’échange, mais l’ERP attend une nouvelle commande qui n’arrive jamais. Ailleurs, l’entrepôt renvoie la taille M parce que le connecteur reprend la ligne d’origine. Le service client a accepté une opération commerciale précise ; les systèmes exécutent encore le parcours d’une vente ordinaire. Le risque est de renvoyer la mauvaise taille ou de doubler la préparation pendant une correction manuelle.
La difficulté tient aux identités et aux étapes : article retourné, variante de remplacement, traitement du retour, préparation sortante et solde financier. Un échange de même valeur peut demander une nouvelle expédition sans nouveau paiement. Un retour accepté peut aussi rester en transport, sans pièce disponible à remettre en vente. Un statut unique ne permet pas de décider correctement ces deux mouvements.
Vous allez organiser ce dossier entre Shopify, l’ERP et le WMS, puis examiner huit situations fictives : changement de taille à prix égal, complément de 15 euros, traitement partiel, variante inconnue, paiement ambigu et retour en quarantaine. Le corrigé vérifie des décisions locales ; il aide à préparer la recette de votre connecteur sans présenter un test hors ligne comme une expédition réellement exécutée.
Dawap accompagne les projets d’intégration API et les connexions Shopify avec votre système d’information. Le périmètre se qualifie avec vos équipes commerce, logistique et gestion, ainsi qu’avec l’installateur de votre ERP lorsque ses documents ou ses interfaces doivent évoluer.
Dans quels cas examiner le flux des échanges Shopify
Ce parcours concerne une boutique qui utilise les échanges natifs Shopify et transmet ses opérations à un système de gestion ou de préparation externe. Une application de retours peut appliquer une autre convention, notamment créer une commande de remplacement. Il faut identifier le mécanisme réellement installé avant d’interpréter une absence de nouvelle commande comme un incident.
Reconstituer la promesse faite à la cliente
Choisissez un dossier déjà repris par le support. Retrouvez la commande, le retour, la taille reçue et la taille promise. Demandez ensuite quelle action manque : admission du retour, préparation du remplacement, paiement complémentaire ou remise en stock. Cette question évite de lancer un remboursement pour résoudre une simple absence d’instruction logistique.
Le signal faible est une opération qui semble terminée sur un écran alors qu’un autre service attend toujours sa référence. Une cliente peut recevoir la confirmation d’échange tandis que le WMS ne connaît que l’ancien colis. Mesurez ces dossiers à partir de la variante attendue et de l’instruction acceptée, plutôt qu’à partir du seul nombre de commandes importées.
Distinguer échange natif et commande de remplacement
La documentation Shopify consacrée aux échanges dans les intégrations précise que l’échange natif modifie la commande existante. Il relie retour, lignes d’échange et nouvelle préparation. La conséquence pour votre connecteur est concrète : surveiller seulement la création de commandes laisse ce parcours sans sortie.
Votre ERP peut néanmoins demander un document supplémentaire pour préparer la nouvelle taille. Ce choix appartient à son fonctionnement, pas à une prétendue nouvelle commande Shopify. Conservez le lien entre document de gestion, commande d’origine et échange. Le dossier peut alors expliquer pourquoi une deuxième préparation existe sans présenter la cliente comme ayant passé une deuxième vente indépendante.
Relier commande, retour et variante de remplacement
La même veste en deux tailles représente deux variantes qui ne doivent pas partager leur instruction de stock. Les références commerciales visibles aident le support ; les identifiants des lignes et des variantes servent au mapping. Le connecteur conserve les deux afin de retrouver le dossier sans dépendre d’un libellé susceptible de changer.
Garder les lignes entrantes et sortantes séparées
La référence de l’objet Return expose la commande liée, les lignes retournées et les lignes d’échange. Ces ensembles ne décrivent pas le même déplacement. Dans votre modèle métier, une unité M reçue n’autorise donc pas à décrémenter M pour expédier la taille L.
Le dossier de rapprochement associe boutique, commande, retour, ligne d’échange, variante et instruction de préparation. La référence d’un événement reçu ne remplace aucun de ces objets. Cette filiation doit rester disponible dans l’ERP ou dans le middleware, même si l’écran client affiche simplement « échange de taille ».
Refuser le remplacement fondé seulement sur le titre produit
La documentation ExchangeLineItem fournit notamment l’identifiant de variante, son SKU et les lignes de commande associées. Plusieurs champs produit restent nullables. Le connecteur doit donc traiter une variante indisponible ou non reconnue comme un manque à qualifier, sans inventer une correspondance depuis le titre.
Dans le cas concret E du corrigé, V-UNKNOWN n’existe pas dans la table de correspondance. Aucune instruction sortante n’est préparée. Le catalogue ou l’équipe intégration doit résoudre le mapping, puis relire le dossier. Substituer automatiquement le SKU vendu à l’origine ferait disparaître l’erreur technique au prix d’un nouveau colis incorrect.
Transmettre les quantités traitées plutôt que toute la demande
Un échange peut être demandé pour deux articles alors qu’une seule ligne est prête à partir. Il faut montrer cette différence au support et à l’entrepôt. La quantité commerciale initiale, la quantité traitée et celle affectée à une préparation constituent trois informations à rapprocher avant d’envoyer une instruction.
Une ligne d’échange créée ne signifie pas un départ autorisé
ExchangeLineItem distingue des quantités traitées, non traitées et traitables. Ces champs décrivent l’avancement de la ligne ; ils ne prouvent pas son expédition. Le programme local reçoit ces valeurs déjà normalisées, puis les compare à la quantité de préparation retenue. Il ne fabrique pas une mission WMS depuis la seule quantité demandée.
Dans A, une unité est demandée, aucune n’est traitée et aucune préparation n’est fournie. Le résultat local reste à zéro instruction. Dans D, deux unités sont demandées et une seule est traitée ; la préparation fournie porte cette unité. Le résultat demeure une unité sortante, avec une attente visible pour la suite.
Respecter les fractions sans effacer l’attente restante
Une première prise en charge peut débloquer une taille pendant que l’autre attend un contrôle ou une disponibilité. La fiche métier doit afficher le réalisé et le reste attendu pour chaque ligne. Un compteur global « retour traité » risque de donner au support une réponse trop large alors que la deuxième unité n’a pas encore été prise en charge.
La reprise doit retrouver les fractions déjà transmises. Relire le dossier D conserve une instruction d’une unité dans le témoin local. En production, l’évolution d’une instruction déjà acceptée exige le contrat du WMS : ajustement, nouvelle fraction ou refus de modification. Ajouter la nouvelle quantité à chaque lecture ne constitue pas une stratégie de mise à jour.
Retrouver la bonne préparation dans la commande d’origine
Une commande ayant déjà été livrée possède des références logistiques historiques. L’échange ajoute un besoin sortant, sans rendre l’ancien colis prêt à repartir. Le middleware doit sélectionner les lignes concernées, l’affectation actuelle et les éventuelles retenues, puis transmettre une instruction dont l’origine reste recherchable.
Le traitement du retour peut créer le besoin sortant
La mutation officielle returnProcess confirme des quantités de retour et d’échange, traite les dispositions et crée des préparations pour les échanges. Son contrat inclut aussi des erreurs métier. Une réponse technique reçue doit donc être examinée avant d’annoncer qu’un traitement demandé a produit ses effets.
Pour une intégration de lecture, documentez séparément comment ce résultat devient observable dans la boutique. Un webhook peut réveiller un worker chargé de relire les objets utiles. Le contrat du handler précise ses entrées, notamment le retour et les lignes relues, puis sa sortie vers la file de préparation. Le webhook déclenche ce contrôle ; le handler n’envoie pas au WMS une copie du message avec le statut « préparé » ajouté par convention.
Le routage et les retenues comptent autant que la quantité
La documentation Shopify recommande de contrôler les préparations et leurs retenues. Une nouvelle ligne ne doit pas être confondue avec une ancienne mission clôturée. Définissez dans le contrat d’adaptation les champs qui relient variante, ligne, emplacement et préparation sélectionnée ; une correspondance incertaine reste une anomalie visible.
Le corrigé reçoit explicitement FO-NEW et son état courant. Il ne recherche pas ces références dans une vraie boutique. Cette limite est utile pour la recette : l’adaptateur doit d’abord prouver qu’il fournit la bonne préparation. La projection locale peut ensuite vérifier sa décision, mais ne compense pas une sélection erronée en amont.
Séparer valeur échangée, paiement et droit de préparer
Une différence de prix demande une décision financière ; une nouvelle taille demande une décision logistique. Ces décisions peuvent avancer à des moments différents. Le support doit savoir si le dossier attend une somme, une libération de préparation ou une preuve de réception, sans confondre ces attentes.
Un échange à valeur égale peut partir sans nouveau paiement
La documentation d’intégration Shopify indique qu’un échange de même valeur, taxes comprises, ne produit pas de transaction financière supplémentaire. La vente initiale couvre les nouveaux articles. Elle signale aussi que les paiements d’échanges en ligne ne sont pas encore directement associés au retour, contrairement aux remboursements de ce parcours.
Cette différence invalide un contrôle qui exige systématiquement une nouvelle capture sur chaque échange. Le cas B compare deux valeurs fournies de 40 euros et obtient un solde nul. Une préparation ouverte et correctement mappée produit une instruction locale d’une unité. Le modèle ne crée ni paiement supplémentaire ni remboursement compensatoire pour expliquer ce départ.
Un complément calculé n’est pas un complément encaissé
Dans C, les montants fictifs retenus sont 40 euros pour l’article repris et 55 pour le remplacement, soit 15 euros à collecter. La préparation fournie est ON_HOLD. Le modèle conserve le solde et ne prépare aucun départ. Son témoin positif fournit ensuite l’état OPEN : une instruction est créée pour la nouvelle taille.
Le contrôle utilise l’état fourni, sans déduire sa libération d’une addition ou d’un message du service client. Les choix commerciaux de départ avant paiement et les permissions correspondantes se qualifient dans votre configuration. L’interface de suivi doit pouvoir expliquer cette décision ; elle ne transforme pas automatiquement le complément attendu en paiement accepté.
Ne pas rapprocher deux paiements possibles par commodité
La finance doit retrouver l’effet de l’échange dans les pièces de gestion et les mouvements de paiement. Un montant identique peut apparaître plusieurs fois dans une commande ou dans une période. La proximité temporelle constitue un indice, sans suffire à prouver une association lorsque plusieurs opérations restent plausibles.
Conserver le résultat commercial et sa preuve de règlement
La documentation Return fournit des transactions et un résultat financier suggéré. Le premier ensemble et le second n’ont pas la même fonction : une suggestion aide à préparer une opération, tandis que les mouvements documentent son traitement. Votre adaptateur conserve les références et le périmètre de lecture avant de préparer la sortie attendue par la gestion.
La facture initiale, un éventuel avoir et le document de remplacement dépendent de votre processus ERP validé. Le dossier Shopify et ERP : boutique, gestion et finance traite cette répartition. Le présent parcours ne fixe pas une écriture comptable universelle pour toutes les situations d’échange.
Garder un rapprochement ambigu à l’écart de l’export financier
Dans le scénario F, deux candidats fictifs portent chacun 15 euros et restent plausibles selon les données fournies. Le sélecteur ne choisit aucun identifiant. Lorsque le témoin ne contient plus qu’un candidat qualifié, il retourne cette référence. Ce résultat démontre une décision locale de mise en attente, sans certifier une méthode d’association sur les API réelles.
Pour le flux de production, convenez des preuves permettant de départager les candidats : références disponibles, historique commercial, chronologie documentée et validation du responsable financier en cas de doute. Le dossier des paiements Shopify, Stripe et PayPal complète ce rapprochement. Une exception peut rester ouverte sans bloquer artificiellement toutes les autres lignes de la boutique.
Remettre la taille retournée en stock après sa propre décision
Le retour de M et le départ de L affectent deux références. Un échange commercial accepté ne dit pas si M est revenu, si son état permet la revente ni dans quel emplacement il se trouve. La synchronisation doit préserver ces informations afin qu’une promesse de disponibilité ne repose pas sur un colis encore en route.
Recevoir une unité ne la rend pas automatiquement disponible
Le parcours Shopify de traitement des retours et échanges distingue réception, traitement et choix de remise en stock à un emplacement. Il permet aussi de traiter une partie du retour. Votre politique d’entrepôt doit préciser comment ces choix rejoignent l’ERP et quelle équipe confirme l’état physique.
Dans G, une pièce M est déclarée reçue et placée en quarantaine dans les données fictives. Sa disponibilité reste nulle, tandis que l’instruction de remplacement concerne L. Le témoin suivant fournit une décision de remise en stock : la disponibilité de M passe à une unité. Le programme n’a inspecté aucune veste ; il a appliqué les entrées déclarées.
Éviter que l’échange augmente le stock de la mauvaise variante
Lorsqu’une intégration utilise seulement le produit parent, les tailles risquent de se compenser dans un total apparemment stable. Le stock global d’une veste peut sembler correct, avec pourtant une unité M de trop et une unité L de moins. Contrôlez les références de variante sur chacun des mouvements avant de comparer le total.
Attribuez le responsable de réception, celui de disposition et celui de disponibilité commerciale. Les trois rôles peuvent appartenir à la même équipe, mais leurs preuves restent distinctes. Un retour bloqué par son inspection ne justifie pas une correction arbitraire de stock dans Shopify pour faire disparaître l’écart de l’ERP.
Exercice corrigé : matrice des échanges et du stock
Le jeu hors ligne emploie la boutique S1, la commande O1, le retour R1, la ligne E1 et la préparation FO-NEW. La variante V-L correspond à SKU-L ; l’article repris correspond à SKU-M. Chaque groupe démarre dans une base de démonstration indépendante, sauf les relectures et témoins positifs explicitement reliés.
Choisir l’action avant de consulter la réponse
Pour A à H, indiquez la quantité sortante autorisée par les entrées, l’éventuel motif d’attente et la disponibilité du retour. Les montants servent seulement aux comparaisons déclarées en EUR : 40 contre 40 dans B et 40 contre 55 dans C. Les valeurs sont fournies sur la même base, taxes comprises, sans frais supplémentaires dans ces deux dossiers fictifs. D porte sur les quantités d’une fraction et ne certifie pas le bilan financier complet d’un échange à deux unités.
Le programme contrôle séparément projection logistique, disponibilité retournée et sélection d’un candidat financier. Il n’appelle ni Shopify ni un WMS. Sa clé locale d’instruction comprend boutique, commande, retour, échange et préparation. Cette unicité explique le rejeu du témoin, sans garantir qu’un destinataire réel acceptera une seule livraison du même effet.
| Cas | Dossier fictif | Résultat local | Suite à donner |
|---|---|---|---|
| A | Une unité demandée, zéro traitée, sans préparation | Zéro instruction sortante | Attendre le traitement et sa préparation |
| B | M remplacé par L, 40 euros contre 40, préparation ouverte | Une unité L ; solde nul | Transmettre le remplacement sans inventer un paiement |
| C | 40 euros repris, 55 pour L, préparation retenue | 15 euros attendus ; zéro départ préparé | Retrouver la décision de libération |
| D | Deux unités demandées, une traitée et affectée | Une unité sortante ; relecture inchangée | Garder la fraction restante visible |
| E | Variante V-UNKNOWN sans correspondance ERP | Mapping refusé ; zéro instruction | Qualifier la variante sans reprendre l’ancien SKU |
| F | Deux candidats plausibles de 15 euros | Association ambiguë ; aucune référence choisie | Obtenir une preuve financière discriminante |
| G | M reçu en quarantaine, L prêt à partir | M disponible à zéro ; une instruction pour L | Décider séparément la disposition de M |
| H | Lecture déclarée incomplète | Refus avant projection ; aucune instruction | Compléter le périmètre de lecture |
Lire les témoins positifs et les limites du résultat
Les huit groupes ont été exécutés en Python. La relecture de B conserve une seule instruction. C obtient une unité sortante après réception d’une préparation ouverte. F sélectionne T1 quand les entrées ne proposent plus qu’un candidat qualifié. G rend une unité M disponible après la décision fournie de remise en stock, sans changer l’instruction pour L.
Ces contrôles ne valident ni une inspection physique, ni une capture de paiement, ni un appel GraphQL, ni une livraison concurrente vers l’ERP. Les identifiants, valeurs, états et correspondances sont fabriqués. Une recette connectée doit prouver l’adaptateur, les droits de l’application, les effets destinataires et leurs confirmations avant que cette logique puisse commander une expédition réelle.
Reprendre un dossier sans produire une deuxième mission
La correction du connecteur doit couvrir l’arrivée tardive d’une information et la perte d’une réponse destinataire. Un dossier relu peut être mieux renseigné tout en portant le même effet sortant. L’observation nouvelle et la nouvelle instruction ne doivent donc pas être déduites du seul nombre de messages reçus.
La notification réveille une lecture qualifiée
Documentez les événements retenus, le schéma du payload et l’objet relu pour chaque transition. L’endpoint GraphQL Admin, sa version, les scopes et l’authentification autorisée appartiennent à cette recette. Les pages API consultées le 11 octobre 2026 redirigent vers latest avec la version 2026-10 affichée ; les champs doivent être confirmés pour la version réellement appelée.
Le worker conserve l’événement, lance la lecture et vérifie les erreurs ainsi que la pagination. Dans H, une lecture incomplète n’entre pas dans la projection locale. En production, les connexions de retours, de lignes et de préparations peuvent demander des lectures distinctes : finir une seule page ne prouve pas la complétude du dossier annoncé.
Une réponse WMS perdue exige une recherche de l’effet
Le rejeu local réussit parce que la clé d’instruction retrouve son entrée existante. Pour le WMS ou l’ERP, définissez la référence externe, la recherche d’une mission déjà acceptée et la politique d’idempotence disponible. Un timeout après acceptation ne doit pas déclencher automatiquement une autre préparation de la taille L.
Le retry et son backoff traitent les tentatives techniques, sans résoudre à eux seuls une incertitude métier. Le runbook distingue lecture Shopify à refaire, mapping à compléter, retenue à examiner et effet destinataire à rechercher. Le dossier des webhooks reçus dans le désordre approfondit cette reprise lorsqu’une observation ancienne revient après un traitement plus récent.
Plan d’action : qualifier un échange avant d’étendre le flux
Commencez par un échange de même valeur avec deux tailles réellement distinctes. Faites parcourir au dossier la boutique, le middleware, la gestion et l’entrepôt. Le livrable attendu est une filiation lisible jusqu’à l’instruction acceptée, avec le statut physique de l’article repris affiché séparément du départ de son remplacement.
Fixez ensuite les responsabilités : commerce pour la promesse, finance pour le solde et les documents, logistique pour réception et disposition, intégration pour mapping et reprise. Validez avec l’installateur ERP les interfaces disponibles : API native, module partenaire ou middleware. Une référence documentée côté Shopify ne prouve pas qu’un connecteur installé sait déjà la traiter.
La mise en œuvre passe par un mapping versionné et des cas de recette qui reprennent A à H. La QA contrôle les quantités et références, la CI exerce les refus et les témoins positifs. Comparez d’abord les résultats aux dossiers existants sans envoyer les missions supplémentaires ; une migration doit également identifier les anciens échanges déjà transmis manuellement.
Priorisez les écarts selon l’action exposée : mauvaise variante prête à partir, double instruction possible, stock repris trop tôt, puis dossier incomplet sans effet sortant. La décision urgente peut être de retenir une mission particulière, pas de couper toute la boutique. Chaque attente reçoit un responsable et une preuve attendue, afin que le support sache expliquer la prochaine étape.
Mesurer le coût des recherches avant de calculer un gain
Une hypothèse illustrative comprend cinq tickets de mapping à 14 minutes, quatre recherches de paiement à 21 minutes et trois vérifications de stock à 12 minutes. Le total atteint 70 + 84 + 36 = 190 minutes, soit 3 h 10. Il s’agit d’une base fictive exécutée dans le témoin, sans mesure de temps d’un client Dawap.
Sur votre activité, relevez ces durées par motif et le nombre d’échanges concernés. Le gain ne se déduit pas de la seule vitesse de l’API : il dépend des recherches réellement supprimées, des dossiers encore ambigus et des colis incorrects évités. Une correction qui accélère le flux tout en laissant les variantes mal mappées peut augmenter son coût opérationnel.
Définir les critères de passage et la surveillance après livraison
- Retrouver le SKU retourné et celui du remplacement dans leurs références respectives.
- Refuser une seconde mission lorsque le destinataire confirme la première au rejeu.
- Conserver la fraction restante après une préparation partielle.
- Bloquer la disponibilité du retour tant que sa disposition reste en quarantaine.
Après livraison, suivez les échanges sans instruction, les variantes inconnues, les reprises à effet incertain et les retours disponibles malgré une disposition bloquante. Définissez un délai d’escalade adapté à vos promesses logistiques ; aucun seuil universel n’est imposé ici. Un contrôle de cohérence régulier complète les alertes techniques et donne au responsable une liste de dossiers actionnables.
Erreurs fréquentes : faire disparaître l’écart au mauvais endroit
Créer une vente indépendante pour satisfaire l’import
Dupliquer une commande parce que le connecteur n’a pas vu l’échange peut produire une seconde demande de paiement ou une mission concurrente de celle déjà préparée à la main. Si l’ERP exige un document de remplacement, sa création doit suivre une règle explicite et garder l’origine. L’absence de nouvelle commande Shopify n’est pas une autorisation de dupliquer la vente.
Avant toute réparation historique, retrouvez les instructions déjà acceptées, y compris celles transmises par le support. La correction du mapping futur ne retire pas les colis déjà partis. La reprise doit rapprocher ces effets et désigner les opérations à traiter selon votre système de gestion, avec une décision conservée pour chaque dossier.
Forcer un remboursement ou un stock pour obtenir un statut vert
Un échange à prix égal ne devient pas plus explicable si l’on crée un remboursement puis une nouvelle vente pour satisfaire un indicateur. De même, rendre M disponible dès l’acceptation du retour peut afficher un stock cohérent tout en promettant une pièce absente. Corrigez le contrat de lecture et la séparation des mouvements avant de modifier les données métier.
Paradoxalement, un dossier partiellement ouvert peut être le résultat correct : remplacement prêt, retour en quarantaine, association financière encore à qualifier. L’écran doit montrer ces axes et leurs responsables. Fermer le dossier entier pour réduire la file de tickets retire précisément l’information dont l’équipe a besoin pour le terminer.
Conclusion : une nouvelle taille avec une origine conservée
Un échange Shopify doit conserver sa commande, distinguer les variantes et expliquer chaque préparation. La demande commerciale, le traitement, le solde et la disposition physique n’avancent pas nécessairement ensemble. Les rapprocher donne au support une réponse utilisable et à l’entrepôt une instruction précise.
Les huit situations montrent des décisions limitées mais vérifiables : une unité L pour l’échange à valeur égale, une attente sur le complément retenu, une seule fraction transmise, un mapping inconnu refusé et une taille M indisponible en quarantaine. La recette réelle doit retrouver ces décisions avec les preuves des interfaces effectivement installées.
Pour cadrer vos flux d’intégration API, réunissez un échange traité, sa préparation et les références présentes dans la gestion. Dawap peut qualifier le parcours, ses écarts et les règles de reprise avec vos équipes avant d’étendre l’automatisation à toutes les tailles et tous les entrepôts.
