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

核心優(yōu)勢(shì)：

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

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

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

plaintext

Authorization: Bearer
AI寫代碼
示例（Python）：

python

運(yùn)行

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 服務(wù)與端點(diǎn)
Wildberries 提供多個(gè)獨(dú)立 API 服務(wù)，按功能劃分：

1?? 市場(chǎng)服務(wù) (Marketplace API)
核心端點(diǎn)：

訂單管理：

GET /api/v1/orders - 獲取訂單列表
POST /api/v1/orders/{orderId}/status - 更新訂單狀態(tài)
GET /api/v1/order-stickers/{orderId} - 獲取訂單標(biāo)簽
商品管理：

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

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

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

POST /api/v2/search-report/report - 獲取搜索報(bào)告（關(guān)鍵詞排名、轉(zhuǎn)化率）
POST /api/v2/search-report/product/search-texts - 獲取產(chǎn)品熱門搜索詞openapi.wildberries.ru
3?? 其他關(guān)鍵服務(wù)
庫(kù)存服務(wù)：GET /api/v2/stocks - 獲取庫(kù)存，POST /api/v2/stocks - 更新庫(kù)存
價(jià)格服務(wù)：PUT /api/v1/prices - 更新價(jià)格，GET /api/v1/prices - 獲取價(jià)格
反饋服務(wù)：GET /api/v1/feedbacks - 獲取客戶評(píng)價(jià)，POST /api/v1/feedbacks - 回復(fù)評(píng)價(jià)
文檔服務(wù)：生成發(fā)票、裝箱單等商業(yè)文檔
四、API 使用關(guān)鍵技巧
1?? 速率限制與優(yōu)化
限制規(guī)則（部分示例）：

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

plaintext

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

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

limit：每頁(yè)結(jié)果數(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寫代碼
處理大結(jié)果集：

python

運(yùn)行

# 偽代碼：獲取所有訂單
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ù)過(guò)濾與篩選
通用過(guò)濾參數(shù)：

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

401 Unauthorized：無(wú)效令牌或令牌過(guò)期→ 重新驗(yàn)證令牌，必要時(shí)重新生成

403 Forbidden：權(quán)限不足→ 檢查令牌權(quán)限，確認(rèn)是否有訪問(wèn)該端點(diǎn)的權(quán)限

404 Not Found：端點(diǎn)或資源不存在→ 檢查 URL 拼寫，確認(rèn) API 版本是否正確

429 Too Many Requests：請(qǐng)求頻率過(guò)高→ 應(yīng)用退避策略：等待X-Ratelimit-Retry秒后重試

5xx 服務(wù)器錯(cuò)誤：

臨時(shí)問(wèn)題，建議重試（遵循退避原則）
記錄錯(cuò)誤，聯(lián)系 Wildberries 支持（如有商業(yè)合作）
2?? 調(diào)試技巧
使用 **/ping** 端點(diǎn)測(cè)試連接與令牌有效性（每個(gè)服務(wù)都有獨(dú)立 ping）：

plaintext

# 市場(chǎng)服務(wù)
https://marketplace-api.wildberries.ru/ping

# 分析服務(wù)
https://seller-analytics-api.wildberries.ru/ping
AI寫代碼
成功返回：{"status": "OK"}

利用Swagger 文檔（https://openapi.wb.ru）查看完整 API 規(guī)范，包括請(qǐng)求 / 響應(yīng)示例

六、實(shí)戰(zhàn)示例：獲取銷售統(tǒng)計(jì)
1?? 獲取產(chǎn)品銷售詳情
API 端點(diǎn)：

plaintext

POST /api/v2/nm-report/detail
Host: https://seller-analytics-api.wildberries.ru
AI寫代碼
請(qǐng)求示例：

json

{
"nmIds": [123456], # 商品ID（必填）
"period": {
"start": "2025-11-01", # 開始日期（必填）
"end": "2025-11-30" # 結(jié)束日期（必填）
},
"timezone": "Europe/Moscow", # 時(shí)區(qū)（可選，默認(rèn)莫斯科）
"orderBy": {
"field": "orders", # 排序字段（如訂單數(shù)、瀏覽量）
"order": "desc" # 排序方向
}
}
AI寫代碼

響應(yīng)示例：

json

{
"data": [
{
"nmId": 123456,
"name": "Product Name",
"openCard": 1500, # 卡片瀏覽量
"addToCart": 300, # 添加到購(gòu)物車
"orders": 50, # 訂單數(shù)
"ordersSumRub": 15000 # 訂單總金額（盧布）
}
]
}
AI寫代碼

2?? 獲取搜索分析（需 Jam 訂閱）
API 端點(diǎn)：

plaintext

POST /api/v2/search-report/product/search-texts
Host: https://seller-analytics-api.wildberries.ru
AI寫代碼
請(qǐng)求示例：

json

{
"nmIds": [123456], # 商品ID（必填）
"currentPeriod": { # 當(dāng)前分析周期
"start": "2025-11-01",
"end": "2025-11-30"
},
"topOrderBy": "orders", # 排序方式：openCard/orders/cartToOrder等
"limit": 10 # 返回最多10個(gè)關(guān)鍵詞
}
AI寫代碼
響應(yīng)示例：

json

{
"data": [
{
"text": "product keyword", # 搜索關(guān)鍵詞
"hits": 100, # 搜索次數(shù)
"openCard": 20, # 點(diǎn)擊卡片數(shù)
"orders": 5 # 訂單數(shù)
}
]
}
AI寫代碼

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

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

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

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

審核編輯 黃宇