网络优惠券兑换

服务器网址¶

常用网址	https://coupon.withhive.com
沙盒网址	https://sandbox-coupon.withhive.com

优惠券服务器 IP¶

描述	确保从游戏服务器中取消应用以下IP的入站防火墙规则。
常见IP	13.124.83.83, 52.78.11.220, 3.34.204.168, 3.35.59.227, 43.202.201.239, 43.200.188.52
沙盒IP	43.155.155.10

优惠券使用 API¶

基础¶

描述	使用发行的优惠券处理和发送物品
参考指南	标识符政策
URL	/tp/coupon/api
方法	POST		响应格式	JSON
HTTP头	内容类型	application/json	调用的百分比
	授权	Bearer Token (AppCenter Token)

请求参数¶

字段名称	类型	必需 (强制: M, 选项: O)	描述
game_index	整数	M	AppCenter 游戏索引
coupon	字符串	M	优惠券号码
cs_code	字符串	M	游戏内用户的客服代码
server_id	字符串	M	交付物品的游戏服务器 ID (例如: KR)
language	字符串	O	响应消息的语言代码 (默认: 英语) (请参阅参考指南中的语言代码) 用于在游戏屏幕上直接显示消息
additionalinfo	字符串	O	发送到游戏服务器的附加信息 (以 JSON 字符串格式交付)

响应元素¶

字段名称	类型	必需 (强制: M, 选项: O)	描述
code	整数	Y	响应代码 (100: 成功)
message	字符串	Y	根据响应代码的结果消息

调用示例

curl -L -v
 -d '{"game_index":539,"coupon":"HIVESDKTEST","cs_code":"123456789","server_id":"KR","additionalinfo":"{"user_level":50,"chanel":1,"sub_sever":"1"}"}'
 -H "Content-Type: text/html"
 -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAzNzc4OTU2LCJqdGkiOiIxODczMTExMzIwIn0.OxWo4R6UdI0BLP1ckt8RlMFrPAb5H7TNedmLFV1Cawc"
 https://sandbox-coupon.withhive.com/tp/coupon/api

请求示例

>> POST /tp/coupon/api HTTP/2
> Host: sandbox-coupon.withhive.com 
> user-agent: curl/7.68.0 
> Content-Type: application/json
> Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAzNzc4OTU2LCJqdGkiOiIxODczMTExMzIwIn0.OxWo4R6UdI0BLP1ckt8RlMFrPAb5H7TNedmLFV1Cawc
> Accept: */*
> Content-Length: 163

响应示例

< HTTP/2 200
 < server: nginx
 < date: Wed, 23 Mar 2022 09:49:29 GMT
 < content-type: application/json; charset=utf-8
 {"code":100,"message":"The Coupon Code has been redeemed."}

响应代码 (API 服务器)¶

代码	描述	消息
100	成功	优惠券代码已被兑换。
200	请求参数错误	没有参数或无效的参数名称。
202	超过账户使用限制	有效优惠券的数量已超过。
203	团体优惠券可用数量超过	有效优惠券的数量已超过！
204	与游戏数据和发行的优惠券不匹配	仅在相应游戏的活动优惠券兑换处可用。
302	优惠券不存在	优惠券代码不存在。请再检查一次。
303	优惠券正在使用中	优惠券已被使用。
304	已使用的优惠券	优惠券已被使用。
305	超过优惠券的使用限制 (独特优惠券过期可用数量)	所有发行的优惠券均已使用。
306	已过期的优惠券	优惠券已过期。
311	停止发行的优惠券	优惠券已停止发行。
312	优惠券使用前	优惠券尚不可用。（测试优惠券除外）
400	发送所有项目失败	兑换优惠券失败。如果问题仍然存在，请联系客户支持。
401	发送多个项目失败	部分兑换优惠券失败。请联系客户支持。
500	数据库通信错误	兑换优惠券失败。如果问题仍然存在，请联系客户支持。
501	服务器通信失败	兑换优惠券失败。如果问题仍然存在，请联系客户支持。

API协议关于验证用户和搜索游戏服务器列表¶

定义了验证用户和检索游戏服务器列表的协议。为此，游戏服务器首先应禁用针对coupon server IP的防火墙入站规则，以启用游戏服务器与优惠券服务器之间的API通信。

基础¶

描述	定义了一个API协议，用于验证游戏服务器上的用户并搜索可以使用优惠券的游戏服务器列表
网址	Hive 控制台 > 账单 > 优惠券 > 网页优惠券兑换设置 > 设置 > 注册游戏服务器API
方法	POST		响应格式	JSON
HTTP头	内容类型	application/json	调用的百分比

请求参数（优惠券服务器到游戏服务器）¶

字段名称	类型	必需 (强制: M, 可选: O)	描述
cs_code	字符串	M	用户的 CS CODE
server	数组	O	启用网页优惠券兑换选项的游戏服务器列表，位于项目管理菜单中。前往Hive 控制台 > 账单 > 优惠券 > 网页优惠券兑换设置 > 选择您的应用，搜索，并点击设置 > 服务器信息中具有有效 API URL 的服务器列表，且其服务器曝光为“开启”

响应元素（游戏服务器到优惠券服务器）¶

字段名称	类型	必需 (强制: M, 选项: O)	描述
code	整数	M	响应代码 (100: OK)
message	字符串	M	根据响应代码的结果消息
data	对象	M	响应数据（仅在成功响应时返回，错误时不响应）
┕ default_lang	字符串	M	默认设置语言（如果没有设置语言则暴露）
┕ extra_display	整数	O	在优惠券兑换服务器列表中，服务器名称后额外显示`additionalinfo`值 (※ 当未提供`extra_display`值时不暴露) (仅在JSON值中显示并用连字符分隔值) 0 : 显示完整的`additionalinfo`值 (例如，ASIA – 50 – PLATINUM – USER – 0 – 0 ) 1或更高 : 在`additionalinfo`值中暴露的项目数量 (例如，如果返回`1`，则暴露`ASIA`，第一个值。)
┕ server_list	数组	M	服务器列表
┕ server_id	字符串	M	传递物品的游戏服务器ID (例如，KR)
┕ server_display_names	对象	M	在优惠券兑换服务器列表中暴露的多语言服务器名称 (※ 需要默认语言和显示语言)
┕ ko ~ ar	字符串	O	ko : 韩语 en : 英语 ja : 日语 zh-hans : 中文（简体） zh-hant : 中文（繁体） de : 德语 fr : 法语 ru : 俄语 es : 西班牙语 pt : 葡萄牙语 id : 印尼语 th : 泰语 vi : 越南语 it : 意大利语 tr : 土耳其语 ar : 阿拉伯语
┕ additionalinfo	对象	O	发送到游戏服务器的额外值，用于请求交付物品

请求示例

{
    "cs_code": "20000013680",
    "server": [
      "kr",
      "cn",
      "en",
      "jp"
    ]
  }

* 响应示例

// ※ The "additionalinfo" value below is a sample. You can send a required value to a game server additionally.
// ※ "server_display_name" is a server name displayed to users, and "server_id" is exposed when making a request to a game server.
{
    "code": 100,
    "message": "Success",
    "data": {
  "default_lang": "en",
  "extra_display": 0,
      "server_list": [
        {
          "server_id": "KR",
          "server_display_names": {
            "ko": "한국서버",
            "en": "Korea Server",
            "ja": "韓国サーバー",
            "zh-hans": "韓國服務器",
            "zh-hant": "韩国服务器",
            "de": "Koreanischer Server",
            "fr": "Serveur coréen",
            "ru": "Корейский сервер",
            "es": "servidor coreano",
            "pt": "servidor coreano",
            "id": "server korea",
            "th": "เซิฟเวอร์เกาหลี",
            "vi": "Máy chủ hàn quốc",
            "it": "Server coreano",
            "tr": "Kore sunucusu",
            "ar": "الخادم الكوري"
          },
          "additionalinfo": {
            "region": "ASIA",
            "user_detail": {
              "level": 50,
              "tier": "PLATINUM",
              "nickname": "USER",
              "gold": "0",
              "gem": "0"
            }
          }
        },
        ......
      ]
    }
  }
  // When an error occurs because of a wrong parameter
  {
    "code": 200,
  "message": "No parameter, or invalid parameter name."
  }
  // Invalid user data (CS_CODE)
  {
    "code": 201,
  "message": "No data, or invalid cs_code."
  }

示例屏幕
- 将从游戏服务器发送到服务器选择 UI 的字符串原样显示

验证创作者优惠券的API协议¶

基础¶

描述	定义了一个API协议，用于验证来自游戏服务器或创作者服务器的创作者优惠券
网址	Hive 控制台 > 账单 > 优惠券 > 网页优惠券兑换设置 > 设置 > 注册创作者API
方法	POST		响应格式	JSON
HTTP头	内容类型	application/json

请求参数（优惠券服务器到创作者（游戏）服务器）¶

字段名称	类型	必需 (强制: M, 选项: O)	描述
cs_code	字符串	M	用户的 CS 代码
coupon_code	字符串	M	优惠券号码
additionalinfo	对象	O	发送到创作者服务器或游戏服务器的附加信息。

响应元素（创建者（游戏）服务器到优惠券服务器）¶

字段名称	类型	必需 (强制: M, 选项: O)	描述
code	整数	M	响应代码 (100: OK)
message	字符串	M	根据响应代码的结果消息

请求示例

{
  "cs_code": "20000013680",
  "coupon_code”: “ABCD"
}

响应示例

// Success
{
    "code":100, "message": "Success"
}
// invoking an error becase of invalid parameters
{
    "code":200, "message": "No parameter, or invalid parameter name."
}
// when the coupon received from a creator is invalid
{
    "code":201, "message": "No data, or invalid creator."
}

(PC屏幕) 当优惠券不可用时