# 金币发放
# 1. 全局约定
金币相关接口为服务端接口，开发者必须通过服务端访问，不得通过客户端访问。
# 1.1 基础定义
- app_id: 快手海外小游戏开放平台给开发者分配的 app 标识，如未获得请联系运营注册快手开发者帐号，注册后可从 快手海外小游戏开放平台 查看
- app_secret: 快手海外小游戏开放平台分配给游戏的秘钥，用于加密数据及校验权限，如未获得请联系运营注册快手开发者帐号，注册后可从 快手海外小游戏开放平台 查看。注： app_secret 请妥善保管，不要泄露。
- access_token: 快手海外小游戏开放平台 server 端 api 调用凭证
- reward_id: 奖励id，用于调用金币发放接口时，指定要下发的奖励id。
说明及获取方式如下:
金币规则配置：开发者将游戏内设计的金币发放点位规则，根据发放的场景、任务、类型等进行抽象和整理成excel列表，并在开放平台后台-开发设置-金币配置处上传金币规则表。金币规则表模版也可以在金币配置处获取。注意：金币规则表的设计在上传开放平台后台前需要同步平台运营侧，以确认金币发放点位设计合理以及没有资损风险。
建议开发者将所有场景、任务、类型组合进行枚举，例如每日任务为开宝箱，可开多个宝箱，则每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：金币 |
| 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：金币 | 否 |
| ts | long | 时间戳，单位：毫秒 | 是 |
| sign | 签名 | 参数签名规则见 签名规则 | 否 |
# 响应:
- Content-Type: application/json
- Body内容：
| 名称 | 类型 | 取值说明 |
|---|---|---|
| result | int | 成功 1 |
| data | json | 响应数据data结构 |
- data内容：
| 名称 | 类型 | 取值说明 |
|---|---|---|
| amount | 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 | 不支持的国家 | 不支持的国家 |