Marketplace Selling

Tích hợp API Walmart WFS: Toàn bộ luồng gọi và cạm bẫy

Tìm hiểu tích hợp API Walmart WFS theo từng endpoint: chuyển đổi sản phẩm, nhập hàng, đơn WFS, giới hạn tồn kho và lỗi gây hỏng đồng bộ.

Ảnh đại diện Long Nguyen

Long Nguyen

Lập trình viên Fullstack · Kỹ sư AI · Nhà nghiên cứu

• • 4 phút đọc •
Sơ đồ tổng quan tích hợp API Walmart WFS, gồm các nhóm endpoint về feed, xử lý đơn, tồn kho, đơn hàng và Multichannel Solutions

Những API nào thực sự tạo nên một tích hợp Walmart WFS?

Không có một “WFS API” riêng với máy chủ, thông tin xác thực hay SDK riêng. Walmart Fulfillment Services nằm trong Walmart Marketplace API tại marketplace.walmartapis.com: một nhóm endpoint chỉ dành cho WFS dưới /v3/fulfillment/, hai loại WFS feed và một số thay đổi về cách hoạt động của các endpoint mà có thể bạn đã gọi sẵn.

Điểm phân biệt này quyết định kiến trúc hệ thống. WFS không phải là một connector thứ hai được gắn thêm bên cạnh connector Marketplace — đây là một phương thức xử lý đơn hàng làm thay đổi cách connector hiện tại hoạt động theo từng SKU và từng đơn hàng.

Nhiệm vụ Endpoint / feed Chỉ dành cho WFS?
Tạo sản phẩm trực tiếp dưới dạng WFS POST /v3/feeds?feedType=MP_WFS_ITEM Endpoint dùng chung, loại WFS feed
Chuyển sản phẩm hiện có sang WFS POST /v3/feeds?feedType=OMNI_WFS Endpoint dùng chung, loại WFS feed
Gửi tồn kho đến trung tâm xử lý đơn hàng /v3/fulfillment/inbound-shipments và các endpoint liên quan Có
Đọc lượng hàng WFS đang có WFS inventory (New) cùng các báo cáo đối soát, tình trạng và nhật ký theo từng sản phẩm Có
Lấy đơn hàng của khách GET /v3/orders với shipNodeType Endpoint dùng chung, thay đổi tham số
Xử lý đơn ngoài Walmart bằng tồn kho WFS Các endpoint Multichannel Solutions Có
Đặt vận chuyển hàng đến FC Walmart Preferred Carriers (mới) / carrier rate quote (legacy) Có
Bổ sung hàng, chuyển đổi và đề xuất sản phẩm chưa xuất bản Các endpoint Recommendations Có
Kiểm tra hàng bị giữ do hazmat Hazmat Items On hold Có

Nếu hệ thống tích hợp của bạn đã kết nối với Marketplace, khoảng 70% dự án WFS là xây dựng endpoint mới và 30% là kiểm tra lại phần code đã triển khai để tìm những nơi SKU WFS hoạt động khác biệt. Chính 30% còn lại là nơi các tích hợp thường bị lỗi.

Xác thực và các header cần có trong mọi lệnh gọi WFS

Mọi lệnh gọi WFS đều sử dụng cùng quy trình OAuth client-credentials như phần còn lại của Marketplace API. Bạn đổi Client ID và Client Secret lấy access token có thời hạn ngắn, sau đó gửi token này qua header — không gửi dưới dạng giá trị bearer trong 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",
    }

Có ba điều được nêu trong tài liệu tham chiếu nhưng vẫn thường bị các hệ thống tích hợp xử lý sai:

  • Lưu cache token dựa trên expires_in, tuyệt đối không dùng TTL cố định. Tạo token mới cho mỗi lệnh gọi là cách nhanh nhất khiến bạn bị giới hạn tốc độ khi chạy các đợt nhập hàng lớn.
  • WM_QOS.CORRELATION_ID phải là một GUID mới cho mỗi lệnh gọi và bạn nên ghi log giá trị này. Đây là mã duy nhất để Walmart Support truy vết khi một đơn nhập hàng bị lỗi mà không có thông báo; dùng lại hoặc bỏ qua correlation ID có thể biến một yêu cầu hỗ trợ 20 phút thành vấn đề kéo dài cả tuần.
  • Các nhà cung cấp giải pháp cũng phải gửi WM_CONSUMER.CHANNEL.TYPE, được cấp khi onboarding. Người bán tự gọi API thay mặt mình không cần header này; đó là lý do code mẫu của nhà cung cấp được sao chép nguyên xi thường trả về lỗi 400 trên tài khoản người bán trực tiếp.

Đưa sản phẩm vào danh mục WFS: MP_WFS_ITEM và OMNI_WFS

Một đơn nhập hàng chỉ có thể tham chiếu đến SKU đã tồn tại trong danh mục WFS. Các lỗi đơn nhập hàng được Walmart ghi nhận gồm “SKU not in WFS catalog” — và nguyên nhân gần như luôn là lỗi về thứ tự xử lý, không phải lỗi dữ liệu: đội ngũ đã gọi API nhập hàng trước khi feed sản phẩm hoàn tất.

  MP_WFS_ITEM OMNI_WFS
Dùng khi SKU chưa tồn tại trên Walmart SKU đã được bán trực tiếp bởi người bán
Tác dụng Tạo sản phẩm bằng đặc tả sản phẩm WFS Chuyển sản phẩm đã được tiếp nhận sang WFS
Lệnh gọi POST /v3/feeds?feedType=MP_WFS_ITEM POST /v3/feeds?feedType=OMNI_WFS
Đặc tả cần lấy trước Đặc tả sản phẩm WFS qua Get spec Đặc tả chuyển đổi WFS qua Get spec

Cả hai đều xử lý bất đồng bộ. Phản hồi trả về feedId, không phải kết quả cuối cùng. Hãy kiểm tra trạng thái feed cho đến khi feed không còn ở trạng thái INPROGRESS, sau đó đọc lỗi ở cấp độ sản phẩm — feed có thể báo thành công ở cấp header trong khi từng SKU riêng lẻ vẫn không vượt qua bước kiểm tra dữ liệu.

Cạm bẫy về kích thước

Phí WFS được tính dựa trên trọng lượng và kích thước vận chuyển, đồng thời FC sẽ đo lại thùng hàng khi tiếp nhận. Nếu feed sản phẩm chứa kích thước của sản phẩm thay vì kích thước của đơn vị đã đóng gói, sẵn sàng để vận chuyển, mọi ước tính phí do hệ thống tạo ra sau đó đều sai — và bạn chỉ phát hiện ra qua báo cáo đối soát vài tuần sau. Hãy chuẩn hóa kích thước kiện hàng ngay tại thời điểm PIM ghi feed, không xử lý ở bước sau.

Tạo lô hàng nhập vào bằng WFS API, theo từng lệnh gọi

Đây là quy trình WFS cốt lõi: bạn khai báo những gì dự định gửi, Walmart cho biết nơi cần gửi, bạn in nhãn, bàn giao cho đơn vị vận chuyển và gửi thông tin tracking.

# Lệnh gọi Mục đích
1 POST /v3/fulfillment/inbound-preview Chạy thử — xem Walmart sẽ chia đơn như thế nào trước khi xác nhận
2 POST /v3/fulfillment/inbound-shipments Tạo đơn nhập hàng (IO)
3 GET /v3/fulfillment/inbound-shipment-errors Kiểm tra lý do IO bị từ chối
4 GET /v3/fulfillment/inbound-shipments Thông tin cấp lô hàng: gồm những FC nào và có bao nhiêu lô hàng
5 GET /v3/fulfillment/inbound-shipment-items Thông tin cấp SKU theo từng lô hàng cùng trạng thái tiếp nhận
6 PUT /v3/fulfillment/shipment-quantities Điều chỉnh số lượng trước khi lô hàng được giao
7 POST /v3/fulfillment/shipment-label Tạo nhãn cho lô hàng nhập
8 POST /v3/fulfillment/shipment-tracking Gửi thông tin đơn vị vận chuyển và mã tracking
9 DELETE /v3/fulfillment/inbound-shipments/{inboundOrderId} Hủy toàn bộ IO

Đọc trang endpoint, không chỉ trang tổng quan

Trang tổng quan WFS của Walmart liệt kê quy trình này bằng các đường dẫn rút gọn như /v3/inbound-shipments và /v3/shipment-items}, đồng thời hiển thị GET cho hai thao tác thực tế là PUT và POST. Các trang tham chiếu theo từng endpoint mới là nguồn khớp với môi trường production: mọi thao tác nhập hàng đều nằm dưới /v3/fulfillment/. Hãy xây dựng dựa trên tài liệu tham chiếu API fulfillment của Walmart và xem trang tổng quan như một sơ đồ, không phải đặc tả ràng buộc.

Việc chia tách tương tự cũng che giấu một thay đổi ngừng hỗ trợ đang diễn ra: lệnh gọi tạo nhãn bạn cần dùng là POST /v3/fulfillment/shipment-label. Endpoint cũ GET /v3/fulfillment/label/{shipmentId} được đánh dấu deprecated nhưng vẫn là endpoint được phần lớn code mẫu trên Internet gọi đến.

Một inbound order không đồng nghĩa với một shipment

Đây là sai lầm lớn nhất trong mô hình dữ liệu của các tích hợp WFS. Khi bạn tạo IO, Walmart quyết định lô hàng sẽ được gửi đến một fulfillment center hay phải chia cho nhiều trung tâm — và phản hồi sẽ cho bạn biết kết quả. Schema của bạn cần có ba cấp ngay từ đầu:

  1. Inbound order — những gì bạn yêu cầu gửi và là cấp duy nhất có thể hủy
  2. Shipment — một shipment cho mỗi FC đích, mỗi shipment có nhãn, đơn vị vận chuyển và mã tracking riêng
  3. Shipment item — phần chia ở cấp SKU, sau đó dùng để đối soát số lượng đã nhận với số lượng dự kiến

Các đội ngũ mô hình hóa IO thành một danh sách SKU phẳng với một mã tracking sẽ phải viết lại module ngay khi xảy ra lần chia cho nhiều FC đầu tiên — thường là trong tuần thứ hai sau khi chạy production.

Khả năng hủy hẹp hơn bạn nghĩ

Bạn chỉ có thể hủy ở cấp inbound order — hủy một IO sẽ hủy mọi shipment trong đó và không có cách nào hủy riêng một shipment bên trong IO gồm nhiều shipment. Việc hủy cũng bị chặn khi shipment đã chuyển sang trạng thái Receiving in Progress, Closed hoặc Cancelled. Hãy kiểm tra trạng thái bằng lệnh Get Shipments trước khi hiển thị nút hủy trong giao diện của bạn, nếu không người dùng sẽ gặp các lỗi mà bạn không thể giải thích.

Lấy đơn WFS mà không làm hỏng quá trình đồng bộ đơn hàng

Đây là cạm bẫy tạo ra nhiều yêu cầu hỗ trợ kiểu “tích hợp WFS bị hỏng” hơn tất cả các vấn đề khác cộng lại: GET /v3/orders mặc định dùng shipNodeType=SellerFulfilled. Đơn WFS không nằm trong phản hồi đó. Muốn đọc chúng, bạn phải chỉ định rõ:

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)

Một người bán chuyển danh mục sang WFS, doanh số vẫn tiếp tục nhưng ERP lại hiển thị không có đơn hàng mới. Không có gì bị hỏng — quy trình đồng bộ đang tự động lọc chúng theo mặc định. Hướng dẫn API WFS của chính Walmart nêu rõ điều này, và đây vẫn là điều đầu tiên cần kiểm tra khi triển khai WFS.

Điều này dẫn đến hai yêu cầu cho pipeline đơn hàng:

  • Chạy cả hai lượt lấy dữ liệu, không chỉ một. Người bán có mô hình kết hợp cần lượt SellerFulfilled và lượt WFSFulfilled, lưu vào cùng một bảng đơn hàng và ghi kênh fulfillment trên từng dòng.
  • Không bao giờ xác nhận, giao hàng hoặc hủy một dòng đơn WFS. Walmart phụ trách lấy hàng, đóng gói, giao hàng và tracking cho WFS. Nếu code của bạn gọi Acknowledge Orders hoặc Ship Order Lines trên dòng WFS vì đó là quy trình vốn dùng cho các đơn Marketplace, bạn đang ghi dữ liệu vào một luồng mà mình không kiểm soát. Hãy phân nhánh theo kênh fulfillment trước mọi thao tác ghi trên đơn hàng.

Tồn kho WFS: API cho phép ghi gì và không cho phép ghi gì?

Với SKU do người bán tự xử lý, bạn sở hữu số lượng và đẩy số lượng đó qua Inventory API. Với SKU WFS, bạn không sở hữu số lượng tồn kho. Lượng hàng thực có là số lượng đang nằm trong các fulfillment center của Walmart và bạn chỉ có thể đọc.

Thao tác SKU do người bán xử lý SKU WFS
Đẩy số lượng Có, bằng Update inventory Không — Walmart là nguồn dữ liệu chuẩn
Đọc số lượng Inventory / multi-node inventory WFS inventory (New)
Kiểm tra biến động Hệ thống của bạn Inventory log for a WFS item
Đối soát với dự kiến Hệ thống của bạn WFS inventory reconciliation report
Phát hiện tồn kho lâu ngày và vấn đề tình trạng Hệ thống của bạn WFS inventory health report

Quy tắc thiết kế: trong ERP, số lượng WFS là bản sao được cache, không bao giờ là trường có thể ghi. Mọi đường code tính lại số lượng có thể bán rồi đẩy ngược trở lại phải được kiểm soát theo kênh fulfillment.

Hãy dùng báo cáo đối soát và nhật ký tồn kho theo từng sản phẩm như một cặp công cụ thay vì chỉ xem dashboard. Báo cáo đối soát cho biết có chênh lệch; nhật ký sản phẩm cho biết biến động nào gây ra chênh lệch đó — đây là bằng chứng cần thiết khi bạn mở yêu cầu bồi thường cho số hàng nhận thiếu hoặc bị hư hỏng. Hãy định kỳ lấy và lưu cả hai — đây là dấu vết kiểm toán đáng tin cậy duy nhất bạn có, và đó cũng là phần của dịch vụ tích hợp API marketplace mà phần lớn đội ngũ chỉ nhận ra mình cần sau tổn thất đầu tiên.

Xử lý đơn ngoài Walmart bằng tồn kho WFS với Multichannel Solutions

Multichannel Solutions (MCS) là phần trong hệ thống WFS mà nhiều người bán không biết đến: tính năng này cho phép bạn xử lý các đơn đặt trên cửa hàng riêng hoặc kênh khác bằng hàng đang nằm tại các FC của Walmart. Đây là một nhóm endpoint riêng với lệnh onboarding riêng.

  • Đăng ký kênh trước — Tạo thông tin kênh bán MCS, sau đó đọc hoặc cập nhật thông tin. Đơn gửi đến một kênh chưa đăng ký sẽ không được định tuyến.
  • Báo giá trước khi cam kết — Gọi Fetch delivery promise details để lấy ngày giao hàng an toàn có thể hiển thị tại checkout của cửa hàng bạn. Hiển thị một ngày ước đoán rồi để đơn fulfillment thất bại sau đó là cách nhanh chóng tạo ra hàng loạt yêu cầu hỗ trợ.
  • Tạo, theo dõi, hủy — Create MCS customer order, Get MCS fulfillment orders status, Cancel MCS fulfillment order.
  • Trả hàng là một quy trình chính thức — Có các endpoint riêng để tạo, đọc và hủy đơn trả hàng của khách. Hãy kết nối các endpoint này cùng lúc với luồng giao hàng; bổ sung trả hàng sau khi hệ thống đã chạy luôn tốn kém hơn.

Walmart cũng công bố đặc tả OpenAPI cho MCS, vì vậy bạn nên tạo client layer tự động thay vì viết thủ công. Hãy dùng thời gian tiết kiệm được để xây dựng state machine giữa trạng thái đơn hàng của bạn và của Walmart — đó là phần mà trình tạo code không thể cung cấp.

Những endpoint WFS mà phần lớn hệ thống tích hợp không bao giờ gọi

Có bốn endpoint được tạo riêng để giúp vận hành WFS tiết kiệm hơn nhưng thường bị bỏ qua vì nằm trong nhóm Recommendations thay vì Fulfillment:

  • Get WFS Recommended Shipment Quantity — lượng hàng nên đưa vào inbound order tiếp theo. Hãy đưa dữ liệu này vào tác vụ bổ sung hàng thay vì dùng một ngưỡng đặt lại cố định.
  • Restock Recommendations — những SKU nên bổ sung dựa trên lượng tồn hiện tại và nhu cầu dự báo.
  • Fulfill with WFS Recommendations — những SKU đang do người bán xử lý có khả năng hoạt động tốt hơn nếu chuyển sang WFS. Đây là endpoint nên hiển thị cho khách hàng đang cân nhắc sản phẩm nào cần chuyển đổi.
  • Unpublished Recommendations — những sản phẩm WFS hiện chưa được xuất bản và lý do. Một sản phẩm WFS chưa xuất bản vẫn phát sinh phí lưu kho nhưng không tạo doanh số, nên đây là endpoint có giá trị cao nhất trong bốn endpoint và rất đáng thiết lập cảnh báo.

Một lưu ý về vận chuyển hàng: báo giá của Walmart Preferred Carrier cho các chuyến xe nguyên tải không có sẵn qua API, vì vậy hệ thống giả định có thể báo giá lập trình cho mọi lô nhập hàng sẽ cần thêm một bước trong Seller Center đối với FTL. Cũng cần lưu ý các endpoint carrier rate quote tồn tại ở cả bộ cũ và bộ mới — hãy xây dựng trên nhóm Walmart Preferred Carriers mới.

Những cạm bẫy tích hợp WFS gây tốn thời gian nhất

Danh sách kiểm tra trước khi triển khai, được rút ra từ những điểm tài liệu và hành vi thực tế không thống nhất:

Triệu chứng Nguyên nhân thực tế
Không có đơn WFS trong quy trình đồng bộ đơn hàng shipNodeType mặc định là SellerFulfilled
Inbound order bị từ chối: SKU không có trong danh mục WFS IO được gọi trước khi feed sản phẩm xử lý xong
404 trên các endpoint nhập hàng Sao chép đường dẫn từ trang tổng quan nhưng thiếu tiền tố /v3/fulfillment/
Lệnh gọi tạo nhãn trả về thông báo deprecated Dùng GET /v3/fulfillment/label/{shipmentId} thay vì POST /v3/fulfillment/shipment-label
Nút hủy thỉnh thoảng bị lỗi Shipment đã ở trạng thái Receiving in Progress, Closed hoặc Cancelled, hoặc đang cố hủy một shipment bên trong IO
Các mã tracking ghi đè lên nhau IO được mô hình hóa thành một shipment trong khi việc chia cho nhiều FC tạo ra nhiều shipment
Lệnh đẩy tồn kho không có tác dụng Cố ghi số lượng trên SKU WFS
Ước tính phí lệch so với phí thực tế Gửi kích thước sản phẩm thay vì kích thước vận chuyển sau khi đóng gói
Support không thể truy vết lỗi Không lưu WM_QOS.CORRELATION_ID cho từng lệnh gọi

Phần lớn lỗi này dễ phòng tránh nhưng tốn kém để phát hiện trong production, vì cách lỗi thường biểu hiện là im lặng thay vì báo lỗi. Hãy xây dựng log correlation ID và phân nhánh theo kênh fulfillment trước inbound order đầu tiên, không phải sau sự cố đầu tiên.

Nếu bạn đang kết nối WFS vào một hệ thống đa kênh hiện có — hoặc quy trình đồng bộ đơn hàng đã âm thầm bỏ sót một nửa sản lượng — bạn có thể cho chúng tôi biết bạn đang tích hợp gì để nhận báo giá theo phạm vi cụ thể. Không cần tài khoản và không mất phí khi hỏi.

CÂU HỎI THƯỜNG GẶP

Câu hỏi thường gặp

Walmart có một WFS API riêng với thông tin xác thực riêng không?

Không. WFS là một phần của Walmart Marketplace API tại marketplace.walmartapis.com và sử dụng cùng Client ID, Client Secret cũng như quy trình cấp token. Phần dành riêng cho WFS gồm nhóm endpoint dưới /v3/fulfillment/, hai loại feed (MP_WFS_ITEM và OMNI_WFS), các endpoint tồn kho và báo cáo WFS, Multichannel Solutions, Walmart Preferred Carriers và các endpoint đề xuất WFS.

Vì sao đơn WFS không xuất hiện trong GET /v3/orders?

Vì endpoint này mặc định dùng shipNodeType=SellerFulfilled. Hãy truyền shipNodeType=WFSFulfilled để lấy đơn WFS. Người bán có mô hình kết hợp cần chạy cả hai lượt lấy dữ liệu và lưu kênh fulfillment trên từng dòng đơn hàng.

Tôi có thể cập nhật số lượng tồn kho của sản phẩm WFS qua API không?

Không. Walmart sở hữu số lượng của SKU WFS vì hàng hóa thực tế nằm trong các fulfillment center của Walmart. Bạn đọc tồn kho WFS bằng endpoint WFS inventory và kiểm tra bằng báo cáo đối soát tồn kho, báo cáo tình trạng tồn kho cùng nhật ký tồn kho theo từng sản phẩm. Hãy coi số lượng WFS là dữ liệu chỉ đọc trong ERP.

Tôi nên dùng loại feed nào để đưa sản phẩm lên WFS?

Dùng POST /v3/feeds?feedType=MP_WFS_ITEM để tạo sản phẩm chưa tồn tại trên Walmart và POST /v3/feeds?feedType=OMNI_WFS để chuyển đổi sản phẩm đã được tiếp nhận dưới dạng do người bán xử lý. Cả hai đều xử lý bất đồng bộ, vì vậy hãy kiểm tra trạng thái feed và đọc lỗi ở cấp sản phẩm trước khi tạo inbound order cho các SKU đó.

Tôi có thể hủy một shipment riêng bên trong WFS inbound order không?

Không. Việc hủy chỉ thực hiện được ở cấp inbound order; hủy inbound order sẽ hủy mọi shipment trong đó. Bạn cũng không thể hủy khi shipment đã ở trạng thái Receiving in Progress, Closed hoặc Cancelled, vì vậy hãy kiểm tra trạng thái bằng lệnh Get Shipments trước khi cung cấp thao tác hủy trong giao diện của mình.

Tôi có thể xử lý đơn Shopify hoặc đơn từ kênh khác bằng tồn kho WFS không?

Có, thông qua Multichannel Solutions. Trước tiên hãy đăng ký kênh bán, dùng endpoint delivery promise trước khi hiển thị ngày giao hàng tại checkout của riêng bạn, sau đó tạo, theo dõi và hủy các đơn fulfillment qua endpoint MCS. Các trường hợp trả hàng có endpoint riêng để tạo, đọc và hủy, đồng thời nên được kết nối cùng lúc với luồng xử lý đơn chính.

Cập nhật cùng Netalith

Nhận kiến thức công nghệ, cập nhật sản phẩm và ưu đãi đặc biệt qua email.