Void Purchases API

Google Play Voided Purchases API 提供與使用者作廢的購買交易相關的訂單清單。你可以使用這份清單中的資訊來實作撤銷系統，以防止使用者存取這些訂單中的產品。

這個 API 適用於一次性的應用程式內訂單和應用程式訂閱項目。

您可以透過下列方式避免購買交易：

  • 使用者針對訂單要求退款。
  • 使用者取消訂單。
  • 訂單遭到拒付。

  • 開發人員取消訂單或退款。

  • Google 將訂單取消或退款。

使用這個 API 可以為所有應用程式使用者打造更均衡且公平的體驗，特別是應用程式遊戲。

取得存取權

如要使用 Voided Purchases API，您必須具備查看財務資訊的權限。您可以使用 OAuth 用戶端或服務帳戶來提供授權。如果您使用服務帳戶，請在該帳戶中啟用「查看財務報表」權限。

如要進一步瞭解如何取得 Google Play Developer 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

您也可以在要求中加入下列參數，這些參數都是選用項目：

開始時間

自 Unix epoch 開始，您希望在回應中看到最舊且作廢的購買交易所花費的時間 (以毫秒為單位)。根據預設，startTime 是 30 天前的日期。

API 只能顯示過去 30 天內的無效購買交易。無論您為 startTime 提供的值為何，回應中都不會包含較舊的無效交易。

endTime

自 Unix epoch 開始，您想要在回應中看到的最近一次作廢購買時間 (以毫秒為單位)。根據預設，endTime 會設為目前時間。

maxResults
每次回應顯示的失效購買次數上限。預設值為 1000。請注意，這項參數的最大值也是 1000。
token
先前回應的接續權杖，可讓您查看更多結果。
類型

每次回應中出現的無效購買交易類型。如果設為 0，則只會傳回無效的應用程式內購項目。如果設為 1，則將同時忽略應用程式內購的無效購買交易和無效訂閱項目購買交易。預設值為 0。

回應為 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 會依照套件設定以下配額：

  • 每日 6000 次查詢。(一天的開始時間和結束時間為太平洋時間。)
  • 任何 30 秒期間內 30 次查詢。

初始要求的相關規範

在初始 API 要求期間，您可能想要擷取應用程式的所有可用資料。不過，這項程序不太可能用盡您的每日配額。如要以更安全、更一致的方式取得無效購買交易資料，請遵循下列最佳做法：

  • 使用 maxResults 參數的預設值。如此一來，如果您在一天內使用完整的查詢配額，就能擷取 6,000,000 筆無效購買交易的詳細資料。
  • 如果回應中包含 nextPageToken 的值，請在下次要求中將這個值指派給 token 參數。

最佳做法

當您決定在應用程式中使用這個 API 時，請記住，有一種原因會導致購買交易失效，並且沒有任何單一解決方案適用於所有情況。設計撤銷政策和策略時，請務必考量使用者。方法很簡單，只要套用下列建議的做法即可：

  • 這個 API 是全方位策略中的眾多元素之一，可協助解決意外行為。與應用程式內提供合理價格的應用程式搭配使用時，撤銷應用程式內產品存取權通常比較有效率，但又會引起使用者反感的行為設計、造成文化拒絕接受這類行為的強大使用者群，以及回應式和高效的使用者支援管道。
  • 統一管理撤銷政策，確保所有使用者均公平。
  • 建議您在建立不必要行為時，建立分階段政策。例如，先針對應用程式內的早期違規事件發出應用程式內警告，等到使用者發生不當行為時，再提報回應。在萬不得已的情況下，您可以完全禁止使用者與應用程式互動。
  • 加入撤銷政策時，每次更新政策時，您都可以透過應用程式的推廣管道通知使用者相關異動。因此，為了讓使用者充分瞭解應用程式在應用程式生效前，能先充分瞭解這些變更。
  • 您必須清楚告知使用者，並在您採取行動時通知他們，例如撤銷使用者存取應用程式內產品的權限。理想情況下，使用者應該要能對您的決定提出爭議，而這類爭議應合理處理。
  • 監控意見回饋表單和社群論壇，瞭解使用者有哪些異常行為，以及他們採取這類行為的方式。請採取這些行動，做為第一線防線。