一、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 <your_token>
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 系统对接，实现全链路自动化
