一、API核心功能

京东商品详情API（如 jd.item.get或 jd.union.open.goods.query）是京东开放平台提供的核心接口，用于通过商品ID（skuId）或店铺ID检索指定商品的详细信息。该接口支持获取商品基础信息、价格、库存、规格参数、用户评价等多维度数据，是电商数据分析、竞品监控、个性化推荐等场景的重要工具。

二、返回值结构详解

API返回的JSON数据包含以下核心字段，结构示例如下：

json{"code": "0000","message": "成功","data": {"item": {"skuId": "123456789","title": "Redmi K60 Pro 5G手机 12GB+256GB 墨羽","price": 2999.00,"original_price": 3299.00,"promotion": {"type": "满减","desc": "满3000减300","valid_time": "2025-07-25至2025-07-31"},"images": ["https://img.jd.com/detail1.jpg","https://img.jd.com/detail2.jpg"],"desc": "搭载骁龙8 Gen2处理器，支持120W快充...","stock": 50,"skuList": [{"skuId": "123456","name": "墨羽 12GB+256GB","price": 2999.00,"stock": 50}],"attributes": [{"name": "颜色", "value": "墨羽"},{"name": "内存", "value": "12GB+256GB"}],"category": {"id": "123","name": "5G手机"},"brand": {"id": "1001","name": "Redmi","logo": "https://img.jd.com/brand/logo.jpg"},"afterSaleService": {"return_policy": "7天无理由退货","warranty": "1年质保"},"reviews": {"count": 1000,"rating": 4.8,"positive_rate": "95%"}}}}

1. 基础信息字段

skuId：商品唯一标识符，用于定位具体商品或SKU（如不同颜色、尺寸的变体）。
title：商品标题，包含品牌、型号、核心功能的描述性文本。
images：商品图片URL列表，包括主图和详情图，支持高清展示。
desc：商品详细描述，可能包含HTML标签或纯文本，介绍材质、功能、使用方法等。

2. 价格与促销字段

price：当前售价（元）。
original_price：原价，用于划线价展示。
promotion：促销活动详情，包括类型（如满减）、描述（如“满3000减300”）及有效期。

3. 库存与规格字段

stock：实时库存数量，支持判断商品可售性（如“inStock”表示有货）。
skuList：不同规格（如颜色、内存）的价格及库存信息，每个SKU包含 skuId、 name、 price、 stock等字段。

4. 属性与分类字段

attributes：商品属性列表，包含颜色、尺寸、重量、产地等结构化数据。
category：商品所属类目路径，如“手机>5G手机>Redmi”。
brand：品牌信息，包括品牌ID、名称及Logo链接。

5. 评价与售后字段

reviews：评价数据，包含评价数量（ count）、评分（ rating，如4.8分）及好评率（ positive_rate）。
afterSaleService：售后服务条款，包括退换货政策（如“7天无理由退货”）及保修期限（如“1年质保”）。

三、接口调用规范

1. 请求方式

URL：通常为 https://api.jd.com/routerjson。
方法：支持POST请求。

2. 必填参数

method：接口方法名，如 jd.union.open.goods.query。
app_key：应用密钥，需在京东开放平台创建应用后获取。
timestamp：请求时间戳，格式为 YYYY-MM-DD HH:mm:ss。
v：接口版本号，如 1.0。
param_json：JSON格式的查询条件，如 {"skuIds": ["123456789"]}。

3. 签名生成

步骤：
1. 将所有参数按字典序排序后拼接成字符串。
2. 拼接AppSecret前缀和后缀。
3. 使用MD5加密并转大写。

示例代码（Python）：

pythonimport hashlibdef generate_sign(params, app_secret):sorted_params = sorted(params.items())sign_str = app_secret + ''.join(f"{k}{v}" for k, v in sorted_params) + app_secretreturn hashlib.md5(sign_str.encode()).hexdigest().upper()

四、典型应用场景

1. 实时竞品监控

目标：监控竞品价格波动及促销活动。
实现：
- 定期调用API获取竞品 price和 promotion数据。
- 结合历史数据生成价格趋势图表，触发优惠提醒。

2. 库存同步与补货

目标：同步库存数据至ERP系统，优化补货策略。
实现：
- 通过 stock字段实时监控库存。
- 设置阈值（如库存<100），触发自动补货流程。

3. 个性化推荐

目标：结合用户行为及商品详情生成推荐文案。
实现：
- 提取 attributes中的规格信息（如颜色、内存）。
- 结合 promotion中的满减规则，生成“满3000减300”等文案。

4. 数据可视化与分析

目标：分析商品销售表现及用户口碑。
实现：
- 使用 reviews中的评分及好评率生成评价分析报告。
- 结合 monthly_sales（需申请权限）分析销量趋势。

五、注意事项

调用频率限制：
- 京东API默认QPS（每秒请求次数）限制为1000次/分钟，超限可能导致IP封禁。
- 解决方案：本地缓存高频数据，或申请提升配额。
数据延迟：
- 库存、价格数据可能存在5-10分钟延迟，重要场景建议搭配京东官方数据推送服务。
合规性：
- 不得将数据用于非法用途，需严格遵守京东开放平台协议及数据保护法规。
- 评价数据涉及用户隐私，调用前需申请权限并合理使用。
错误处理：
- 签名错误（4001）：检查参数排序及加密逻辑。
- 参数缺失（1001）：核对接口文档要求的必填字段。
- 商品不存在（3005）：确认商品ID是否正确。

六、示例代码（Python）

pythonimport requestsimport hashlibimport timeAPP_KEY = 'your_app_key'APP_SECRET = 'your_app_secret'API_URL = 'https://api.jd.com/routerjson'def generate_sign(params):sorted_params = sorted(params.items())sign_str = APP_SECRET + ''.join(f"{k}{v}" for k, v in sorted_params) + APP_SECRETreturn hashlib.md5(sign_str.encode()).hexdigest().upper()params = {'method': 'jd.union.open.goods.query','app_key': APP_KEY,'timestamp': time.strftime('%Y-%m-%d %H:%M:%S', time.localtime()),'v': '1.0','param_json': '{"skuIds": ["123456789"]}'}params['sign'] = generate_sign(params)response = requests.post(API_URL, data=params)data = response.json()if data['code'] == '0000':print("商品标题:", data['data']['item']['title'])print("当前价格:", data['data']['item']['price'], "元")print("库存数量:", data['data']['item']['stock'], "件")else:print("请求失败:", data['message'])

通过以上实践，开发者可高效利用京东商品详情API实现数据驱动的电商运营策略。

ITPub博客

京东商品详情API返回值应用实践