京东获得JD商品详情 API 返回值说明||京东API接入文档

京东商品详情API返回值核心字段说明

一、商品基础信息

1. 商品ID（skuId/productId）
   • 唯一标识符，用于定位具体商品或SKU（如不同颜色、尺寸的变体）。
   • 示例："skuId": "123456789"
2. 商品标题（title）
   • 包含品牌、型号、核心功能的描述性文本。
   • 示例："title": "Redmi K60 Pro 5G手机 12GB+256GB 墨羽"
3. 商品图片（images/item_imgs）
   • 返回主图、详情图、视频封面等多张图片的URL列表，支持高清展示。
   • 示例：

     json

     "images": [

     "https://img.jd.com/detail1.jpg",

     "https://img.jd.com/detail2.jpg"

     ]

4. 商品描述（description/desc）
   • 详细介绍材质、功能、使用方法等，可能包含HTML标签或纯文本。
   • 示例："desc": "搭载骁龙8 Gen2处理器，支持120W快充..."

二、价格与促销信息

1. 价格字段
   • price：当前售价（元）。
   • original_price：原价（用于划线价展示）。
   • promotion：促销活动详情，如满减、折扣、赠品等。
   • 示例：

     json

     "price": 2999.00,

     "original_price": 3299.00,

     "promotion": {

     "type": "满减",

     "desc": "满3000减300",

     "valid_time": "2025-07-25至2025-07-31"

     }

2. SKU价格列表（skuList）
   • 返回不同规格（如颜色、内存）的价格及库存。
   • 示例：

     json

     "skuList": [

     {

     "skuId": "123456",

     "name": "墨羽 12GB+256GB",

     "price": 2999.00,

     "stock": 50

     }

     ]

三、库存与状态

1. 库存数量（stock/quantity）
   • 实时库存数据，支持判断商品可售性。
   • 示例："stock": 50
2. 库存状态
   • 可能返回"inStock"（有货）、"outOfStock"（无货）等枚举值。

四、商品属性与分类

1. 商品属性（attributes/props）
   • 包含颜色、尺寸、重量、产地等结构化数据。
   • 示例：

     json

     "attributes": [

     {"name": "颜色", "value": "墨羽"},

     {"name": "内存", "value": "12GB+256GB"}

     ]

2. 分类信息（category）
   • 商品所属的类目路径，如“手机>5G手机>Redmi”。
   • 示例：

     json

     "category": {

     "id": "123",

     "name": "5G手机"

     }

五、品牌与售后服务

1. 品牌信息（brand）
   • 包含品牌ID、名称及Logo链接。
   • 示例：

     json

     "brand": {

     "id": "1001",

     "name": "Redmi",

     "logo": "https://img.jd.com/brand/logo.jpg"

     }

2. 售后服务（afterSaleService）
   • 退换货政策、保修期限等。
   • 示例：

     json

     "afterSaleService": {

     "return_policy": "7天无理由退货",

     "warranty": "1年质保"

     }

六、评价与销量

1. 评价数据（reviews）
   • 可能返回评价数量、评分（如4.8分）、好评率等。
   • 示例：

     json

     "reviews": {

     "count": 1000,

     "rating": 4.8,

     "positive_rate": "95%"

     }

2. 销量数据（sales）
   • 30天销量、总销量等（需申请权限）。
   • 示例："monthly_sales": 5000

京东API接入流程

一、注册与权限申请

1. 注册开发者账号
   • 访问京东开放平台，完成企业或个人认证。
2. 创建应用
   • 在控制台创建应用，填写名称、描述，选择“商品详情API”权限。
3. 获取API密钥
   • 审核通过后，获取AppKey和AppSecret，用于身份验证。

二、接口调用规范

1. 请求方式
   • 通常为POST请求，URL如：
     https://api.jd.com/routerjson
2. 请求参数
   • 必填参数：method（接口方法名）、app_key、timestamp、v（版本号）、param_json（JSON格式的查询条件）。
   • 示例：

     json

     {

     "method": "jd.union.open.goods.detail.query",

     "app_key": "YOUR_APP_KEY",

     "timestamp": "2025-07-25 17:00:00",

     "v": "1.0",

     "param_json": "{\"skuIds\": [\"123456789\"]}"

     }

3. 签名生成
   • 按字典序排序参数，拼接AppSecret后进行MD5加密并转大写。
   • Python示例：

     python

     import hashlib

     def 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_secret

     return hashlib.md5(sign_str.encode()).hexdigest().upper()

三、响应处理与错误码

1. 响应格式
   • 返回JSON数据，包含code（状态码）、message（错误信息）、data（业务数据）。
   • 成功示例：

     json

     {

     "code": "0000",

     "message": "成功",

     "data": {

     "item": {

     "title": "Redmi K60 Pro",

     "price": 2999.00

     }

     }

     }

2. 常见错误码
   • 1001：参数缺失
   • 3005：商品不存在
   • 4001：签名验证失败
   • 5000：QPS超限（默认1000次/分钟，需申请提额）

应用场景与优化建议

1. 比价系统
   • 实时监控竞品价格波动，结合促销信息生成优惠提醒。
2. 库存预警
   • 同步库存数据至ERP系统，触发低库存自动补货。
3. 营销活动生成
   • 自动抓取满减、赠品规则，生成个性化推荐文案。
4. 性能优化
   • 缓存策略：对静态数据（如商品描述）本地缓存，减少API调用。
   • 字段过滤：通过fields参数指定返回字段，降低网络负载。
   • 批量查询：支持最多20个SKU同时查询，提升效率。