Marketplace Selling

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.

Photo de profil de Long Nguyen

Long Nguyen

Développeur fullstack · Ingénieur IA · Chercheur

• • 4 min de lecture •
Schéma de l’intégration de l’API Walmart WFS présentant les groupes de points de terminaison liés aux flux, à l’exécution, aux stocks, aux commandes et à Multichannel Solutions

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_ID doit ê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 :

  1. Commande entrante — ce que vous avez demandé à envoyer, et le seul niveau auquel l’annulation est possible
  2. Expédition — une par centre de traitement de destination, chacune avec sa propre étiquette, son propre transporteur et son propre suivi
  3. 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 SellerFulfilled et la récupération WFSFulfilled, 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.

Restez informé avec Netalith

Recevez des ressources de développement, des mises à jour produit et des offres spéciales directement dans votre boîte mail.