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値の中でのみ値が表示され、ハイフンで区切られる) 
 1が返された場合、最初の値ASIAが公開される) | 
| ┕ server_list | 配列 | M | サーバーリスト | 
| ┕ server_id | 文字列 | M | アイテムを配信するゲームサーバーID (例: KR) | 
| ┕ server_display_names | オブジェクト | M | クーポン交換サーバーリストに公開される多言語のサーバー名 (※ デフォルト言語と表示言語が必要) | 
| ┕ ko ~ ar | 文字列 | O | 
 | 
| ┕ additionalinfo | オブジェクト | O | アイテムリクエストのためにゲームサーバーに送信される追加値 | 
- リクエストサンプル
// ※ 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."
  }
クリエイタークーポンの検証に関する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 | レスポンスコードに応じた結果メッセージ | 
- リクエストサンプル
- 応答サンプル
// 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画面) クーポンが利用できない場合

