在电商开发圈摸爬滚打这些年，京东商品详情 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") AI写代码数据示例；数据测试
