网络优惠券兑换

伺服器 URL¶

常用網址	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	遊戲內用戶的 CS 代碼
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 CODE
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螢幕) 當優惠券不可用時