消費情報を送信する
この API は、アプリ ユーザーが払い戻しをリクエストしたときに、ユーザーの消費情報をアプリ ストアに送信します。
消費情報送信 API は、Hive サーバーとアプリ サーバー間のサーバー間通信を使用します。 Hive サーバーは消費情報リクエストをアプリ サーバーに送信し、アプリ サーバーは応答を Hive サーバーに返します。
Info
消費情報の送信は、Apple App Store および Google Play をサポートします。ストアごとにトリガーとレスポンスのデータ仕様が異なるため、以下のタブから統合するストアを選択してください。
Apple App Store¶
ストアに送信される消費情報の中には、アプリサーバー上にのみ存在するものもあります。このデータを Apple App Store に送信するには、アプリ サーバーはデータを Hive サーバーに提供する必要があります。
アプリサーバー URL は、Hive サーバーにデータを提供するためにアプリサーバーによって開かれる API エンドポイントです。以下の仕様に従ってエンドポイントを設定し、アプリサーバーのURLとして登録します。ユーザーが払い戻しをリクエストするたびに、Hive サーバーはこのエンドポイントに POST リクエストを送信し、アプリサーバーから必要なデータを受信します。 Hive サーバーはこのデータを集約し、アプリ開発者に代わって消費情報を Apple App Store に送信します。
全体的なプロセスは次のとおりです。
- アプリ: 以下の仕様に従って API エンドポイントを構成し、サーバー URL を準備します
- アプリ: Hive コンソールの 追加サービス設定 > 消費情報送信 で、Apple App Store を有効にし、サーバー URL を登録します
- アプリクライアント: アプリの実行中に、アプリ内製品消費情報の送信に対する同意を取得します
- アプリユーザー: アプリで返金をリクエストする
- Apple: 消費情報リクエスト (
CONSUMPTION_REQUEST) を Hive サーバーに送信します。 - Hive サーバー: アプリによって登録されたサーバー URL に POST API リクエストを送信し、アプリサーバーからの応答で消費情報を受け取ります
- Hive サーバー: 消費情報を Apple App Store に送信します。 Apple は成功すると HTTP 202 で応答します
Warning
アプリユーザーが同意ポップアップで情報送信に同意しない場合、Hive サーバーはアプリサーバーからデータを受信してもストアに送信しません。ユーザーの同意状態(customerConsented)はアプリサーバーから送信せず、Hive サーバーが直接設定します。
ファイアウォール ルールを無効にする¶
サーバーURLとして登録されたAPIエンドポイントは、リクエストパラメータのユーザー情報(player_id)とトランザクション情報(transaction_id)を利用して消費情報を取得し、以下の仕様に準拠したデータを返す必要があります。
Hive サーバーがアプリ サーバー API エンドポイントにリクエストを送信できるようにするには、アプリ サーバー上の次の IP アドレスのファイアウォール受信ルールを無効にします。
| Hive サーバー IP |
|---|
| 15.165.223.210 |
| 3.34.158.195 |
| 43.202.20.33 |
| 13.209.91.38 |
| 3.34.235.15 |
| 15.165.134.120 |
API リクエストを構成します (Hive サーバーからアプリサーバーへ)¶
以下は、Hive サーバーからアプリサーバーに送信される POST リクエストです。
| API情報 | 説明 |
|---|---|
| 方法 | 役職 |
| 応答フォーマット | JSON |
| コンテンツタイプ | アプリケーション/json |
リクエスト本文¶
リクエストボディは以下の通りです。
| 名前 | 型 | 必須(M:必須、O:任意) | 説明 |
|---|---|---|---|
| gameindex | 整数 | M | App Center Game Index |
| appid | 文字列 | M | App Center アプリID |
| server_id | 文字列 | M | アプリサーバーID |
| player_id | 文字列 | M | アプリ内のユーザー識別子 (購入の検証に使用されるユーザー識別値)。 V1のuser_seqに対応 |
| transaction_id | 文字列 | M | AppleオリジナルのトランザクションID(originalTransactionId) |
| hiveiap_transaction_id | 文字列 | M | 正常に検証されたレシートごとに生成されるトランザクション ID。 Hive IAP v4 受信検証 から返された hiveiap_transaction_id 値 |
以下はリクエスト本文の例です。
{
"gameindex": 539,
"appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
"server_id": "server_01",
"player_id": "222333",
"transaction_id": "2000000123456789",
"hiveiap_transaction_id": "AP_13"
}
API レスポンスを構成する (アプリサーバーから Hive サーバー)¶
アプリサーバーは、処理結果コード(code)、結果メッセージ(message)、消費情報(data)をHiveサーバーに送信します。
応答本文¶
Hive サーバーは、code 値から成功を判断します。値が 200 の場合、リクエストは成功し、サーバーは data を使用します。他のコードの場合、サーバーはアイテムを送信せず、理由として message を記録します。 codeは必須です。省略した場合、リクエストはエラーとして扱われ、項目は送信されません。
| 名前 | 型 | 必須(M:必須、O:任意) | 説明 |
|---|---|---|---|
| code | 整数 | M | 処理結果コード。 200 のみが成功を示します。他のすべてのコードはエラーとして扱われます |
| message | 文字列 | O | 処理結果メッセージ。エラーの理由を説明します |
| data | オブジェクト | M | 応答データ (成功時に必要) |
| ┕ delivery_status | 文字列 | M | 消耗品の納品状況です。以下の 配信ステータス の値の 1 つ |
| ┕ refund_preference | 文字列 | O | 返金優先。以下の 返金設定 の値の 1 つ |
| ┕ consumption_percentage | 整数 | O | 消費率。 0 ~ 100000 ミリパーセント (100000 = 100%) |
| ┕ sample_content_provided | 整数 | O | サンプル コンテンツが提供されたかどうか。 0 または 1 |
応答コード¶
| 値 | 説明 |
|---|---|
| 200 | 成功 |
| 400 | 無効なリクエスト値です |
| 500 | サーバーエラー |
配送ステータス (delivery_status)¶
消耗性アイテムの配信ステータスを示します。この必須フィールドには、次の 5 つの値のいずれかを指定する必要があります。
| 値 | 意味 |
|---|---|
| DELIVERED | 消耗品は納品され、正常に動作します |
| UNDELIVERED_QUALITY_ISSUE | 品質の問題のため商品が配送されませんでした |
| UNDELIVERED_WRONG_ITEM | 異なる商品または間違った商品が配送されました |
| UNDELIVERED_SERVER_OUTAGE | サーバー障害のため商品が届かなかった |
| UNDELIVERED_OTHER | 別の理由で商品が配送されませんでした |
払い戻し優先 (refund_preference)¶
アプリの優先 返金結果 を Apple に送信します。このオプションのフィールドを送信する場合は、次の 3 つの値のいずれかを含める必要があります。
| 値 | 意味 |
|---|---|
| GRANT_FULL | 全額返金を希望します |
| DECLINE | 返金を拒否することを好む |
| GRANT_PRORATED | 主にサブスクリプションについては、部分的または日割り返金を希望します |
Warning
次の値のいずれかが無効な場合、アイテムは除外され、ストアには送信されません。
delivery_statusは必須であり、上記の 5 つの値のいずれかを含める必要があります。- 送信する場合、
refund_preferenceには上記の 3 つの値のいずれかを含める必要があります。 - 送信する場合、
consumption_percentageは 0 ~ 100000 の整数である必要があります。
Note
Hive サーバーは、Apple の規則に従って次の値を自動的に調整します。
delivery_statusがDELIVEREDでない場合、consumption_percentageは 0 として送信されます。 ・refund_preferenceがGRANT_PRORATED(サブスクリプション)の場合、consumption_percentageは省略されます。
以下は、成功したリクエストの応答本文の例です。
Google Play¶
ストアに送信される消費情報の中には、アプリサーバー上にのみ存在するものもあります。このデータを Google Play に送信するには、アプリ サーバーはデータを Hive サーバーに提供する必要があります。
アプリサーバー URL は、Hive サーバーにデータを提供するためにアプリサーバーによって開かれる API エンドポイントです。以下の仕様に従ってエンドポイントを設定し、アプリサーバーのURLとして登録します。払い戻しレビュー通知が発生するたびに、Hive サーバーはこのエンドポイントに POST リクエストを送信し、アプリサーバーから必要なデータを受信します。 Hive サーバーはこのデータを集約し、アプリ開発者に代わって払い戻しレビュー情報を Google に送信します。
全体的なプロセスは次のとおりです。
- アプリ: 以下の仕様に従って API エンドポイントを構成し、サーバー URL を準備します
- アプリ: Hive コンソールの 追加サービス設定 > 消費情報送信 で、Google Play を有効にし、サーバー URL を登録します
- アプリユーザー: クレジット カード発行会社などの金融機関に直接取引の返金 (チャージバック) をリクエストします。
- Google: 返金審査通知 (
pendingRefundReviewNotification) を Hive サーバーに送信します。 - Hive サーバー: アプリによって登録されたサーバー URL に POST API リクエストを送信し、応答でデータを受信します
- Hive サーバー:
orders:reviewrefundを使用して、払い戻しレビュー情報を Google に送信します。 Google は成功すると空の HTTP 200 本文を返します。
Note
Google Play 返金レビューにはアプリ内の同意プロセスは必要ありません。ユーザーが金融機関に直接払い戻し(チャージバック)をリクエストすると、Google は処理のために払い戻し審査通知を Hive サーバーに送信します。
ファイアウォール ルールを無効にする¶
サーバーURLとして登録されたAPIエンドポイントは、リクエストパラメータのユーザー情報(player_id)とトランザクション情報(order_id)を利用して消費情報を取得し、以下の仕様に準拠したデータを返す必要があります。
Hive サーバーがアプリ サーバー API エンドポイントにリクエストを送信できるようにするには、アプリ サーバー上の次の IP アドレスのファイアウォール受信ルールを無効にします。
| Hive サーバー IP |
|---|
| 15.165.223.210 |
| 3.34.158.195 |
| 43.202.20.33 |
| 13.209.91.38 |
| 3.34.235.15 |
| 15.165.134.120 |
API リクエストを構成します (Hive サーバーからアプリサーバーへ)¶
以下は、Hive サーバーからアプリサーバーに送信される POST リクエストです。
| API情報 | 説明 |
|---|---|
| 方法 | 役職 |
| 応答フォーマット | JSON |
| コンテンツタイプ | アプリケーション/json |
リクエストボディは以下の通りです。
| 名前 | 型 | 必須(M:必須、O:任意) | 説明 |
|---|---|---|---|
| gameindex | 整数 | M | App Center Game Index |
| appid | 文字列 | M | App Center アプリID |
| server_id | 文字列 | M | アプリサーバーID |
| player_id | 文字列 | M | アプリ内のユーザー識別子 (購入の検証に使用されるユーザー識別値)。 V1のuser_seqに対応 |
| order_id | 文字列 | M | Google 注文 ID (orderId) |
| hiveiap_transaction_id | 文字列 | M | Hive IAP v4 受信検証 から返された hiveiap_transaction_id 値 |
以下はリクエスト本文の例です。
{
"gameindex": 539,
"appid": "com.com2us.hivesdk.normal.freefull.google.global.android.universal",
"server_id": "server_01",
"player_id": "222333",
"order_id": "GPA.3300-1234-5678-90123",
"hiveiap_transaction_id": "GO_13"
}
API レスポンスを構成する (アプリサーバーから Hive サーバー)¶
アプリサーバーは、処理結果コード(code)、結果メッセージ(message)、消費情報(data)をHiveサーバーに送信します。
Hive サーバーは、code 値から成功を判断します。値が 200 の場合、リクエストは成功し、サーバーは data を使用します。他のコードの場合、サーバーはアイテムを送信せず、理由として message を記録します。 codeは必須です。省略した場合、リクエストはエラーとして扱われ、項目は送信されません。
| 名前 | 型 | 必須(M:必須、O:任意) | 説明 |
|---|---|---|---|
| code | 整数 | M | 処理結果コード。 200 のみが成功を示します。他のすべてのコードはエラーとして扱われます |
| message | 文字列 | O | 処理結果メッセージ。エラーの理由を説明します |
| data | オブジェクト | M | 応答データ (成功時に必要) |
| ┕ refund_preference | 文字列 | M | 返金優先。以下の 返金設定 の値の 1 つ |
| ┕ sample_content_provided | 整数 | M | サンプルコンテンツが提供されているかどうか。 0 または 1 |
| ┕ consumption_percentage_milliunits | 整数 | M | 消費率。 0 ~ 100000 ミリパーセント (100000 = 100%) |
| ┕ consumption_usage_events | 配列 | O | 消費イベントリスト(最大1000)。以下の 消費イベント を参照してください。 |
応答コード¶
| 値 | 説明 |
|---|---|
| 200 | 成功 |
| 400 | 無効なリクエスト値です |
| 500 | サーバーエラー |
払い戻し優先 (refund_preference)¶
アプリの優先返金結果を Google に送信します。この必須フィールドには、次の 4 つの値のいずれかを含める必要があります。
| 値 | 意味 |
|---|---|
| APPROVE | 払い戻しを承認することを希望します |
| DECLINE | 返金を拒否することを好む |
| NEUTRAL | 希望なし(どちらでもない) |
| REFUND_PREFERENCE_UNSPECIFIED | 優先順位が指定されていません |
消費イベント (consumption_usage_events)¶
各消費イベントには次のフィールドが含まれます。すべてのフィールドはオプションですが、location が送信される場合は、location.region_code が必須です。
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| obfuscated_account_id | 文字列 | O | 難読化されたアカウント識別子 |
| obfuscated_profile_id | 文字列 | O | 難読化されたプロファイル識別子 |
| consumption_time | 文字列 | O | 消費時間 (RFC 3339、たとえば、2026-07-20T00:00:00Z) |
| ip_address | 文字列 | O | 利用時のIPアドレス |
| consumption_item_description | 文字列 | O | 消費したアイテムの説明 |
| location | オブジェクト | O | 消費場所情報 |
| ┕ region_code | 文字列 | locationを含む場合はM | 地域コード (CLDR、たとえば、KR) |
| ┕ administrative_area | 文字列 | O | 行政区域 |
| ┕ locality | 文字列 | O | 市 |
| ┕ sublocality | 文字列 | O | サブローカリティ |
Warning
次の値のいずれかが無効な場合、アイテムは除外され、Google に送信されません。
refund_preferenceは必須であり、上記の 4 つの値のいずれかを含める必要があります。sample_content_providedは必須であり、0 または 1 である必要があります。consumption_percentage_milliunitsは必須で、0 ~ 100000 の整数である必要があります。- 送信する場合、
consumption_usage_eventsには最大 1000 個のイベントを含めることができます。イベントにlocationが含まれる場合、location.region_codeが必要です。
以下は、成功したリクエストの応答本文の例です。
{
"code": 200,
"message": "OK",
"data": {
"refund_preference": "APPROVE",
"sample_content_provided": 0,
"consumption_percentage_milliunits": 100000,
"consumption_usage_events": [
{
"consumption_time": "2026-07-20T00:00:00Z",
"ip_address": "203.0.113.10",
"consumption_item_description": "Sample consumed item",
"location": {
"region_code": "KR"
}
}
]
}
}