查询商品详情

API文档最后更新: 2026-08-23

6.3 查询商品详情

  • 请求方式：GET

  • 请求地址：/goods/{productRef}

请求字段：

字段

位置

JSON 类型

必填

含义

productRef

Path

integer

是

商品列表返回的商品编号

返回字段：

字段

JSON 类型

必填

含义

code

integer

是

固定为 0，表示请求成功

message

string

是

本次请求的处理说明

data

object

是

商品详情

data.productRef

integer

是

商品编号

data.catalogRef

integer

是

分类编号

data.title

string

是

商品名称

data.deliveryKind

string

是

card 表示卡密商品；recharge 表示充值商品

data.price

number

是

当前接口账户购买该商品的进货价格，单位为人民币元，最多保留两位小数

data.availability

string

是

available 可以购买；unavailable 暂时不能购买

data.coverUrl

string 或 null

否

商品封面图片的公网地址；没有图片时为 null

data.brand

object 或 null

否

商品品牌；商品未关联有效品牌时为 null

data.brand.brandRef

integer

品牌存在时是

品牌编号

data.brand.name

string

品牌存在时是

品牌名称

data.brand.imageUrl

string 或 null

品牌存在时是

品牌图片的公网 HTTPS 地址；没有图片时为 null

data.details

string

是

商品详情正文，内容为富文本 HTML；没有内容时为空字符串

data.notices

string

是

购买前注意事项，内容为富文本 HTML；没有内容时为空字符串

data.inventoryType

string

是

商品整体库存公开方式

data.remainingUnits

integer 或 null

是

tracked 时为可售数量；其他库存类型为 null

data.revision

integer

是

商品最后更新时间，10 位 Unix 秒级时间戳

data.subscriptionState

string

是

当前账户是否已订阅商品变化通知

data.subscriptionExpiresAt

integer 或 null

是

已订阅时为到期时间；未订阅时为 null

data.variants

object[]

是

完整规格数组；单规格商品也会返回一项

data.variants[].variantRef

integer

是

规格编号；单规格商品固定为 0

data.variants[].title

string

是

规格名称

data.variants[].price

number

是

当前接口账户购买该规格的进货价格，单位为人民币元，最多保留两位小数

data.variants[].availability

string

是

当前规格是否可以购买

data.variants[].inventoryType

string

是

当前规格库存公开方式

data.variants[].remainingUnits

integer 或 null

是

tracked 时为可售数量；其他库存类型为 null

data.variants[].purchaseSchemaRevision

integer

是

当前规格下单模板版本；值变化时重新获取该规格模板

requestId

string

是

本次请求编号，排查问题时提供给平台

返回示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "productRef": 1001,
    "catalogRef": 10,
    "title": "示例充值商品",
    "deliveryKind": "recharge",
    "price": 100.00,
    "availability": "available",
    "coverUrl": "https://cdn.example.com/goods/example.png",
    "brand": {
      "brandRef": 12,
      "name": "示例品牌",
      "imageUrl": "https://cdn.example.com/brands/example.png"
    },
    "details": "<p>这里是商品详情介绍</p>",
    "notices": "<p>下单前请确认充值账号正确</p>",
    "inventoryType": "undisclosed",
    "remainingUnits": null,
    "revision": 1753776000,
    "subscriptionState": "subscribed",
    "subscriptionExpiresAt": 1792991000,
    "variants": [
      {
        "variantRef": 0,
        "title": "默认规格",
        "price": 100.00,
        "availability": "available",
        "inventoryType": "undisclosed",
        "remainingUnits": null,
        "purchaseSchemaRevision": 1753776000
      }
    ]
  },
  "requestId": "req_01K0EXAMPLE"
}

返回一个商品的品牌、详情正文、注意事项、图片、全部规格和当前订阅状态。品牌只在商品详情和 product.changed.productSnapshot 中返回，商品列表不返回品牌。brand 是 v1 新增的非必填响应字段，接入模型必须允许字段缺失；当前接口在商品未关联有效品牌时返回 null。当前平台的“商品介绍”就是这里的 details 商品详情正文；“注意事项”单独通过 notices 返回，不能把两项内容合并处理。第三方把富文本显示给用户前必须进行 HTML 安全过滤。订阅只决定是否接收商品变化通知，不影响查询下单模板和创建订单。商品不存在或当前账户无权查看时，都会返回“商品不可见”。

  • inventoryType=tracked 时，remainingUnits 是当前可售数量。

  • inventoryType=unlimited 时表示不限量，remainingUnits 为 null。

  • inventoryType=undisclosed 时表示不公开库存，remainingUnits 为 null，是否可以购买只看 availability。

  • 充值商品及其规格返回 inventoryType=undisclosed、remainingUnits=null，不要根据库存数量判断是否可以下单。

  • 单规格商品也会返回一项规格，其 variantRef 固定为数字 0。

  • 本接口只返回每个规格的 purchaseSchemaRevision，完整下单模板仍通过 GET /goods/tpl 获取。

上一篇下一篇