在电商开发圈摸爬滚打这些年，京东商品详情 API 的 “细节陷阱” 最让人防不胜防。作为国内自营电商的标杆，它的接口返回里藏着太多 “自营专属逻辑”—— 从嵌套三层的价格体系（秒杀 / PLUS / 区域价），到区分 “总库存” 与 “可售库存” 的库存规则，再到必须传对的 “SKU-ID 绑定” 要求，每次对接都像在拆解京东自营的 “供应链密码”。今天就把这些年踩过的雷、攒的可落地代码全抖出来，给做商家工具、比价系统的朋友避避雷。
一、初次翻车：签名漏传 “v=2.0”，调试到凌晨两点
第一次接京东商品详情 API 是帮比价平台做 “实时价抓取”，按文档写的签名函数连续 5 小时返回40001签名错误。翻遍京东开放平台文档才发现：京东商品详情接口必须显式传 “v=2.0” 版本号，且 timestamp 必须是 13 位毫秒级时间戳，我不仅漏了v参数，还习惯性用了 10 位秒级时间戳，导致加密结果和官方示例差了整整一串字符。
更坑的是，京东签名要求 “参数值必须 URL 编码，但保留-_.~特殊字符”，我误把~也编码成了%7E，结果签名验证直接失败。那天对着官方签名示例算到眼酸，终于磨出能跑通的签名函数，每个京东特有的要求都标红了：
python
运行
import hashlib
import time
import urllib.parse
def generate_jd_detail_sign(params, app_secret):
"""
生成京东商品详情API签名（必传v=2.0+毫秒级timestamp！）
:param params: 请求参数（不含sign）
:param app_secret: 应用密钥
"""
# 1. 强制添加京东商品详情接口特有必传参数，缺一个签名必错
params["v"] = "2.0" # 固定2.0版本，漏传直接40001
params["format"] = "json" # 仅支持json，不支持xml
params["timestamp"] = str(int(time.time() * 1000)) # 13位毫秒级时间戳，秒级必错
params["sign_method"] = "md5" # 京东商品详情接口固定MD5，不是SHA1
# 2. 过滤sign参数，按参数名ASCII升序排序（京东对顺序敏感，差一个字符都不行）
sign_params = {k: v for k, v in params.items() if k != "sign" and v is not None}
sorted_params = sorted(sign_params.items(), key=lambda x: x[0])
# 3. 拼接为key=value&key=value，值URL编码（保留-_.~，其他特殊字符转义）
query_str = "&".join([
f"{k}={urllib.parse.quote(str(v), safe='-_.~')}"
for k, v in sorted_params
])
# 4. 首尾加app_secret，MD5加密后转大写（京东固定首尾加密钥）
sign_str = f"{app_secret}{query_str}{app_secret}"
return hashlib.md5(sign_str.encode()).hexdigest().upper()
# 示例调用（获取商品详情，必须传sku_id）
params = {
"app_key": "your_jd_app_key",
"method": "jd.union.open.goods.detail.query",
"sku_id": "1000283456789", # 京东商品详情只认sku_id，传product_id返回空
"fields": "sku_name,price,stock,specs,promotion_info" # 必须指定返回字段，否则默认只返sku_id
}
params["sign"] = generate_jd_detail_sign(params, "your_app_secret")
数据示例；数据测试
"item": {
"num_iid": "100095082427",
"title": "美素佳儿（Friso）皇家系列 港版1段 HMO婴幼儿配方奶粉 400g/罐",
"desc_short": "",
"price": "204.00",
"total_price": "",
"suggestive_price": "",
"orginal_price": "204.00",
"nick": "Friso美素佳儿海外京东自营旗舰店",
"num": "99",
"min_num": "1",
"detail_url": "https://item.jd.com/100095082427.html#crumb-wrap",
"pic_url": "//img13.360buyimg.com/n12/jfs/t1/334389/11/23386/72402/68ef8472F1caf964a/99a82d9cf066ed71.jpg",
"brand": "美素佳儿（Friso）",
"brandId": "32527",
"rootCatId": "1319",
"cid": "7052",
"desc": "",
"desc_img": [],
"item_imgs": {
"item_img": [
{
"url": "//img10.360buyimg.com/n1/jfs/t1/334389/11/23386/72402/68ef8472F1caf964a/99a82d9cf066ed71.jpg"
},
{
"url": "//img10.360buyimg.com/n1/jfs/t1/227047/20/28086/78467/6730aa87F6cd41b9c/244ff232d595d66c.jpg"
},
{
"url": "//img10.360buyimg.com/n1/jfs/t1/230937/17/26801/118133/6721d42aF88a5c43d/5cae039b705a6578.jpg"
},
{
"url": "//img10.360buyimg.com/n1/jfs/t1/176229/5/51253/2120553/672dbbbfF2c74f743/31a69c9e37bdd8de.jpg"
}
]
},
"item_weight": null,
"post_fee": "",
"express_fee": "",
"ems_fee": "",
"video_id": "",
"is_promotion": "",
"props_name": "1:0:规格:【皇家1段 400g】尝鲜装;1:1:规格:【皇家2段400g】尝鲜装;1:2:规格:港版皇家-1段【0-6月】;1:3:规格:港版皇家-2段【6-12月】;1:4:规格:港版皇家-3段【1-3岁】;1:5:规格:港版皇家-4段【3岁以上】;1:6:规格:港版皇家-3段*6罐;1:7:规格:【箱装】1段*12罐;1:8:规格:【箱装】2段*12罐;1:9:规格:【箱装】3段*12罐;1:10:规格:【箱装】4段*12罐;1:11:规格:【皇家2段400g】新客专享;1:12:规格:港版皇家-3段*3罐;",
"prop_imgs": {
"prop_img": [
{
"properties": "1:6",
"url": "//img10.360buyimg.com/n1/jfs/t1/376149/18/9767/192005/693becb7F0bfc0de9/3f68454d88d9a567.jpg"
},
{
"properties": "1:7",
"url": "//img10.360buyimg.com/n1/jfs/t1/334797/30/22871/73136/68ef84a5F9da65f02/aab5ca17b49a550d.jpg"
},
{
"properties": "1:12",
"url": "//img10.360buyimg.com/n1/jfs/t1/374527/7/8881/194292/693becbfF1191d4da/8e4a2d47bd3be905.jpg"
},
{
"properties": "1:10",
"url": "//img10.360buyimg.com/n1/jfs/t1/376629/19/9864/194414/693bec9dF40299b9b/ca039d8e1942d29c.jpg"
},
{
"properties": "1:9",
"url": "//img10.360buyimg.com/n1/jfs/t1/378635/31/2905/192727/693becaeF1909f9c0/08abb49f30035f0f.jpg"
},
{
"properties": "1:4",
"url": "//img10.360buyimg.com/n1/jfs/t1/379367/27/2843/189774/693becc6F6a970cec/91c3284057477b6c.jpg"
},
{
"properties": "1:2",
"url": "//img10.360buyimg.com/n1/jfs/t1/247328/29/33097/77539/68ef8433F1527fbc4/be219eb4cf982b74.jpg"
},
{
"properties": "1:8",
"url": "//img10.360buyimg.com/n1/jfs/t1/377329/6/7871/168463/693beccaF1be42fb5/4b7b1b005d6de3e5.jpg"
},
{
"properties": "1:0",
"url": "//img10.360buyimg.com/n1/jfs/t1/334389/11/23386/72402/68ef8472F1caf964a/99a82d9cf066ed71.jpg"
},
{
"properties": "1:5",
"url": "//img10.360buyimg.com/n1/jfs/t1/377660/22/9234/189089/693beca6F8a303467/aa8ea0021e3eb413.jpg"
},
{
"properties": "1:3",
"url": "//img10.360buyimg.com/n1/jfs/t1/374155/15/12092/167983/693becceFe631cee7/f15147bc3fa02d42.jpg"
},
{
"properties": "1:11",
"url": "//img10.360buyimg.com/n1/jfs/t1/379187/15/3480/134037/693becd1Fc586fb48/1ffeefbc9dae307d.jpg"
},
{
"properties": "1:1",
"url": "//img10.360buyimg.com/n1/jfs/t1/380873/34/3456/164302/693becd5F3a8bd891/193f7071eb1454b7.jpg"
}
]
},
"property_alias": "1:0:规格:【皇家1段 400g】尝鲜装;1:1:规格:【皇家2段400g】尝鲜装;1:2:规格:港版皇家-1段【0-6月】;1:3:规格:港版皇家-2段【6-12月】;1:4:规格:港版皇家-3段【1-3岁】;1:5:规格:港版皇家-4段【3岁以上】;1:6:规格:港版皇家-3段*6罐;1:7:规格:【箱装】1段*12罐;1:8:规格:【箱装】2段*12罐;1:9:规格:【箱装】3段*12罐;1:10:规格:【箱装】4段*12罐;1:11:规格:【皇家2段400g】新客专享;1:12:规格:港版皇家-3段*3罐;1:12:港版皇家-3段*3罐;",
"props": [
{
"name": "保质期",
"value": "24个月"
},
{
"name": "国产/进口",
"value": "进口"
},
{
"name": "特性",
"value": "其他"
},
{
"name": "适用年龄",
"value": "0-6个月"
},
{
"name": "段位",
"value": "1段"
},
{
"name": "包装形式",
"value": "罐装"
}
],
"total_sold": "0",
"skus": {
"sku": [
{
"price": "204.00",
"orginal_price": "204.00",
"properties": "1:6",
"properties_name": "1:6:规格:港版皇家-3段*6罐",
"quantity": "99",
"sku_id": "100288147082",
"sku_url": "http://item.jd.com/100288147082.html"
},
{
"price": "204.00",
"orginal_price": "204.00",
"properties": "1:7",
"properties_name": "1:7:规格:【箱装】1段*12罐",
"quantity": "99",
"sku_id": "100069627796",
"sku_url": "http://item.jd.com/100069627796.html"
},
{
"price": "204.00",
"orginal_price": "204.00",
"properties": "1:12",
"properties_name": "1:12:规格:港版皇家-3段*3罐",
"quantity": "99",
"sku_id": "100288147000",
"sku_url": "http://item.jd.com/100288147000.html"
},
{
"price": "204.00",
"orginal_price": "204.00",
"properties": "1:10",
"properties_name": "1:10:规格:【箱装】4段*12罐",
"quantity": "99",
"sku_id": "100068665994",
"sku_url": "http://item.jd.com/100068665994.html"
},
{
"price": "204.00",
"orginal_price": "204.00",
"properties": "1:9",
"properties_name": "1:9:规格:【箱装】3段*12罐",
"quantity": "99",
"sku_id": "100068665998",
"sku_url": "http://item.jd.com/100068665998.html"
},
{
"price": "204.00",
"orginal_price": "204.00",
"properties": "1:4",
"properties_name": "1:4:规格:港版皇家-3段【1-3岁】",
"quantity": "99",
"sku_id": "100007006921",
"sku_url": "http://item.jd.com/100007006921.html"
},
{
"price": "204.00",
"orginal_price": "204.00",
"properties": "1:2",
"properties_name": "1:2:规格:港版皇家-1段【0-6月】",
"quantity": "99",
"sku_id": "100005794942",
"sku_url": "http://item.jd.com/100005794942.html"
},
{
"price": "204.00",
"orginal_price": "204.00",
"properties": "1:8",
"properties_name": "1:8:规格:【箱装】2段*12罐",
"quantity": "99",
"sku_id": "100070205221",
"sku_url": "http://item.jd.com/100070205221.html"
},
{
"price": "204.00",
"orginal_price": "204.00",
"properties": "1:0",
"properties_name": "1:0:规格:【皇家1段 400g】尝鲜装",
"quantity": "99",
"sku_id": "100095082427",
"sku_url": "http://item.jd.com/100095082427.html"
},
{
"price": "204.00",
"orginal_price": "204.00",
"properties": "1:5",
"properties_name": "1:5:规格:港版皇家-4段【3岁以上】",
"quantity": "99",
"sku_id": "100005794930",
"sku_url": "http://item.jd.com/100005794930.html"
},
{
"price": "204.00",
"orginal_price": "204.00",
"properties": "1:3",
"properties_name": "1:3:规格:港版皇家-2段【6-12月】",
"quantity": "99",
"sku_id": "100005794932",
"sku_url": "http://item.jd.com/100005794932.html"
},
{
"price": "204.00",
"orginal_price": "204.00",
"properties": "1:11",
"properties_name": "1:11:规格:【皇家2段400g】新客专享",
"quantity": "99",
"sku_id": "100104720586",
"sku_url": "http://item.jd.com/100104720586.html"
},
{
"price": "204.00",
"orginal_price": "204.00",
"properties": "1:1",
"properties_name": "1:1:规格:【皇家2段400g】尝鲜装",
"quantity": "99",
"sku_id": "100017950164",
"sku_url": "http://item.jd.com/100017950164.html"
}
]
},
"seller_id": "1000085822",
"sales": 0,
"shop_id": "1000085822",
"props_list": {
"1:0": "规格:【皇家1段 400g】尝鲜装",
"1:1": "规格:【皇家2段400g】尝鲜装",
"1:2": "规格:港版皇家-1段【0-6月】",
"1:3": "规格:港版皇家-2段【6-12月】",
"1:4": "规格:港版皇家-3段【1-3岁】",
"1:5": "规格:港版皇家-4段【3岁以上】",
"1:6": "规格:港版皇家-3段*6罐",
"1:7": "规格:【箱装】1段*12罐",
"1:8": "规格:【箱装】2段*12罐",
"1:9": "规格:【箱装】3段*12罐",
"1:10": "规格:【箱装】4段*12罐",
"1:11": "规格:【皇家2段400g】新客专享",
"1:12": "规格:港版皇家-3段*3罐"
},
"seller_info": {
"shop_id": 1000085822,
"zhuy": "http://firso.jd.com",
"nick": "Friso美素佳儿海外京东自营旗舰店",
"shop_name": "Friso美素佳儿海外京东自营旗舰店"
},
"props_img": [
{
"1:6": "//img10.360buyimg.com/n1/jfs/t1/376149/18/9767/192005/693becb7F0bfc0de9/3f68454d88d9a567.jpg"
},
{
"1:7": "//img10.360buyimg.com/n1/jfs/t1/334797/30/22871/73136/68ef84a5F9da65f02/aab5ca17b49a550d.jpg"
},
{
"1:12": "//img10.360buyimg.com/n1/jfs/t1/374527/7/8881/194292/693becbfF1191d4da/8e4a2d47bd3be905.jpg"
},
{
"1:10": "//img10.360buyimg.com/n1/jfs/t1/376629/19/9864/194414/693bec9dF40299b9b/ca039d8e1942d29c.jpg"
},
{
"1:9": "//img10.360buyimg.com/n1/jfs/t1/378635/31/2905/192727/693becaeF1909f9c0/08abb49f30035f0f.jpg"
},
{
"1:4": "//img10.360buyimg.com/n1/jfs/t1/379367/27/2843/189774/693becc6F6a970cec/91c3284057477b6c.jpg"
},
{
"1:2": "//img10.360buyimg.com/n1/jfs/t1/247328/29/33097/77539/68ef8433F1527fbc4/be219eb4cf982b74.jpg"
},
{
"1:8": "//img10.360buyimg.com/n1/jfs/t1/377329/6/7871/168463/693beccaF1be42fb5/4b7b1b005d6de3e5.jpg"
},
{
"1:0": "//img10.360buyimg.com/n1/jfs/t1/334389/11/23386/72402/68ef8472F1caf964a/99a82d9cf066ed71.jpg"
},
{
"1:5": "//img10.360buyimg.com/n1/jfs/t1/377660/22/9234/189089/693beca6F8a303467/aa8ea0021e3eb413.jpg"
},
{
"1:3": "//img10.360buyimg.com/n1/jfs/t1/374155/15/12092/167983/693becceFe631cee7/f15147bc3fa02d42.jpg"
},
{
"1:11": "//img10.360buyimg.com/n1/jfs/t1/379187/15/3480/134037/693becd1Fc586fb48/1ffeefbc9dae307d.jpg"
},
{
"1:1": "//img10.360buyimg.com/n1/jfs/t1/380873/34/3456/164302/693becd5F3a8bd891/193f7071eb1454b7.jpg"
}
],
