L’ERP annonce une commande MCF livrée, mais le support voit encore un colis en transit. Le connecteur reçoit pourtant les notifications Amazon et sa file ne contient aucune erreur. Le problème peut venir d’un contrat devenu trop simpliste : un statut de commande close est traduit en livraison, ou un nouveau message est accepté sans que les informations de colis soient réellement comprises.
En pratique, migrer les notifications MCF demande de séparer le transport du message, son schéma et sa signification métier. La réception d’un JSON valide ne prouve pas que la commande, l’expédition et le colis sont correctement rapprochés. Une intégration API conçue autour de vos flux métier doit conserver ces niveaux jusqu’aux écrans ERP et aux messages envoyés aux clients.
Les notes Amazon du 30 septembre 2026 annoncent un schéma de notification plus détaillé pour Fulfillment Outbound. Nous examinons la transition vers le contrat 2026-07-04, puis proposons une recette sur une commande fictive à deux colis. Aucun abonnement Amazon ni envoi réel n’est modifié ici ; les exemples servent à préparer la migration de votre connecteur.
Le livrable est une correspondance explicite entre événements, identités et états internes, accompagnée d’une procédure de bascule et de reprise. L’intégration Amazon FBA et MCF dans votre SI doit notamment répondre à une question simple : ce message décrit-il la clôture du traitement Amazon, le départ d’une expédition ou la remise d’un colis ?
Pour qui cette migration devient prioritaire
Les connecteurs qui lisent un statut unique
Ce dossier concerne les éditeurs de connecteurs, intégrateurs et DSI qui alimentent un ERP, un OMS ou un service client à partir de notifications MCF. Le point de vigilance est une ancienne règle qui réduit tous les événements à « en cours », « expédié » ou « livré ». Cette simplification peut devenir dangereuse lorsqu’un message contient une information plus précise que le modèle interne ne sait pas représenter.
Commencez par les décisions déclenchées : mise à jour d’écran, courriel, clôture de ticket, libération d’une attente ou rapprochement logistique. Une mauvaise traduction n’a pas le même effet si elle change seulement une ligne de monitoring ou si elle affirme au client que sa commande est arrivée. L’inventaire des consommateurs détermine les tests et l’ordre de migration.
Un sujet distinct du choix commercial MCF
Le choix de confier ses ventes hors Amazon à MCF exige une qualification de service, de pays et de coût. La migration étudiée ici intervient ensuite, lorsque le circuit doit conserver des informations fiables. Elle ne démontre pas qu’une application Shopify ou un parcours logistique particulier est disponible pour votre entreprise. Elle ne remplace pas non plus le contrôle des autorisations SP-API.
Le parcours officiel de notification décrit notamment l’autorisation du vendeur, le rôle Amazon Fulfillment et la destination SQS. Vérifiez ces prérequis dans le compte et la région concernés. Une réussite avec un compte de test ne prouve pas que tous les vendeurs gérés par votre application disposent du même périmètre.
Identifier les changements de contrat utiles
La documentation de migration Amazon maintient les versions 1.0 et 2026-07-04 au moment de cette vérification. Le nouveau contrat introduit un événement de statut colis, réorganise les objets et utilise un identifiant colis textuel. Le tableau ci-dessous retient les changements à examiner dans le parseur ; il ne remplace pas le schéma complet.
| Objet à traiter | Ancien contrat | Contrat 2026-07-04 |
|---|---|---|
| Enveloppe métier | Payload.FulfillmentOrderStatusNotification | Payload.order |
| Commande | SellerFulfillmentOrderId | order.orderId |
| Expédition | FulfillmentShipment | order.shipments[] |
| Identité du colis | PackageNumber, entier | packageId, chaîne |
| Date de l’événement | StatusUpdatedDateTime | EventTime, dans l’enveloppe |
Amazon précise qu’une seule expédition par commande est actuellement prise en charge malgré la forme en tableau de shipments[]. Il décrit aussi deliveryTime comme une estimation, et retire les retours de cette notification. Vérifiez ces limites avant d’étendre le traitement : une forme de données ne constitue pas une promesse de disponibilité fonctionnelle.
La conséquence pour le connecteur est de versionner le décodage. L’adaptateur sélectionne un parseur à partir de la version annoncée, produit un contrat interne commun et refuse les formes inconnues dans une file de diagnostic. Une succession de valeurs par défaut peut faire disparaître les symptômes tout en fabriquant un état faux. Un message incompris doit rester visible et reprenable.
Séparer commande close, expédition partie et colis livré
Trois objets, trois questions opérationnelles
La documentation du cycle des notifications distingue les états de commande, d’expédition et de colis. Elle décrit COMPLETE comme une commande close dont les quantités ont été expédiées ou annulées, tandis que DELIVERED concerne la livraison d’un colis. Les événements de commande ne contiennent pas les objets expédition et colis.
Dans votre modèle interne, conservez donc au moins le traitement de la commande et le suivi de livraison comme deux dimensions. L’ERP peut afficher « traitement logistique clos, livraison en cours ». Cette formulation évite qu’un statut unique force une conclusion trop large. Le support doit aussi voir quelles quantités ont été annulées ou restent à examiner avant d’interpréter une clôture partielle.
Éviter une traduction par ressemblance de mots
Ne mappez pas un mot comme « complete » vers « terminé pour le client » sans préciser l’objet concerné. Écrivez une table de traduction par version, type d’événement et statut. Pour chaque ligne, indiquez l’état interne modifié et les effets permis. Une mise à jour de commande ne doit pas écraser l’état connu d’un colis simplement parce qu’elle est arrivée plus tard.
Un statut inconnu ne devient pas « livré » ni « en cours » par défaut. Il conserve sa valeur brute et déclenche une qualification. Le système peut continuer à afficher les dernières informations établies, avec un avertissement d’actualisation incomplète. Cette sortie est préférable à une régression silencieuse qui rendrait l’écran rassurant mais incorrect.
Conserver les identités sans convertir le nouveau colis en entier
Une clé qui respecte le périmètre du vendeur
Dans le modèle proposé, une identité interne de suivi associe vendeur, commande, expédition et colis. Sa composition exacte dépend du contrat de vos systèmes ; elle doit être documentée. Un identifiant trouvé chez un vendeur ne suffit pas à rattacher un événement à la commande homonyme d’un autre. Les traitements multi-comptes doivent garder cette frontière lors de la collecte, du stockage et de la reprise.
Le nouveau packageId est une chaîne : conservez-la telle quelle. Un cast numérique peut supprimer un préfixe, des zéros significatifs ou échouer sur une valeur future. Ne déduisez pas non plus qu’une ancienne valeur entière et une nouvelle chaîne désignent nécessairement le même colis. La correspondance doit venir d’un rapprochement documenté avec les commandes et expéditions, pas d’une simple ressemblance.
Le numéro de suivi n’est pas la clé de tout le dossier
Un transporteur, un numéro de suivi et un identifiant colis répondent à des besoins différents. Le suivi peut être absent au début du parcours, et son format dépend du transporteur. Gardez l’identité logistique même lorsque le lien de tracking n’est pas encore disponible. L’arrivée du suivi enrichit le colis existant ; elle ne doit pas créer une seconde ligne sans rapprochement.
Pour les anciens flux, la référence getPackageTrackingDetails v2020-07-01 utilise un packageNumber issu de getFulfillmentOrder. Ne réutilisez pas ce contrat par habitude pour un identifiant de la nouvelle version. Qualifiez l’opération de consultation correspondant à la version cible et conservez cette dépendance dans la documentation du connecteur.
Cas concret : un colis livré et un colis retardé
Construire une population connue avant le calcul
La commande fictive MCF-84 comprend trois unités, préparées dans une seule expédition S-84 et deux colis. P-A contient deux unités et P-B une unité. Le registre de correspondance a été établi avant la réception des événements ci-dessous. Ces identifiants et horaires sont pédagogiques ; ils ne reproduisent pas une commande Amazon réelle ni un payload complet.
| Événement du scénario | Fait conservé | Conclusion permise |
|---|---|---|
| Commande COMPLETE | Traitement de la commande clos | Examiner quantités et colis ; aucune preuve globale de remise |
| P-A DELIVERED | Deux unités dans le colis indiqué livré | Livraison partielle suivie |
| P-B DELAYED | Une unité dans un colis retardé | Suivi client encore ouvert |
| P-B DELIVERED après rapprochement | Les deux colis attendus sont indiqués livrés | Clôture de livraison selon la politique métier |
Le compteur montre un colis sur deux livré, puis deux sur deux. Si l’on suit les unités rattachées, il indique d’abord deux unités sur trois. Ces fractions ne sont pas interchangeables : les tailles des colis diffèrent. Aucune des deux ne prouve à elle seule la conformité du contenu reçu ; elles décrivent le suivi de la population logistique connue.
Ce que l’ERP et le support doivent afficher
Le dossier client présente les deux colis, leurs quantités rattachées, le dernier fait connu et la source. Le message associé à P-A ne doit pas annoncer que toute la commande est livrée. Pour P-B, une estimation reste une estimation ; elle ne doit pas être transformée en preuve de remise par le seul passage de l’heure prévue.
Si la population des colis n’est pas encore établie, le système affiche une complétude inconnue. Il ne calcule pas une livraison totale sur le seul colis retrouvé. Cette règle complète la migration du schéma : comprendre chaque événement ne suffit pas lorsque le registre de rapprochement omet une partie de la commande. La recette doit donc contrôler aussi ce registre.
Traiter doublons et événements reçus dans le désordre
Le transport ne fournit pas une chronologie métier parfaite
Les files SQS standard peuvent livrer plusieurs fois un message et ne garantissent pas un ordre strict. AWS recommande une conception idempotente face aux répétitions. La recette du consommateur doit donc inclure répétition, retard et reprise après interruption.
Conservez séparément la date métier de l’événement, la date de publication disponible et la date de réception locale. Trier uniquement par arrivée peut faire revenir un colis livré à un état antérieur. Cependant, une comparaison de dates n’est pas toujours une résolution suffisante d’un conflit. En cas de faits incompatibles, appliquez une politique explicite de rapprochement avec la source, au lieu d’inventer un ordre certain.
Un second scénario : le message revient après l’envoi client
À 14 h, le système reçoit un événement indiquant P-A livré, met à jour le suivi et prépare un courriel. Il redémarre avant l’acquittement du message. À 14 h 02, le même événement revient. L’idempotence attendue conserve un seul fait métier et une seule intention d’envoi. Un journal qui empêche uniquement la double ligne de suivi peut encore laisser partir deux courriels.
La clé de traitement du message et la clé de l’effet externe doivent donc être définies chacune à leur niveau. Une intention d’envoi persistée peut être reprise sans recréer le message commercial. Si le résultat de l’envoi est inconnu, rapprochez-le selon les possibilités du prestataire. Ne revendiquez pas une garantie « exactement une fois » de bout en bout sur la seule présence d’un identifiant de notification.
Appliquer des mises à jour ciblées plutôt que remplacer tout l’objet
Une notification de commande sans colis ne signifie pas que les colis précédemment connus ont disparu. Le contrat interne doit distinguer absence de propriété, liste vide explicitement reçue et suppression établie. Remplacer l’agrégat ERP par chaque objet reçu peut effacer le tracking à l’arrivée d’un événement moins détaillé. Ce défaut est facile à manquer si la recette ne contient que des messages complets.
Pour chaque type, définissez les champs qu’il peut modifier et ceux qu’il laisse inchangés. Le parseur produit une observation typée ; le service de projection applique les règles. Cette séparation rend la migration plus lisible : un changement de nom de champ reste dans l’adaptateur, tandis que la décision d’annoncer une livraison reste dans une politique métier testée.
La journalisation conserve la version reçue, les identifiants utiles et le motif de toute mise à l’écart. Évitez d’exposer des payloads complets contenant des données personnelles dans des journaux largement accessibles. Le support a besoin d’une chronologie exploitable, pas nécessairement de toutes les données brutes. Les règles d’accès et de conservation doivent accompagner le stockage technique.
Réserver un budget aux lectures de rapprochement
Le middleware ne doit pas transformer chaque notification en plusieurs lectures immédiates de toute la commande. Regroupez les besoins de rapprochement par vendeur et commande, puis utilisez la version API qualifiée. Un polling complémentaire peut rechercher les dossiers restés incohérents ; il possède son propre budget et son suivi de fraîcheur. Si une opération renvoie plusieurs pages, conservez la pagination jusqu’à la fin avant de déclarer une population complète.
Le SDK choisi doit exposer les opérations et modèles de la version cible ; sa présence ne valide pas votre traduction métier. Écrivez aussi la politique de timeout et de reprise : un délai de lecture dépassé ne modifie pas l’état logistique connu. Un backoff borné évite une rafale de nouvelles lectures lors d’un incident. Les paramètres seront fixés d’après les limites de chaque opération et les engagements du service, puis éprouvés avec une réponse lente et une indisponibilité simulées.
Préparer la bascule sans doubler les effets
Comparer les projections hors du circuit d’action
Déployez d’abord le nouveau parseur avec un corpus de messages représentatifs et des résultats attendus. Une lecture parallèle interne peut produire une projection de comparaison sans déclencher de courriel, d’écriture ERP ou d’action SAV. Le but est d’observer les écarts avant de donner autorité au nouveau traitement. Cette comparaison ne nécessite pas de supposer deux abonnements Amazon simultanés.
Relevez ensuite l’abonnement réellement actif, sa version et sa destination avec les opérations de gestion documentées. La procédure de changement dépend de l’état existant et des possibilités autorisées pour ce type de notification. Préparez un créneau, une responsabilité de bascule, une vérification de réception et un rapprochement des commandes pendant l’intervalle. Une instruction générique de création ne doit pas être exécutée aveuglément sur un abonnement déjà en service.
Prévoir un retour qui conserve les messages nouveaux
Le rollback doit expliquer ce qui arrive aux messages 2026-07-04 déjà reçus si l’ancienne application reprend. Un ancien parseur incapable de les comprendre ne constitue pas un retour sûr. Conservez une version applicative capable de lire les deux contrats ou une procédure de mise en attente et de reprise. Les messages archivés doivent garder leur version d’origine.
Le périmètre de retour comprend aussi les projections et effets déjà produits. Revenir au binaire précédent ne retire pas un courriel envoyé et ne recrée pas une donnée effacée. Le responsable d’exploitation doit pouvoir distinguer message reçu, projection appliquée, action préparée et effet confirmé. Ces étapes donnent une base au rapprochement après incident.
Recetter les frontières qui peuvent mentir à l’ERP
| Cas de recette | Preuve attendue | Blocage |
|---|---|---|
| Ancien et nouveau contrat | Parseur choisi par version, identités conservées | Valeur par défaut qui masque un champ absent |
| Commande COMPLETE, colis en transit | Clôture de traitement distincte de livraison | Courriel de livraison totale |
| Événement de commande sans colis | Tracking existant préservé | Effacement par remplacement global |
| Message répété | Une seule intention d’effet métier | Double message client |
| Événement ancien reçu tard | Historique conservé, conflit traité | Régression silencieuse du suivi |
| Identifiant colis textuel | Valeur exacte conservée | Conversion numérique ou collision |
| Version ou statut inconnu | Diagnostic et reprise attribués | Livraison inventée |
Cette matrice est une recette proposée. Elle doit être exécutée sur vos adaptateurs, votre stockage et vos consommateurs. Le tutoriel Amazon indique que les commandes sandbox n’émettent pas ces notifications ; les opérations sandbox simulent les transitions d’état. Une simulation de statut ne constitue donc pas une preuve de transport jusqu’à votre file réelle. Distinguez tests de parseur, tests d’intégration et réception contrôlée dans l’environnement autorisé.
Pour chaque test, conservez l’entrée, la sortie et les effets interdits observés comme absents. Le seuil d’ouverture est strict sur les cas critiques : aucune confusion de vendeur, aucun effacement de colis connu, aucun message client injustifié. Le volume de messages traités sans exception technique ne compense pas un échec sur ces décisions métier.
Erreurs fréquentes dans une migration de notifications
La première erreur consiste à modifier seulement la version d’abonnement. Le JSON peut continuer à être accepté par un décodeur permissif, tandis que les champs utiles deviennent vides. Rendez les propriétés indispensables explicites et contrôlez la projection obtenue. Une courbe de réception stable n’est pas une preuve que les colis sont encore rattachés aux commandes.
La deuxième est de comparer les versions uniquement sur le nombre d’événements. Une granularité supplémentaire peut produire davantage de messages pour un même parcours. Comparez les faits reconstruits et les effets autorisés, pas une égalité artificielle des compteurs. Une différence doit être expliquée par le type d’événement, la période et la population de commandes concernées.
La troisième est de transformer l’estimation de livraison en échéance certaine. Paradoxalement, disposer d’une date plus tôt peut dégrader le service si l’interface la présente comme une promesse confirmée. Nommez la donnée, sa source et son actualisation. Le message client doit conserver la distinction entre prévision, état transporteur et action de votre propre service.
Plan d’action : passer du parseur à une reprise exploitable
Établir le contrat et la responsabilité de chaque effet
Recensez les abonnements et consommateurs du flux, puis attribuez un propriétaire à chaque décision. En entrée, le contrat garde version, vendeur, commande, objet concerné et horodatage ; en sortie, il produit une observation typée ou une mise en attente motivée. La responsabilité de la traduction logistique revient au métier avec l’intégrateur, tandis que l’exploitation possède la procédure de reprise.
Constituez un corpus autorisé, anonymisé lorsque nécessaire, et ajoutez les cas synthétiques de rupture. La recette vérifie les identités, les états et la conservation des données absentes d’un événement partiel. Le monitoring mesure les rejets par version, les dossiers non rapprochés et l’âge de la file de reprise. Le repli suspend les effets incertains tout en conservant les messages pour diagnostic.
Ouvrir progressivement et rapprocher les résultats
Activez la nouvelle projection sur un périmètre maîtrisé après validation des cas critiques. Comparez les commandes, les colis attendus et les états présentés à l’ERP. Le responsable métier contrôle quelques parcours complets, y compris un retard et une annulation, plutôt qu’un échantillon composé seulement de livraisons simples. Les écarts reçoivent un motif, un responsable et une prochaine action.
Élargissez lorsque les divergences sont comprises et que la procédure de retour a été répétée sur l’environnement de recette. Conservez la version du schéma et de l’adaptateur avec les preuves. Les changements futurs de contrat doivent déclencher une revue des hypothèses, particulièrement l’identité des colis, la cardinalité des expéditions et les types d’événements. Cette surveillance appartient à l’exploitation du connecteur.
Le budget inclut développement, essais, observation de bascule et traitement des dossiers ambigus. Fixez une durée maximale d’attente avant escalade selon vos engagements de service ; n’appliquez pas une valeur universelle copiée d’un exemple. Une intégration réussie permet au support de comprendre ce qui manque, et à l’équipe technique de reprendre sans rejouer indistinctement tous les effets.
- À faire : décoder par version, conserver les identités et séparer traitement de commande, expédition et livraison.
- À différer : activer les messages client tant que les projections et les reprises n’ont pas été recettées sur les cas critiques.
- À refuser : traduire un statut inconnu en réussite, convertir arbitrairement les identifiants colis ou présenter une estimation comme une remise confirmée.
Prolonger la migration vers le contrat d’exploitation
Le panorama des API Amazon FBA, stocks et MCF replace ces notifications dans les autres interfaces. Le dossier sur le contrat d’un connecteur ERP approfondit mapping, responsabilités et reprise au-delà du seul suivi colis.
Pour harmoniser plusieurs transporteurs, consultez la normalisation des statuts de tracking. Si le cockpit annonce une livraison sans population de colis retrouvable, le diagnostic des commandes clôturées sur une liste vide aide à examiner la règle de consolidation plutôt que le transport du message.
Recevoir un nouveau suivi pour un colis déjà connu
La migration du schéma et la correction d’une référence transport sont deux évolutions distinctes. Le changement annoncé par Amazon pour le 26 octobre 2026 étend le déclenchement de l’événement Shipment du flux version 1.0 aux remplacements de tracking. Le diagnostic d’un nouveau suivi MCF qui recrée une expédition examine les consommateurs qui ignorent la seconde valeur ou la prennent pour un nouveau départ.
Sa recette conserve deux colis tout en corrigeant le couple transporteur et numéro de l’un d’eux. Elle traite aussi une réponse de rapprochement dépassée et une intention de correction devenue obsolète. Ces contrôles complètent la validation du parseur : comprendre le message ne suffit pas si l’ERP, le portail client ou le worker d’envoi continue d’appliquer une règle conçue pour une seule réception.
Conclusion : conserver le sens derrière la nouvelle notification
La migration MCF ne se termine pas lorsque le nouveau JSON est accepté. Elle doit conserver l’objet concerné, son identité et ce que son état permet réellement d’affirmer. Une commande close, une expédition partie et un colis livré restent des faits différents, même lorsqu’ils traversent la même file.
Le contrat interne protège cette séparation. Il conserve les valeurs textuelles, traite les observations partielles et rend les formes inconnues visibles. Les scénarios de doublon et de réponse tardive montrent ensuite pourquoi la reprise doit inclure les effets client, au-delà de la seule mise à jour du suivi.
Les références officielles décrivent la version disponible et ses limites ; votre recette établit le comportement de l’intégration Amazon FBA et MCF réellement utilisée. Le passage en production exige les deux. Une documentation d’API ne certifie pas votre projection ERP, et un test synthétique ne prouve pas la réception d’une notification sur votre abonnement.
L’accompagnement en intégration API de Dawap relie contrats externes, règles métier et exploitation. Le résultat attendu est un flux dont les états restent compréhensibles pendant la migration, avec des colis retrouvables et une reprise qui n’invente ni livraison ni nouvel effet.
