# 钻石
# 1. 全局约定
钻石相关接口为服务端接口，开发者必须通过服务端访问。
# 1.1 基础定义
- app_id: 快手海外小游戏开放平台给开发者分配的 app 标识，如未获得请联系运营注册快手开发者帐号，注册后可从 快手海外小游戏开放平台 查看
- app_secret: 快手海外小游戏开放平台分配给游戏的秘钥，用于加密数据及校验权限，如未获得请联系运营注册快手开发者帐号，注册后可从 快手海外小游戏开放平台 查看。注： app_secret 请妥善保管，不要泄露
- access_token: 快手海外小游戏开放平台 server 端 api 调用凭证
- item_id: 点位id，在调用钻石发放或消耗接口时使用
说明:
- 发放或扣除钻石时，若数量未超过阈值，则可在请求时直接传入钻石数量
- 对于大额的发放或扣除，必须在请求时传入点位ID
- 目前小游戏平台支持的发放和扣除点位如下：
| 点位ID | 钻石数量 |
|---|---|
| 1 | 1 |
| 5 | 5 |
| 10 | 10 |
| 20 | 20 |
| 30 | 30 |
| 40 | 40 |
| 50 | 50 |
| 60 | 60 |
| 70 | 70 |
| 80 | 80 |
| 90 | 90 |
| 100 | 100 |
| 150 | 150 |
| 200 | 200 |
| 250 | 250 |
| 300 | 300 |
| 400 | 400 |
| 500 | 500 |
| 600 | 600 |
| 700 | 700 |
| 800 | 800 |
| 900 | 900 |
| 1000 | 1000 |
| 2000 | 2000 |
| 3000 | 3000 |
| 5000 | 5000 |
# 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/diamond/balance
- 请求参数:
| 名称 | 类型 | 取值说明 | 是否参与签名 |
|---|---|---|---|
| app_id | string | 从快手海外小游戏开放平台获取的 app_id | 是 |
| open_id | string | 游戏服务器通过 code2Session 接口换的用户唯一标识 | 是 |
| ts | long | 时间戳，单位：毫秒 | 是 |
| sign | 签名 | 参数签名规则见 签名规则 | 否 |
# 响应:
- Content-Type: application/json
- Body内容：
| 名称 | 类型 | 取值说明 |
|---|---|---|
| result | int | 成功 1 |
| data | json | 响应数据data结构 |
- data内容：
| 名称 | 类型 | 取值说明 |
|---|---|---|
| balance | long | 余额 |
# 2.2. 钻石发放
# 请求:
- POST /rest/o/game/diamond/reward
- Content-Type: application/json
- Body参数:
| 名称 | 类型 | 取值说明 | 是否参与签名 |
|---|---|---|---|
| app_id | string | 从快手海外小游戏开放平台获取的 app_id | 是 |
| app_version | string | 小游戏版本号，如：1.0.0 | 是 |
| open_id | string | 游戏服务器通过 code2Session 接口换的用户唯一标识 | 是 |
| item_id | string | 点位id | 是 |
| amount | long | 数量 | 是 |
| 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内容：
| 名称 | 类型 | 取值说明 |
|---|---|---|
| item_id | string | 请求参数中带的 item_id |
| biz_no | string | 请求参数中带的 biz_no |
| amount | int | 成功发放的钻石数量 |
# 2.3. 钻石消耗
# 请求:
- POST /rest/o/game/diamond/consume
- Content-Type: application/json
- Body参数:
| 名称 | 类型 | 取值说明 | 是否参与签名 |
|---|---|---|---|
| app_id | string | 从快手海外小游戏开放平台获取的 app_id | 是 |
| app_version | string | 小游戏版本号，如：1.0.0 | 是 |
| open_id | string | 游戏服务器通过 code2Session 接口换的用户唯一标识 | 是 |
| item_id | string | 点位id | 是 |
| amount | long | 数量 | 是 |
| 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内容：
| 名称 | 类型 | 取值说明 |
|---|---|---|
| item_id | string | 请求参数中带的 item_id |
| biz_no | string | 请求参数中带的 biz_no |
| amount | int | 成功消耗的钻石数量 |
# 3. 错误码定义
# 3.1 access_token相关错误码
access_token校验失败，响应的Http Status为401。详见 access_token接口 “访问受保护资源”小节。
# 3.2 业务相关错误码
Http Status 200
| result | msg | 错误码说明 |
|---|---|---|
| 100003 | 无效请求，请确认后重试 | app_id无效 |
| 100005 | 无效请求，请确认后重试 | biz_no无效，请确认请求是否已设置biz_no参数 |
| 100006 | 无效请求，请确认后重试 | open_id无效，请确认用户已登录并得到openId |
| 100007 | 无效请求，请确认后重试 | env无效 |
| 100020 | 缺少签名参数 | 缺少签名参数 |
| 100021 | 签名信息已失效，请重新签名 | 签名信息已失效，请重新签名 |
| 100022 | 签名错误 | 签名校验未通过 |
| 110302 | 指定点位不存在 | 指定的点位不存在 |
| 110304 | 实时校验未通过 | 实时校验未通过 |
| 110305 | 请不要使用重复的单号 | bizNo已使用过 |
| 100306 | 需指定档位或金额 | 点位ID和数量均未指定 |
| 100307 | 操作频次过高，请稍后重试 | 同一用户发放或扣除频次过高 |
| 100308 | 该点位操作次数已达上限，请尝试其它点位 | 指定点位的发放或扣除次数达到当天的上限 |
| 100309 | 单笔金额超限 | 发放或扣除的单笔金额超过平台限制 |
| 100310 | 用户在游戏中操作金额已达上限 | 此用户在本游戏中发放或扣除的金额超过平台限制 |
| 100311 | 用户在全部游戏中操作金额已达上限 | 此用户在全部游戏中发放或扣除的金额超过平台限制 |
| 100312 | 本游戏中操作金额已达上限 | 本游戏中发放或扣除的金额超过平台限制 |
| 100412 | 调用内部接口失败 | 小游戏平台调用内部接口时失败 |