京东商品详情 API jd.item.get 完整技术说明文档

文档概述

接口名称：jd.item.get（京东宙斯 JOS 商家服务商版商品全量详情接口，旧别名 item.jd.get）

接口用途：根据商品 SKU ID/Item ID 查询自营 / 第三方店铺完整商品元数据，支撑 ERP 同步、商品中台、竞品监控、店铺铺货、数据大屏等企业级场景

调用网关： c0b.cc/R4rbK2

传输协议：HTTPS POST/GET

数据格式：JSON（默认）、XML 可选

接口版本：v2.0

权限要求：京东开放平台企业认证 + 店铺授权 + 接口权限申请；基础 QPS=2，企业服务商可申请 5~50QPS

区分说明：

jd.item.get：商家服务商接口，数据最全（真实库存、全规格 SKU、售后、参数、详情图文、店铺资质）
jd.union.open.goods.detail.query：联盟推广接口，无真实库存、仅含推广佣金，不可替代本接口

一、接口基础信息

1.1 公共请求参数（所有调用必传）

参数名	类型	是否必填	说明
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 大写签名，签名规则：`app_secret + 所有参数按key升序拼接 + app_secret` 后 MD5
access_token	String	店铺授权场景必填	OAuth 店铺授权令牌，服务商托管店铺必须携带

1.2 业务入参（核心查询参数）

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

1.3 标准请求示例（URL 拼接参数）

http

POST https://api.jd.com/routerjson
Content-Type: application/x-www-form-urlencoded

app_key=YOUR_APP_KEY
&method=jd.item.get
×tamp=2026-06-17 16:30:00
&v=2.0
&format=json
&skuId=100012345678
&fields=skuId,title,brand,category,priceInfo,stockInfo,skuList,imageList,paramList,salesInfo,shopInfo
&sign=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
&access_token=YOUR_ACCESS_TOKEN

1.4 签名生成伪代码（Python）

python

import hashlib

def get_jd_sign(params: dict, app_secret: str) -> str:
    # 1. 剔除sign参数
    sign_params = {k:v for k,v in params.items() if k != "sign"}
    # 2. 按键名升序拼接key+value
    sorted_items = sorted(sign_params.items(), key=lambda x: x[0])
    raw_str = "".join([f"{k}{v}" for k, v in sorted_items])
    # 3. 前后拼接app_secret，MD5大写
    sign_source = f"{app_secret}{raw_str}{app_secret}"
    md5_val = hashlib.md5(sign_source.encode("utf-8")).hexdigest().upper()
    return md5_val

二、原始完整返回 JSON 示例（jd.item.get）

json

{
    "jd_item_get_response": {
        "code": 0,
        "msg": "success",
        "item": {
            "skuId": 100012345678,
            "itemId": 1001234567,
            "title": "华为Mate 60 Pro 12GB+512GB 雅丹黑 5G智能手机",
            "shortTitle": "Mate60 Pro 雅丹黑",
            "saleState": 1,
            "publishTime": "2025-09-10 08:30:00",
            "offlineTime": "",
            "brand": {
                "brandId": 1000123,
                "brandName": "华为(HUAWEI)",
                "brandLogo": "https://img10.360buyimg.com/brand/logo/huawei.png"
            },
            "category": {
                "cid1": 1713,
                "cid1Name": "手机通讯",
                "cid2": 1714,
                "cid2Name": "手机",
                "cid3": 1715,
                "cid3Name": "智能手机"
            },
            "priceInfo": {
                "marketPrice": "6999.00",
                "jdPrice": "6499.00",
                "promotionPrice": "6299.00",
                "memberPrice": "6199.00",
                "currency": "CNY",
                "promotionList": [
                    {
                        "promotionId": 98765,
                        "promotionName": "满6000减200",
                        "startTime": "2026-06-01 00:00:00",
                        "endTime": "2026-06-30 23:59:59",
                        "promotionType": "full_reduce"
                    }
                ]
            },
            "stockInfo": {
                "totalStockNum": 326,
                "stockState": 33,
                "stockDesc": "现货有货",
                "limitBuyNum": 2,
                "isPreSale": false,
                "preSaleDesc": ""
            },
            "imageInfo": {
                "mainImg": "https://img10.360buyimg.com/n1/jfs/t1/200000/30/32000/120000/abcdef123/1a2b3c4d.jpg",
                "imageList": [
                    "https://img10.360buyimg.com/n1/jfs/t1/200000/30/32000/120000/abcdef123/1a2b3c4d.jpg",
                    "https://img10.360buyimg.com/n1/jfs/t1/200000/30/32000/120001/abcdef123/2a2b3c4d.jpg",
                    "https://img10.360buyimg.com/n1/jfs/t1/200000/30/32000/120002/abcdef123/3a2b3c4d.jpg"
                ],
                "detailHtml": "<html>商品详情图文富文本...</html>"
            },
            "paramList": [
                {"name": "品牌", "value": "华为"},
                {"name": "型号", "value": "Mate 60 Pro"},
                {"name": "运行内存", "value": "12GB"},
                {"name": "机身存储", "value": "512GB"},
                {"name": "屏幕尺寸", "value": "6.8英寸"},
                {"name": "机身颜色", "value": "雅丹黑"}
            ],
            "skuList": [
                {
                    "subSkuId": 100012345678,
                    "skuTitle": "华为Mate 60 Pro 12GB+512GB 雅丹黑",
                    "propsText": "颜色:雅丹黑;内存:12GB+512GB",
                    "skuPrice": "6299.00",
                    "skuStock": 126,
                    "skuImg": "https://img10.360buyimg.com/n1/sku_black.jpg"
                },
                {
                    "subSkuId": 100012345679,
                    "skuTitle": "华为Mate 60 Pro 12GB+512GB 白沙银",
                    "propsText": "颜色:白沙银;内存:12GB+512GB",
                    "skuPrice": "6299.00",
                    "skuStock": 200,
                    "skuImg": "https://img10.360buyimg.com/n1/sku_white.jpg"
                }
            ],
            "salesInfo": {
                "totalSales": 126800,
                "monthSales": 3620,
                "commentCount": 89600,
                "goodCommentRate": "98.6%",
                "score": 4.9
            },
            "shopInfo": {
                "shopId": 1000888888,
                "shopName": "华为京东自营官方旗舰店",
                "shopType": "self",
                "shopScore": 4.95,
                "province": "北京市"
            },
            "serviceInfo": {
                "supportJdLogistics": true,
                "sevenDayReturn": true,
                "warrantyYear": "1年全国联保",
                "supportInvoice": true
            }
        }
    }
}

2.1 异常返回 JSON 示例（SKU 不存在）

json

{
    "error_response": {
        "code": 30001,
        "msg": "skuId不存在，请检查商品编号"
    }
}

三、顶层 & 核心字段完整说明

3.1 顶层返回结构

正常返回：jd_item_get_response 对象
异常返回：error_response 对象

3.2 item 主对象一级字段

表格

字段	类型	说明
skuId	Long	当前查询单品 SKU 唯一 ID
itemId	Long	商品主 ID（多规格商品父 ID）
title	String	完整商品标题
shortTitle	String	短标题（前端列表展示）
saleState	Int	上架状态：1 上架 0 下架
publishingTime	String	商品首次上架时间
offlineTime	String	下架时间，空 = 在售
brand	Object	品牌子对象
category	Object	三级分类对象
priceInfo	Object	价格、促销集合
stockInfo	Object	库存、限购、预售
imageInfo	Object	主图、轮播图、详情富文本
paramList	Array	商品规格参数数组
skuList	Array	全规格 SKU 列表
salesInfo	Object	销量、评价、评分
shopInfo	Object	店铺信息（自营 / 第三方）
serviceInfo	Object	售后、物流、发票服务

3.3 子对象字段拆解（建模核心）

3.3.1 brand 品牌

brandId：品牌 ID
brandName：品牌全称
brandLogo：品牌 Logo 地址

3.3.2 category 三级类目

cid1/cid1Name：一级类目

cid2/cid2Name：二级类目

cid3/cid3Name：三级类目

3.3.3 priceInfo 价格模块

marketPrice：专柜原价

jdPrice：京东日常售价

promotionPrice：当前活动到手价

memberPrice：PLUS 会员价

promotionList：促销活动数组（满减 / 优惠券 / 秒杀）

3.3.4 stockInfo 库存模块

totalStockNum：总库存数量

stockState：33 = 有货，34 = 无货，35 = 预售

limitBuyNum：单人限购件数

isPreSale：是否预售

preSaleDesc：预售发货说明

3.3.5 imageInfo 素材模块

mainImg：首图

imageList：轮播图数组

detailHtml：商品详情富文本 HTML（含图文）

3.3.6 skuList 多规格 SKU 数组

subSkuId：子 SKU 编号

skuTitle：规格标题

propsText：规格键值文本（颜色；尺寸；内存）

skuPrice：单品售价

skuStock：单品库存

skuImg：规格对应图片

四、落地结构化模型（数据库 / ORM 标准分层模型）

4.1 分层设计思路

将原始 JSON 扁平化拆分为主商品表、SKU 子表、参数表、图片表、促销表，解决 JSON 嵌套难查询、索引失效问题，适配 MySQL/PostgreSQL。

4.2 1. 商品主表 jd_item_main（单条 /skuId 唯一主键）

表格

字段名	类型	映射来源
id	BIGINT PK	skuId
item_id	BIGINT	itemId
title	VARCHAR(500)	title
short_title	VARCHAR(200)	shortTitle
sale_state	TINYINT	saleState
publish_time	DATETIME	publishingTime
offline_time	DATETIME	offlineTime
brand_id	BIGINT	brand.brandId
brand_name	VARCHAR(100)	brand.brandName
cid1	INT	category.cid1
cid1_name	VARCHAR(50)	category.cid1Name
cid2	INT	category.cid2
cid2_name	VARCHAR(50)	category.cid2Name
cid3	INT	category.cid3
cid3_name	VARCHAR(50)	category.cid3Name
market_price	DECIMAL(10,2)	priceInfo.marketPrice
jd_price	DECIMAL(10,2)	priceInfo.jdPrice
promotion_price	DECIMAL(10,2)	priceInfo.promotionPrice
member_price	DECIMAL(10,2)	priceInfo.memberPrice
total_stock	INT	stockInfo.totalStockNum
stock_state	TINYINT	stockInfo.stockState
limit_buy	INT	stockInfo.limitBuyNum
is_presale	TINYINT	stockInfo.isPreSale
presale_desc	VARCHAR(500)	stockInfo.preSaleDesc
main_img	VARCHAR(500)	imageInfo.mainImg
detail_html	TEXT	imageInfo.detailHtml
total_sales	INT	salesInfo.totalSales
month_sales	INT	salesInfo.monthSales
comment_count	INT	salesInfo.commentCount
good_comment_rate	VARCHAR(20)	salesInfo.goodCommentRate
score	DECIMAL(3,2)	salesInfo.score
shop_id	BIGINT	shopInfo.shopId
shop_name	VARCHAR(200)	shopInfo.shopName
shop_type	VARCHAR(20)	shopInfo.shopType
support_jd_logistics	TINYINT	serviceInfo.supportJdLogistics
seven_day_return	TINYINT	serviceInfo.sevenDayReturn
warranty_info	VARCHAR(200)	serviceInfo.warrantyYear
create_at	DATETIME	入库时间
update_at	DATETIME	接口更新时间

4.3 2. SKU 规格子表 jd_item_sku（一对多，关联 skuId）

表格

字段	类型	关联 / 来源
id	BIGINT PK	自增
parent_sku_id	BIGINT FK	jd_item_main.id
sub_sku_id	BIGINT	skuList.subSkuId
sku_title	VARCHAR(500)	skuTitle
props_text	VARCHAR(300)	propsText
sku_price	DECIMAL(10,2)	skuPrice
sku_stock	INT	skuStock
sku_img	VARCHAR(500)	skuImg
update_at	DATETIME	更新时间

4.4 3. 商品参数表 jd_item_param（一对多）

表格

字段	类型	来源
id	BIGINT PK	自增
sku_id	BIGINT FK	主表 skuId
param_name	VARCHAR(100)	paramList.name
param_value	VARCHAR(500)	paramList.value

4.5 4. 商品图片表 jd_item_image（一对多轮播图）

表格

字段	类型	来源
id	BIGINT PK	自增
sku_id	BIGINT FK	主表 skuId
img_url	VARCHAR(500)	imageList 数组每一项
sort	TINYINT	图片排序序号

4.6 5. 促销活动表 jd_item_promotion（一对多）

表格

字段	类型	来源
id	BIGINT PK	自增
sku_id	BIGINT FK	主表 skuId
promotion_id	BIGINT	promotionList.promotionId
promotion_name	VARCHAR(300)	promotionName
promotion_type	VARCHAR(50)	promotionType
start_time	DATETIME	startTime
end_time	DATETIME	endTime

4.7 统一结构化 JSON 模型（业务中间层输出，前端 / 下游服务直接使用）

json

{
  "code": 0,
  "message": "success",
  "data": {
    "base": {
      "skuId": 100012345678,
      "itemId": 1001234567,
      "title": "华为Mate 60 Pro 12GB+512GB 雅丹黑 5G智能手机",
      "shortTitle": "Mate60 Pro 雅丹黑",
      "saleState": 1,
      "brand": {"id":1000123,"name":"华为(HUAWEI)","logo":"xxx"},
      "category": {"c1":1713,"c1Name":"手机通讯","c2":1714,"c2Name":"手机","c3":1715,"c3Name":"智能手机"},
      "shop": {"shopId":1000888888,"shopName":"华为京东自营官方旗舰店","shopType":"self"}
    },
    "price": {
      "marketPrice": "6999.00",
      "jdPrice": "6499.00",
      "promotionPrice": "6299.00",
      "memberPrice": "6199.00",
      "promotions": [{"promotionId":98765,"name":"满6000减200","type":"full_reduce","start":"2026-06-01","end":"2026-06-30"}]
    },
    "stock": {
      "totalStock": 326,
      "state": 33,
      "stateDesc": "现货有货",
      "limitBuy": 2,
      "isPreSale": false
    },
    "media": {
      "mainImg": "https://xxx.jpg",
      "imageList": ["img1","img2","img3"],
      "detailHtml": "商品详情富文本"
    },
    "params": [{"name":"品牌","value":"华为"},{"name":"内存","value":"12GB+512GB"}],
    "skuList": [
      {"subSkuId":100012345678,"title":"雅丹黑","props":"颜色:雅丹黑","price":"6299.00","stock":126,"img":"xxx"},
      {"subSkuId":100012345679,"title":"白沙银","props":"颜色:白沙银","price":"6299.00","stock":200,"img":"xxx"}
    ],
    "sales": {
      "totalSales": 126800,
      "monthSales": 3620,
      "commentCount": 89600,
      "score": 4.9,
      "goodRate": "98.6%"
    },
    "service": {
      "jdLogistics": true,
      "sevenReturn": true,
      "warranty": "1年全国联保",
      "supportInvoice": true
    }
  }
}

五、常见错误码与排错

错误码	错误描述	解决方案
30001	skuId 不存在	核对商品 ID，区分 itemId/skuId
10001	app_key 无效	检查应用密钥、应用状态是否审核通过
10003	sign 签名错误	检查参数排序、时间戳、app_secret
20005	无接口调用权限	开放平台后台申请 `jd.item.get` 权限
40002	access_token 失效	重新发起店铺 OAuth 授权
50001	QPS 超限	降低并发，申请提升 QPS 额度

六、工程落地最佳实践

字段过滤：调用时携带fields参数，只拉取业务所需字段，减少网络与解析耗时
分层存储：原始 JSON 归档 MongoDB，结构化分层存入 MySQL，兼顾原始日志与查询性能
定时同步：商品监控场景按 1~6 小时轮询；铺货 / ERP 场景实时调用
SKU 主键隔离：以 skuId 作为唯一业务主键，多规格商品单独存储子 SKU 表，避免规格覆盖
图片资源处理：返回图片 URL 统一转 HTTPS、缓存本地 CDN，降低前端加载耗时
参数标准化：paramList 数组转为 key-value 键值对存入参数表，支持按规格筛选商品
限流熔断：封装调用客户端，增加 QPS 限流、超时重试、异常熔断机制

分析中 投票中 优化中 已优化 已回复 待规划 {{opt.name}} 分析中 投票中 优化中 已优化 已回复 待规划 京东商品详情API技术说明文档（jd.item.get｜含原始 JSON + 落地结构化模型）

京东商品详情 API jd.item.get 完整技术说明文档

文档概述

一、接口基础信息

1.1 公共请求参数（所有调用必传）

1.2 业务入参（核心查询参数）

1.3 标准请求示例（URL 拼接参数）

1.4 签名生成伪代码（Python）

二、原始完整返回 JSON 示例（jd.item.get）

2.1 异常返回 JSON 示例（SKU 不存在）

三、顶层 & 核心字段完整说明

3.1 顶层返回结构

3.2 item 主对象一级字段

3.3 子对象字段拆解（建模核心）

3.3.1 brand 品牌

3.3.2 category 三级类目

3.3.3 priceInfo 价格模块

3.3.4 stockInfo 库存模块

3.3.5 imageInfo 素材模块

3.3.6 skuList 多规格 SKU 数组

四、落地结构化模型（数据库 / ORM 标准分层模型）

4.1 分层设计思路

4.2 1. 商品主表 jd_item_main（单条 /skuId 唯一主键）

4.3 2. SKU 规格子表 jd_item_sku（一对多，关联 skuId）

4.4 3. 商品参数表 jd_item_param（一对多）

4.5 4. 商品图片表 jd_item_image（一对多轮播图）

4.6 5. 促销活动表 jd_item_promotion（一对多）

4.7 统一结构化 JSON 模型（业务中间层输出，前端 / 下游服务直接使用）

五、常见错误码与排错

六、工程落地最佳实践

分析中已回复待规划 {{opt.name}}
分析中已回复待规划
京东商品详情API技术说明文档（jd.item.get｜含原始 JSON + 落地结构化模型）