京东商品信息 API 的核心价值，在于把商品详情页中**价格、库存、SKU、图片、类目、店铺、促销**等分散信息，收敛为一份可稳定消费的结构化 JSON。下面按“查询 → 解析 → 接入 → 应用 → 避坑”的路径展开。
---
### 先分清两个层面：查什么，用什么查
京东商品信息 API 在实际使用中通常涉及两个不同体系，选错入口会导致字段缺失或权限不足。
**京东联盟体系**的 `jd.union.open.goods.detail.query` 是获取商品完整详情最常用的入口。传入一个 SKU ID，即可返回标题、价格、优惠券、库存、SKU 规格、图片、评价等全维度数据，适合比价监控、商品同步、选品分析等场景。联盟接口的核心优势在于**促销与佣金信息完整**，如果业务涉及 CPS 导购或联盟推广，这是首选。
**京东开放平台（JOS）体系**的 `jd.item.get`（部分文档中也写作 `jingdong.item.read.get`）则更贴近商家后台和 ERP 场景，核心入参同样是 SKU 编号，返回商品基础信息、SKU 规格、图集、参数属性、促销、店铺、自营标识等完整业务数据，支持自营、第三方店铺和京东国际商品。两个体系在字段命名和响应结构上有差异，但底层商品数据源是一致的。
无论用哪个体系，**查询的主键必须是 SKU ID，而不是 SPU ID**。SKU 对应具体颜色、内存组合的唯一库存单元，价格和库存是绑定在 SKU 上的；SPU 只是一个产品型号（如 iPhone 15 Pro Max），一个 SPU 下可能包含数十个 SKU，直接查 SPU 拿不到准确的价格和库存。
---
### 请求参数：核心只有四类
虽然不同接口的公共参数略有差异，但业务侧真正需要关注的参数可以归为四类：
**① 身份凭证。** 包括 `app_key`、`app_secret`（用于签名，不直接传输）、`access_token`（部分接口需要），以及 `method`、`timestamp`、`v`、`sign_method`、`sign` 等公共参数。签名是接入的第一道门槛，后文单独说明。
**② 商品定位。** `sku_id` 或 `skuIds` 是必传项。批量查询时部分接口支持一次传入多个 SKU，例如 `jingdong.item.list.get` 单次最多支持 20 个商品 ID。
**③ 地域参数（容易被忽略但很关键）。** `area` 或 `area_id` 用于指定地区编码。京东的**价格、库存、促销活动具有地域性**：不传 `area` 时，接口通常返回北京地区的默认数据；如果你的业务实际发货仓或销售区域在华东、华南，拿到的库存和价格可能并不准确，竞品监控场景下甚至会造成误告警。
**④ 字段裁剪。** `fields` 参数用于指定需要返回的字段集合。不传时默认返回全集，但建议**始终显式指定**业务真正需要的字段，这样可以显著减小返回包体积，降低接口超时和触发限流的概率。
---
### 返回字段：按业务模块拆解
京东商品详情接口的返回通常是一个多层 JSON，顶层有 `code`、`message` 等状态字段，业务数据包裹在 `data`、`result` 或 `goodsInfo` 等节点下。按业务模块看，核心字段可分为以下几组：
**价格体系。** 最需要区分的是 `jd_price`（前台实时售价）与 `market_price`（划线价/厂商指导价）。`market_price` 仅用于展示折扣力度，**不能作为实际售价使用**。促销信息通常放在 `promotion_info` 或 `couponInfo` 中，可能包含优惠券面额、满减描述、活动起止时间。需要注意的是，**接口通常不直接返回“最终到手价”**，真实到手价需要由业务层将售价与优惠券、满减叠加后自行计算。
**库存状态。** `stock_state` 用数字标识可售状态：1 通常为现货，33 为无货可预订，34 为无货不可购买，36 为采购中。库存同样是**区域可售库存**，不是全国总库存，`area` 参数必须与业务发货区域一致。预售商品会带有 `preSaleStatus` 标记，不能直接按现货库存处理。
**SKU 规格。** 多规格商品会在 `sku_list` 中返回子 SKU 数组，每个子项包含 `sku_id`、`spec_text`（如“黑色 128G”）、`sku_price`、`sku_stock` 等。一个常见错误是只取外层的商品价格和库存，而忽略了真正的价格和库存是绑定在子 SKU 上的。
**图片与详情。** `pic_url` 或 `main_image` 是主图，`images` 或 `image_list` 是轮播图集，`desc` 是商品详情的 HTML 源码。京东图片域名 `360buyimg.com` 存在防盗链机制，直接外链到其他平台或自有系统可能出现 403 或裂图，需要下载转存到对象存储后再使用。
**店铺与品牌类目。** `shop_id`、`seller_nick`、`is_self` 用于区分自营与第三方店铺；`brand` 对象提供品牌 ID 和名称；`cat_id` 和 `cat_name` 提供类目层级信息。这些字段在铺货类目映射和竞品归属分析中高频使用。
---
### 接入与调用：签名是核心门槛
接入流程本身不复杂，但签名和调用细节决定了后续稳定性。
**第一步：在京东开放平台创建应用。** 完成开发者认证后，创建应用并申请商品详情查询权限，获取 `app_key` 和 `app_secret`。`app_secret` 只用于本地签名计算，不应出现在请求参数或日志中。
**第二步：生成签名。** 将所有非空请求参数按参数名 ASCII 升序排序，只拼接各参数的 value（或按 `key+value` 形式），首尾各加一次 `app_secret`，进行 MD5 或 SHA256 哈希后转为大写。时间戳格式通常为 `yyyy-MM-dd HH:mm:ss`（东八区），与服务器时间偏差超过 10 分钟会被直接拒绝。
**第三步：发送请求。** 以 HTTPS POST（部分接口也支持 GET）提交到京东网关。以下是一个精简的 Python 签名与请求骨架，展示的是调用逻辑本身：
```python
import requests, hashlib, time
def jd_sign(params, app_secret):
items = sorted(params.items())
raw = "".join(f"{k}{v}" for k, v in items)
src = app_secret + raw + app_secret
return hashlib.md5(src.encode()).hexdigest().upper()
params = {
"method": "jd.item.get",
"app_key": "YOUR_APP_KEY",
"access_token": "YOUR_ACCESS_TOKEN",
"timestamp": time.strftime("%Y-%m-%d %H:%M:%S"),
"v": "2.0",
"sign_method": "md5",
"sku_id": "100012345678",
"fields": "sku_id,title,price_info,stock_info,image_info,sku_list"
}
params["sign"] = jd_sign(params, "YOUR_APP_SECRET")
resp = requests.post("https://api.jd.com/routerjson", data=params, timeout=10)
data = resp.json()
```
这段代码的核心是**先排序、再拼接、首尾加 secret、MD5 转大写**；业务参数中显式指定了 `fields`，避免拉回无关字段。
---
### 从查询到应用：四类典型场景的字段选择
不同业务场景对字段的需求差异很大，**按场景裁剪字段**是控制调用成本和响应延迟的第一步。
**比价与竞品价格监控。** 核心字段是 `price_info`、`promotion_info`、`stock_info` 和 `sku_list`。落地逻辑是：将历史价格快照存入 Redis 或数据库，定时轮询重点竞品（高频场景 5—10 分钟，长尾商品 30—60 分钟），对比价格下跌、新增活动或库存清零时触发告警。真实到手价需要业务层叠加优惠券和满减逻辑，不能直接取单一字段。
**ERP 货源同步与库存校验。** 核心字段是 `stock_info`、`sku_list`、`price_info` 和 `isAvailable`。热销 SKU 缓存 5—10 分钟，长尾 SKU 缓存 30 分钟；但**下单前应绕过缓存直接调用一次接口校验可售库存**，防止超卖。同时需要解析预售标记和限购字段，避免将预售库存当作现货扣减。
**跨平台铺货与商品搬家。** 需要 `title`、`image_list`、`paramList`、`sku_list`、`price_info` 和详情 HTML。关键动作包括：图片下载转存、京东类目到目标平台的映射、SPU/SKU 层级重组、过滤 HTML 中的站内跳转和埋点代码。标题、图片、属性等静态字段可缓存 24 小时，不必每次刊登都实时调用。
**选品分析。** 核心字段是 `category`、`brand`、`salesInfo`（总销量、月销）、`commentSummary`（评价数、好评率）以及价格区间。选品系统通常需要结合商品列表接口做类目扫描，再用详情接口对候选商品做深度字段拉取，依靠销量、好评率、价格带筛选潜力商品。
---
### 工程化避坑：比接口文档更关键的部分
**限流与重试。** 京东 API 存在 QPS 限制和每日调用配额。收到 429 或限流错误码时，不能立即无间隔重试，应采用**指数退避 + 最大重试次数**（通常 2 次即可），并优先将非实时请求放入队列延迟处理。
**缓存分层。** 价格和库存是高频变动字段，但不是所有业务都需要秒级实时性。标题、图片、类目、参数等静态字段缓存周期可以放长；价格库存缓存 5—10 分钟；下单校验等强一致性场景绕过缓存直调。这样可以在接口配额和业务实时性之间取得平衡。
**SPU 与 SKU 不要混用。** 这是京东商品 API 最高频的踩坑点：查询必须传 `sku_id`，价格库存遍历必须落到子 SKU，业务主键应使用 `sku_id` 而非 SPU ID。
**图片防盗链与详情清洗。** 图片 URL 不能假设可以直接外链，需要本地化转存；详情 HTML 需要过滤站内链接、埋点脚本和广告标签后再入库。
---
把以上环节串起来，京东商品信息 API 的使用路径可以概括为：**用 SKU ID 定位商品，按场景裁剪字段发起签名请求，解析时严格区分价格层级与 SKU 层级，落地时配合地域参数、缓存分层和指数退避重试**。接口本身提供的是结构化原料，真正决定业务效果的，是在“到手价计算、SKU 遍历、库存地域性、图片转存”这几个环节上的处理精度。
