在电商开发圈摸爬滚打这些年，京东商品详情 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" } ],