本文详解 woocommerce rest api `products/batch` 接口批量更新失败的核心原因：错误地手动拼接 json 字符串导致请求体格式非法，以及如何通过 python 字典结构+原生 `json` 序列化确保请求合规。
在使用 WooCommerce REST API 进行产品批量更新时，一个高频陷阱是手动拼接 JSON 字符串（如 "{"update": [...]}"），这极易引入语法错误、编码问题或类型不匹配，最终导致 API 静默失败——请求返回 HTTP 200 状态码，但响应体为空（"data": []），且无任何错误提示。正如问题中所见，日志显示 Body Content 是一个被双引号包裹的字符串，而非合法 JSON 对象，这意味着服务器根本未解析出有效数据。
✅ 正确做法：用 Python 字典构造请求体，交由 requests 自动序列化
WooCommerce 的 /wp-json/wc/v3/products/batch 接口期望的请求体是一个标准 JSON 对象，其顶层键必须为 "update"，值为产品对象列表。每个产品对象应为字典（dict），而非字符串。关键点如下：
- ❌ 错误：data = "{\"update\": [" + ", ".join(str(p) for p in products) + "]}"
- ✅ 正确：data = {"update": products_list} —— products_list 是纯 Python 字典列表，wcapi.post() 内部会自动调用 json.dumps() 并设置 Content-Type: application/json
以下为完整、可直接复用的示例代码：
from woocommerce import API
# 初始化 API 客户端（请替换为你的实际配置）
wcapi = API(
url="https://example.com",
consumer_key="your_consumer_key",
consumer_secret="your_consumer_secret",
version="wc/v3",
timeout=30
)
# 构建产品更新列表（务必使用 dict，非 str！）
product_list = [
{
"id": 8056,
"manage_stock": True, # 布尔值，非字符串 "true"
"stock_quantity": 5,
"name": "Product_1",
"status": "publish",
"regular_price": "12.95",
"categories": [{"id": 21485}]
},
{
"id": 44848,
"manage_stock": True,
"stock_quantity": 48,
"name": "Product_2",
"status": "publish",
"regular_price": "0.3",
"categories": [{"id": 21485}]
}
# ... 更多产品
]
# 分批提交（推荐 batch_size ≤ 100，避免超时或内存压力）
batch_size = 100
total = len(product_list)
print(f"总计 {total} 个产品，将分批处理...")
for i in range(0, total, batch_size):
batch = product_list[i:i + batch_size]
payload = {"update": batch} # 核心：字典结构，非字符串！
print(f"▶ 正在提交第 {i//batch_size + 1} 批（{len(batch)} 项）...")
try:
response = wcapi.post("products/batch", payload).json()
# 检查响应是否包含成功更新的数据
if "update" in response and len(response["update"]) > 0:
print(f"✅ 批次 {i//batch_size + 1} 更新成功：{len(response['update'])} 个产品")
else:
print(f"⚠️ 批次 {i//batch_size + 1} 未返回更新结果，请检查响应：{response}")
except Exception as e:
print(f"❌ 批次 {i//batch_size + 1} 请求异常：{e}")⚠️ 关键注意事项
- 布尔值必须为 True/False，而非字符串 "true"/"false"：WooCommerce API 严格校验类型，传字符串会导致字段被忽略。
- 避免手动 json.dumps()：woocommerce-python 库已内置 JSON 序列化逻辑；若手动转为字符串再传入，会触发二次编码（变成字符串中的字符串），破坏结构。
- 验证 API 权限：确保 Consumer Key 具备 edit_products 能力（通常需管理员或编辑角色）。
- 启用调试日志：在 API(...) 初始化时添加 wp_api=True, verify_ssl=False（仅开发环境）并开启 logging，便于排查网络层问题。
- 响应解析逻辑：成功响应中 response["update"] 是更新后的产品对象列表；若为空数组，大概率是请求体格式错误或部分产品 ID 不存在。
遵循以上规范，即可彻底解决“无响应、无报错、不更新”的顽疾，实现稳定高效的 WooCommerce 批量商品管理。
