京东 JD.com商品详情 API

Q: 为什么有的价格显示不出来？

京东会因登录或会员条件遮罩详情页价格。price_masked 为真时，price_display 是页面显示的原文，不要当成精确成交价；监测价格时把这类记录单独标出来。

Q: 商品下架或缺货怎么判断？

看 available，它是当前的可售状态，不可售时 unavailable_reason 给出京东页面上的原因；stock_state 是京东公开的库存状态码，可以一起存下来看变化。

POST

接口健康状态

24h 健康值: 正常
24h 平均耗时: —

健康 / 正常
可用
少量可用
基本不可用

正常

24 小时趋势

30 天趋势

商品详情：返回单个对象；主要字段 item_id、url、title、price、price_display、price_masked。

京东商品详情按 item_id 读取一件京东商品：标题、品牌与型号、价格与原价、可售状态、库存状态、全部商品图、规格变体、条码、产地、保修说明，以及店铺、是否自营、是否京东物流配送。它回答「这件商品现在卖多少、能不能买、由谁发货」，适合价格监测、竞品参数整理和商品库补全。

item_id 填商品数字 ID，或不带参数的 item.jd.com 数字商品页链接，新式的不透明商品链接不接受。读价格前先看 price_masked：京东会因登录或会员条件遮罩价格，为真时 price_display 不能当精确成交价。available 和 unavailable_reason 说明当前是否可售。

单价 $1.39 / 千次（每次 $0.001389），失败与空结果不扣费。同步返回；慢任务可在请求体加 "mode": "async"，先拿 job_id 再轮询。

AI 提示词

复制下面这段给你常用的 AI 助手：里面写好了这个接口的参数、返回字段和示例请求，它会先问清你的需求，再帮你写采集脚本。

请帮我用 EveryInfra 的「京东 JD.com 商品详情」接口（jd/product_detail）写一个数据采集脚本。

接口约定：
- 请求：POST https://api.everyinfra.com/api/v1/social，请求头 Authorization: Bearer <API Key>；Key 从环境变量 EVERYINFRA_API_KEY 读取，不要写进代码。
- 请求体里 platform 填 jd，action 填 product_detail，参数放在 params 里。
- 必填参数：
  - item_id：京东商品数字 ID，或不带 query/fragment 的 https://item.jd.com/<数字>.html；不接受 /product/<opaque>.html 等新式不透明链接。
- 返回一个对象，主要字段：item_id（京东商品数字 ID）、url、title、price、price_display（京东页面显示的价格原文）、price_masked（详情页价格是否被京东遮罩）、currency、available（采集时是否可售（product_d…）、unavailable_reason（不可售时京东页面给出的公开原因）、shop_id（京东店铺数字 ID）、shop_name（公开店铺名称）、shop_url（京东店铺公开页面）；一共 31 个字段，完整列表见 https://api.everyinfra.com/api/v1/social/catalog?platform=jd。
- 示例请求体：
{
  "platform": "jd",
  "action": "product_detail",
  "params": {
    "item_id": "https://item.jd.com/100012043978.html"
  }
}
- 计费：$1.39 / 千次；失败和空结果不扣费。
- 一次要采几十上百个时，在请求体加 "mode": "async"：先拿到 job_id，再轮询 GET https://api.everyinfra.com/api/v1/jobs/{job_id} 取结果。
- 返回 422 时，按错误信息里的候选参数和允许值修正；返回 429 或 503 时，按 Retry-After 等待后重试。

写代码前，先问清楚我要采哪些对象、一共多少个、需要哪些字段、结果存成什么格式，再把方案和大概花费讲给我确认。

请求参数

参数名	位置	类型	必填	默认值	说明
`Authorization`	header	`string`	是	-	Bearer 加你的 API Key。在控制台创建；不要放进网址或代码仓库。
`platform`	body	`string`	是	`jd`	平台标识，固定值。
`action`	body	`string`	是	`product_detail`	能力标识，固定值。
`item_id`	body.params	未声明	是	-	京东商品数字 ID，或不带 query/fragment 的 https://item.jd.com/<数字>.html；不接受 /product/<opaque>.html 等新式不透明链接。

代码示例

bash

curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "jd",
  "action": "product_detail",
  "params": {
    "item_id": "https://item.jd.com/100012043978.html"
  }
}'

[OpenAPI 定义 (JSON)]示例从环境变量 EVERYINFRA_API_KEY 读取 Key，复制出去的代码不含你的 Key。

只接受纯数字 item_id 或不带 query/fragment 的旧式 item.jd.com 数字商品页，不接受任意京东 URL。

响应示例

字段预览

这组示例参数还没有真实样例：这里只按契约列出响应结构和字段，值用 … 占位，不是一次真实调用的结果。

json

{
  "id": "req_…",
  "platform": "jd",
  "action": "product_detail",
  "results": {
    "item_id": …,
    "url": …,
    "title": …,
    "price": …,
    "price_display": …,
    "price_masked": …,
    "currency": …,
    "available": …,
    "unavailable_reason": …,
    "shop_id": …,
    "shop_name": …,
    "shop_url": …,
    "category_id": …,
    "category": …,
    "stock": …,
    "stock_state": …,
    "color": …,
    "size": …,
    "weight": …,
    "image_url": …,
    "image_urls": …,
    "is_jd_self": …,
    "brand": …,
    "model": …,
    "original_price": …,
    "upc": …,
    "warranty": …,
    "product_area": …,
    "is_jd_express": …,
    "variant_count": …,
    "variants": …,
    "platform": …
  },
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}

返回字段

业务数据在 results 里；下表是每条记录可能包含的字段，平台没有提供的值不会被补造。

字段	含义
`item_id`	京东商品数字 ID；search 可把它直接交给详情、评价或价格能力。
`url`	该记录在原平台上的可访问链接。
`title`	标题。平台无标题概念时（如纯文本帖）为 null。
`price`	价格数值，不含货币符号；币种见 currency。
`price_display`	京东页面显示的价格原文；可能因登录或会员条件被遮罩。
`price_masked`	详情页价格是否被京东遮罩；为 true 时不要把 price_display 当精确成交价。
`currency`	价格币种代码（如 CNY、USD）。price 存在但 currency 为 null 时不要假定币种。
`available`	采集时是否可售（product_detail、product_price、shop 的商品行）；缺货时为 false，null 表示页面没给。
`unavailable_reason`	不可售时京东页面给出的公开原因。
`shop_id`	京东店铺数字 ID。
`shop_name`	公开店铺名称。
`shop_url`	京东店铺公开页面。
`category_id`	商品所在的京东末级类目 ID（product_detail）。
`category`	分类名称，取值为原平台的分类体系，未做跨平台归一。
`stock`	京东页面公开的库存数量；null 表示页面没给，不是 0。
`stock_state`	京东公开的库存状态码。
`color`	京东页面上这个 SKU 的颜色（或外观）属性值。
`size`	京东页面上这个 SKU 的尺码、容量或规格属性值。
`weight`	京东页面上的商品重量原文（product_detail）；null 表示页面没写。
`image_url`	图片链接：search、product_detail、shop、skus 里是商品主图（封面）；description_images 里是这一行的那张详情图（京东图床的 https 原图）。
`image_urls`	商品图集链接列表（含主图，按京东页面上的顺序）；单数 image_url 是其中第一张。京东「商品介绍」区的详情长图不在这里，用 description_images 另取。
`is_jd_self`	是否为京东自营商品。
`brand`	商品品牌。
`model`	商品型号。
`original_price`	京东展示的原价；null 表示页面未提供，可能与促销后的 price 不同。
`upc`	商品条码（UPC/EAN）；null 表示页面未提供。
`warranty`	保修说明原文。
`product_area`	产地。
`is_jd_express`	是否由京东物流配送。
`variant_count`	变体（SKU）数量；null 表示无变体或未提供。skus 的每一行都带同一个值：它大于本次返回的行数时，说明被 limit 截断或有 SKU 这次没取到。
`variants`	变体列表，每项含名称、SKU、价格、库存状态等；null 表示无变体或未提供。
`platform`	数据来源平台标识，与请求里的 platform 一致（如 xiaohongshu、tiktok）。

常见问题

`item_id` 能填哪些格式？

填京东商品数字 ID，或不带查询参数和锚点的 https://item.jd.com/<数字>.html。/product/ 开头的新式不透明链接不接受；京东搜索结果里的 item_id 可以直接用。

为什么有的价格显示不出来？

京东会因登录或会员条件遮罩详情页价格。price_masked 为真时，price_display 是页面显示的原文，不要当成精确成交价；监测价格时把这类记录单独标出来。

商品下架或缺货怎么判断？

看 available，它是当前的可售状态，不可售时 unavailable_reason 给出京东页面上的原因；stock_state 是京东公开的库存状态码，可以一起存下来看变化。

错误与计费

401: 缺少 Key 或 Key 无效。先鉴权再校验参数，未鉴权的请求拿不到参数结构。
422: 参数名或取值不对。错误信息会列出这项能力支持的参数、允许值和最接近的候选，按它改即可；发生在扣费之前。
402: 余额不足，请先充值。
429: 超过账户的每分钟请求上限（名下所有 Key 合计；Key 自设了更低上限时先按它算），按 Retry-After 等待后再试。需要更高上限可在控制台买提速包。
503: 暂时无法完成。已预扣的费用按原账本退回；响应里的 billing 与 refund 写明实际结果，结果未知时会明确标出，不要直接重发。
200 空结果: 请求完成但没有数据，不扣费（billing.reason = empty_result_refunded）。