商品查询

查询当前渠道已开通的 SPU 列表。

SPU 的清结算模式由 CXH 为每个渠道预设。一个 SPU 可能配置一个或多个 cyclePlan(同一权益包不同的"周期×期数×价格"组合);orders/create 时通过 (periodType, period, totalCycles) 命中具体 plan,渠道侧不可在下单时自定义 SPU 配置。

POST /openapi/v1/products/list

请求

字段	必填	说明
settlementMode	—	选填筛选,仅列出指定模式的 SPU(CXH_DEDUCT / CHANNEL_COLLECT);不传返回全部
productCode	—	选填,精确匹配单个 SPU

{}

响应 data

字段	类型	说明
items	array	SPU 列表
items[].productCode	string	SPU 编码;作为 订阅下单 入参
items[].spuName	string	终端用户可见的名称
items[].description	string | null	终端用户可见的描述
items[].settlementMode	string	该 SPU 在当前渠道的清结算模式;orders/create 入参 settlementMode 必须与此一致
items[].cyclePlans	array	该 SPU 可选的周期套餐;至少一个,可能多个。每个 plan 由 (periodType, period, totalCycles) 三元组联合唯一标识
items[].cyclePlans[].periodType	string	DAY / MONTH
items[].cyclePlans[].period	int	周期单位倍率,即每 N 个 periodType 为一期
items[].cyclePlans[].totalCycles	int	总期数
items[].cyclePlans[].cycleAmountCent	long	单期对客金额(分);取自当前渠道的分销价
items[].cyclePlans[].totalAmountCent	long	= cycleAmountCent × totalCycles,展示用
items[].cyclePlans[].isDefault	boolean	该 SPU 内至多一个为 true;作为 orders/create 不传 cycle 三字段时的兜底 plan

{
  "items": [
    {
      "productCode": "TEST_SPU_001",
      "spuName": "超享汇会员·月卡",
      "description": "覆盖 X / Y / Z 权益,详情见运营介绍",
      "settlementMode": "CXH_DEDUCT",
      "cyclePlans": [
        {
          "periodType": "MONTH",
          "period": 1,
          "totalCycles": 12,
          "cycleAmountCent": 1990,
          "totalAmountCent": 23880,
          "isDefault": true
        },
        {
          "periodType": "MONTH",
          "period": 1,
          "totalCycles": 6,
          "cycleAmountCent": 2200,
          "totalAmountCent": 13200,
          "isDefault": false
        }
      ]
    }
  ]
}

字段说明

• cyclePlans 中的 (periodType, period, totalCycles) 联合唯一,渠道在 orders/create 入参中传这三个字段时必须命中其中一个 plan,否则 420007
• orders/create 不传 cycle 三字段时:若该 SPU 仅含一个 plan 直接命中;若多个 plan 则使用 isDefault=true 的兜底
• cycleAmountCent 为当前渠道的分销价,渠道侧不可在 orders/create 修改
• 不同期数 / 价格 / 结算模式可以放同一 SPU 的不同 cyclePlan,也可以使用独立 productCode,由运营在配置时决定
• 沙箱环境下 cycleAmountCent / totalAmountCent 可能为 0(BD 尚未配置该渠道分销价);切生产前请确认实际价格与 BD 报价一致

典型用法

1. 接入初始化:启动时调用一次,本地缓存 5–10 分钟(SPU 配置变更频率低)
2. 下单前:在前端展示供用户选择,选定后填入 订阅下单 入参 productCode + 命中的 cycle 三字段
3. 价格核对:orders/create 响应中的实际金额以下单时刻的渠道分销价为准。若与本接口先前返回的 plan 不一致,说明配置在两次调用之间发生了变更(运营改价 / 调整 SPU);以下单响应为准,并视情况重新拉取本接口刷新缓存

新增 SPU / 调整价格 / 调整结算模式请联系 BD,渠道接口侧不可自助。