一、API 基礎概覽
Wildberries 提供 RESTful 風格 API，通過 HTTP 協(xié)議與賣家系統(tǒng)集成，支持自動化管理店鋪、獲取實時數(shù)據(jù)和生成分析報告。官方文檔以 Swagger (OpenAPI) 格式提供，可導入 Postman 等工具或生成客戶端代碼。

核心優(yōu)勢：

全流程自動化：訂單處理、庫存管理、價格更新
實時數(shù)據(jù)獲?。轰N售統(tǒng)計、客戶反饋、搜索分析
系統(tǒng)集成：與 ERP/WMS/CRM 無縫對接
合規(guī)安全：官方認證，避免反爬蟲限制
二、API 認證與令牌獲取
1?? 獲取 API 令牌（必選）
操作步驟：

登錄賣家中心：https://seller.wildberries.ru
點擊賬戶名 → 設置 (Settings) → API 集成 (Access to API)
點擊 "創(chuàng)建新令牌 (Create new token)"
輸入令牌名稱，選擇權限范圍
可選：Test scope（僅測試環(huán)境）、Read only（只讀權限）
建議：選擇所需功能的最小權限組合，提高安全性
點擊創(chuàng)建，復制生成的令牌（僅顯示一次，保存好?。?br /> 令牌特性：

JWT 格式，有效期180 天，到期需重新生成
可創(chuàng)建多個令牌，分別用于不同功能（如報表、訂單）
2?? 使用令牌發(fā)起請求
在請求頭中添加：

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 - 更新訂單狀態(tài)
GET /api/v1/order-stickers/{orderId} - 獲取訂單標簽
商品管理：

GET /api/v1/products - 獲取商品目錄
POST /api/v1/products - 創(chuàng)建新產(chǎn)品
PUT /api/v1/products/{nmId} - 更新商品信息
2?? 分析服務 (Analytics API)
核心端點：

產(chǎn)品統(tǒng)計：

POST /api/v2/nm-report/detail - 獲取產(chǎn)品詳情統(tǒng)計（按 nmID / 品牌 / 標簽）
POST /api/v2/nm-report/grouped - 獲取分組產(chǎn)品統(tǒng)計openapi.wildberries.ru
搜索分析（需Jam 訂閱）：

POST /api/v2/search-report/report - 獲取搜索報告（關鍵詞排名、轉化率）
POST /api/v2/search-report/product/search-texts - 獲取產(chǎn)品熱門搜索詞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 - 回復評價
文檔服務：生成發(fā)票、裝箱單等商業(yè)文檔
四、API 使用關鍵技巧
1?? 速率限制與優(yōu)化
限制規(guī)則（部分示例）：

大多數(shù)端點：每分鐘 300 次請求，建議間隔≥200ms
分析 API：每分鐘 3 次請求，非常嚴格openapi.wildberries.ru
特殊端點：如 /ping，每 30 秒 3 次
響應頭中的限制信息：

plaintext

X-Ratelimit-Remaining: 99 # 剩余可立即發(fā)送的請求數(shù)
X-Ratelimit-Retry: 2 # 需等待的秒數(shù)（429錯誤時）
X-Ratelimit-Limit: 100 # 最大突發(fā)請求數(shù)
X-Ratelimit-Reset: 30 # 重置時間（秒）
AI寫代碼
最佳實踐：

使用指數(shù)退避策略處理 429 錯誤
分批處理：將大量請求拆分為多個批次，添加合理間隔
監(jiān)控響應頭，動態(tài)調整請求頻率
2?? 數(shù)據(jù)分頁處理
分頁參數(shù)（多數(shù)端點支持）：

limit：每頁結果數(shù)（最大通常為 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?? 數(shù)據(jù)過濾與篩選
通用過濾參數(shù)：

dateFrom/dateTo：時間范圍
nmIds：商品 ID 列表（如：?nmIds=123,456）
statuses：狀態(tài)列表（如訂單狀態(tài)）
priceFrom/priceTo：價格區(qū)間openapi.wildberries.ru
五、常見錯誤處理
1?? 錯誤分類與解決方案
4xx 客戶端錯誤：

401 Unauthorized：無效令牌或令牌過期→ 重新驗證令牌，必要時重新生成

403 Forbidden：權限不足→ 檢查令牌權限，確認是否有訪問該端點的權限

404 Not Found：端點或資源不存在→ 檢查 URL 拼寫，確認 API 版本是否正確

429 Too Many Requests：請求頻率過高→ 應用退避策略：等待X-Ratelimit-Retry秒后重試

5xx 服務器錯誤：

臨時問題，建議重試（遵循退避原則）
記錄錯誤，聯(lián)系 Wildberries 支持（如有商業(yè)合作）
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 規(guī)范，包括請求 / 響應示例

六、實戰(zhàn)示例：獲取銷售統(tǒng)計
1?? 獲取產(chǎn)品銷售詳情
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", # 時區(qū)（可選，默認莫斯科）
"orderBy": {
"field": "orders", # 排序字段（如訂單數(shù)、瀏覽量）
"order": "desc" # 排序方向
}
}
AI寫代碼

響應示例：

json

{
"data": [
{
"nmId": 123456,
"name": "Product Name",
"openCard": 1500, # 卡片瀏覽量
"addToCart": 300, # 添加到購物車
"orders": 50, # 訂單數(shù)
"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, # 搜索次數(shù)
"openCard": 20, # 點擊卡片數(shù)
"orders": 5 # 訂單數(shù)
}
]
}
AI寫代碼

七、最佳實踐與注意事項
1?? 性能優(yōu)化建議
批量處理：

訂單 / 庫存更新：使用批量 API，減少請求次數(shù)
數(shù)據(jù)獲?。涸O置合理的 limit（建議 50-100），分批獲取
緩存策略：

對不常變的基礎數(shù)據(jù)（如商品類目、國家列表）設置緩存
分析數(shù)據(jù)可按天 / 周緩存，避免頻繁請求
異步處理：

使用支持異步的 HTTP 客戶端（如 Python 的 aiohttp）
批量任務并行處理，提高效率
2?? 安全與合規(guī)
最小權限原則：為不同功能創(chuàng)建獨立令牌，僅賦予必要權限
定期輪換：令牌到期前（建議每 120 天）生成新令牌，廢棄舊令牌
錯誤處理：
記錄所有 API 錯誤，監(jiān)控錯誤率
對 429 錯誤實現(xiàn)智能退避，避免賬號被臨時封禁
3?? 實用工具推薦
API 調試：Postman（直接導入 Swagger 文檔）
代碼生成：使用 Swagger CodeGen 生成各語言客戶端
數(shù)據(jù)可視化：將 API 數(shù)據(jù)接入 BI 工具（如 Tableau、Power BI）
監(jiān)控：設置 API 調用監(jiān)控，預警異常流量
八、下一步行動建議
立即獲取令牌：登錄賣家中心創(chuàng)建 API 令牌，保存好
測試連接：使用 /ping 端點驗證令牌有效性
選擇起點：
訂單管理：自動化訂單處理流程
數(shù)據(jù)分析：獲取銷售報告，優(yōu)化產(chǎn)品策略
庫存同步：實現(xiàn)實時庫存更新，避免超賣
小規(guī)模測試：先調用簡單端點，熟悉 API 響應結構
系統(tǒng)集成：與現(xiàn)有 ERP/WMS 系統(tǒng)對接，實現(xiàn)全鏈路自動化

審核編輯 黃宇