Wildberries API 全解析

一、API 基础概览
Wildberries 提供 RESTful 风格 API，通过 HTTP 协议与卖家系统集成，支持自动化管理店铺、获取实时数据和生成分析报告。官方文档以 Swagger (OpenAPI) 格式提供，可导入 Postman 等工具或生成客户端代码。

核心优势：

全流程自动化：订单处理、库存管理、价格更新
实时数据获取：销售统计、客户反馈、搜索分析
系统集成：与 ERP/WMS/CRM 无缝对接
合规安全：官方认证，避免反爬虫限制
二、API 认证与令牌获取
1️⃣ 获取 API 令牌（必选）
操作步骤：

登录卖家中心：https://seller.wildberries.ru
点击账户名 → 设置 (Settings) → API 集成 (Access to API)
点击 "创建新令牌 (Create new token)"
输入令牌名称，选择权限范围
可选：Test scope（仅测试环境）、Read only（只读权限）
建议：选择所需功能的最小权限组合，提高安全性
点击创建，复制生成的令牌（仅显示一次，保存好！）
令牌特性：

JWT 格式，有效期180 天，到期需重新生成
可创建多个令牌，分别用于不同功能（如报表、订单）
2️⃣ 使用令牌发起请求
在请求头中添加：

plaintext

Authorization: Bearer
AI写代码
示例（Python）：

python

运行

import requests

token = "your_api_token"
headers = {"Authorization": f"Bearer {token}"}
url = "https://suppliers-api.wildberries.ru/api/v1/orders"

response = requests.get(url, headers=headers)
print(response.json())
AI写代码
三、核心 API 服务与端点
Wildberries 提供多个独立 API 服务，按功能划分：

1️⃣ 市场服务 (Marketplace API)
核心端点：

订单管理：

GET /api/v1/orders - 获取订单列表
POST /api/v1/orders/{orderId}/status - 更新订单状态
GET /api/v1/order-stickers/{orderId} - 获取订单标签
商品管理：

GET /api/v1/products - 获取商品目录
POST /api/v1/products - 创建新产品
PUT /api/v1/products/{nmId} - 更新商品信息
2️⃣ 分析服务 (Analytics API)
核心端点：

产品统计：

POST /api/v2/nm-report/detail - 获取产品详情统计（按 nmID / 品牌 / 标签）
POST /api/v2/nm-report/grouped - 获取分组产品统计openapi.wildberries.ru
搜索分析（需Jam 订阅）：

POST /api/v2/search-report/report - 获取搜索报告（关键词排名、转化率）
POST /api/v2/search-report/product/search-texts - 获取产品热门搜索词openapi.wildberries.ru
3️⃣ 其他关键服务
库存服务：GET /api/v2/stocks - 获取库存，POST /api/v2/stocks - 更新库存
价格服务：PUT /api/v1/prices - 更新价格，GET /api/v1/prices - 获取价格
反馈服务：GET /api/v1/feedbacks - 获取客户评价，POST /api/v1/feedbacks - 回复评价
文档服务：生成发票、装箱单等商业文档
四、API 使用关键技巧
1️⃣ 速率限制与优化
限制规则（部分示例）：

大多数端点：每分钟 300 次请求，建议间隔≥200ms
分析 API：每分钟 3 次请求，非常严格openapi.wildberries.ru
特殊端点：如 /ping，每 30 秒 3 次
响应头中的限制信息：

plaintext

X-Ratelimit-Remaining: 99    # 剩余可立即发送的请求数
X-Ratelimit-Retry: 2         # 需等待的秒数（429错误时）
X-Ratelimit-Limit: 100       # 最大突发请求数
X-Ratelimit-Reset: 30        # 重置时间（秒）
AI写代码
最佳实践：

使用指数退避策略处理 429 错误
分批处理：将大量请求拆分为多个批次，添加合理间隔
监控响应头，动态调整请求频率
2️⃣ 数据分页处理
分页参数（多数端点支持）：

limit：每页结果数（最大通常为 100）
offset/skip：偏移量，从第几条开始
sort：排序字段
order：排序方向（asc/desc）
示例 URL：

plaintext

https://suppliers-api.wildberries.ru/api/v1/orders?limit=50&offset=100&sort=createdAt&order=desc
AI写代码
处理大结果集：

python

运行

# 伪代码：获取所有订单
offset = 0
limit = 100
all_orders = []

while True:
   response = requests.get(f"{url}?limit={limit}&offset={offset}", headers=headers)
   orders = response.json().get("data", [])
   
   if not orders:
       break
   
   all_orders.extend(orders)
   offset += limit
AI写代码

3️⃣ 数据过滤与筛选
通用过滤参数：

dateFrom/dateTo：时间范围
nmIds：商品 ID 列表（如：?nmIds=123,456）
statuses：状态列表（如订单状态）
priceFrom/priceTo：价格区间openapi.wildberries.ru
五、常见错误处理
1️⃣ 错误分类与解决方案
4xx 客户端错误：

401 Unauthorized：无效令牌或令牌过期→ 重新验证令牌，必要时重新生成

403 Forbidden：权限不足→ 检查令牌权限，确认是否有访问该端点的权限

404 Not Found：端点或资源不存在→ 检查 URL 拼写，确认 API 版本是否正确

429 Too Many Requests：请求频率过高→ 应用退避策略：等待X-Ratelimit-Retry秒后重试

5xx 服务器错误：

临时问题，建议重试（遵循退避原则）
记录错误，联系 Wildberries 支持（如有商业合作）
2️⃣ 调试技巧
使用 **/ping** 端点测试连接与令牌有效性（每个服务都有独立 ping）：

plaintext

# 市场服务
https://marketplace-api.wildberries.ru/ping

# 分析服务
https://seller-analytics-api.wildberries.ru/ping
AI写代码
成功返回：{"status": "OK"}

利用Swagger 文档（https://openapi.wb.ru）查看完整 API 规范，包括请求 / 响应示例

六、实战示例：获取销售统计
1️⃣ 获取产品销售详情
API 端点：

plaintext

POST /api/v2/nm-report/detail
Host: https://seller-analytics-api.wildberries.ru
AI写代码
请求示例：

json

{
 "nmIds": [123456],  # 商品ID（必填）
 "period": {
   "start": "2025-11-01",  # 开始日期（必填）
   "end": "2025-11-30"    # 结束日期（必填）
 },
 "timezone": "Europe/Moscow",  # 时区（可选，默认莫斯科）
 "orderBy": {
   "field": "orders",      # 排序字段（如订单数、浏览量）
   "order": "desc"         # 排序方向
 }
}
AI写代码

响应示例：

json

{
 "data": [
   {
     "nmId": 123456,
     "name": "Product Name",
     "openCard": 1500,     # 卡片浏览量
     "addToCart": 300,     # 添加到购物车
     "orders": 50,         # 订单数
     "ordersSumRub": 15000 # 订单总金额（卢布）
   }
 ]
}
AI写代码

2️⃣ 获取搜索分析（需 Jam 订阅）
API 端点：

plaintext

POST /api/v2/search-report/product/search-texts
Host: https://seller-analytics-api.wildberries.ru
AI写代码
请求示例：

json

{
 "nmIds": [123456],      # 商品ID（必填）
 "currentPeriod": {      # 当前分析周期
   "start": "2025-11-01",
   "end": "2025-11-30"
 },
 "topOrderBy": "orders", # 排序方式：openCard/orders/cartToOrder等
 "limit": 10             # 返回最多10个关键词
}
AI写代码
响应示例：

json

{
 "data": [
   {
     "text": "product keyword",  # 搜索关键词
     "hits": 100,                # 搜索次数
     "openCard": 20,             # 点击卡片数
     "orders": 5                 # 订单数
   }
 ]
}
AI写代码

七、最佳实践与注意事项
1️⃣ 性能优化建议
批量处理：

订单 / 库存更新：使用批量 API，减少请求次数
数据获取：设置合理的 limit（建议 50-100），分批获取
缓存策略：

对不常变的基础数据（如商品类目、国家列表）设置缓存
分析数据可按天 / 周缓存，避免频繁请求
异步处理：

使用支持异步的 HTTP 客户端（如 Python 的 aiohttp）
批量任务并行处理，提高效率
2️⃣ 安全与合规
最小权限原则：为不同功能创建独立令牌，仅赋予必要权限
定期轮换：令牌到期前（建议每 120 天）生成新令牌，废弃旧令牌
错误处理：
记录所有 API 错误，监控错误率
对 429 错误实现智能退避，避免账号被临时封禁
3️⃣ 实用工具推荐
API 调试：Postman（直接导入 Swagger 文档）
代码生成：使用 Swagger CodeGen 生成各语言客户端
数据可视化：将 API 数据接入 BI 工具（如 Tableau、Power BI）
监控：设置 API 调用监控，预警异常流量
八、下一步行动建议
立即获取令牌：登录卖家中心创建 API 令牌，保存好
测试连接：使用 /ping 端点验证令牌有效性
选择起点：
订单管理：自动化订单处理流程
数据分析：获取销售报告，优化产品策略
库存同步：实现实时库存更新，避免超卖
小规模测试：先调用简单端点，熟悉 API 响应结构
系统集成：与现有 ERP/WMS 系统对接，实现全链路自动化

审核编辑 黄宇