コンテンツにスキップ

消費情報を送信する

この 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 に送信します。

全体的なプロセスは次のとおりです。

  1. アプリ: 以下の仕様に従って API エンドポイントを構成し、サーバー URL を準備します
  2. アプリ: Hive コンソールの 追加サービス設定 > 消費情報送信 で、Apple App Store を有効にし、サーバー URL を登録します
  3. アプリクライアント: アプリの実行中に、アプリ内製品消費情報の送信に対する同意を取得します
  4. アプリユーザー: アプリで返金をリクエストする
  5. Apple: 消費情報リクエスト (CONSUMPTION_REQUEST) を Hive サーバーに送信します。
  6. Hive サーバー: アプリによって登録されたサーバー URL に POST API リクエストを送信し、アプリサーバーからの応答で消費情報を受け取ります
  7. 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は省略されます。

以下は、成功したリクエストの応答本文の例です。

{
        "code": 200,
        "message": "OK",
        "data": {
                "delivery_status": "DELIVERED",
                "refund_preference": "GRANT_FULL",
                "consumption_percentage": 100000,
                "sample_content_provided": 0
        }
}

Google Play

ストアに送信される消費情報の中には、アプリサーバー上にのみ存在するものもあります。このデータを Google Play に送信するには、アプリ サーバーはデータを Hive サーバーに提供する必要があります。

アプリサーバー URL は、Hive サーバーにデータを提供するためにアプリサーバーによって開かれる API エンドポイントです。以下の仕様に従ってエンドポイントを設定し、アプリサーバーのURLとして登録します。払い戻しレビュー通知が発生するたびに、Hive サーバーはこのエンドポイントに POST リクエストを送信し、アプリサーバーから必要なデータを受信します。 Hive サーバーはこのデータを集約し、アプリ開発者に代わって払い戻しレビュー情報を Google に送信します。

全体的なプロセスは次のとおりです。

  1. アプリ: 以下の仕様に従って API エンドポイントを構成し、サーバー URL を準備します
  2. アプリ: Hive コンソールの 追加サービス設定 > 消費情報送信 で、Google Play を有効にし、サーバー URL を登録します
  3. アプリユーザー: クレジット カード発行会社などの金融機関に直接取引の返金 (チャージバック) をリクエストします。
  4. Google: 返金審査通知 (pendingRefundReviewNotification) を Hive サーバーに送信します。
  5. Hive サーバー: アプリによって登録されたサーバー URL に POST API リクエストを送信し、応答でデータを受信します
  6. 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"
                                }
                        }
                ]
        }
}