发送消费信息

本 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 服务器：向应用商店传输消费信息（成功时 Apple 返回 HTTP 202 响应）

要传输到应用商店的消费信息中，也包含仅存在于应用服务器上的数据。在这种情况下，若要让 Hive 服务器将消费信息传输到应用商店，应用服务器必须先将数据传递给 Hive 服务器。

应用服务器 URL 是应用服务器为向 Hive 服务器传递数据而开放的 API 端点。配置好 API 端点并注册为应用服务器 URL 后，每当用户请求退款时，Hive 服务器都会向该 API 端点发送 POST 请求，并从应用服务器接收所需数据。Hive 服务器会汇总这些数据，并代表应用完成向应用商店传输消费信息。

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 个值之一。