Voided 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

您也可以在要求中加入下列參數,每個參數都是選用參數:

startTime

您要在回應中看到的最舊無效購買交易,自 Unix 紀元以來的時間 (以毫秒為單位)。根據預設,startTime 設為 30 天前。

API 只能顯示過去 30 天內作廢的購買交易。無論您為 startTime 提供的值為何,回應中不會包含先前作廢的購買交易。

endTime

您要在回應中看到的最新無效購買交易,自 Unix 紀元以來的時間 (以毫秒為單位)。根據預設,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 會根據每個套件設定下列配額:

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

初始要求規範

在初始 API 要求期間,您可能想要擷取應用程式的所有可用資料。雖然很少見,但此程序可能會耗盡您的每日配額。如要以更安全、更一致的方式取得作廢的購買交易資料,請遵循下列最佳做法:

  • 使用 maxResults 參數的預設值。如此一來,如果您使用一天的完整查詢配額,就可以擷取 6,000,000 項作廢的購買交易詳細資料。
  • 如果回應包含 nextPageToken 的值,請在下一個要求期間將這個值指派給 token 參數。

最佳做法

在應用程式中使用這個 API 時,請注意許多原因都可能導致購買交易失效,也沒有單一解決方案適用於所有情況。設計撤銷政策和策略時,您應考量使用者的需求。方法是採行下列建議做法:

  • 制定完善的策略時,請將這個 API 做為處理不尋常行為的眾多元素之一。一般來說,搭配提供合理價格的應用程式內購應用程式、避免產生不當行為的應用程式設計、由文化拒絕此類行為的強大使用者族群,以及有回應效率且有效率的使用者支援管道,此時,撤銷應用程式內產品的存取權通常會更有效率。
  • 統一管理撤銷政策,確保所有使用者都能享有公正性。
  • 如要解決非預期的行為,請考慮制定階段性政策。例如,先從應用程式內警告用於早期違規,然後在使用者不想要的行為繼續時提報回應。在不得已的情況下,您可以完全禁止使用者與應用程式互動。
  • 如果您推出撤銷政策且每次更新,請使用應用程式的外聯管道告知使用者相關變更。在變更在應用程式中生效前,建議您讓使用者有時間清楚瞭解這些變更。
  • 請向使用者公開相關資訊,並在每次採取行動 (例如撤銷使用者的應用程式存取權) 時告知他們。在理想情況下,使用者應該能夠對您的決定提出爭議,且應以合理的方式處理這類爭議。
  • 監控意見回饋表單和社群論壇,瞭解是什麼因素促使使用者採取不想要的行為,以及他們如何執行這類行為。做為第一道防線,根據這些洞察資訊採取行動。