Voided Purchases API

Google Play Voided Purchases API 提供了一个订单列表，这些订单与用户已作废的购买交易相关联。您可以利用此列表中的信息来实现一个撤消系统，阻止用户访问这些订单中的商品。

此 API 适用于一次性应用内订单和应用订阅。

在以下情况中，购买交易将被视为作废：

• 用户针对其订单请求退款。
• 用户取消其订单。
• 订单遭到退单。

• 开发者取消订单或针对订单办理退款。

  注意：Voided Purchases API 中只会显示已撤消的订单。如果开发者在未设置撤消选项的情况下针对购买交易办理退款，那么此 API 不会返回相应订单。

• Google 取消订单或针对订单办理退款。

通过使用此 API，您可以为应用的所有用户打造更平衡且公平的体验，尤其是当您的应用属于游戏时。

注意：不同于与订单相关的其他数据来源，Voided Purchases API 包含由付款处理方退单的购买交易。因此，您可能会发现来自此 API 的信息与来自其他订单相关数据来源的信息不一致。

注意：只有在需要撤消购买交易时，Voided Purchases API 才会返回作废的购买交易。开发者可以使用此 API 来指明其何时采取额外的操作。不过，有些购买交易可能因从未获得开发者的确认而发生退款，因此可能不存在于开发者的记录中。

获得访问权限

如要使用 Voided Purchases API，您需要拥有查看财务信息的权限。您可以使用 OAuth 客户端或服务账号来提供授权。如果您使用的是服务账号，请在此账号中启用“查看财务报告”权限。

如要详细了解如何获得授权以访问 Google Play Developer API，请参阅以下指南：

• 设置 API 访问客户端
• 添加开发者账号用户并管理权限

查看已作废的购买交易

使用 GET 方法请求提供已作废购买交易的列表。在请求中，请加入您的应用的完全限定软件包名称（如 com.google.android.apps.maps），以及您在获取 API 访问权限时收到的授权令牌。

GET https://www.googleapis.com/androidpublisher/v3/applications/
your_package_name/purchases/voidedpurchases?access_token=your_auth_token

您还可以在请求中加入以下参数（各参数均为可选）：

startTime

您想在响应中看到的最早作废的购买交易的时间（以自 UNIX 纪元以来的毫秒数表示）。默认情况下，startTime 设为 30 天前。

此 API 只能显示在过去 30 天内发生的已作废购买交易。无论您将 startTime 设成什么值，更早的已作废购买交易都不会包含在响应中。

注意：系统会根据给定记录被视为作废的时间来过滤响应中的已作废购买交易。给定记录是否被视为作废是由 API 而不是由响应中返回的 voidedTimeMillis 的值决定的。

endTime

您想在响应中看到的最晚作废的购买交易的时间（以自 UNIX 纪元以来的毫秒数表示）。默认情况下，endTime 设为当前时间。

注意：系统会根据给定记录被视为作废的时间来过滤响应中的已作废购买交易。给定记录是否被视为作废是由 API 而不是由响应中返回的 voidedTimeMillis 的值决定的。

maxResults

每个响应中出现的已作废购买交易的数量上限。默认情况下，此值为 1,000。请注意，此参数的最大值也是 1,000。

token

之前响应中的续页令牌；可让您查看更多结果。

type

每个响应中出现的已作废购买交易的类型。如果设为 0，则系统只会返回已作废的应用内购买交易。如果设为 1，则系统将返回已作废的应用内购买交易和已作废的订阅购买交易。默认值为 0。

注意：在请求接收已作废的订阅购买交易之前，您必须在响应中改用 orderId，此 ID 可唯一标识一次性购买交易和订阅。否则，您将收到采用同一 PurchaseToken 的多个订阅订单。

includeQuantityBasedPartialRefund

是否包括发生了基于数量的部分退款（仅适用于多件购买交易）的已作废购买交易。如果为 true，则可能会返回额外的已作废购买交易以及 voidedQuantity，后者表示基于数量的部分退款的退款数量。默认值为 false。

注意：当购买交易的剩余总数量得到退款时，相应的已作废购买交易将不会有对应的 voidedQuantity，这可作为购买交易已全额退款的信号。例如，如果一笔购买交易涉及 10 件商品，陆续按数量 2、3 和 5 进行了 3 次退款，则会产生 3 笔已作废的购买交易。前两笔已作废购买交易对应的 voidedQuantity 值将分别为 2 和 3，第三笔已作废购买交易则没有对应的 voidedQuantity。

响应是一个 JSON 字符串，其中包含已作废购买交易的列表。如果结果数量超过了在 maxResults 请求参数中指定的数量，响应就会包含一个 nextPageToken 值，您可以将该值传递给后续请求来查看更多结果。列表中的第一个结果显示的是最早作废的购买交易。

{
  "tokenPagination": {
    "nextPageToken": "next_page_token"
  },
  "voidedPurchases": [
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "some_purchase_token",
      "purchaseTimeMillis": "1468825200000",
      "voidedTimeMillis": "1469430000000",
      "orderId": "some_order_id",
      "voidedSource": "0",
      "voidedReason": "4"
    },
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "some_other_purchase_token",
      "purchaseTimeMillis": "1468825100000",
      "voidedTimeMillis": "1470034800000",
      "orderId": "some_other_order_id",
      "voidedSource": "2",
      "voidedReason": "5"
    },
  ]
}

配额

Voided Purchases API 会针对每个软件包设置以下配额：

• 每天查询不超过 6,000 次（一天是从太平洋时间午夜开始，并于次日同一时间结束）。
• 在任何时长为 30 秒的期限内，查询不超过 30 次。

初次请求指南

初次提交 API 请求时，您可能需要获取应用的所有可用数据。此流程有可能会将您的每日配额消耗一空，不过这种情况不太可能出现。如需以更安全、更统一的方式获取已作废购买交易的相关数据，请按以下最佳实践进行操作：

• 使用 maxResults 参数的默认值。这样一来，如果您将一天的查询配额全部用尽，便可检索 600 万笔已作废购买交易的详细信息。
• 如果响应包含 nextPageToken 的值，请在下次提交请求期间将此值赋予 token 参数。

最佳实践

注意：除了使用此 API，开发者还应集成实时开发者通知 (RTDN)。 集成 RTDN 后，每当用户的使用权在您的应用中发生变化时，包括用户作废了购买交易时，您都会收到来自 Google 的通知。

在您的应用中使用此 API 时，请注意，将购买交易作废的原因是多种多样的，并没有任何单一的解决方案可以适用于所有情况。设计撤消政策和策略时，应时刻为用户着想。为此，您可以采取以下推荐做法：

• 使用此 API 作为综合策略中的众多要素之一来应对不良行为。在下列情况下，撤消对应用内商品的访问权限通常会更有效：应用的应用内购商品价格合理；应用设计有助于抑制不良行为；有一个强大的用户群，该用户群所接受的文化会摒弃不良行为；用户支持渠道响应迅速且富有效率。
• 统一管理撤消政策，确保公平对待所有用户。
• 解决不良行为时，考虑创建分阶段策略。例如，对早期违规行为进行应用内警告，并在用户继续进行不良行为时升级响应措施。作为终极措施，您可以彻底阻止用户与您的应用进行互动。
• 引入撤消政策后，每次更新此政策时，均通过应用的推广渠道将相关更改通知给用户。先为用户留出充足的时间来清楚了解这些更改，然后再让更改在应用中生效。
• 对用户开诚布公，并在每次采取措施（例如撤消用户对某个应用内商品的访问权限）时通知用户。理想情况下，用户应能针对您的决定提出异议，并且此类异议应受到公平对待。
• 监控反馈表单和社区论坛，以了解导致用户出现不良行为的原因，及其采取此类行为的方式。根据这些数据分析采取措施，并以此作为第一道防线。