asset basic API

1. 获取商品列表

GET /bp/asset/product_configs

接口功能：根据传入的参数条件，获取满足条件的商品列表。

请求头部参数 (Headers)

X-BytePower-Sign：请求体签名

请求参数

请求参数在 query string 中，支持的参数如下：

Parameters	Type	Required	Desc
pay_platform	string	false	支付平台，仅支持 stripe 和 paypal。如果设置了此参数，则只返回支持该支付平台的商品列表
bp_product_id	string	false	bytepower product_id。如果设置了此参数，则只返回指定 product_id 的商品列表

请求参数示例：

bash

# 获取支持 stripe 支付方式的商品列表:
/bp/asset/product_configs?pay_platform=stripe

# 获取支持 stripe 或 paypal 支付方式的商品列表:
/bp/asset/product_configs?pay_platform=stripe&pay_platform=paypal

# 获取 bytepower product_id 为 product_id1 或 product_id2 的商品列表：
/bp/asset/product_configs?bp_product_id=product_id1&bp_product_id=product_id2

当 pay_platform 和 bp_product_id 参数条件一起使用时，获取的商品列表为满足 pay_platform 条件且满足 bp_product_id 条件的商品（即各个条件的交集），举例如下：

bash

# 获取支持 paypal 支付方式，且bytepower product_id 为 product_id1 或 product_id2 的商品列表：
/bp/asset/product_configs?pay_platform=paypal&bp_product_id=product_id1&bp_product_id=product_id2

响应

HTTP 状态码：200

参数	Type	Desc
product_configs	array	商品列表，每个元素是一个 product_config 数据结构

product_config 数据结构见 product_config 对象说明

响应示例：

json

{
  "product_configs": [
    {
      "asset": [
        {
          "duration": "",
          "first_gift_period": "",
          "free_bonus_period": "",
          "free_bonus_quantity": 0,
          "grace_period": "",
          "is_autorenewable": false,
          "is_consumable": false,
          "name": "pro",
          "quantity": 0,
          "trial_period": "",
          "type": "nonconsumable"
        }
      ],
      "description": "",
      "pay": [
        {
          "coupon_id": "",
          "free_bonus_price_id": "",
          "name": "Default",
          "pay_platform": "stripe",
          "price_description": "",
          "price_id": "stripe_pro_price_id_1",
          "product_id": "stripe_pro_product_1",
          "refund_period": "",
          "trial_price_id": ""
        }
      ],
      "price": [
        {
          "country_code": "Default",
          "currency": "USD",
          "original_price": 0,
          "price": 5,
          "region": "DEFAULT",
          "trial_price": 0
        }
      ],
      "product_id": "BUYCZQFHXF63QQDI",
      "product_name": "pro_product_1",
      "quota": 0,
      "tags": {}
    },
    {
      "asset": [
        {
          "duration": "1-day",
          "first_gift_period": "",
          "free_bonus_period": "",
          "free_bonus_quantity": 0,
          "grace_period": "",
          "is_autorenewable": true,
          "is_consumable": true,
          "name": "vip",
          "quantity": 100,
          "trial_period": "",
          "type": "subscription"
        }
      ],
      "description": "[vip_1_day_no_trial]",
      "pay": [
        {
          "coupon_id": "",
          "free_bonus_price_id": "",
          "name": "Default",
          "pay_platform": "stripe",
          "price_description": "",
          "price_id": "price_1MtmHLJeDjdpBmRtBqwsZo1J",
          "product_id": "prod_Nf6UbpD9Tz2vGg",
          "refund_period": "1-day",
          "trial_price_id": ""
        },
        {
          "name": "Default",
          "pay_platform": "paypal",
          "plan_description": "",
          "plan_id": "P-86E6357727421122EMXOZZOI",
          "product_id": "PROD-7X917145DM3139335",
          "refund_period": ""
        }
      ],
      "price": [
        {
          "country_code": "Default",
          "currency": "USD",
          "original_price": 10,
          "price": 10,
          "region": "DEFAULT",
          "trial_price": 0
        }
      ],
      "product_id": "BUY4GM3SSXAKHI56",
      "product_name": "vip_1_day_no_trial",
      "quota": 0,
      "tags": {
        "limited_test_123": "true"
      }
    }
  ]
}

HTTP 状态码：4xx 描述：错误响应示例：

json

{
  "error": {
    "error_type": "invalid_parameter",
    "message": "xxxxx"
  }
}

error_type：

invalid_parameter (请求参数错误)

2. 获取当前用户的内购资产列表

GET /bp/asset/me

接口功能：获取当前用户的内购资产列表。

请求头部参数 (Headers)

参考接入 BytePower

X-BytePower-Session-Token：登录后获取用户的 session
X-BytePower-Sign：请求体签名

请求参数

无

响应

HTTP 状态码：200

参数	Type	Desc
assets	array	资产列表，每个元素是一个 asset 数据结构

asset 数据结构见 asset 对象说明

响应示例：

json

{
  "assets": [
    {
      "last_recovery_time": "2024-10-12T00:00:00Z",
      "name": "vip2",
      "quantity": 1,
      "recoverable": true,
      "recovery_period": 1,
      "recovery_quantity": 1,
      "type": "consumable",
      "valid_seconds": 0
    },
    {
      "bp_product_id": "BUY4GM3SSXAKHI56",
      "custom_expire_time": "0001-01-01T00:00:00Z",
      "expire_time": "2024-10-13T07:31:52Z",
      "is_auto_renewable": true,
      "is_consumable": true,
      "is_refund": false,
      "is_trial_period": false,
      "name": "vip",
      "origin": "purchase",
      "platform": "stripe",
      "product_id": "prod_Nf6UbpD9Tz2vGg",
      "quantity": 100,
      "receipt_id": "sub_1Q8dKGJeDjdpBmRtz66r4GiO",
      "refund_time": "0001-01-01T00:00:00Z",
      "sub_canceled": false,
      "sub_canceled_time": "0001-01-01T00:00:00Z",
      "sub_canceled_ts": 0,
      "total_quantity": 100,
      "type": "subscription",
      "valid_seconds": 97901
    }
  ]
}

HTTP 状态码：4xx 描述：错误响应示例：

json

{
  "error": {
    "error_type": "account.invalid_session",
    "message": "xxxxx"
  }
}

error_type：

account.invalid_session(session 错误)

3. 获取当前用户的订阅历史

GET /bp/asset/subscription_history

接口功能：返回当前用户的历史订阅列表，目前只返回 stripe paypal 的历史订阅列表。

请求头部参数 (Headers)

参考接入 BytePower

X-BytePower-Session-Token：登录后获取用户的 session
X-BytePower-Sign：请求体签名

请求参数

请求参数在 query string 中，支持的参数如下：

Parameters	Type	Required	Desc
pay_platform	string	false	支付平台，可选择 paypal 或 stripe。不传参数时，同时查询 stripe 和 paypal 的订阅历史。

响应

HTTP 状态码：200

参数	Type	Desc
subscription_history	array	历史订阅列表，每个元素是一个 subscription_history 数据结构

subscription_history 数据结构见 subscription_history 对象说明

响应示例：

json

{
  "subscription_history": [
    {
      "asset_name": "vip",
      "bp_product_id": "BUYNLT6M3QST4R5F",
      "customer_id": "cus_R0eYzppxtT85V0",
      "id": "sub_1Q8dFGJeDjdpBmRt5kDGIvnL",
      "platform": "stripe",
      "stripe_price_id": "price_1MtmPmJeDjdpBmRtJm9nMYZE",
      "stripe_product_id": "prod_Nf6dZGfCIERbqP"
    },
    {
      "asset_name": "vip",
      "bp_product_id": "BUYMJ4YQHEFW3OLG",
      "id": "I-R0XYUHL6FT6P",
      "paypal_plan_id": "P-1N146430CT3511025MXOZ2EY",
      "paypal_product_id": "PROD-6FM833567X9180113",
      "platform": "paypal"
    }
  ]
}

HTTP 状态码：4xx 描述：错误响应示例：

json

{
  "error": {
    "error_type": "invalid_parameter",
    "message": "xxxxx"
  }
}

error_type：

invalid_parameter (请求参数错误)

4. 取消订阅

POST /bp/asset/subscription/cancel

接口功能：取消自动续订的订阅。

如果 with_refund 参数为 false, 仅取消订阅但不退款。操作后，如果是在【免费试用期】，则资产立即失效；如果不是在【免费试用期】，那么本期资产仍然有效，本期结束后资产失效且不再续费，在这种情况下，在资产失效前，stripe 订阅可以调用 recover_and_update 接口恢复订阅，paypal 订阅不能恢复。

如果 with_refund 参数为 true，如果在 refund period 期间，则取消订阅并给用户退款，资产立即失效；如果不在 refund period 期间，则操作返回失败。

目前只支持 stripe 和 paypal 平台的订阅取消。

请求头部参数 (Headers)

参考接入 BytePower

X-BytePower-Session-Token：登录后获取用户的 session。
X-BytePower-Sign：请求体签名

请求体

content-type: "application/json"

Parameters	Type	Required	Desc
asset_name	string	true	资产名称
with_refund	bool	false	是否同时退款，默认不填为 false，即不退款

请求体示例：

json

{
  "asset_name": "vip",
  "with_refund": false
}

响应

HTTP 状态码：200

参数	Type	Desc
canceled_sub	object	被取消的订阅信息
assets	array	用户的 asset 信息

canceled_sub 数据结构见 canceled_sub 对象说明

响应示例：

json

{
  "assets": [
    {
      "custom_expire_time": "0001-01-01T00:00:00Z",
      "expire_time": "2024-02-28T06:33:24Z",
      "is_auto_renewable": true,
      "is_consumable": true,
      "is_trial_period": true,
      "name": "vip",
      "origin": "purchase",
      "platform": "paypal",
      "product_id": "PROD-7X917145DM3139335",
      "quantity": 300,
      "receipt_id": "I-08GVT9V0JTKR",
      "sub_canceled": false,
      "sub_canceled_time": "0001-01-01T00:00:00Z",
      "sub_canceled_ts": 0,
      "total_quantity": 300,
      "type": "subscription",
      "valid_seconds": 101407
    }
  ],
  "canceled_sub": {
    "id": "I-08GVT9V0JTKR",
    "platform": "paypal"
  }
}

HTTP 状态码：4xx 描述：错误响应示例：

json

{
  "error": {
    "error_type": "invalid_parameter",
    "message": "xxxxx"
  }
}

error_type：

invalid_parameter (请求参数错误)
config_invalid （console 配置问题）
backend unavailable (paypal 或 stripe 等第三方错误)

数据结构

product_config

参数	类型	说明
product_id	string	bytepower product id
product_name	string	bytepower 商品名称
quota	string	限额（只对 stripe 和 paypal 平台有效）
asset	array	商品配置对应的资产配置，详见 asset_config 说明
pay	array	商品配置对应的支付配置，详见 pay_config 说明
price	array	商品配置对应的价格配置，详见 price_config 说明
description	string	商品说明，用于页面展示
tags	object	商品的 tags, object key 为 tag 名称，object value 为 tag 值

asset_config

参数	类型	说明
name	string	资产名称
type	string	资产类型，如 consumable, nonconsumable, subscription
quantity	integer	资产数量，对 consumable 资产和 consumable subscription 有效
duration	string	资产时长，以 period 字符串表示，period 字符串格式见本文档说明
is_autorenewable	bool	是否为自动续订的购买方式，对 subscription 资产有效
trial_period	string	试用期，以 period 字符串表示
grace_period	string	续约宽限期，以 period 字符串表示
is_consumable	bool	资产是否可以被消耗。consumable 资产返回 true，nonconsumable 资产返回 false；consumable subscription 返回 true，nonconsumable subscription 返回 false。
free_bonus_period	string	free bonus 时间，以 period 字符串表示，对 stripe 支付方式有效
free_bonus_quantity	integer	free bonus period 期间的资产数量，对 stripe 支付方式有效
first_gift_period	integer

pay_config

每个平台的 pay_config 字段不同，具体如下：

stripe_pay_config

参数	类型	说明
pay_platform	string	支付平台, stripe
name	string	stripe 平台配置名称
product_id	string	stripe 平台的 product_id
price_id	string	string 平台的 price_id
trial_price_id	string	付费试用期的 stripe 平台 price_id，对付费试用期有效
free_bonus_price_id	string	free bonus 期间的 stripe price_id，对带 free_bonus_period 的商品有效，price_id 对应的价格需要为 0
coupon_id	string	stripe 平台的 coupon_id
refund_period	string	可退款时间，用 period 字符串表示。用户购买后，可在指定的时间段内进行退款
price_description	string	对 price_id 的描述性信息

paypal_pay_config

参数	类型	说明
pay_platform	string	支付平台, paypal
name	string	paypal 平台配置名称
product_id	string	paypal 平台的 product_id
plan_id	string	paypal 平台的 plan_id
refund_period	string	可退款时间，用 period 字符串表示。用户购买后，可在指定的时间段内进行退款
plan_description	string	对 plan_id 的描述性信息

price_config

参数	类型	说明
currency	string	币种
region	string	地区，默认地区为 DEFAULT
country_code	string	国家码，默认为 Default
price	double	价格
original_price	double	原始价格
trial_price	double	试用期价格

period_string

period 字符串由三部分组成: 数量（整数类型， >=0），分隔符(中横线), 单位(minute, hour, day, week, month, year)，三部分间无空格。举例如下：

"0-day", "20-minute", "2-year", "3-week", "10-hour", "3-month"

asset

asset 分为 consumable, nonconsumable 和 subscription 3 种，每种 asset 数据结构的字段不同，具体如下：

consumable asset

参数	类型	说明
name	string	资产名称
type	string	资产类型, consumable
quantity	integer	资产数量
valid_seconds	integer	资产有效时长（以秒数计）
recoverable	bool	是否可恢复
recovery_period	integer	恢复时间
recovery_quantity	integer	恢复数量
last_recovery_time	string	上次恢复时间，格式如 2024-10-12T00:00:00Z

nonconsumable asset

参数	类型	说明
name	string	资产名称
type	string	资产类型, nonconsumable
is_limited	bool	资产是否有时效限制
valid_seconds	integer	资产有效时长（以秒数计），当 is_limited 为 true 时返回该字段

subscription asset

参数	类型	说明
name	string	资产名称
type	string	资产类型, subscription
bp_product_id	string	bytepower product id，目前只 stripe/paypal 订阅返回该字段
product_id	string	第三方支付平台的 product_id
platform	string	支付平台, 如 stripe, paypal
receipt_id	string	第三方支付平台的订阅 id
expire_time	string	资产失效时间，格式如 2024-10-13T07:31:52Z
custom_expire_time	string	bytepower console 上设置的资产失效时间，格式如 2024-10-13T07:31:52Z
is_consumable	bool	资产是否可消耗
quantity	integer	资产数量，is_consumable 为 true 时有效
total_quantity	integer	本期订阅的资产总数量，is_consumable 为 true 时有效
origin	string	来源, 如 purchase
is_refund	bool	是否被退款
refund_time	string	退款时间，格式如 2024-10-13T07:31:52Z
sub_canceled	bool	是否被取消
sub_canceled_time	string	取消时间，格式如 2024-10-13T07:31:52Z
sub_canceled_ts	int	取消时间的秒级时间戳
valid_seconds	int	资产有效时长（以秒数计）
is_trial_period	bool	是否处于试用期
is_auto_renewable	bool	是否是自动续订订阅

subscription_history

每个支付平台的 subscription_history 的字段会有所不同，具体如下:

stripe_subscription_history

参数	类型	说明
id	string	stripe 订阅 id
platform	string	支付平台, stripe
bp_product_id	string	bytepower product_id
stripe_product_id	string	stripe 平台的 product_id
stripe_price_id	string	stripe 平台的 price_id
asset_name	string	资产名称
customer_id	string	stripe 平台的 customer_id

paypal_subscription_history

参数	类型	说明
id	string	paypal 订阅 id
platform	string	支付平台, paypal
bp_product_id	string	bytepower product_id
paypal_product_id	string	paypal 平台的 product_id
paypal_plan_id	string	paypal 平台的 plan_id
asset_name	string	资产名称

canceled_sub

参数	类型	说明
id	string	订阅 id
platform	string	订阅平台，如 stripe, paypal

举例如下:

json

{
  "id": "I-08GVT9V0JTKR",
  "platform": "paypal"
}

asset basic API ​

1. 获取商品列表 ​

GET /bp/asset/product_configs ​

请求头部参数 (Headers) ​

请求参数 ​

响应 ​

2. 获取当前用户的内购资产列表 ​

GET /bp/asset/me ​

请求头部参数 (Headers) ​

请求参数 ​

响应 ​

3. 获取当前用户的订阅历史 ​

GET /bp/asset/subscription_history ​

请求头部参数 (Headers) ​

请求参数 ​

响应 ​

4. 取消订阅 ​

POST /bp/asset/subscription/cancel ​

请求头部参数 (Headers) ​

请求体 ​

响应 ​

数据结构 ​

product_config ​

asset_config ​

pay_config ​

stripe_pay_config ​

paypal_pay_config ​

price_config ​

period_string ​

asset ​

consumable asset ​

nonconsumable asset ​

subscription asset ​

subscription_history ​

stripe_subscription_history ​

paypal_subscription_history ​

canceled_sub ​

asset basic API

1. 获取商品列表

GET /bp/asset/product_configs

请求头部参数 (Headers)

请求参数

响应

2. 获取当前用户的内购资产列表

GET /bp/asset/me

请求头部参数 (Headers)

请求参数

响应

3. 获取当前用户的订阅历史

GET /bp/asset/subscription_history

请求头部参数 (Headers)

请求参数

响应

4. 取消订阅

POST /bp/asset/subscription/cancel

请求头部参数 (Headers)

请求体

响应

数据结构

product_config

asset_config

pay_config

stripe_pay_config

paypal_pay_config

price_config

period_string

asset

consumable asset

nonconsumable asset

subscription asset

subscription_history

stripe_subscription_history

paypal_subscription_history

canceled_sub