發送消費信息

我們提供讓應用程式使用者請求退款時，將使用者消費資訊傳送至 App Store 的 API。

「消費資訊傳輸」API 採用 Hive 伺服器與應用程式伺服器之間的 Server-to-Server 通訊方式：Hive 伺服器向應用程式伺服器發出消費資訊傳輸請求後，應用程式伺服器會將回應值回傳給 Hive 伺服器。

運作流程¶

「消費資訊傳輸」API 呼叫與回應的整體運作流程摘要如下。

1. 應用程式：透過配置 API 端點準備伺服器 URL
2. 應用程式：在 Hive 控制台中選擇啟用消費資訊傳輸，並註冊伺服器 URL
3. 應用程式用戶端：在應用程式執行狀態下，同意傳輸應用程式內商品消費資訊
4. 應用程式使用者：在應用程式中請求退款
5. Apple：向 Hive 伺服器發送消費資訊請求（CONSUMPTION_REQUEST）
6. Hive 伺服器：向應用程式註冊的伺服器 URL 發送 POST API 請求，並從應用程式伺服器接收回應值作為消費資訊資料
7. Hive 伺服器：將消費資訊傳輸至 App Store（成功時 Apple 會回應 HTTP 202）

要傳輸至 App Store 的消費資訊中，也有僅存在於應用程式伺服器上的資料。在這種情況下，若要讓 Hive 伺服器將消費資訊傳輸至 App Store，應用程式伺服器必須先將資料傳遞給 Hive 伺服器。

應用程式伺服器 URL 是應用程式伺服器為了將資料傳遞給 Hive 伺服器，而在應用程式伺服器上開放的 API 端點。配置 API 端點並註冊為應用程式伺服器 URL 後，每當使用者請求退款時，Hive 伺服器就會向此 API 端點發送 POST 請求，並從應用程式伺服器接收所需的資料。Hive 伺服器會彙整這些資料，並代替應用程式完成向 App Store 傳輸消費資訊。

API 端點配置 (伺服器 URL)¶

應用程式伺服器透過將註冊為伺服器 URL 的 API 端點接收請求時，須以請求參數中的使用者資訊（player_id）與交易資訊（transaction_id）查詢消費資訊，並回傳符合回應規範的資料。

解除防火牆規則¶

為了讓 Hive 伺服器能夠向應用程式伺服器的 API 端點發送請求，應用程式伺服器必須針對下列 IP 位址解除防火牆入站規則。

解除防火牆規則後，請參考以下內容配置 API 端點。

API 請求 (Hive 伺服器 → 應用程式伺服器) 配置¶

Hive 伺服器發送至應用程式伺服器的 POST 請求資訊如下。

Request body¶

請求本文資訊如下。

請求本文範例如下。

{
    "gameindex": 539,
    "appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
    "server_id": "server_01",
    "player_id": "222333",
    "transaction_id": "2000000123456789"
}

API 回應 (應用程式伺服器 → Hive 伺服器) 配置¶

應用程式伺服器會將處理結果代碼（code）、結果訊息（message）與消費資訊（data）傳遞給 Hive 伺服器。

Response body¶

Hive 伺服器會以 code 值判斷是否成功。若為 200 則視為成功並使用 data；其他代碼則不傳送該筆資料，並將 message 記錄為原因。code 為必要欄位，若未傳送則視為錯誤，不會傳送該筆資料。

回應成功範例如下。

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

回應代碼¶

傳遞狀態（delivery_status）¶

表示消耗性項目的傳遞狀態，必須為下列 5 個值之一（必要）。

退款偏好（refund_preference）¶

將應用程式偏好的退款處理方向傳遞給 Apple（選填）。若傳送此值，須為下列 3 個值之一。