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

參數名

類型

是否必填

示例值

說明

method

string

jingdong.ware.productbigfield.get

指定調用的 API 方法名稱

app_key

string

開發者應用的 Key

access_token

string

授權獲取的 OAuth2 令牌

timestamp

string

2025-04-30 14:10:00

當前時間,格式為 yyyy-MM-dd HH:mm:ss

v

string

2.0

API 版本號

sign

string

請參考上篇生成簽名的規則

360buy_param_json

string

{"skuId":123456789}

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

參數名

示例值

說明

page

1

頁碼,從 1 開始

pageSize

20

每頁筆數,最大支援 50

cid1

737

一級分類 ID,例如手機類為 737

brandId

14026

品牌 ID(可選)

keyword

"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

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

三、實戰技巧與建議

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

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

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

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

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

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

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

錯誤碼

問題說明

解決方案

3001

請求參數錯誤或非法 JSON 格式

確認 360buy_param_json 是否格式正確

401

access_token 無效

需要重新授權並刷新令牌

403

接口訪問權限不足

前往京東應用後台,申請相應接口權限

500

系統內部錯誤

稍後重試,或聯繫京東開發者支援

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

五、總結與下期預告

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

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

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

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

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

Articles related to APIs :

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