Intégration de l’API Walmart WFS : appels et pièges
Cartographie de l’intégration de l’API Walmart WFS : articles, expéditions entrantes, commandes, stocks et pièges qui interrompent les synchronisations.
Long Nguyen
Développeur fullstack · Ingénieur IA · Chercheur
Quelles API composent réellement une intégration Walmart WFS ?
Il n’existe pas d’« API WFS » distincte avec son propre hôte, ses propres identifiants ou son propre SDK. Walmart Fulfillment Services est intégré à l’API Walmart Marketplace, à l’adresse marketplace.walmartapis.com : un groupe de points de terminaison exclusivement WFS sous /v3/fulfillment/, deux types de flux WFS et plusieurs changements de comportement dans des points de terminaison que vous appelez probablement déjà.
Cette distinction détermine votre architecture. WFS n’est pas un second connecteur à ajouter à côté de votre connecteur Marketplace : c’est un mode d’exécution qui modifie le comportement de votre connecteur existant pour chaque SKU et chaque commande.
| Opération | Point de terminaison / flux | Exclusif à WFS ? |
|---|---|---|
| Créer directement des articles comme WFS | POST /v3/feeds?feedType=MP_WFS_ITEM |
Point de terminaison partagé, type de flux WFS |
| Convertir des articles existants en WFS | POST /v3/feeds?feedType=OMNI_WFS |
Point de terminaison partagé, type de flux WFS |
| Envoyer des stocks vers un centre de traitement | /v3/fulfillment/inbound-shipments et points de terminaison associés |
Oui |
| Consulter le stock WFS disponible | Inventaire WFS (New), rapprochement, rapports de santé et journaux par article | Oui |
| Récupérer les commandes clients | GET /v3/orders avec shipNodeType |
Point de terminaison partagé, paramètres différents |
| Préparer des commandes non Walmart à partir du stock WFS | Points de terminaison Multichannel Solutions | Oui |
| Réserver le transport vers le centre de traitement | Walmart Preferred Carriers (new) / devis tarifaire transporteur (legacy) | Oui |
| Réapprovisionner, convertir et traiter les suggestions de publication | Points de terminaison Recommendations | Oui |
| Vérifier les blocages liés aux matières dangereuses | Hazmat Items On hold | Oui |
Si votre intégration utilise déjà Marketplace, environ 70 % d’un projet WFS correspondent à de nouveaux points de terminaison, et 30 % à l’audit du code déjà déployé pour repérer les situations où un SKU WFS se comporte différemment. C’est cette seconde partie qui fait tomber les intégrations.
Authentification et en-têtes requis pour chaque appel WFS
Chaque appel WFS repose sur le même flux OAuth avec identifiants client que le reste de l’API Marketplace. Vous échangez un Client ID et un Client Secret contre un jeton d’accès à durée limitée, puis vous envoyez ce jeton dans un en-tête : pas comme valeur bearer dans Authorization.
import base64, uuid, requests
BASE = "https://marketplace.walmartapis.com"
AUTH = base64.b64encode(f"{CLIENT_ID}:{CLIENT_SECRET}".encode()).decode()
def fetch_token():
r = requests.post(
f"{BASE}/v3/token",
headers={
"Authorization": f"Basic {AUTH}",
"WM_SVC.NAME": "Walmart Marketplace",
"WM_QOS.CORRELATION_ID": str(uuid.uuid4()),
"Accept": "application/json",
},
data={"grant_type": "client_credentials"},
timeout=30,
)
r.raise_for_status()
body = r.json()
return body["access_token"], int(body["expires_in"])
def wfs_headers(token):
return {
"WM_SEC.ACCESS_TOKEN": token,
"WM_SVC.NAME": "Walmart Marketplace",
"WM_QOS.CORRELATION_ID": str(uuid.uuid4()),
"Accept": "application/json",
"Content-Type": "application/json",
}
Trois points que les pages de référence précisent, mais que la plupart des intégrations gèrent encore mal :
- Mettez le jeton en cache en fonction de
expires_in, jamais avec une durée de vie codée en dur. Régénérer un jeton à chaque appel est le moyen le plus rapide d’être limité sur un traitement entrant à fort volume. WM_QOS.CORRELATION_IDdoit être un GUID différent à chaque appel, et vous devez le journaliser. C’est le seul identifiant que le support Walmart peut suivre lorsqu’une commande entrante échoue silencieusement ; un identifiant réutilisé ou absent transforme un ticket de 20 minutes en problème d’une semaine.- Les fournisseurs de solutions envoient également
WM_CONSUMER.CHANNEL.TYPE, fourni lors de l’intégration. Les vendeurs qui appellent l’API pour leur propre compte n’en ont pas besoin : c’est pourquoi le code d’exemple copié d’un fournisseur renvoie souvent une erreur 400 sur un compte vendeur direct.
Ajouter des articles au catalogue WFS : MP_WFS_ITEM ou OMNI_WFS ?
Une commande entrante ne peut référencer qu’un SKU déjà présent dans le catalogue WFS. Les erreurs documentées par Walmart pour les commandes entrantes incluent « SKU not in WFS catalog » — et il s’agit presque toujours d’un problème d’ordre des opérations, pas de données : l’équipe a lancé l’appel entrant avant la fin du traitement du flux d’articles.
MP_WFS_ITEM |
OMNI_WFS |
|
|---|---|---|
| À utiliser lorsque | Le SKU n’existe pas encore sur Walmart | Le SKU est déjà actif avec une exécution par le vendeur |
| Fonctionnement | Crée l’article avec la spécification d’article WFS | Convertit un article ingéré pour WFS |
| Appel | POST /v3/feeds?feedType=MP_WFS_ITEM |
POST /v3/feeds?feedType=OMNI_WFS |
| Spécification à récupérer en premier | Spécification d’article WFS via Get spec | Spécification de conversion WFS via Get spec |
Les deux opérations sont asynchrones. La réponse fournit un feedId, pas le résultat. Interrogez le point de terminaison d’état du flux jusqu’à ce que celui-ci quitte INPROGRESS, puis consultez les erreurs au niveau des articles : un flux peut signaler une réussite au niveau global alors que certains SKU échouent individuellement à la validation.
Le piège des dimensions
Les frais WFS dépendent du poids d’expédition et des dimensions, et le centre de traitement remesure vos cartons à leur réception. Si votre flux d’articles contient les dimensions du produit au lieu de celles de l’unité emballée et prête à expédier, toutes les estimations de frais produites ensuite par votre système seront fausses — et vous ne le découvrirez qu’en consultant un rapport de rapprochement plusieurs semaines plus tard. Normalisez les dimensions emballées au moment où votre PIM génère le flux, et non en aval.
Créer une expédition entrante avec l’API WFS, appel par appel
Voici le workflow WFS central : vous déclarez ce que vous prévoyez d’envoyer, Walmart vous indique où l’expédier, vous imprimez les étiquettes, vous remettez le colis au transporteur et vous transmettez le suivi.
| # | Appel | Fonction |
|---|---|---|
| 1 | POST /v3/fulfillment/inbound-preview |
Simulation — voir comment Walmart répartirait la commande avant de la confirmer |
| 2 | POST /v3/fulfillment/inbound-shipments |
Créer la commande entrante (IO) |
| 3 | GET /v3/fulfillment/inbound-shipment-errors |
Vérifier pourquoi une IO a été refusée |
| 4 | GET /v3/fulfillment/inbound-shipments |
Détails au niveau de l’expédition : centres de traitement concernés et nombre d’expéditions |
| 5 | GET /v3/fulfillment/inbound-shipment-items |
Détails par SKU et par expédition, avec le statut de réception |
| 6 | PUT /v3/fulfillment/shipment-quantities |
Corriger les quantités avant la livraison de l’expédition |
| 7 | POST /v3/fulfillment/shipment-label |
Générer l’étiquette de l’expédition entrante |
| 8 | POST /v3/fulfillment/shipment-tracking |
Transmettre le transporteur et les numéros de suivi |
| 9 | DELETE /v3/fulfillment/inbound-shipments/{inboundOrderId} |
Annuler l’intégralité de l’IO |
Consultez les pages des points de terminaison, pas la page récapitulative
La page récapitulative WFS de Walmart présente cette séquence avec des chemins abrégés tels que /v3/inbound-shipments et /v3/shipment-items, et indique GET pour deux opérations qui sont en réalité PUT et POST. Ce sont les pages de référence de chaque point de terminaison qui correspondent à la production : toutes les opérations entrantes se trouvent sous /v3/fulfillment/. Construisez votre intégration à partir des pages de référence de l’API de traitement Walmart et considérez la vue d’ensemble comme un schéma, pas comme un contrat.
Le même découpage dissimule une dépréciation active : l’appel d’étiquette à utiliser est POST /v3/fulfillment/shipment-label. L’ancien GET /v3/fulfillment/label/{shipmentId} est marqué comme obsolète, mais c’est encore celui qu’utilise la plupart des exemples de code disponibles en ligne.
Une commande entrante ne correspond pas à une seule expédition
C’est la principale erreur de modélisation des données dans les intégrations WFS. Lorsque vous créez une IO, Walmart décide si elle sera expédiée vers un seul centre de traitement ou répartie entre plusieurs — et la réponse vous indique lesquels. Votre schéma doit prévoir trois niveaux dès le départ :
- Commande entrante — ce que vous avez demandé à envoyer, et le seul niveau auquel l’annulation est possible
- Expédition — une par centre de traitement de destination, chacune avec sa propre étiquette, son propre transporteur et son propre suivi
- Article de l’expédition — la répartition au niveau du SKU, puis le rapprochement entre les quantités reçues et attendues
Les équipes qui modélisent une IO comme une liste plate de SKU avec un seul numéro de suivi doivent réécrire le module dès qu’une répartition entre plusieurs centres de traitement survient, ce qui arrive généralement dès la deuxième semaine de production.
L’annulation est plus limitée qu’on ne le pense
Vous ne pouvez annuler qu’au niveau de la commande entrante : annuler une IO annule toutes les expéditions qu’elle contient, et il est impossible d’annuler une seule expédition au sein d’une IO composée de plusieurs expéditions. L’annulation est également bloquée dès qu’une expédition atteint le statut Receiving in Progress, Closed ou Cancelled. Vérifiez son statut avec l’appel Get Shipments avant d’afficher un bouton d’annulation dans votre interface, sans quoi vos utilisateurs rencontreront des échecs que vous ne pourrez pas leur expliquer.
Récupérer les commandes WFS sans interrompre votre synchronisation
Voici le piège qui génère davantage de tickets « l’intégration WFS ne fonctionne pas » que tous les autres problèmes réunis : GET /v3/orders utilise par défaut shipNodeType=SellerFulfilled. Les commandes WFS n’apparaissent pas dans cette réponse. Pour les récupérer, vous devez les demander explicitement :
params = {
"shipNodeType": "WFSFulfilled", # default is SellerFulfilled
"createdStartDate": "2026-10-01",
"limit": "100",
}
r = requests.get(f"{BASE}/v3/orders", headers=wfs_headers(token), params=params)
Un vendeur convertit son catalogue en WFS, les ventes continuent, mais son ERP n’affiche aucune nouvelle commande. Rien n’est défaillant : la synchronisation les exclut par défaut. Le guide API WFS de Walmart le précise explicitement, et c’est toujours le premier point à vérifier lors d’un lancement WFS.
Deux conséquences pour votre pipeline de commandes :
- Exécutez les deux récupérations, pas une seule. Un vendeur mixte doit effectuer la récupération
SellerFulfilledet la récupérationWFSFulfilled, puis enregistrer les résultats dans la même table de commandes en stockant le canal d’exécution sur chaque ligne. - Ne confirmez, n’expédiez et n’annulez jamais une ligne de commande WFS. Walmart prend en charge la préparation, l’emballage, l’expédition et le suivi des commandes WFS. Si votre code appelle Acknowledge Orders ou Ship Order Lines sur une ligne WFS parce qu’il le fait habituellement pour les commandes Marketplace, il intervient dans un processus que vous ne contrôlez pas. Vérifiez le canal d’exécution avant toute opération d’écriture sur une commande.
Stock WFS : ce que l’API permet d’écrire — et ce qu’elle ne permet pas
Pour les SKU exécutés par le vendeur, vous maîtrisez la quantité et l’envoyez avec l’API Inventory. Pour les SKU WFS, vous ne maîtrisez rien. La quantité disponible correspond à ce qui se trouve physiquement dans les centres de traitement Walmart, et vous ne pouvez y accéder qu’en lecture.
| Opération | SKU exécuté par le vendeur | SKU WFS |
|---|---|---|
| Envoyer une quantité | Oui, avec Update inventory | Non — Walmart est la source de référence |
| Consulter la quantité | Inventory / multi-node inventory | WFS inventory (New) |
| Auditer les mouvements | Votre propre système | Inventory log for a WFS item |
| Rapprocher avec les prévisions | Votre propre système | WFS inventory reconciliation report |
| Repérer les problèmes d’ancienneté et de santé | Votre propre système | WFS inventory health report |
La règle de conception est simple : dans votre ERP, une quantité WFS est une copie mise en cache, jamais un champ modifiable. Tout chemin de code qui recalcule une quantité disponible à la vente et la renvoie doit être bloqué selon le canal d’exécution.
Utilisez le rapport de rapprochement et le journal d’inventaire par article comme deux outils complémentaires plutôt que comme de simples tableaux de bord. Le rapport de rapprochement vous indique qu’un écart existe ; le journal de l’article précise quel mouvement l’a causé — c’est la preuve nécessaire pour ouvrir une réclamation concernant des unités reçues en quantité insuffisante ou endommagées. Récupérez les deux selon un calendrier défini et stockez-les : ce sont les seuls éléments d’audit fiables dont vous disposerez, et c’est précisément ce que la plupart des équipes découvrent trop tard dans leur projet d’intégration d’API marketplace.
Préparer des commandes hors Walmart à partir du stock WFS avec Multichannel Solutions
Multichannel Solutions (MCS) est la partie de l’offre WFS dont les vendeurs ignorent le plus souvent l’existence : elle permet de préparer des commandes passées sur votre propre boutique ou sur un autre canal à partir des stocks déjà présents dans les centres de traitement Walmart. Il s’agit d’un groupe de points de terminaison distinct, avec son propre appel d’intégration.
- Enregistrez d’abord le canal — Créez les informations du canal de vente MCS, puis consultez-les ou mettez-les à jour. Les commandes envoyées vers un canal non enregistré ne seront pas acheminées.
- Obtenez un devis avant de promettre une date — Fetch delivery promise details renvoie la date de livraison que vous pouvez afficher en toute sécurité lors du paiement sur votre boutique. Afficher une estimation puis laisser la commande d’exécution échouer ensuite est le meilleur moyen de créer une file de demandes au support.
- Créez, suivez et annulez — Create MCS customer order, Get MCS fulfillment orders status, Cancel MCS fulfillment order.
- Les retours doivent être intégrés dès le départ — Des points de terminaison distincts permettent de créer, consulter et annuler les commandes de retour client. Connectez-les en même temps que le flux aller : ajouter les retours après le déploiement coûte toujours plus cher.
Walmart publie également une spécification OpenAPI pour MCS. Il est donc préférable de générer la couche client plutôt que de l’écrire manuellement. Consacrez le temps gagné à la machine à états qui relie le statut de vos commandes au leur : c’est la partie qu’un générateur ne peut pas vous fournir.
Les points de terminaison WFS que la plupart des intégrations n’appellent jamais
Quatre points de terminaison ont été conçus spécialement pour réduire le coût d’exploitation de WFS. Ils sont pourtant souvent ignorés parce qu’ils sont classés dans Recommendations plutôt que dans Fulfillment :
- Get WFS Recommended Shipment Quantity — indique quoi placer dans la prochaine commande entrante. Intégrez cette donnée à votre tâche de réapprovisionnement au lieu d’utiliser un seuil de commande fixe.
- Restock Recommendations — indique quels SKU réapprovisionner en fonction du stock actuel et de la demande prévue.
- Fulfill with WFS Recommendations — indique quels SKU exécutés par le vendeur sont susceptibles d’obtenir de meilleurs résultats avec WFS. C’est le point de terminaison à présenter à un client qui cherche à déterminer quels articles convertir.
- Unpublished Recommendations — indique quels articles WFS sont actuellement non publiés et pourquoi. Un article WFS non publié génère des frais de stockage sans aucune vente : c’est donc le plus utile des quatre et celui qui mérite une alerte.
Une réserve concernant le transport : les devis Walmart Preferred Carrier pour les chargements complets ne sont pas disponibles via l’API. Un système qui suppose pouvoir chiffrer chaque expédition entrante automatiquement devra donc prévoir une étape dans Seller Center pour le FTL. Notez également que les points de terminaison de devis tarifaires transporteurs existent dans une ancienne version et une nouvelle : développez votre intégration avec le groupe Walmart Preferred Carriers.
Les pièges de l’intégration WFS qui font perdre le plus de temps
Voici une checklist avant mise en production, fondée sur les écarts entre la documentation et le comportement réel :
| Symptôme | Cause réelle |
|---|---|
| Aucune commande WFS dans la synchronisation | shipNodeType utilise par défaut SellerFulfilled |
| Commande entrante refusée : SKU absent du catalogue WFS | L’IO a été lancée avant la fin du traitement du flux d’articles |
| Erreur 404 sur les points de terminaison entrants | Chemins copiés depuis la page récapitulative sans le préfixe /v3/fulfillment/ |
| L’appel d’étiquette renvoie une dépréciation | Utilisation de GET /v3/fulfillment/label/{shipmentId} au lieu de POST /v3/fulfillment/shipment-label |
| Le bouton d’annulation échoue par intermittence | L’expédition est déjà à l’état Receiving in Progress, Closed ou Cancelled, ou l’utilisateur tente d’annuler une seule expédition au sein d’une IO |
| Les numéros de suivi s’écrasent mutuellement | L’IO a été modélisée comme une seule expédition, alors qu’une répartition entre plusieurs centres en a produit plusieurs |
| Les mises à jour de stock ne produisent aucun effet visible | Des écritures de quantité ont été tentées sur des SKU WFS |
| Les estimations de frais s’écartent des montants réels | Les dimensions du produit ont été envoyées au lieu des dimensions d’expédition du colis |
| Le support ne peut pas suivre l’échec | Aucun WM_QOS.CORRELATION_ID n’a été enregistré pour chaque appel |
La plupart de ces problèmes sont peu coûteux à prévenir, mais très coûteux à diagnostiquer en production, car l’échec se manifeste généralement par un silence plutôt que par une erreur. Mettez en place le journal des identifiants de corrélation et la distinction par canal d’exécution avant la première commande entrante, et non après le premier incident.
Si vous connectez WFS à une plateforme multicanale existante — ou si votre synchronisation de commandes ne voit plus discrètement la moitié de votre volume — vous pouvez nous indiquer ce que vous intégrez et demander un devis ciblé. Aucun compte requis et aucune obligation pour poser votre question.
FAQ
Questions fréquentes
Existe-t-il une API Walmart WFS distincte avec ses propres identifiants ?
Non. WFS fait partie de l’API Walmart Marketplace à l’adresse marketplace.walmartapis.com et utilise le même Client ID, le même Client Secret et le même flux de jeton. Les éléments spécifiques à WFS sont un groupe de points de terminaison sous /v3/fulfillment/, deux types de flux (MP_WFS_ITEM et OMNI_WFS), les points de terminaison d’inventaire et de rapports WFS, Multichannel Solutions, Walmart Preferred Carriers et les points de terminaison de recommandations WFS.
Pourquoi mes commandes WFS n’apparaissent-elles pas dans GET /v3/orders ?
Parce que le point de terminaison utilise par défaut shipNodeType=SellerFulfilled. Transmettez shipNodeType=WFSFulfilled pour récupérer les commandes WFS. Un vendeur mixte doit effectuer les deux récupérations et enregistrer le canal d’exécution sur chaque ligne de commande.
Puis-je mettre à jour les quantités de stock des articles WFS via l’API ?
Non. Walmart maîtrise les quantités des SKU WFS, car les unités se trouvent physiquement dans ses centres de traitement. Vous consultez le stock WFS avec le point de terminaison d’inventaire WFS et vous l’auditez avec le rapport de rapprochement d’inventaire, le rapport de santé de l’inventaire et le journal d’inventaire par article. Traitez la quantité WFS comme une donnée en lecture seule dans votre ERP.
Quel type de flux dois-je utiliser pour placer des articles sur WFS ?
Utilisez POST /v3/feeds?feedType=MP_WFS_ITEM pour créer des articles qui n’existent pas encore sur Walmart, et POST /v3/feeds?feedType=OMNI_WFS pour convertir des articles déjà ingérés comme articles exécutés par le vendeur. Les deux opérations sont asynchrones : interrogez l’état du flux et consultez les erreurs au niveau des articles avant de créer une commande entrante pour ces SKU.
Puis-je annuler une seule expédition au sein d’une commande entrante WFS ?
Non. L’annulation ne fonctionne qu’au niveau de la commande entrante, et l’annulation d’une commande entrante annule toutes les expéditions qu’elle contient. Vous ne pouvez pas non plus annuler une expédition après qu’elle a atteint le statut Receiving in Progress, Closed ou Cancelled. Vérifiez donc son état avec l’appel Get Shipments avant de proposer une action d’annulation dans votre interface.
Puis-je préparer des commandes Shopify ou d’autres commandes non Walmart à partir du stock WFS ?
Oui, grâce à Multichannel Solutions. Enregistrez d’abord le canal de vente, utilisez le point de terminaison de promesse de livraison avant d’afficher une date dans votre tunnel de paiement, puis créez, suivez et annulez les commandes d’exécution via les points de terminaison MCS. Les retours disposent de leurs propres points de terminaison de création, de consultation et d’annulation et doivent être intégrés en même temps.