京東 API 鑑權與簽名機制全解：安全對接的關鍵指南

在上一篇文章中，我們完成了京東開放平台的帳號註冊與應用建立，為後續 API 對接奠定了基礎。本篇將深入剖析京東 API 的鑑權與簽名機制，涵蓋以下核心內容：

1. 為什麼需要鑑權

2. 系統安全參數總覽

3. 簽名算法原理與程式範例

4. OAuth2.0 動態令牌獲取流程

5. 常見錯誤解析與實戰最佳實踐

掌握這些知識後，您將能夠安全且穩定地調用京東開放平台的各類 API，為實際業務場景做好充分準備。

一、為什麼需要鑑權？

京東開放平台提供的是對接電商業務核心資料的能力，例如商品資訊、訂單明細、用戶身份、庫存數據等。這些資料具有極高敏感性，若缺乏嚴格的授權控制與驗證機制，極易導致數據洩漏、業務錯亂甚至安全事故。

因此，平台設計了以下安全需求：

• 請求合法性驗證：只有擁有授權的應用才可以調用 API；

• 資料完整性保護：防止在傳輸過程中請求被篡改；

• 可審計性支援：每次請求都能清楚地追溯至特定的 AppKey 與用戶操作。

這些需求對應的解決方案，就是 API 調用中的「鑑權」與「簽名」機制。

二、系統參數與安全參數說明

在調用任何京東開放平台接口時，開發者除了需要提供與業務邏輯相關的參數外，還必須提供一組公共系統參數，以保證請求的安全性與標準格式。

註：若調用的是僅限平台級的接口（無需用戶授權），可不傳入 access_token。

這些參數將與業務參數共同構成簽名基礎，用以驗證請求合法性。

三、簽名算法原理與實作範例

京東開放平台提供基於 MD5、HMAC-MD5、HMAC-SHA256 的多種簽名算法，推薦使用 HMAC 類型以提升安全性。整體流程包含五大步驟：

1. 收集參數

除了 sign 參數本身，其餘所有系統參數與業務參數均需參與簽名，空值參數可忽略。

2. 參數升序排列

將所有參與簽名的鍵值對依照 ASCII 字符順序進行升序排列，這一步驟的精確性對生成正確簽名至關重要。

3. 拼接原始字串

• 若使用 MD5：

  signature_base = AppSecret + key1 + value1 + key2 + value2 + ... + AppSecret
  sign = MD5(signature_base).toUpperCase()
  

• 若使用 HMAC 類型：

  signature_base = key1 + value1 + key2 + value2 + ...
  sign = HMAC_ALGO(AppSecret, signature_base).toUpperCase()
  

4. 計算摘要值

依照所選算法，計算出十六進位制的摘要字串。注意字元編碼需統一為 UTF-8。

5. 轉大寫並附加至請求中

最終簽名需轉為大寫後，作為 sign 參數傳入請求。

Python 簽名範例程式

import hashlib
import hmac
import json
def generate_sign(params: dict, app_secret: str, algo: str = 'MD5') -> str:
items = sorted((k, v) for k, v in params.items() if v is not None and k != 'sign')
if algo.upper().startswith("HMAC"):
base = ''.join(f"{k}{v}" for k, v in items)
hash_func = hashlib.md5 if algo.upper() == 'HMAC-MD5' else hashlib.sha256
digest = hmac.new(app_secret.encode('utf-8'), base.encode('utf-8'), hash_func).hexdigest()
else:
base = app_secret + ''.join(f"{k}{v}" for k, v in items) + app_secret
digest = hashlib.md5(base.encode('utf-8')).hexdigest()
return digest.upper()
params = {
"method": "jingdong.sku.get",
"app_key": "YOUR_APP_KEY",
"timestamp": "2025-04-29 10:00:00",
"v": "2.0",
"360buy_param_json": json.dumps({"skuId": 123456})
}
app_secret = "YOUR_APP_SECRET"
sign = generate_sign(params, app_secret)
print("簽名 =", sign)

四、OAuth2.0 動態令牌獲取流程

對於需用戶授權的接口（如查詢訂單、獲取用戶資料等），除了應用級簽名外，還需提供 access_token。此令牌基於 OAuth2.0 的標準授權碼流程獲取：

1. 引導用戶授權

將用戶引導至以下網址進行授權：

https://oauth.jd.com/oauth/authorize
?client_id=YOUR_APP_KEY
&response_type=code
&redirect_uri=YOUR_CALLBACK_URL

授權完成後，京東將用戶瀏覽器重定向回 redirect_uri，並在 URL 中附帶 code。

2. 獲取 Access Token

應用伺服器使用此 code 與 App 資訊，向京東伺服器發送請求獲取 access_token：

POST https://oauth.jd.com/oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id=YOUR_APP_KEY
&client_secret=YOUR_APP_SECRET
&code=AUTHORIZATION_CODE
&redirect_uri=YOUR_CALLBACK_URL

返回資料中包含：

{
"access_token": "USER_ACCESS_TOKEN",
"refresh_token": "REFRESH_TOKEN",
"expires_in": 86400
}

3. 刷新令牌

當 access_token 即將過期，可使用 refresh_token 獲取新的令牌對：

grant_type=refresh_token
&client_id=YOUR_APP_KEY
&client_secret=YOUR_APP_SECRET
&refresh_token=REFRESH_TOKEN

安全注意事項

• 請妥善保管 client_secret 及 refresh_token，嚴禁暴露於前端；

• 所有授權與調用請求必須使用 HTTPS 以防中間人攻擊；

• Token 須加密儲存並設定有效期自動刷新機制。

五、常見問題解析與最佳實踐

1. 簽名錯誤

• 未正確排序或漏掉參數；

• 加密演算法與文檔描述不一致；

• timestamp 與京東伺服器誤差超過 5 分鐘，可考慮自動同步時間。

2. 401 未授權

• access_token 失效，需重新授權或使用 refresh_token；

• 應用尚未申請對應接口的訪問權限，可至應用後台確認。

3. 403 權限不足

• API 調用頻率已超限，需提交升級申請；

• 嘗試調用未開通的接口功能，請補充授權並通過審核。

4. 避免重複請求

• 業務層需實現幂等邏輯；

• 生成簽名時避免引入隨機變量，確保相同參數輸出固定簽名值。

六、小結

京東開放平台的鑑權與簽名機制，是保障資料安全與請求有效的基石。從理解系統參數、掌握簽名邏輯、到處理 OAuth2.0 授權流程，都是接入京東 API 的必修課。建議在實際開發中，將簽名與鑑權流程封裝為中間層模組，實現統一與可維護的安全邏輯，為穩定高效的系統對接打下堅實基礎。

Articles related to APIs :

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

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