京东商品详情 API 接口全面讲解

京东商品详情 API 是京东开放平台（JD Open Platform） 提供的核心数据接口，支持通过编程方式获取商品的标题、价格、库存、SKU规格、评价等 120+ 字段 ，数据实时性可达分钟级，延迟 ≤30 秒。

---

一、核心接口体系（2026 最新版）

京东商品详情 API 分为两大体系：

体系	接口方法名	适用场景	调用限制
商家开放平台（JOS）	jingdong.item.read.get	单品详情（全字段），ERP对接	基础: 2QPS/1000次/日；企业: 5~50QPS
	jingdong.item.list.get	批量详情（≤20 SKU）	1次 = 20次单品调用
	jingdong.item.sku.get	单SKU明细（含属性/库存）	同单品接口
	jingdong.item.spu.get	SPU聚合信息	1QPS/500次/日
京东联盟（CPS）	jd.union.open.goods.detail.query	联盟商品详情（含佣金），比价/推广	10QPS/5000~10万次/日
	jd.union.open.goods.skuid.query	SKU规格/价格查询	同联盟详情接口
	jd.union.open.goods.spu.query	SPU聚合信息（含同款）	8QPS/5000次/日

📌 最常用的两个接口：

• jd.item.get （旧版名称 item.jd.get）：获取单个商品详细信息，适合商品采集、数据同步
• jd.union.open.goods.detail.query：联盟商品详情，含佣金信息，适合比价工具、推广选品

---

二、请求方式与基础参数

属性	说明
协议	HTTPS
请求方式	POST（推荐）/ GET
数据格式	JSON
API 地址	https://api.jd.com/routerjson

公共参数（所有接口必传）

参数名	类型	必填	说明
method	String	✅	接口方法名，如 jd.item.get
app_key	String	✅	开放平台应用 ID
access_token	String	✅	授权令牌（商家接口需店铺授权）
timestamp	String	✅	时间戳，格式 yyyy-MM-dd HH:mm:ss，误差 ≤5min
format	String	✅	返回格式，固定 json
v	String	✅	接口版本，固定 2.0
sign	String	✅	MD5 签名
sign_method	String	✅	签名方法，固定 md5

业务参数（以 jd.item.get 为例）

参数名	类型	必填	说明
num_iid / sku_id	String	✅	京东商品 ID（详情页 URL 中的数字）
fields	String	❌	指定返回字段，如 title,price,stock，可减少数据量
is_promotion	Boolean	❌	是否返回促销信息，默认 true
param_json	JSON字符串	❌	扩展参数，如 {"skuIds":["123456"]}

---

三、签名生成（核心！）

京东 API 采用 MD5 签名验证机制，步骤如下：

`① 将所有请求参数（不含 sign 本身）按参数名 ASCII 码升序排序
② 拼接为字符串：k1v1k2v2k3v3...
③ 拼接 AppSecret：AppSecret + 拼接串 + AppSecret
④ MD5 加密并转大写 → 即为 sign
`

Python 签名实现

python

`import hashlib
import time

def generate_sign(params, app_secret):
    # ① 按参数名排序
    sorted_params = sorted(params.items(), key=lambda x: x[0])
    # ② 拼接字符串
    sign_str = app_secret + ''.join([f"{k}{v}" for k, v in sorted_params]) + app_secret
    # ③ MD5 加密并转大写
    return hashlib.md5(sign_str.encode('utf-8')).hexdigest().upper()
`

Java 签名实现

java

`private static String md5(String str) throws Exception {
    MessageDigest md = MessageDigest.getInstance("MD5");
    byte[] bytes = md.digest(str.getBytes("UTF-8"));
    StringBuilder sb = new StringBuilder();
    for (byte b : bytes) {
        sb.append(String.format("%02x", b));
    }
    return sb.toString().toUpperCase();
}

// 签名逻辑
List<String> paramNames = new ArrayList<>(params.keySet());
Collections.sort(paramNames);
StringBuilder signStr = new StringBuilder();
for (String name : paramNames) {
    signStr.append(name).append(params.get(name));
}
signStr.append(APP_SECRET);
String sign = md5(signStr.toString());
`

---

四、返回数据结构（120+ 字段）

json

`{
  "jd_item_get_response": {
    "wareInfo": {
      "wareId": 100060000001,
      "title": "Apple iPhone 15 256GB 黑色 移动联通电信5G手机",
      "price": {
        "salePrice": 7999.00,      // 当前售价
        "marketPrice": 8999.00,     // 原价/市场价
        "promotionInfo": {          // 促销信息
          "promotionPrice": 7699.00,
          "couponInfo": "满7000减300"
        }
      },
      "imageInfo": {
        "imageList": [
          "https://img10.360buyimg.com/n1/s540x540_jfs/...jpg"
        ]
      },
      "brandInfo": {
        "brandId": 1000000000,
        "brandName": "Apple"
      },
      "categoryInfo": {
        "categoryId": 1000000000,
        "categoryName": "手机"
      },
      "shopInfo": {
        "shopId": 1000000000,
        "shopName": "Apple产品京东自营旗舰店",
        "shopType": 1
      },
      "skuList": [
        {
          "skuId": "123456789",
          "name": "墨羽 12GB+256GB",
          "price": 2999.00,
          "stock": 50,
          "attributes": {"颜色": "墨羽", "内存": "12GB+256GB"}
        }
      ],
      "afterService": {
        "returnPolicy": "7天无理由退货",
        "warranty": "全国联保1年"
      },
      "commentInfo": {
        "rating": 4.8,
        "reviewCount": 123456
      }
    }
  }
}
`

核心字段分类

分类	字段	说明
📦 基础信息	title、brand、category、num_iid	商品标题、品牌、类目、ID
💰 价格体系	salePrice、marketPrice、promotionInfo	售价、原价、促销价
📊 库存销售	stock、sales、isJdSale	库存、销量、是否京东自营
🎨 媒体资源	imageList、video_url、sku_images	主图、详情图、视频
🔧 SKU规格	skuList[]	颜色/尺寸等变体及独立价格库存
⭐ 评价数据	rating、review_count	评分、评论总数（需单独接口）
🚚 服务信息	delivery、after_service	配送方式、售后政策

---

五、完整调用示例（Python）

python

`import requests
import hashlib
import time
import json

class JDAPI:
    def __init__(self, app_key, app_secret):
        self.app_key = app_key
        self.app_secret = app_secret
        self.api_url = "https://api.jd.com/routerjson"

    def generate_sign(self, params):
        sorted_params = sorted(params.items(), key=lambda x: x[0])
        sign_str = self.app_secret + ''.join([f"{k}{v}" for k, v in sorted_params]) + self.app_secret
        return hashlib.md5(sign_str.encode('utf-8')).hexdigest().upper()

    def get_item_detail(self, sku_id, fields=None):
        params = {
            "method": "jd.item.get",
            "app_key": self.app_key,
            "timestamp": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime()),
            "format": "json",
            "v": "2.0",
            "sign_method": "md5",
            "360buy_param_json": json.dumps({"skuId": sku_id})
        }
        if fields:
            params["fields"] = fields

        params["sign"] = self.generate_sign(params)

        response = requests.post(self.api_url, data=params)
        return response.json()


# ─── 使用 ───
api = JDAPI(app_key="YOUR_APP_KEY", app_secret="YOUR_APP_SECRET")
result = api.get_item_detail(sku_id="100060000001", fields="title,price,stock,skuList")
print(json.dumps(result, indent=2, ensure_ascii=False))
`

---

六、接入流程总览

`① 注册京东开放平台账号
       ↓
② 创建应用 → 获取 AppKey + AppSecret
       ↓
③ 申请接口权限（商品详情查询）
       ↓
④ 阅读 API 文档，构建签名逻辑
       ↓
⑤ 发送请求 → 解析 JSON 响应
       ↓
⑥ 业务集成（缓存/数据分析/前端展示）
`

🔗 官方入口：https://open.jd.com/

---

七、常见错误码

错误码	含义	解决方案
1001	参数缺失	检查 sku_id、timestamp 是否正确
3005	商品不存在	验证 SKU 有效性
10003	签名错误	检查签名算法、参数排序
4003	QPS 超限	申请提额或实现本地缓存

---

八、性能优化建议

策略	说明
🗂️ 本地缓存	商品描述/品牌等静态数据缓存 5~30 分钟
🎯 字段过滤	用 fields 参数只取需要的字段，降低网络负载
🔄 批量查询	单次最多查 200 个 SKU，减少请求次数
⏰ 错峰调用	避开大促高峰期，防止 QPS 超限

---

九、典型应用场景

场景	使用接口	价值
📊 比价系统	jd.union.open.goods.detail.query	实时监控竞品价格波动
📦 库存同步	jingdong.item.read.get	ERP 系统库存实时对齐
🔍 竞品分析	jd.item.get 批量查询	分析 SKU 布局与定价策略
🛒 代购/海淘	联盟接口	商品信息同步 + 下单
📈 数据分析	全部接口	挖掘销售趋势、用户偏好

如需最新接口文档，建议直接访问 京东开放平台控制台 → API 调试模块 获取实时文档。