?

在電商系統(tǒng)開發(fā)、價(jià)格監(jiān)控、競(jìng)品分析等場(chǎng)景中，獲取商品的原始詳情數(shù)據(jù)是基礎(chǔ)且關(guān)鍵的一環(huán)。京東作為國(guó)內(nèi)領(lǐng)先的電商平臺(tái)，提供了相應(yīng)的API接口供開發(fā)者調(diào)用。本文將介紹如何使用京東開放平臺(tái)的API接口獲取商品詳情原數(shù)據(jù)。

一、 接口基本說(shuō)明

接口地址： 通常為 https://api.jd.com/routerjson (具體路徑請(qǐng)以京東開放平臺(tái)最新文檔為準(zhǔn))

HTTP方法： GET 或 POST

認(rèn)證方式： 需要調(diào)用方在京東開放平臺(tái)注冊(cè)成為開發(fā)者，創(chuàng)建應(yīng)用并獲得 app_key 和 app_secret。調(diào)用時(shí)需進(jìn)行簽名認(rèn)證，通常采用 OAuth 2.0 或京東自定義的簽名算法（如 JOS 簽名）。

數(shù)據(jù)格式： 請(qǐng)求和響應(yīng)數(shù)據(jù)通常采用 JSON 格式。

二、 核心請(qǐng)求參數(shù)

調(diào)用商品詳情接口，以下參數(shù)是必需的：

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

access_token： 用戶授權(quán)后獲得的訪問(wèn)令牌（對(duì)于需要用戶授權(quán)的場(chǎng)景）。對(duì)于部分基礎(chǔ)商品信息查詢，可能只需應(yīng)用級(jí)授權(quán)。

app_key： 開發(fā)者在京東開放平臺(tái)創(chuàng)建應(yīng)用后獲得的 App Key。

timestamp： 請(qǐng)求發(fā)起的時(shí)間戳，格式通常為 yyyy-MM-dd HH:mm:ss。

v： API版本號(hào)，如 2.0。

sign： 根據(jù)請(qǐng)求參數(shù)、app_secret 和特定簽名規(guī)則生成的簽名值，用于驗(yàn)證請(qǐng)求的合法性。簽名算法需嚴(yán)格遵循京東開放平臺(tái)文檔。

業(yè)務(wù)參數(shù)： 具體到商品詳情查詢，最核心的業(yè)務(wù)參數(shù)是商品的唯一標(biāo)識(shí)：

sku_id： 京東商品的SKU ID (庫(kù)存量單位編號(hào))，是標(biāo)識(shí)具體商品的最常用ID。例如 123456789。

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

三、 返回?cái)?shù)據(jù)結(jié)構(gòu)（示例）

一個(gè)成功的API調(diào)用響應(yīng)將包含商品詳情的詳細(xì)信息。數(shù)據(jù)結(jié)構(gòu)龐大且可能因接口版本和商品類目不同而有差異，但通常會(huì)包含以下核心字段：

{
  "code": "0", // 響應(yīng)碼，0表示成功
  "message": "success", // 響應(yīng)消息
  "result": {
    "skuId": 123456789, // 商品SKU ID
    "wareId": 987654321, // 商品ID (可能同skuId或不同)
    "name": "【京東自營(yíng)】XX品牌 高性能智能手機(jī) 8GB+256GB 曜石黑", // 商品名稱
    "brandName": "XX品牌", // 品牌名稱
    "productArea": "中國(guó)", // 產(chǎn)地
    "upc": "6921234567890", // UPC編碼
    "saleUnit": "臺(tái)", // 銷售單位
    "weight": "0.2", // 重量 (kg)
    "packListing": "手機(jī) x1, 充電器 x1, 數(shù)據(jù)線 x1, 說(shuō)明書 x1", // 包裝清單
    "wreadMe": "請(qǐng)閱讀說(shuō)明書...", // 使用說(shuō)明/注意事項(xiàng)
    "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, // 京東價(jià)
      "jdPrice": 3999.00, // 同京東價(jià)
      "marketPrice": 4299.00, // 市場(chǎng)價(jià)/原價(jià)
      // 可能還有plus價(jià)格等
    },
    "categoryId": 9987, // 類目ID
    "categoryPath": "手機(jī)通訊>手機(jī)>智能手機(jī)", // 類目路徑
    "shopInfo": {
      "shopId": 1000000123, // 店鋪ID
      "shopName": "XX品牌京東自營(yíng)旗艦店", // 店鋪名稱
      "score": "4.9", // 店鋪評(píng)分
      "logisticsScore": "4.8" // 物流評(píng)分
    },
    "baseBigFieldInfo": {
      // 商品基礎(chǔ)屬性集合 (鍵值對(duì)形式)
      "商品毛重": "0.22kg",
      "商品產(chǎn)地": "中國(guó)大陸",
      "CPU型號(hào)": "驍龍8 Gen2",
      "運(yùn)行內(nèi)存": "8GB",
      "機(jī)身存儲(chǔ)": "256GB",
      // ... 更多屬性
    },
    "introductionHtml": "...", // 商品詳情介紹 (HTML格式)
    "introductionMobiles": "...", // 移動(dòng)端商品詳情 (HTML格式)
    "wareQD": "商品特色描述..." // 商品亮點(diǎn)
  }
}

四、 調(diào)用流程與注意事項(xiàng)

注冊(cè)開發(fā)者賬號(hào)： 訪問(wèn)京東開放平臺(tái)，完成開發(fā)者注冊(cè)。

創(chuàng)建應(yīng)用： 在控制臺(tái)創(chuàng)建應(yīng)用，獲取 app_key 和 app_secret。

閱讀文檔： 仔細(xì)查閱目標(biāo)商品詳情API的 最新 官方文檔，確認(rèn)準(zhǔn)確的 method 名稱、必需參數(shù)、可選參數(shù)、請(qǐng)求方式、簽名算法。

構(gòu)造請(qǐng)求：

設(shè)置 method, app_key, timestamp, v 等固定參數(shù)。

設(shè)置業(yè)務(wù)參數(shù) sku_id 或 ware_id。

根據(jù)官方簽名算法（如 JOS 簽名），使用 app_secret 和所有請(qǐng)求參數(shù)（按規(guī)則排序后）生成 sign。

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

發(fā)送請(qǐng)求： 使用 HTTP Client (如 HttpURLConnection, OkHttp, Requests 等) 發(fā)送請(qǐng)求。

處理響應(yīng)：

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

解析 result 對(duì)象，獲取所需商品數(shù)據(jù)。

處理可能的錯(cuò)誤碼（如簽名錯(cuò)誤 1001、參數(shù)錯(cuò)誤 1002、無(wú)權(quán)限 1003、頻率限制 1004 等）。

注意事項(xiàng)：

權(quán)限與授權(quán)： 確保你的應(yīng)用有調(diào)用該API的權(quán)限。部分敏感數(shù)據(jù)可能需要商家或用戶授權(quán) (access_token)。

頻率限制： 京東API有嚴(yán)格的調(diào)用頻率限制，需遵守平臺(tái)規(guī)則，避免因頻繁調(diào)用被封禁。

數(shù)據(jù)時(shí)效性： API返回的數(shù)據(jù)是調(diào)用時(shí)刻的快照，商品價(jià)格、庫(kù)存等信息可能實(shí)時(shí)變化。

數(shù)據(jù)使用合規(guī)： 獲取的數(shù)據(jù)需遵守京東開放平臺(tái)的數(shù)據(jù)使用協(xié)議，不得用于非法用途。

HTTPS： 所有請(qǐng)求均應(yīng)通過(guò) HTTPS 協(xié)議發(fā)送。

簽名安全： app_secret 是核心機(jī)密，務(wù)必妥善保管，切勿泄露。

五、 簡(jiǎn)單調(diào)用示例 (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'  # 假設(shè)的方法名
sku_id = '123456789'
timestamp = time.strftime('%Y-%m-%d %H:%M:%S', time.localtime())
v = '2.0'

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

# 2. 按規(guī)則排序參數(shù) (如字母序)
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. 計(jì)算 MD5 (或 SHA, 以文檔為準(zhǔn))
sign = hashlib.md5(sign_str.encode('utf-8')).hexdigest().upper()

# 5. 添加 sign 到參數(shù)
params['sign'] = sign

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

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

六、 總結(jié)

京東平臺(tái)提供的商品詳情API接口是獲取商品原始數(shù)據(jù)的有效途徑。開發(fā)者在使用前需仔細(xì)閱讀官方文檔，嚴(yán)格遵守調(diào)用規(guī)范、簽名算法和頻率限制，并確保數(shù)據(jù)使用的合法性。通過(guò)合理利用此API，可以高效地構(gòu)建電商數(shù)據(jù)服務(wù)、分析系統(tǒng)等應(yīng)用。如有任何疑問(wèn)，歡迎大家留言探討。

?審核編輯 黃宇