コンテンツにスキップ

Web クーポン交換

サーバーURL

共通URL https://coupon.withhive.com
サンドボックスURL 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 呼び出しの割合
認証 ベアラートークン(AppCenterトークン)

リクエストパラメータ

フィールド名 タイプ 必須 (必須: 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 DB通信エラー クーポンの引き換えに失敗しました。
問題が解決しない場合は、カスタマーサポートにお問い合わせください。
501 サーバー通信の失敗 クーポンの引き換えに失敗しました。
問題が解決しない場合は、カスタマーサポートにお問い合わせください。

ユーザーの確認とゲームサーバーリストの検索に関するAPI契約

ユーザーを検証し、ゲームサーバーのリストを取得するためのプロトコルを定義します。これを行うために、ゲームサーバーはまず、API通信を有効にするためにcoupon server IPに対して設定されたファイアウォールの受信ルールを無効にする必要があります。

基礎

説明 ゲームサーバーからユーザーを検証し、クーポンを使用できるゲームサーバーリストを検索するためのAPI契約を定義しました
URL Hive コンソール > 請求 > クーポン > ウェブ クーポン 交換 設定 > 設定 > 登録 ゲームサーバーAPI
メソッド POST レスポンス形式 JSON
HTTPヘッダー コンテンツタイプ application/json 呼び出しの割合

リクエストパラメータ(クーポンサーバーからゲームサーバーへ)

フィールド名 タイプ 必須 (必須: M, オプション: O) 説明
cs_code 文字列 M ユーザーのCSコード
server 配列 O アイテム管理メニューでウェブクーポン交換オプションを有効にするゲームサーバーのリスト。Hive コンソール > billing > Coupon > Web Coupon Exchange Settings > アプリを選択し、検索して、settings > the 有効なAPI URLを持ち、サーバー公開が「ON」のサーバー情報のリストをクリックします。

レスポンス要素 (ゲームサーバーからクーポンサーバーへ)

フィールド名 タイプ 必須 (必須: 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契約を定義しました
URL 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画面) クーポンが利用できない場合