?

在電商系統開發、價格監控、競品分析等場景中，獲取商品的原始詳情數據是基礎且關鍵的一環。京東作為國內領先的電商平臺，提供了相應的API接口供開發者調用。本文將介紹如何使用京東開放平臺的API接口獲取商品詳情原數據。

一、 接口基本說明

接口地址： 通常為 https://api.jd.com/routerjson (具體路徑請以京東開放平臺最新文檔為準)

HTTP方法： GET 或 POST

認證方式： 需要調用方在京東開放平臺注冊成為開發者，創建應用并獲得 app_key 和 app_secret。調用時需進行簽名認證，通常采用 OAuth 2.0 或京東自定義的簽名算法（如 JOS 簽名）。

數據格式： 請求和響應數據通常采用 JSON 格式。

二、 核心請求參數

調用商品詳情接口，以下參數是必需的：

method： 指定要調用的API方法名。例如，獲取商品詳情的方法可能類似于 jingdong.ware.read.findWareById 或 biz.product.getdetail (請務必查閱官方文檔確認最新方法名)。

access_token： 用戶授權后獲得的訪問令牌（對于需要用戶授權的場景）。對于部分基礎商品信息查詢，可能只需應用級授權。

app_key： 開發者在京東開放平臺創建應用后獲得的 App Key。

timestamp： 請求發起的時間戳，格式通常為 yyyy-MM-dd HH:mm:ss。

v： API版本號，如 2.0。

sign： 根據請求參數、app_secret 和特定簽名規則生成的簽名值，用于驗證請求的合法性。簽名算法需嚴格遵循京東開放平臺文檔。

業務參數： 具體到商品詳情查詢，最核心的業務參數是商品的唯一標識：

sku_id： 京東商品的SKU ID (庫存量單位編號)，是標識具體商品的最常用ID。例如 123456789。

或者 ware_id： 在某些接口中可能使用商品ID (Ware ID)。

三、 返回數據結構（示例）

一個成功的API調用響應將包含商品詳情的詳細信息。數據結構龐大且可能因接口版本和商品類目不同而有差異，但通常會包含以下核心字段：

{
  "code": "0", // 響應碼，0表示成功
  "message": "success", // 響應消息
  "result": {
    "skuId": 123456789, // 商品SKU ID
    "wareId": 987654321, // 商品ID (可能同skuId或不同)
    "name": "【京東自營】XX品牌 高性能智能手機 8GB+256GB 曜石黑", // 商品名稱
    "brandName": "XX品牌", // 品牌名稱
    "productArea": "中國", // 產地
    "upc": "6921234567890", // UPC編碼
    "saleUnit": "臺", // 銷售單位
    "weight": "0.2", // 重量 (kg)
    "packListing": "手機 x1, 充電器 x1, 數據線 x1, 說明書 x1", // 包裝清單
    "wreadMe": "請閱讀說明書...", // 使用說明/注意事項
    "imagePath": "https://imgX.jd.com/xxxx.jpg", // 主圖URL
    "imageList": [ // 商品圖列表
      "https://imgX.jd.com/xxxx_1.jpg",
      "https://imgX.jd.com/xxxx_2.jpg"
    ],
    "priceInfo": {
      "price": 3999.00, // 京東價
      "jdPrice": 3999.00, // 同京東價
      "marketPrice": 4299.00, // 市場價/原價
      // 可能還有plus價格等
    },
    "categoryId": 9987, // 類目ID
    "categoryPath": "手機通訊>手機>智能手機", // 類目路徑
    "shopInfo": {
      "shopId": 1000000123, // 店鋪ID
      "shopName": "XX品牌京東自營旗艦店", // 店鋪名稱
      "score": "4.9", // 店鋪評分
      "logisticsScore": "4.8" // 物流評分
    },
    "baseBigFieldInfo": {
      // 商品基礎屬性集合 (鍵值對形式)
      "商品毛重": "0.22kg",
      "商品產地": "中國大陸",
      "CPU型號": "驍龍8 Gen2",
      "運行內存": "8GB",
      "機身存儲": "256GB",
      // ... 更多屬性
    },
    "introductionHtml": "...", // 商品詳情介紹 (HTML格式)
    "introductionMobiles": "...", // 移動端商品詳情 (HTML格式)
    "wareQD": "商品特色描述..." // 商品亮點
  }
}

四、 調用流程與注意事項

注冊開發者賬號： 訪問京東開放平臺，完成開發者注冊。

創建應用： 在控制臺創建應用，獲取 app_key 和 app_secret。

閱讀文檔： 仔細查閱目標商品詳情API的 最新 官方文檔，確認準確的 method 名稱、必需參數、可選參數、請求方式、簽名算法。

構造請求：

設置 method, app_key, timestamp, v 等固定參數。

設置業務參數 sku_id 或 ware_id。

根據官方簽名算法（如 JOS 簽名），使用 app_secret 和所有請求參數（按規則排序后）生成 sign。

將參數組裝成 Query String (GET) 或 Form Data/JSON Body (POST)。

發送請求： 使用 HTTP Client (如 HttpURLConnection, OkHttp, Requests 等) 發送請求。

處理響應：

檢查 code 是否為 0 (成功)。

解析 result 對象，獲取所需商品數據。

處理可能的錯誤碼（如簽名錯誤 1001、參數錯誤 1002、無權限 1003、頻率限制 1004 等）。

注意事項：

權限與授權： 確保你的應用有調用該API的權限。部分敏感數據可能需要商家或用戶授權 (access_token)。

頻率限制： 京東API有嚴格的調用頻率限制，需遵守平臺規則，避免因頻繁調用被封禁。

數據時效性： API返回的數據是調用時刻的快照，商品價格、庫存等信息可能實時變化。

數據使用合規： 獲取的數據需遵守京東開放平臺的數據使用協議，不得用于非法用途。

HTTPS： 所有請求均應通過 HTTPS 協議發送。

簽名安全： app_secret 是核心機密，務必妥善保管，切勿泄露。

五、 簡單調用示例 (Python偽代碼)

import requests
import hashlib
import time
import urllib.parse

app_key = 'YOUR_APP_KEY'
app_secret = 'YOUR_APP_SECRET'  # 注意保密！
method = 'jingdong.ware.read.findWareById'  # 假設的方法名
sku_id = '123456789'
timestamp = time.strftime('%Y-%m-%d %H:%M:%S', time.localtime())
v = '2.0'

# 1. 準備參數 (除 sign 外)
params = {
    'method': method,
    'app_key': app_key,
    'timestamp': timestamp,
    'v': v,
    'sku_id': sku_id
}

# 2. 按規則排序參數 (如字母序)
sorted_params = sorted(params.items(), key=lambda x: x[0])

# 3. 拼接字符串 (例如: app_key=xxx&method=yyy&...&sku_id=zzz + app_secret)
sign_str = app_secret
for k, v in sorted_params:
    sign_str += k + v
sign_str += app_secret

# 4. 計算 MD5 (或 SHA, 以文檔為準)
sign = hashlib.md5(sign_str.encode('utf-8')).hexdigest().upper()

# 5. 添加 sign 到參數
params['sign'] = sign

# 6. 發送請求 (GET 示例)
response = requests.get('https://api.jd.com/routerjson', params=params)

# 7. 處理響應
if response.status_code == 200:
    data = response.json()
    if data['code'] == '0':
        product_info = data['result']
        print(f"商品名稱: {product_info['name']}")
        print(f"京東價: ￥{product_info['priceInfo']['price']}")
        # ... 處理其他數據
    else:
        print(f"API錯誤! code: {data['code']}, message: {data['message']}")
else:
    print(f"HTTP請求失敗! 狀態碼: {response.status_code}")

六、 總結

京東平臺提供的商品詳情API接口是獲取商品原始數據的有效途徑。開發者在使用前需仔細閱讀官方文檔，嚴格遵守調用規范、簽名算法和頻率限制，并確保數據使用的合法性。通過合理利用此API，可以高效地構建電商數據服務、分析系統等應用。如有任何疑問，歡迎大家留言探討。

?審核編輯 黃宇