京東開放平台實戰③：商品查詢與詳情 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. 請求參數

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 requests
import 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. 請求參數說明

整體包裝於 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。

• 若需批量拉取商品，建議實作分頁迴圈與錯誤重試機制，避免一次性拉取過多導致限流。

三、實戰技巧與建議

1. 先列表再詳情
   用戶在搜尋商品時，先調用 search.sku.list 快速獲取列表，點擊商品後再使用 productbigfield.get 獲取詳情資訊，有效降低 API 請求壓力。

2. 商品圖片尺寸優化
   回傳的 imagePath 支援在圖片 URL 尾部加上樣式後綴來裁切大小，例如：

   https://img.jd.com/path.jpg!cc_290x290
   

   可依據前端顯示需求設計不同尺寸圖。

3. 減少頻繁拉取全量數據
   商品清單變化頻率較低，建議配合商品變更通知、時間戳增量拉取等策略，避免無效重複查詢，減少 API 限流風險。

4. 多條件過濾提升精準度
   除關鍵詞外，建議增加分類、品牌等維度條件組合使用，提升搜尋結果準確性。

四、錯誤碼對照與排查指引

建議在系統中加入錯誤碼日誌記錄，方便問題快速定位與修復。

五、總結與下期預告

本篇文章我們已完成以下內容的學習與實踐：

• 熟悉並實作了京東開放平台的商品詳情與列表接口；

• 掌握了如何通過 360buy_param_json 傳遞 JSON 結構參數；

• 瞭解了分頁查詢、商品圖片處理、分類與品牌篩選等應用技巧；

• 搭建了從搜尋 → 列表 → 詳情的完整商品展示流程。

Articles related to APIs :

• JD API Authentication and Signature Mechanism: A Complete Guide for Secure Integration

• Complete Guide to Accessing the JD Open Platform (JOS)

如您需要方便快速使用 Jingdong API 可聯係我們：support@luckdata.com