版本：V2.0｜适用：ERP、跨境铺货、竞品监控、反向海淘代购、选品中台、比价系统 定位：根据 SKU 编号获取京东商品完整结构化详情；本手册包含接口规范、标准 JSON 样例、8 大业务场景落地、缓存限流策略、踩坑清单、Python 最小可运行 Demo
一、接口基础说明
1.1 基础信息
接口名称：jd .item.get（（京东商品详情 API，taobaoapi2014 前往体验））
正式网关：c0b.cc/R4rbK2
请求方式：HTTPS GET / POST
返回格式：json /xml（推荐 json）
API 版本：v2.0
核心能力：根据 num_iid 商品 ID，查询商品基础信息、价格、SKU、图文、类目、规格参数、上下架状态
1.1 接口区分（选型必看）
表格
| 接口 | 官方名称 | 适用对象 | 核心差异 |
|---|---|---|---|
| jd.item.get（第三方服务商版） | 商品详情查询 | 供应链、铺货、代购、竞品监控 | 全量图文、SKU、价格、促销；库存为区域可售库存；无需京东店铺授权 |
| jingdong.item.read.get（JOS 商家版） | 商家商品读取 | 京东 POP / 自营商家 ERP | 精确仓配库存、可联动订单售后，必须拥有京东店铺 |
| jd.union.open.goods.detail.query（联盟版） | 联盟商品详情 | CPS 导购、小程序 | 自带佣金、推广链接，无实时精准库存 |
本手册以 jd.item.get 第三方通用详情接口为主，HTTPS POST 调用，返回 JSON，版本 v2.0。
1.2 请求公共参数
表格
| 参数 | 类型 | 是否必传 | 说明 |
|---|---|---|---|
| method | string | 是 | jd.item.get |
| app_key | string | 是 | 应用 key |
| app_secret | string | 是 | 密钥，用于 MD5 签名，禁止硬编码 |
| skuId | string | 是 | 京东 SKU 编号（10 位数字），核心入参 |
| area | string | 否 | 区域编码 1_72_2799_0，决定该地区价格、库存、运费，不传默认北京区域数据，会造成价格库存失真 |
| fields | string | 否 | 按需筛选返回字段，例如 skuId,title,priceInfo,skuList,stockInfo，减少报文体积 |
| v | string | 是 | 接口版本，固定2.0 |
| timestamp | string | 是 | 13 位毫秒时间戳；服务器时间偏差不可大于 5 分钟，否则签名报错 |
| sign_method | string | 是 | md5 |
| format | string | 否 | json |
签名规则：所有非空参数按 ASCII 升序排序，拼接 secret，MD5 大写输出 sign 签名值。
1.3 标准返回 JSON 示例（精简）
json
{"code": 200,"msg": "success","data": {"skuId": "100012345678","title": "2026新款高性能轻薄笔记本电脑","subTitle": "金属机身｜14英寸高清屏","brand": {"brandId": 10086,"brandName": "联想","brandLogo": "https://img10.360buyimg.com/brand/logo/xxx.jpg"},"category": {"cid1": 670,"cid1Name": "电脑办公","cid2": 671,"cid2Name": "笔记本","cid3": 672,"cid3Name": "轻薄本"},"priceInfo": {"marketPrice": "5999.00","jdPrice": "5499.00","promotionPrice": "5299.00","memberPrice": "5199.00","currency": "CNY","promotionList": [{"promotionId": 88661,"promotionName": "满5000减200","promotionType": "full_reduce","startTime": "2026‑07‑01 00:00:00","endTime": "2026‑08‑31 23:59:59"}]},"stockInfo": {"stockNum": 368,"availableStock": 312,"isAvailable": true,"limitPurchase": "限购2件","preSaleStatus": 0},"salesInfo": {"totalSales": 12680,"monthSales": 2420},"imageInfo": {"mainImage": "https://img14.360buyimg.com/n1/jfs/txxx.jpg","imageList": ["https://img14.360buyimg.com/n1/jfs/txxx1.jpg","https://img14.360buyimg.com/n1/jfs/txxx2.jpg"]},"skuList": [{"subSkuId": "10001234567801","properties": "颜色:深空灰;内存:16G+512G","skuPrice": "5299.00","skuStock": 126},{"subSkuId": "10001234567802","properties": "颜色:银色;内存:16G+1T","skuPrice": "5699.00","skuStock": 88}],"shopInfo": {"shopId": 100998,"shopName": "联想京东自营旗舰店","shopType": "self"},"attributeList": [{"attrName":"CPU型号","attrValue":"Intel i7‑1360P"},{"attrName":"屏幕尺寸","attrValue":"14英寸"}],"descHtml":"<div>商品详情HTML正文……</div>","logisticsInfo":{"isFreeShipping":true,"nextDayArrival":true}}}
错误码说明
- 1000：签名错误（时间不同步、参数漏传、secret 错误）
- 2001：权限不足，接口未开通
- 429：调用频率超限
- 7：接口网关超时
- 50001：skuId 不存在 / 已下架
二、八大业务场景完整落地方案
场景 1｜跨平台铺货（1688/Ozon/Temu/Shopee 一键搬家）
业务目标：采集京东商品，清洗后刊登至跨境、国内第三方店铺，替代爬虫，保证字段稳定。需要字段：title、imageList、attributeList、skuList、priceInfo、descHtml、brand、category 落地逻辑
- 调用 jd.item.get 获取原始 JSON；
- 图片 URL 处理：京东图片域名 360buyimg.com，部分平台不允许外链，必须下载转存对象存储，替换图片地址；
- 属性映射：京东类目→目标平台类目映射表；结构化属性转为目标平台规格参数；
- SKU 映射：京东 subSkuId 映射外部平台 sku 编码，价格做汇率 / 利润加成；
- 过滤 HTML 内京东站内跳转链接，清理广告标签；缓存策略：标题、图片、属性缓存 24h，不要每次刊登都调用；风险点：京东部分商品图片有防盗链，直接粘贴刊登会裂图，必须本地化转存。
场景 2｜竞品价格 & 促销监控系统（品牌 / 渠道商）
业务目标：定时监控竞品价格变动、大促活动上线，价格跌破阈值自动预警。需要字段：priceInfo、promotionList、stockInfo、skuList 落地逻辑
- Redis 存储历史价格快照，key=skuId，存储历史价格、活动、时间；
- 定时任务轮询：重点竞品 5‑10 分钟调用一次，长尾商品 30‑60 分钟；
- 真实到手价计算逻辑：真实到手价 = min(promotionPrice,memberPrice)，叠加满减、优惠券后做预估算；
- 对比快照，发生价格下跌、新增活动、库存清零，推送企业微信 / 钉钉告警；
- 区分：标价 marketPrice 仅做划线展示，不能作为实际售价；限流策略：令牌桶，QPS 不超过接口配额 80%，防止 429；坑：area 区域参数缺失，拿到北京价格，和业务实际销售地区不一致，造成误告警。
场景 3｜ERP 货源同步（以京东为供货源）
业务目标：同步京东 SKU 售价、可售库存，防止超卖、亏损下单。需要字段：stockInfo、skuList、priceInfo、isAvailable 落地逻辑
- 热销 SKU：缓存 5‑10 分钟；长尾 SKU 缓存 30 分钟；
- 业务下单前，绕过缓存直接调用一次接口校验可售库存；
- 解析preSaleStatus预售标记，预售商品不能直接扣现货库存；
- 限购字段limitPurchase，订单系统做下单数量拦截；降级逻辑：接口超时，使用 Redis 缓存旧数据，记录告警日志，禁止直接拒绝下单；
注意：该接口库存为区域可售库存，不是全国总库存，area 必须设置为业务发货地区编码稀土掘金。
场景 4｜反向海淘 / 集运代购系统（mulebuy/superbuy 同类系统）
业务目标：海外用户选购京东商品，前端展示商品详情、价格、库存、包邮标签。需要字段：title、imageList、priceInfo、logisticsInfo、attributeList、skuList 落地逻辑
- 前端展示时做币种转换 CNY→外币；
- isFreeShipping京东包邮标签作为系统展示标签，注意京东包邮不等于可以直接发海外；
- SKU 选择器完全复用接口返回 skuList；
- 用户提交代购订单前，实时调用接口校验该 SKU 是否可售；优化：商品详情页首次加载读取 Redis 缓存，仅下单动作实时请求 API；风险：京东自营部分商品仅支持国内配送，接口无法直接返回海外可配送标记，业务层需要维护黑名单表过滤不能集运商品。
场景 5｜AI 智能选品系统（供应链数据分析）
业务目标：批量挖掘类目爆款，按月销、价格区间、好评、库存筛选潜力货源。需要字段：salesInfo、priceInfo、category、stockInfo、attributeList 落地逻辑
- 搭配京东搜索接口拿到类目下 skuId 列表；
- 循环调用 jd.item.get 拿到每个商品结构化数据，入库 MySQL；
- 筛选规则示例：月销 > 500、库存 > 100、价格区间过滤，输出候选货源；
- 结合评论 API 做差评率辅助筛选；性能优化：尽可能使用批量接口jd.items.batch.get，一次最多 50 个 SKU，降低请求次数；非实时数据分析任务放在凌晨低峰执行，避开大促高峰期。
场景 6｜比价小程序、导购平台
业务目标：展示京东商品价格、活动，给用户做比价参考。
建议优先评估联盟接口jd.union.open.goods.detail.query，自带佣金和推广链接；jd.item.get 落地要点
- 不要高频刷取，用户访问触发优先读缓存；
- 对外展示必须标注数据来源京东；限制：该接口不直接返回 CPS 佣金，如需推广链路，必须再调用联盟接口获取推广 url。
场景 7｜商品舆情分析配套数据源（评论舆情系统前置）
业务目标：商品基础元数据，绑定评论接口，做竞品口碑监控。需要字段：skuId、title、brand、category、shopInfo 落地逻辑
- jd.item.get 拿到商品基础元信息；
- 调用京东评论 API 获取评论集合；
- 将品牌、类目、店铺标签附加到每条评论，做 AI 舆情、差评预警；缓存策略：商品基础元信息缓存 24h，无需随评论同步刷新。
场景 8｜自建商城 / 内部供应链中台
业务目标：把京东作为货源池，内部商城展示商品，用于企业采购、内部选品。落地要点
- 图片全部转存自有存储，防盗链；
- area 配置业务实际采购地区；
- 价格不要直接透传京东价格，业务层叠加加价规则；
- 库存仅作参考，下单前实时校验，不能完全依赖接口库存做扣减。
