京東開放平台實戰③:商品查詢與詳情 API 全解析
引言
在前兩篇文章中,我們分別介紹了「如何註冊 + 獲取憑證 + 調試接口」以及「如何進行簽名 + 授權」的操作流程。從本篇開始,將正式進入京東開放平台的實戰應用階段,首先聚焦於商品模組,深入講解兩個最常用、也最具代表性的接口:
jingdong.ware.productbigfield.get
:查詢單個商品的詳細資訊;jingdong.search.sku.list
:商品列表查詢接口,支援關鍵詞搜尋、篩選、分頁等功能。
本文將提供完整的請求參數說明、返回結構解析以及實際程式碼範例,幫助開發者快速掌握商品模組的核心能力,為後續功能拓展奠定基礎。
一、商品詳情接口:jingdong.ware.productbigfield.get
該接口用於查詢指定商品(SKU 或 SPU)的詳細資料,涵蓋商品標題、主圖、價格、庫存、品牌、分類、屬性等豐富資訊,是展示商品詳情頁的基礎接口之一。
1. 接口地址
沙箱環境:
https://sandbox-api.jd.com/routerjson
正式環境:
https://api.jd.com/routerjson
開發初期建議使用沙箱環境進行調試,確認請求與回應邏輯正常後再切換至正式環境。
2. 請求參數
參數名 | 類型 | 是否必填 | 示例值 | 說明 |
---|---|---|---|---|
| string | 是 |
| 指定調用的 API 方法名稱 |
| string | 是 | — | 開發者應用的 Key |
| string | 是 | — | 授權獲取的 OAuth2 令牌 |
| string | 是 |
| 當前時間,格式為 |
| string | 是 |
| API 版本號 |
| string | 是 | — | 請參考上篇生成簽名的規則 |
| string | 是 |
| JSON 格式的業務請求參數 |
3. 回傳欄位(示例結構)
{"jingdong_ware_productbigfield_get_responce": {
"code": 0,
"skuId": 123456789,
"title": "Apple iPhone 15 Pro",
"price": "7999.00",
"stock": 125,
"brand": "Apple",
"category": "手機",
"images": ["https://img.jd.com/image1.jpg", "https://img.jd.com/image2.jpg"],
"attributes": [
{"key": "螢幕尺寸", "value": "6.1吋"},
{"key": "儲存容量", "value": "256GB"},
{"key": "處理器", "value": "A17 Pro"},
{"key": "顏色", "value": "銀色"}
]
}
}
商品屬性通常是動態欄位,會依據不同商品類別有所差異。
4. 調用範例(Python)
import requestsimport json
from your_sign_utils import generate_sign
params = {
"method": "jingdong.ware.productbigfield.get",
"app_key": YOUR_APP_KEY,
"access_token": YOUR_ACCESS_TOKEN,
"timestamp": "2025-05-01 10:00:00",
"v": "2.0",
"360buy_param_json": json.dumps({"skuId": 123456789})
}
sign = generate_sign(params, YOUR_APP_SECRET)
params["sign"] = sign
response = requests.get("https://api.jd.com/routerjson", params=params)
print(response.json())
建議針對不同回應錯誤進行異常處理,提升系統穩定性。
二、商品列表接口:jingdong.search.sku.list
此接口支援按關鍵詞、品牌、分類等條件搜索商品集合,回傳商品摘要資訊,適用於構建搜尋結果頁、商品列表頁等場景,是電商前台的核心數據來源之一。
1. 請求參數說明
參數名 | 示例值 | 說明 |
---|---|---|
| 1 | 頁碼,從 1 開始 |
| 20 | 每頁筆數,最大支援 50 |
| 737 | 一級分類 ID,例如手機類為 737 |
| 14026 | 品牌 ID(可選) |
| "iPhone" | 搜尋關鍵詞,可支援模糊搜尋、複數詞組等 |
整體包裝於 360buy_param_json
:
{"page": 1,
"pageSize": 10,
"keyword": "iPhone",
"cid1": 737
}
2. 回應欄位(結構示例)
{"jingdong_search_sku_list_responce": {
"code": 0,
"result": {
"totalItem": 200,
"skuList": [
{
"skuId": 123456,
"name": "Apple iPhone 15",
"price": "7999.00",
"imagePath": "https://img.jd.com/iphone.jpg"
},
{
"skuId": 123457,
"name": "Apple iPhone 15 Pro Max",
"price": "9999.00",
"imagePath": "https://img.jd.com/iphone_pro.jpg"
}
]
}
}
}
每筆商品資料僅包含基本資訊,詳細內容需使用 productbigfield.get
進一步獲取。
3. 分頁處理建議
每頁最大筆數為 50,建議根據使用情況設定為 20~50。
使用回應欄位
totalItem
來計算總頁數,例如totalItem ÷ pageSize
。若需批量拉取商品,建議實作分頁迴圈與錯誤重試機制,避免一次性拉取過多導致限流。
三、實戰技巧與建議
先列表再詳情
用戶在搜尋商品時,先調用search.sku.list
快速獲取列表,點擊商品後再使用productbigfield.get
獲取詳情資訊,有效降低 API 請求壓力。商品圖片尺寸優化
回傳的imagePath
支援在圖片 URL 尾部加上樣式後綴來裁切大小,例如:https://img.jd.com/path.jpg!cc_290x290
可依據前端顯示需求設計不同尺寸圖。
減少頻繁拉取全量數據
商品清單變化頻率較低,建議配合商品變更通知、時間戳增量拉取等策略,避免無效重複查詢,減少 API 限流風險。多條件過濾提升精準度
除關鍵詞外,建議增加分類、品牌等維度條件組合使用,提升搜尋結果準確性。
四、錯誤碼對照與排查指引
錯誤碼 | 問題說明 | 解決方案 |
---|---|---|
3001 | 請求參數錯誤或非法 JSON 格式 | 確認 |
401 | access_token 無效 | 需要重新授權並刷新令牌 |
403 | 接口訪問權限不足 | 前往京東應用後台,申請相應接口權限 |
500 | 系統內部錯誤 | 稍後重試,或聯繫京東開發者支援 |
建議在系統中加入錯誤碼日誌記錄,方便問題快速定位與修復。
五、總結與下期預告
本篇文章我們已完成以下內容的學習與實踐:
熟悉並實作了京東開放平台的商品詳情與列表接口;
掌握了如何通過
360buy_param_json
傳遞 JSON 結構參數;瞭解了分頁查詢、商品圖片處理、分類與品牌篩選等應用技巧;
搭建了從搜尋 → 列表 → 詳情的完整商品展示流程。
Articles related to APIs :
如您需要方便快速使用 Jingdong API 可聯係我們:support@luckdata.com