摘要
在电商竞品监控、比价系统、商品信息中台开发场景中，京东商品基础信息、价格、规格、库存、图片、类目等数据是核心数据源。很多项目初期选择网页爬虫抓取商品详情，但页面经常改版、JS 动态渲染、防盗链、IP 风控等问题带来极高维护成本。本文基于京东开放平台宙斯体系商品详情接口，讲解接口基础规范、请求入参、返回结构，附带标准 JSON 返回样例，梳理字段解析要点、开发踩坑、业务落地场景，提供合规稳定的官方接口落地方案。
1. 接口基础信息
jd.item_get（京东淘商品详情 API），输入参数为商品唯一 ID num_iid，返回完整商品详情结构化 JSON 数据。
接口简介
接口名称：jd.item_get（京东商品详情API，taobaoapi2014前往体验）
请求网关： c0b.cc/R4rbK2 （HTTPS，支持 GET/POST）
接口版本：2.0
调用限制：存在单秒频次、每日调用配额，高频场景需做限流、缓存 处理。
核心作用：根据商品 ID，获取商品标题、价格、SKU、库存、图文、类 目、销量、规格属性等全量详情数据。
接口能力覆盖
- 商品基础元数据：标题、售价、划线价、销量、库存、发货地
- 多媒体资源：主图、轮播图、HTML 详情描述
- SKU 规格集合：多规格价格、库存、规格文本
- 商品属性参数：材质、尺码、品牌等类目属性
- 店铺信息：店铺 ID、店铺昵称、店铺类型
- 营销促销信息：活动价、优惠券标签
2. 请求入参说明
| 参数名 | 是否必传 | 说明 |
|---|---|---|
| app_key | 是 | 京东开放平台应用密钥，创建应用获取 |
| method | 是 | 接口方法名 |
| timestamp | 是 | 13 位毫秒时间戳 |
| v | 是 | 协议版本，一般 2.0 |
| sign_method | 是 | 签名算法：sha256 |
| sign | 是 | 参数排序后加密生成的签名串 |
| access_token | 否 | 授权令牌，部分接口需要 |
| skuIds | 是 | 商品 SKU 编号，支持批量传入多个 SKU |
| fields | 否 | 按需指定返回字段，减少返回包大小，提升接口响应速度 |
推荐 fields：skuId,title,priceInfo,imageInfo,category,brand,skuList,stockInfo,salesInfo,shopInfo
3. 返回核心字段说明
外层根节点：code、message、result，result内为商品数组goodsInfoList
| 字段 | 数据类型 | 说明 | 开发注意事项 |
|---|---|---|---|
| skuId | string | 商品 SKU 编号 | 最小销售单元 ID，主键 |
| title | string | 商品完整标题 | 用于检索、展示 |
| shortTitle | string | 短标题 | 列表展示用 |
| saleState | int | 上下架状态 | 1 上架，0 下架，下架商品部分字段为空 |
| priceInfo | object | 价格对象 | 包含市场价、京东售价、促销价、优惠券信息 |
| imageInfo | object | 图片集合 | 主图、轮播图数组，图片链接有防盗链 |
| brand | object | 品牌信息 | brandId、brandName、品牌 logo |
| category | object | 类目信息 | 一级 / 二级 / 三级类目 ID 与名称 |
| skuList | array | 多规格 SKU 数组 | 一个 SPU 对应多个 SKU，颜色、版本、容量区分 |
| stockInfo | object | 库存信息 | 可用库存、是否可售、限购、预售标识 |
| salesInfo | object | 销量评价数据 | 总销量、月销、评价总数、好评率 |
| shopInfo | object | 店铺信息 | 店铺 ID、店铺名称、是否京东自营 |
| paramList | array | 商品规格参数 | 材质、尺寸、产地等属性键值对 |
4. JSON 返回样例
javascript
{
"code": 0,
"message": "success",
"result": {
"goodsInfoList": [
{
"skuId": "100089765432",
"title": "无线蓝牙耳机主动降噪长续航入耳式耳机",
"shortTitle": "主动降噪蓝牙耳机",
"saleState": 1,
"priceInfo": {
"marketPrice": "299.00",
"jdPrice": "199.00",
"promotionPrice": "179.00",
"currency": "CNY"
},
"imageInfo": {
"mainImg": "https://img10.360buyimg.com/n1/main.jpg",
"imageList": [
"https://img10.360buyimg.com/n1/img1.jpg",
"https://img10.360buyimg.com/n1/img2.jpg"
]
},
"brand": {
"brandId": 2365,
"brandName": "声麦",
"brandLogo": "https://img10.360buyimg.com/brand/logo.png"
},
"category": {
"cid1": 737,
"cid1Name": "数码",
"cid2": 738,
"cid2Name": "耳机",
"cid3": 739,
"cid3Name": "蓝牙耳机"
},
"skuList": [
{
"subSkuId": "100089765433",
"property": "黑色 | 标准版"
},
{
"subSkuId": "100089765434",
"property": "白色 | 顶配版"
}
],
"stockInfo": {
"availableStock": 312,
"isAvailable": true,
"limitPurchase": "限购2件"
},
"salesInfo": {
"totalSales": 12680,
"monthSales": 2420,
"commentCount": 32600,
"goodRate": "97.6%"
},
"shopInfo": {
"shopId": 100012389,
"shopName": "声麦数码官方自营旗舰店",
"isJdSelf": true
},
"paramList": [
{"name":"续航","value":"40小时"},
{"name":"蓝牙版本","value":"5.4"}
]
}
]
}
}5. 调用流程简述
- 在京东开放平台创建应用，申请对应接口权限；
- 组装公共参数与业务参数，参数按规则排序，SHA256 生成 sign 签名；
- 传入 skuIds，配置需要的 fields，发起 POST 请求；
- 解析返回 JSON，循环遍历
goodsInfoList，读取各 SKU 详情； - skuId 作为唯一主键，入库存储，用于增量同步；
- 业务侧：比价监控、商品中台、竞品信息采集。
6. 业务落地场景
- 电商比价系统：定时抓取竞品售价、促销活动；
- 商品信息中台：统一采集京东商品基础资料、规格参数；
- 竞品分析：监控竞品上下架、库存变动、销量趋势；
- 选品系统：抓取类目、品牌、好评率，辅助电商选品。
7. 开发踩坑实录
- 签名算法错误：京东默认 SHA256，不要沿用淘宝的 MD5 签名；
- 时间戳格式错误：必须 13 位毫秒，10 位秒级直接鉴权失败；
- SKU 和 SPU 区分：接口入参是 SKU ID，不是 SPU，批量查询注意传参；
- 下架商品：saleState=0 时，部分价格、库存字段为空，代码要做空值判断；
- QPS 限制：联盟接口 QPS 较低，批量拉取必须增加请求间隔；
- 图片链接带防盗链，仅内部业务查看，不可直接对外引用。