沃尔玛商品详情 API（核心接口如 Product Retrieval API）是沃尔玛开发者平台（Walmart Developer Portal）提供的标准化数据接口，支持获取商品基础信息、价格、库存、规格、商家信息等核心数据，适配电商分析、供应链管理、导购工具开发等场景。以下是 从前置准备到代码调用、数据解析 的全流程实操指南，基于 Python 语言实现，兼顾专业性与易用性，技术开发者可直接落地对接。

一、前置准备工作

1. 注册沃尔玛开发者账号并获取权限

• 可报告博主，完成企业 / 个人实名认证（企业认证可获取更高调用配额）；
• 创建应用（Application），获取核心凭证：Client ID（应用唯一标识）、Client Secret（签名密钥）；
• 申请商品详情 API 权限：在应用后台勾选 Product Retrieval 接口权限，等待平台审核（通常 1-3 个工作日），审核通过后即可获取调用资格。

⚠️ 关键注意：沃尔玛 API 分为 沙箱环境（Sandbox） 和 生产环境（Production），测试阶段优先使用沙箱环境，避免消耗生产环境配额。

2. 明确接口核心信息

• 核心接口：Product Retrieval API（获取单商品详情）、Bulk Products API（批量获取商品详情）；
• 请求方式：RESTful 风格，支持 GET 方法；
• 认证方式：OAuth 2.0 授权（需先获取 Access Token，再调用商品详情接口）；
• 响应格式：默认 JSON，支持结构化字段解析；
• 沙箱环境地址：https://sandbox-api.walmart.com，生产环境地址：https://api.walmart.com。

3. Python 环境配置

安装必备依赖库，用于授权请求、接口调用、数据解析：

pip install requests  # 发送 HTTP 请求
pip install python-dotenv  # 管理敏感配置（Client ID/Secret）
pip install pandas  # 可选，用于数据格式化存储

二、核心流程：OAuth 2.0 授权 + 接口调用

沃尔玛 API 强制要求 OAuth 2.0 授权，需先通过 Client ID 和 Client Secret 获取 Access Token（有效期 1 小时），再用 Token 调用商品详情接口。

1. 配置敏感信息（避免硬编码）

创建 .env 文件存储敏感配置，提高代码安全性：

# .env 文件内容
WALMART_CLIENT_ID=你的ClientID
WALMART_CLIENT_SECRET=你的ClientSecret
WALMART_ENV=sandbox  # 可选：sandbox（沙箱）、production（生产）

2. 获取 Access Token（Python 实现）

import os
import requests
from dotenv import load_dotenv

# 加载环境变量
load_dotenv()

def get_walmart_access_token():
    """获取 OAuth 2.0 Access Token"""
    # 授权地址（沙箱/生产环境区分）
    env = os.getenv("WALMART_ENV", "sandbox")
    token_url = "https://sandbox-api.walmart.com/v3/token" if env == "sandbox" else "https://api.walmart.com/v3/token"
    
    # 授权参数
    payload = {
        "grant_type": "client_credentials",
        "client_id": os.getenv("WALMART_CLIENT_ID"),
        "client_secret": os.getenv("WALMART_CLIENT_SECRET")
    }
    
    try:
        response = requests.post(token_url, data=payload, timeout=10)
        response.raise_for_status()  # 抛出 HTTP 错误（如 401 授权失败）
        token_data = response.json()
        return token_data["access_token"]  # 返回 Access Token
    except requests.exceptions.RequestException as e:
        raise Exception(f"获取 Access Token 失败：{str(e)}，响应内容：{response.text if 'response' in locals() else ''}")

# 测试获取 Token
if __name__ == "__main__":
    access_token = get_walmart_access_token()
    print("Access Token 获取成功：", access_token)

3. 调用商品详情 API（单商品查询）

以 Product Retrieval API 为例，通过商品 ID（productId）获取商品详情，核心参数与响应解析如下：

完整代码实现

def get_walmart_product_detail(product_id, access_token):
    """
    调用沃尔玛商品详情 API
    :param product_id: 商品唯一 ID（沙箱环境可使用测试商品 ID：如 123456789）
    :param access_token: OAuth 2.0 Access Token
    :return: 结构化商品详情数据
    """
    # 接口地址（沙箱/生产环境区分）
    env = os.getenv("WALMART_ENV", "sandbox")
    api_url = f"https://sandbox-api.walmart.com/v3/items/{product_id}" if env == "sandbox" else f"https://api.walmart.com/v3/items/{product_id}"
    
    # 请求头（携带 Access Token）
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }
    
    # 可选参数：筛选返回字段（减少数据传输量）
    params = {
        "fields": "itemId,title,brand,price,availability,attributes,images"  # 需返回的字段列表
    }
    
    try:
        response = requests.get(api_url, headers=headers, params=params, timeout=15)
        response.raise_for_status()
        product_data = response.json()
        return product_data
    except requests.exceptions.RequestException as e:
        raise Exception(f"调用商品详情 API 失败：{str(e)}，响应内容：{response.text if 'response' in locals() else ''}")

# 主流程：获取 Token + 调用商品详情
if __name__ == "__main__":
    try:
        # 1. 获取 Access Token
        access_token = get_walmart_access_token()
        
        # 2. 调用商品详情 API（沙箱测试商品 ID：123456789，生产环境需替换为真实商品 ID）
        product_id = "123456789"
        product_detail = get_walmart_product_detail(product_id, access_token)
        
        # 3. 打印核心商品信息
        print("=== 沃尔玛商品详情 ===")
        print(f"商品 ID：{product_detail.get('itemId')}")
        print(f"商品标题：{product_detail.get('title')}")
        print(f"品牌：{product_detail.get('brand')}")
        print(f"售价：{product_detail.get('price', {}).get('currentPrice', {}).get('value')} {product_detail.get('price', {}).get('currentPrice', {}).get('currency')}")
        print(f"库存状态：{product_detail.get('availability', {}).get('status')}")
        print(f"主图 URL：{product_detail.get('images', {}).get('primaryImage', {}).get('url')}")
        
    except Exception as e:
        print(f"执行失败：{str(e)}")

4. 批量获取商品详情（Bulk Products API）

若需批量查询多个商品，可使用 Bulk Products API，通过 itemIds 参数传入多个商品 ID（用逗号分隔），代码示例：

def get_walmart_bulk_products(product_ids, access_token):
    """
    批量获取商品详情
    :param product_ids: 商品 ID 列表（如 ["123456789", "987654321"]）
    :param access_token: Access Token
    :return: 批量商品详情
    """
    env = os.getenv("WALMART_ENV", "sandbox")
    api_url = "https://sandbox-api.walmart.com/v3/items" if env == "sandbox" else "https://api.walmart.com/v3/items"
    
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }
    
    params = {
        "itemIds": ",".join(product_ids),  # 批量商品 ID 拼接
        "fields": "itemId,title,price,availability"
    }
    
    try:
        response = requests.get(api_url, headers=headers, params=params, timeout=20)
        response.raise_for_status()
        return response.json()
    except Exception as e:
        raise Exception(f"批量获取商品详情失败：{str(e)}")

# 测试批量调用
if __name__ == "__main__":
    access_token = get_walmart_access_token()
    product_ids = ["123456789", "987654321"]  # 沙箱测试商品 ID
    bulk_data = get_walmart_bulk_products(product_ids, access_token)
    print("批量商品详情：", bulk_data)

三、数据解析关键要点

沃尔玛商品详情 API 返回的 JSON 数据结构清晰，核心字段解析如下：

1. 核心字段映射

字段路径	含义	示例值
itemId	商品唯一 ID	"123456789"
title	商品标题	"Walmart 无线蓝牙耳机"
brand	品牌名称	"Walmart Essentials"
price.currentPrice.value	当前售价	29.99
price.currentPrice.currency	货币单位	"USD"
availability.status	库存状态	"IN_STOCK"（有货）
attributes.categoryPath	商品类目	"Electronics/Audio"
images.primaryImage.url	主图 URL	"https://i5.walmartimages.com/..."
variants.variant	SKU 列表（多规格商品）	[{"variantId": "xxx",...}]

2. 复杂字段解析示例（SKU 规格提取）

# 从商品详情中提取 SKU 信息
def parse_sku_info(product_detail):
    sku_list = []
    variants = product_detail.get("variants", {}).get("variant", [])
    for variant in variants:
        sku_info = {
            "variantId": variant.get("variantId"),
            "color": variant.get("attributes", {}).get("color"),
            "size": variant.get("attributes", {}).get("size"),
            "price": variant.get("price", {}).get("currentPrice", {}).get("value"),
            "stockStatus": variant.get("availability", {}).get("status")
        }
        sku_list.append(sku_info)
    return sku_list

# 调用解析函数
sku_info = parse_sku_info(product_detail)
print("SKU 规格信息：", sku_info)

四、常见错误排查（避坑指南）

1. 错误码 401（Unauthorized）

• 原因：Client ID/Secret 错误、Access Token 过期或无效；
• 排查：核对 .env 中的凭证是否正确，重新获取 Access Token（有效期 1 小时，需定时刷新）。

2. 错误码 403（Forbidden）

• 原因：未申请商品详情 API 权限、沙箱环境调用生产接口；
• 排查：在沃尔玛开发者平台确认接口权限已开通，检查环境地址是否匹配（沙箱 / 生产）。

3. 错误码 429（Too Many Requests）

• 原因：调用频率超限（沃尔玛默认限制：沙箱 100 次 / 分钟，生产 500 次 / 分钟）；
• 排查：添加请求延迟（time.sleep(0.1)）、实现限流逻辑，批量调用时拆分请求批次。

4. 错误码 404（Not Found）

• 原因：商品 ID 无效、商品已下架；
• 排查：确认商品 ID 正确，沙箱环境需使用平台提供的测试商品 ID（如 123456789）。

五、进阶优化与合规建议

1. 代码优化

• Token 缓存：Access Token 有效期 1 小时，用 Redis 或本地缓存存储，避免重复获取；
• 异常重试：使用 tenacity 库实现带退避策略的重试（应对网络波动）：

  bash

  pip install tenacity
  

  from tenacity import retry, stop_after_attempt, wait_exponential
  
  @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=2, max=10))
  def get_walmart_product_detail(product_id, access_token):
      # 原有接口调用逻辑
  

• 批量请求拆分：Bulk Products API 单次最多支持 20 个商品 ID，批量查询时按 20 个 / 批次拆分。

2. 合规使用要求

• 数据用途：仅用于自身经营需求，禁止转售、恶意采集商品数据；
• 频率控制：严格遵守沃尔玛 API 调用配额，避免高频请求导致账号封禁；
• 隐私保护：不得提取商品关联的用户隐私信息，仅使用公开商品数据。

总结

Python 调用沃尔玛商品详情 API 的核心流程是 “OAuth 2.0 授权 → 获取 Access Token → 调用接口 → 数据解析”，关键在于正确配置授权凭证、区分沙箱 / 生产环境、处理频率限制与异常情况。通过本文的代码示例，可快速实现单商品 / 批量商品详情的获取，适配电商数据分析、供应链管理等场景。

若需进一步优化（如 Token 自动刷新、数据入库 MySQL），或对接其他沃尔玛 API（如库存 API、订单 API），可基于本文框架扩展开发。