Kwai Game

# 金币发放

# 1. 全局约定

金币相关接口为服务端接口，开发者必须通过服务端访问，不得通过客户端访问。

# 1.1 基础定义


  • app_id: 快手海外小游戏开放平台给开发者分配的 app 标识，如未获得请联系运营注册快手开发者帐号，注册后可从 快手海外小游戏开放平台 查看
  • app_secret: 快手海外小游戏开放平台分配给游戏的秘钥，用于加密数据及校验权限，如未获得请联系运营注册快手开发者帐号，注册后可从 快手海外小游戏开放平台 查看。注： app_secret 请妥善保管，不要泄露。
  • access_token: 快手海外小游戏开放平台 server 端 api 调用凭证
  • reward_id: 奖励id，用于调用金币发放接口时，指定要下发的奖励id。

说明及获取方式如下:
  • 开发者将游戏内设计的金币发放卡点，根据发放的场景、任务、类型等进行抽象和整理成卡点列表，并在游戏接入金币api前，提交快手小游戏平台方审核
  • 快手小游戏官方审核通过后，会在系统内配置游戏卡点信息，开发者即可正常调用金币发放接口
  • 建议开发者将所有场景、任务、类型组合进行枚举，例如每日任务为开宝箱，可开多个宝箱，则每1个单独设置一项(对应一个reward_id)
  • reward_id 需要限定在 10 个字符以内，且只能包含数字，字母，英文下划线

举例

reward_id
(游戏提供)		 卡点描述
(游戏提供)		 下发金币
(游戏提供)		 每用户每日请求次数
(游戏提供)		 国家
(巴西：BRA
印尼：IDN)
1 每日挑战 60 1 BRA
2 升级1次英雄 30 1 BRA
3 升级2次英雄 30 1 BRA
reward_1 开第1个宝箱 30 1 BRA
reward_2 开第2个宝箱 60 1 BRA

# 1.2 服务域名


https://game.kwai.com

# 1.3 请求参数说明

  • 对于 GET 请求，请求参数应以 QueryString 的形式写在 URL 中。
  • 对于 POST 请求，部分参数需以 QueryString 的形式写在 URL 中（一般只有access_token，如有额外参数会在文档里的 URL 中体现），其它参数如无特殊说明均以 JSON 字符串格式写在 POST 请求的 body 中。

# 1.4 请求参数校验

  • 金币相关接口的校验包括OAuth2和参数验签。

  • 为通过OAuth2验证，需在请求的URL末尾加上 access_token=获取到的access_token。 access_token 可以通过 获取access_token 接口获取（不参与签名)，有效期一般为 1 小时。

  • 在access_token有效期内访问 获取access_token 接口将返回原access_token，不会更新access_token。

  • access_token失效后，使用access_token访问受保护接口会返回401错误（详见 获取access_token 接口的“访问受保护资源”小节），此时应调用获取access_token接口获取新的access_token。

  • 参数签名规则见 签名规则 ，各接口参与签名的参数标记于各接口说明中。

# 2.金币接口说明

本节所述所有请求都需要将 access_token 以参数名 access_token 拼接到 query url 参数中，以下不再赘述。

# 2.1. 金币奖励配置

# 请求:

  • GET /rest/o/game/kcoin/reward/config
  • 请求参数:
名称 类型 取值说明 是否参与签名
country string 三位国家码（大写）。巴西：BRA，印尼：IDN，巴基斯坦：PAK 是
app_id string 从快手海外小游戏开放平台获取的 app_id 是
app_version string 小游戏版本号，如：1.0.0 是
env string 开发者可以通过 ks.getSystemInfoSync().host.env 接口获取，详见 ks.getSystemInfoSync 是
ts long 时间戳，单位：毫秒 是
sign 签名 参数签名规则见 签名规则 否

# 响应:

  • Content-Type: application/json
  • Body内容：
名称 类型 取值说明
result int 成功 1
data json 响应数据data结构

  • data内容：
名称 类型 取值说明
reward_items list 奖励列表reward_items对象结构

  • reward_item内容：
名称 类型 取值说明
reward_id string 奖励ID
reward_scene string 奖励场景
currency_type int 币种，默认为0。0：金币，3：激励游戏币，4：Snaplay游戏币
coin_amount int 货币数量
times_limit_per_day int 每天发放次数限制
level int 档位价值。0：默认，1：高价值档位，2：中价值档位，3：低价值档位，4：个性化档位。参 用户价值标签

# 2.2. 金币发放

注：为确保金币的顺利发放，需要目标用户先通过Kwai App登录到游戏中，否则会被风控拦截。

# 请求:

  • POST /rest/o/game/kcoin/reward
  • Content-Type: application/json
  • Body参数:
名称 类型 取值说明 是否参与签名
app_id string 从快手海外小游戏开放平台获取的 app_id 是
app_version string 小游戏版本号，如：1.0.0 是
open_id string 游戏服务器通过 code2Session 接口换的用户唯一标识 是
reward_id string 奖励id，用于获取游戏对应的奖励信息 是
biz_no string 业务流水号，开发者自己定义，请求成功后原样返回，同一个流水号只能成功请求一次金币发放 是
env string 开发者可以通过 ks.getSystemInfoSync().host.env 接口获取，详见 ks.getSystemInfoSync 是
ts long 时间戳，单位：毫秒 是
sign 签名 参数签名规则见 签名规则 否

# 响应

  • Content-Type: application/json
  • Body内容：
名称 类型 取值说明
result int 成功 1，其他值见错误码定义
data json 响应数据data结构

  • data内容：
名称 类型 取值说明
appId string 请求参数中带的 app_id
openId string 请求参数中带的 open_id
rewardId string 请求参数中带的 reward_id
bizNo string 请求参数中带的 biz_no
amount int 成功发放的货币数量

说明：

  • 此接口有一个可选参数 v，当 v=1 时，响应中的各字段为下划线连接方式，可按需选用。

    举例： 使用 /rest/o/game/kcoin/reward?v=1 进行请求时，data中的字段为：app_id、open_id、reward_id、biz_no、amount。

  • 传入的app_version值高于正式版本的时候，小游戏平台会自动将env映射为test，可以基于此特性对新点位进行本地测试和提审。

# 2.3. 今日累计发放

# 请求:

  • GET /rest/o/game/kcoin/reward/today
  • 请求参数:
名称 类型 取值说明 是否参与签名
app_id string 从快手海外小游戏开放平台获取的 app_id 是
app_version string 小游戏版本号，如：1.0.0 是
open_id string 游戏服务器通过 code2Session 接口换的用户唯一标识（参与签名) 是
env string 开发者可以通过 ks.getSystemInfoSync().host.env 接口获取，详见 ks.getSystemInfoSync 是
currency_type int 币种，默认为0。0：金币，3：激励游戏币。普通赚金游戏传0即可 否
ts long 时间戳，单位：毫秒 是
sign 签名 参数签名规则见 签名规则 否

# 响应:

  • Content-Type: application/json
  • Body内容：
名称 类型 取值说明
result int 成功 1
data json 响应数据data结构

  • data内容：
名称 类型 取值说明
amount int 用户今日累计成功发放金币数

# 2.4. 用户余额

功能：用于查询激励游戏币余额

# 请求:

  • GET /rest/o/game/kcoin/user/balance
  • 请求参数:
名称 类型 取值说明 是否参与签名
app_id string 从快手海外小游戏开放平台获取的 app_id 是
open_id string 游戏服务器通过 code2Session 接口换的用户唯一标识（参与签名) 是
env string 开发者可以通过 ks.getSystemInfoSync().host.env 接口获取，详见 ks.getSystemInfoSync 是
currency_type int 币种，目前只支持 3：激励游戏币；使用其它数值获取余额时均返回0 是
ts long 时间戳，单位：毫秒 是
sign 签名 参数签名规则见 签名规则 否

# 响应:

  • Content-Type: application/json
  • Body内容：
名称 类型 取值说明
result int 成功 1
data json 响应数据data结构

  • data内容：
名称 类型 取值说明
currency_type int 币种，3：激励游戏币
balance int 用户余额

# 3. 错误码定义


# 3.1 access_token相关错误码

access_token校验失败，响应的Http Status为401。详见 access_token接口 “访问受保护资源”小节。


# 3.2 业务相关错误码

Http Status 200

result msg 错误码说明
100000 系统繁忙，请稍后重试 系统繁忙
100001 无效参数，请查看接口文档 传入参数无效，请查看接口文档
100002 无效请求，请确认后重试 有非法参数
100003 无效请求，请确认后重试 app_id无效
100004 无效请求，请确认后重试 reward_id无效，请确认是否已经向快手海外小游戏平台方申请奖励卡点
100005 无效请求，请确认后重试 biz_no无效，请确认请求是否已设置biz_no参数
100006 无效请求，请确认后重试 open_id无效，请确认游戏账号是否有效
100007 无效请求，请确认后重试 env无效，请确认游戏账号是否有效
100020 缺少签名参数 缺少签名参数
100021 签名信息已失效，请重新签名 签名信息已失效，请重新签名
100022 签名错误 签名校验未通过
100030 缺少奖励配置 缺少奖励配置
100031 缺少奖励配置项 缺少reward_item配置
100041 找不到对应的用户，请确认后重试 找不到对应的用户，请确认后重试
100042 无效请求，用户需要登录 无效请求，用户需要登录
100050 金币领取失败，请重试 单笔奖励金额超过上限
100051 用户游戏金币领取已达上限，请明天再来 用户游戏金币领取已达上限，请明日再试
100052 金币领取达到上限，请明天再来 游戏金币领取已达上限，请明日再试
100053 该点位金币领取次数已达上限，请尝试其它点位 该点位金币领取次数已达上限，请尝试其它点位
100054 金币领取达到上限，请明天再来 用户金币领取已达今日上限，请明日再来
100055 金币领取失败，请重试 金币领取过于频繁，请稍后再试
100061 金币已领取，请勿重复请求 金币已领取，请勿重复请求
100062 异常请求 异常请求
100063 金币领取失败，请重试 奖励发放失败，可重试
100064 金币领取失败，内部接口调用失败 内部接口无法调用，请稍后再试
100065 金币领取失败，内部接口调用失败 内部接口返回错误，请稍后再试
120045 不支持的国家 不支持的国家

← 钻石 →