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画面) クーポンが利用できない場合

