京东商品详情数据API接口响应示例|参数解析

用户722230150787
49 阅读7分钟

前言：京东商品详情数据API是电商领域开发者常用的接口之一，广泛应用于商品数据采集、电商平台对接、数据分析等场景。本文将详细展示接口响应示例，并对核心参数进行逐字段解析，帮助开发者快速理解接口返回数据结构，提升对接效率。

一、接口基础信息

在查看响应示例和参数解析前，先明确接口的基础调用信息，避免对接时出现基础错误：

  • 接口名称：京东商品详情查询接口
  • 接口地址：api.jd.com/routerjson（…
  • 请求方式：GET/POST（推荐POST，避免参数暴露）
  • 核心请求参数：app_key（应用密钥）、sign（签名）、method（接口方法名，如jd.union.open.goods.detail.query）、skuId（商品ID，核心业务参数）、timestamp（时间戳）、format（返回格式，默认json）
  • 权限要求：需在京东开放平台完成应用注册，获取对应接口调用权限

二、完整响应示例

以下是接口返回的标准JSON格式响应示例，包含商品基础信息、价格信息、库存信息、规格参数等核心数据（实际响应字段可能因商品类型、接口版本略有差异）：

{
  "code": 200,
  "message": "success",
  "data": {
    "skuId": 100012345678,
    "spuId": 1000123456,
    "productName": "京东京造 无线蓝牙耳机 半入耳式 长续航降噪",
    "brandName": "京东京造",
    "mainImage": "https://img10.360buyimg.com/n1/jfs/t1/12345/67/8910/123456/abcdef1234567890/1234567890123.jpg",
    "detailImages": [
      "https://img10.360buyimg.com/n1/jfs/t1/12346/68/8911/123457/abcdef1234567891/1234567890124.jpg",
      "https://img10.360buyimg.com/n1/jfs/t1/12347/69/8912/123458/abcdef1234567892/1234567890125.jpg"
    ],
    "priceInfo": {
      "jdPrice": 199.00,
      "originalPrice": 299.00,
      "promotionPrice": 179.00,
      "promotionStartTime": 1735689600000,
      "promotionEndTime": 1736294400000,
      "isPromotion": true
    },
    "stockInfo": {
      "stockNum": 568,
      "isStock": true,
      "areaStock": {
        "Beijing": 120,
        "Shanghai": 98,
        "Guangzhou": 156
      }
    },
    "specInfo": {
      "specList": [
        {
          "specName": "颜色",
          "specValues": ["白色", "黑色", "蓝色"]
        },
        {
          "specName": "续航时间",
          "specValues": ["24小时", "36小时"]
        }
      ],
      "selectedSpec": {
        "颜色": "白色",
        "续航时间": "24小时"
      }
    },
    "salesInfo": {
      "monthSales": 12560,
      "totalSales": 89632,
      "commentCount": 3256
    },
    "shopInfo": {
      "shopId": 1000001234,
      "shopName": "京东京造官方旗舰店",
      "shopScore": 4.9,
      "isJdShop": true
    },
    "detailDesc": "<p>京东京造无线蓝牙耳机，采用半入耳式设计，佩戴舒适...</p><img src="https://img10.360buyimg.com/n1/jfs/t1/12348/70/8913/123459/abcdef1234567893/1234567890126.jpg"/>",
    "createTime": 1728000000000,
    "updateTime": 1735600000000
  }
}

三、核心参数解析

响应数据分为三个层级：顶层响应状态、data核心数据、data子层级数据。以下按层级对核心参数进行详细解析，明确各字段含义、数据类型及应用场景：

3.1 顶层响应状态参数

用于判断接口调用是否成功，是对接时首先需要处理的字段：

参数名数据类型说明示例值
codeInteger响应状态码：200表示调用成功；非200表示失败（具体错误码可参考京东开放平台文档）200
messageString响应信息：成功时返回"success"，失败时返回具体错误描述（如"skuId不能为空"）"success"
dataObject核心商品数据：调用成功时返回，失败时为null详见上述响应示例

3.2 data核心商品基础参数

商品的核心标识和基础信息，是区分不同商品的关键：

参数名数据类型说明应用场景
skuIdLong商品SKU ID：京东商品的最小库存单位标识，唯一对应一款具体规格的商品商品详情页跳转、库存查询、订单创建等
spuIdLong商品SPU ID：京东商品的标准产品单位标识，对应一类商品（多个SKU可能属于同一个SPU）商品分类展示、相关商品推荐等
productNameString商品名称：包含商品核心属性的完整名称商品列表展示、搜索匹配等
brandNameString品牌名称：商品所属品牌品牌筛选、品牌专题页展示等
mainImageString商品主图URL：商品的封面图片商品列表封面、详情页首图展示等
detailImagesArray商品详情图URL列表：展示商品细节的图片集合商品详情页图片展示等

3.3 data子层级：价格信息（priceInfo）

商品的各类价格及促销相关信息，是交易环节的核心数据：

参数名数据类型说明注意事项
jdPriceDouble京东价：商品当前的基础售价可能受会员等级、优惠券等影响，实际支付价可能更低
originalPriceDouble原价：商品的吊牌价或非促销时期的售价用于展示优惠力度（如"直降100元"）
promotionPriceDouble促销价：商品当前参与促销活动的售价（如618、双11促销价）仅当isPromotion为true时有效
promotionStartTimeLong促销开始时间：时间戳（毫秒级），对应北京时间需转换为yyyy-MM-dd HH:mm:ss格式后使用
promotionEndTimeLong促销结束时间：时间戳（毫秒级），对应北京时间需注意时间差，避免错过促销周期
isPromotionBoolean是否处于促销中：true-是，false-否用于判断是否展示促销标签、促销价等

3.4 data子层级：库存信息（stockInfo）

商品的库存状态及区域分布信息，用于判断商品是否可售：

参数名数据类型说明应用场景
stockNumInteger总库存数量：商品当前的总可用库存库存预警、限购逻辑处理等
isStockBoolean是否有货：true-有货，false-无货商品可售状态展示、下单按钮状态控制等
areaStockObject区域库存分布：key为地区名称（如北京、上海），value为对应地区的库存数量区域限购、就近发货逻辑处理等

3.5 其他关键子层级参数

除上述核心参数外，还有两个常用子层级参数需要关注：

3.5.1 规格信息（specInfo）

商品的规格属性及当前选中规格，用于商品规格选择、SKU切换等场景：

  • specList：规格列表，数组类型，每个元素包含specName（规格名称，如颜色、续航时间）和specValues（规格值列表，如["白色","黑色"]）
  • selectedSpec：当前选中的规格，对象类型，key为规格名称，value为选中的规格值（如{"颜色":"白色"}）

3.5.2 销售信息（salesInfo）

商品的销售数据，用于数据分析、热销商品排序等场景：

  • monthSales：月销量，近30天的销售数量
  • totalSales：总销量，商品上架后的累计销售数量
  • commentCount：评论数量，商品的累计评论数

3.5.3 店铺信息（shopInfo）

商品所属店铺信息，用于店铺展示、商家资质审核等场景：

  • shopId：店铺ID，唯一标识一家店铺
  • shopName：店铺名称
  • shopScore：店铺评分，反映店铺服务质量
  • isJdShop：是否为京东自营店，true-是，false-第三方店铺

四、对接注意事项

  1. 签名验证：京东API要求对请求参数进行签名验证，需严格按照开放平台文档中的签名算法生成sign参数，否则会调用失败。

  2. 字段兼容性：不同商品类型（如家电、服饰、食品）的响应字段可能存在差异，对接时需做好字段非空判断，避免空指针异常。

  3. 时间戳转换：响应中的时间字段（如promotionStartTime）为毫秒级时间戳，需转换为常规时间格式后使用。

  4. 调用频率限制：京东开放平台对API调用频率有严格限制，需合理控制调用频率，避免触发限流机制。

  5. 数据缓存：商品详情数据变化频率较低，可对响应数据进行缓存（如Redis缓存），减少重复调用，提升系统性能。

五、总结

本文详细展示了京东商品详情数据API的响应示例，并对顶层状态参数、核心商品基础参数、价格信息、库存信息等关键字段进行了逐一生动解析，同时给出了对接过程中的核心注意事项。开发者在实际对接时，可参考本文的响应示例和参数说明，快速理解数据结构，结合自身业务场景处理响应数据。如需进一步了解接口的请求参数配置、错误码处理等内容，可参考京东开放平台官方文档。

附录：京东开放平台官方文档地址：open.jd.com/（需注册登录后查看对应…

avatar
文章
阅读
粉丝