京东商品详情接口完全指南：从接入到落地的全链路实战-阿里云开发者社区

在电商数据化运营时代，商品详情接口是连接业务系统与京东商品数据的核心管道。无论是 ERP 同步、价格监控、跨境铺货，还是供应链选品比价，都需要稳定、准确地获取京东商品的完整结构化数据。本文将系统梳理京东商品详情接口的全貌，覆盖官方开放平台和京东联盟两条主线，并附可直接落地的代码示例。

一、京东详情接口的两大体系

京东的商品详情能力分散在两个不同的开放平台中，定位和使用场景截然不同：

表格

维度	京东开放平台（JOS）	京东联盟开放平台
核心接口	`jd.item.get` / `jingdong.item.read.get`	`jd.union.open.goods.query` / `jd.union.open.goods.promotiongoodsinfo.query`
数据侧重	商品全量元数据（真实库存、SKU、详情图、售后等）	推广信息（佣金比例、优惠券、推广链接）
权限要求	企业认证 + 店铺授权（部分接口）	京东联盟账号 + 推广位绑定
适用场景	ERP 同步、商品中台、竞品监控	CPS 推广、导购返利、比价展示
QPS 限制	基础 2 QPS，企业服务商可申请 5~50	按联盟等级分配

关键认知： 联盟接口虽然也能拿到商品标题、价格、图片等基础信息，但不含真实库存和完整 SKU 规格，且价格字段是推广价而非实时京东价，不能替代官方商品详情接口用于供应链或 ERP 场景

。

二、官方商品详情接口：jd.item.get

这是京东开放平台（JOS）提供的商家服务商版商品全量详情接口，数据最全、字段最丰富，是企业级应用的首选。

2.1 接口基础信息

项目	说明
接口地址	`https://api.jd.com/routerjson`
协议	HTTPS
请求方式	POST / GET
数据格式	JSON（默认）/ XML
接口版本	v2.0
权限要求	京东开放平台企业认证 + 接口权限申请

基础 QPS 为 2，企业服务商可根据业务规模申请提升至 5~50 。

2.2 请求参数

公共参数（所有调用必传）：

参数名	类型	必填	说明
`app_key`	String	是	应用唯一标识
`method`	String	是	固定值：`jd.item.get`
`timestamp`	String	是	北京时间，格式 `yyyy-MM-dd HH:mm:ss`，用于签名校验防重放
`v`	String	是	接口版本，固定 `2.0`
`format`	String	否	返回格式，`json` 或 `xml`，默认 `json`
`sign`	String	是	MD5 大写签名
`access_token`	String	店铺授权场景必填	OAuth 店铺授权令牌

业务参数（核心查询参数）：

表格

参数名	类型	必填	说明
`skuId`	Long	二选一	单品 SKU 编号（精准单规格查询，推荐）
`itemId`	Long	二选一	商品主商品 ID（多 SKU 套装商品入口 ID）
`fields`	String	否	字段过滤，逗号分隔，不传返回全量字段，可减少返回体积

2.3 签名生成规则

京东开放平台采用 MD5 签名机制，签名规则为：

plain

sign = MD5( app_secret + 所有参数按 key 升序拼接 + app_secret ).upper()

Python 签名示例：

Python

import hashlib
def generate_sign(params, app_secret):
    # 按 key 升序排序，排除 sign 本身
    sorted_params = sorted((k, v) for k, v in params.items() if k != 'sign')
    # 拼接成 key=value 字符串
    param_str = ''.join(f"{k}{v}" for k, v in sorted_params)
    # 首尾拼接 app_secret
    sign_str = f"{app_secret}{param_str}{app_secret}"
    return hashlib.md5(sign_str.encode('utf-8')).hexdigest().upper()

2.4 完整调用示例（Python）

Python

import requests
import hashlib
import time
from urllib.parse import quote
APP_KEY = 'your_app_key'
APP_SECRET = 'your_app_secret'
ACCESS_TOKEN = 'your_access_token'  # 店铺授权场景需要
def jd_sign(params):
    sorted_params = sorted((k, v) for k, v in params.items() if k != 'sign')
    param_str = ''.join(f"{k}{v}" for k, v in sorted_params)
    sign_str = f"{APP_SECRET}{param_str}{APP_SECRET}"
    return hashlib.md5(sign_str.encode('utf-8')).hexdigest().upper()
def get_item_detail(sku_id):
    timestamp = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime())
    
    params = {
        'method': 'jd.item.get',
        'app_key': APP_KEY,
        'access_token': ACCESS_TOKEN,
        'timestamp': timestamp,
        'v': '2.0',
        'format': 'json',
        'skuId': sku_id,
        'fields': 'skuId,title,priceInfo,stockInfo,imageInfo,skuList,paramList,shopInfo'
    }
    
    params['sign'] = jd_sign(params)
    
    # 参数需要 URL 编码
    encoded_params = {k: quote(str(v)) for k, v in params.items()}
    
    url = 'https://api.jd.com/routerjson'
    response = requests.post(url, data=encoded_params, timeout=30)
    return response.json()
# 调用示例
result = get_item_detail('100012345678')
print(result)

2.5 返回数据结构解析

jd.item.get 返回的 JSON 结构非常完整，核心字段如下

：

JSON

{
    "jd_item_get_response": {
        "code": 0,
        "msg": "success",
        "item": {
            "skuId": 100012345678,
            "itemId": 1001234567,
            "title": "华为Mate 60 Pro 12GB+512GB 雅丹黑",
            "shortTitle": "Mate60 Pro 雅丹黑",
            "saleState": 1,
            "brand": {
                "brandId": 1000123,
                "brandName": "华为(HUAWEI)"
            },
            "category": {
                "cid1": 1713,
                "cid1Name": "手机通讯",
                "cid2": 1714,
                "cid2Name": "手机",
                "cid3": 1715,
                "cid3Name": "智能手机"
            },
            "priceInfo": {
                "marketPrice": "6999.00",
                "jdPrice": "6499.00",
                "promotionPrice": "6299.00",
                "memberPrice": "6199.00",
                "promotionList": [...]
            },
            "stockInfo": {
                "totalStockNum": 326,
                "stockState": 33,
                "stockDesc": "现货有货",
                "limitBuyNum": 2
            },
            "imageInfo": {
                "mainImg": "https://...",
                "imageList": ["...", "..."],
                "detailHtml": "<html>商品详情图文富文本...</html>"
            },
            "paramList": [
                {"name": "品牌", "value": "华为"},
                {"name": "运行内存", "value": "12GB"}
            ],
            "skuList": [
                {
                    "subSkuId": 100012345678,
                    "skuTitle": "华为Mate 60 Pro 12GB+512GB 雅丹黑",
                    "propsText": "颜色:雅丹黑;内存:12GB+512GB",
                    "skuPrice": "6299.00",
                    "skuStock": 126
                }
            ],
            "salesInfo": {
                "totalSales": 126800,
                "monthSales": 3620,
                "commentCount": 89600,
                "goodCommentRate": "98.6%"
            },
            "shopInfo": {
                "shopId": 1000888888,
                "shopName": "华为京东自营官方旗舰店",
                "shopType": "self",
                "shopScore": 4.95
            },
            "serviceInfo": {
                "supportJdLogistics": true,
                "sevenDayReturn": true,
                "warrantyYear": "1年全国联保"
            }
        }
    }
}

关键字段说明：

字段路径	说明
`priceInfo.jdPrice`	京东价（划线价）
`priceInfo.promotionPrice`	促销价（实际到手价）
`stockInfo.stockState`	库存状态码，`33` = 现货有货，`34` = 现货无货，`40` = 可配送等
`stockInfo.totalStockNum`	总库存数量
`skuList`	多规格 SKU 列表，含每个子 SKU 的价格和库存
`imageInfo.detailHtml`	商品详情页富文本 HTML（含图文详情）
`shopInfo.shopType`	`self` = 自营，`pop` = 第三方商家

三、批量查询接口：jingdong.item.list.get

当需要同时查询多个商品时，单品接口效率太低。京东提供了批量查询能力：

项目	说明
接口	`jingdong.item.list.get`
单次上限	20 个商品 ID
请求参数	`skuIds` = `123,456,789`（逗号分隔）
返回结构	数组形式返回多个商品详情

适用场景： 购物车同步、批量价格监控、商品中台批量更新。

四、京东联盟详情接口：推广场景专用

如果你的业务是导购、返利、CPS 推广，而非供应链或 ERP，应该使用京东联盟接口。

4.1 核心接口

接口	用途
`jd.union.open.goods.query`	关键词/条件搜索商品列表，含推广信息
`jd.union.open.goods.promotiongoodsinfo.query`	根据 SKU ID 批量查询商品推广信息
`jd.union.open.goods.bigfield.query`	查询商品图文详情大字段

4.2 联盟接口 vs 官方接口对比

能力	官方 `jd.item.get`	联盟 `jd.union.open.goods.query`
真实库存	✅ 有	❌ 无
完整 SKU 规格	✅ 有	⚠️ 部分
佣金比例	❌ 无	✅ 有
优惠券信息	❌ 无	✅ 有
推广链接	❌ 无	✅ 有
详情图 HTML	✅ 有	⚠️ 需单独调大字段接口

结论： 供应链、ERP、库存管理必须用官方接口；导购、返利、内容电商用联盟接口。

五、八大业务场景落地指南

基于 jd.item.get 的完整数据能力，以下是八个典型落地场景

：

场景 1：ERP 商品同步

核心字段： skuId, title, priceInfo, stockInfo, skuList, paramList
逻辑： 定时轮询商品列表，对比本地数据库，价格/库存变化时触发更新
频率： 价格监控建议每 5~15 分钟一次，库存监控可更频繁

场景 2：跨境铺货（Ozon / Temu / Shopee）

核心字段： title, imageList, attributeList, skuList, priceInfo, descHtml
注意点：

京东图片域名 360buyimg.com 部分平台不允许外链，必须下载转存对象存储
属性需要映射到目标平台类目（如京东"运行内存" → Ozon"RAM"）
详情 HTML 需清洗标签，适配目标平台编辑器

场景 3：竞品监控与价格预警

核心字段： priceInfo.promotionPrice, stockInfo.stockState, salesInfo
逻辑： 采集竞品 SKU，建立价格基线，促销价低于阈值时触发告警

场景 4：供应链选品比价

核心字段： priceInfo, stockInfo, shopInfo, serviceInfo
逻辑： 同一品类下多 SKU 横向对比，筛选"自营 + 高库存 + 低售后率"的优质货源

场景 5：商品中台建设

将京东商品数据标准化为内部商品模型，统一供给前端商城、小程序、B 端分销系统

场景 6：反向海淘代购

海外用户通过你的平台购买京东商品，需实时展示京东商品详情、价格、库存

场景 7：库存联动与自动补货

WMS 检测到库存低于安全线时，自动查询京东货源库存，有货则触发采购流程

场景 8：数据大屏与 BI 分析

聚合多 SKU 的销售数据、价格趋势、评论情感分析，支撑运营决策

六、踩坑清单与最佳实践

1. 权限申请是最大门槛

个人开发者无法申请交易类接口，必须企业/个体工商户资质
部分接口需要缴纳保证金（通常 1~3 万元）
申请时业务描述要清晰，说明数据用途和场景

2. 签名失败是最常见的报错

时间戳必须使用北京时间，且与服务器时间误差不能超过 5 分钟
参数拼接时不要包含 sign 字段本身
所有参数值必须做 URL 编码后再发送
MD5 结果必须转大写

3. 图片处理

主图和详情图 URL 有时效性，不要长期缓存原始 URL
详情 HTML 中的图片路径可能是相对路径，需要补全域名
跨境场景必须下载图片到自有 CDN，避免外链失效

4. 缓存与限流策略

基础 QPS 只有 2，高频场景必须做本地缓存 + 分布式缓存
价格/库存建议缓存 5~15 分钟，商品基础信息（标题、图片、参数）可缓存 1~24 小时
批量查询优先用 jingdong.item.list.get，减少请求次数

5. 字段过滤减少传输体积

通过 fields 参数只返回需要的字段，可显著降低响应体积和提升接口速度
例如：fields=skuId,title,priceInfo,stockInfo 比全量返回快 30% 以上

6. 异常处理

商品下架或 SKU 变更时，接口可能返回 sku not found 或空数据
必须做好降级策略：接口异常时读取缓存数据，避免前端展示空白

七、总结

京东商品详情接口是电商数据化的基础设施，但选对接口、申请对权限、做好缓存和异常处理，才是稳定落地的关键。

表格

你的场景	推荐接口	关键注意点
ERP / WMS 同步	`jd.item.get`	需要企业资质，申请商品信息权限
批量价格监控	`jingdong.item.list.get`	单次 20 个，做好缓存和限流
CPS / 导购 / 返利	`jd.union.open.goods.query`	注册京东联盟，绑定推广位
跨境铺货	`jd.item.get` + 图片下载	HTML 清洗、属性映射、图片转存
竞品监控	`jd.item.get`	定时轮询 + 价格基线 + 告警触发

如遇任何疑问或有进一步的需求，请随时与我私信或者评论联系。

京东商品详情接口完全指南：从接入到落地的全链路实战