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