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

每個回應中顯示的無效交易數量上限。根據預設，這個值為 1000。請注意，這個參數的最大值也是 1000。

token

先前回應中的接續符記，可供您查看更多結果。

類型

每則回覆中顯示的已取消交易類型。如果設為 0，系統只會傳回已取消的應用程式內購買交易。如果設為 1，系統會傳回已取消的應用程式內商品和訂閱項目。預設值為 0。

注意：要求接收已取消的訂閱交易前，請先改用回覆中的 orderId，這個 ID 可做為一次性購買交易和訂閱項目的專屬識別碼。否則，您會收到多筆具有相同 PurchaseToken 的訂閱訂單。

includeQuantityBasedPartialRefund

是否要納入依數量提供部分退款的取消交易，這項功能僅適用於購買多件商品。如果true, 可退回的交易作廢項目數量較多，則會以voidedQuantity 表示依數量部分退款的退款數量。預設值為 false。

注意：如果購買交易的剩餘總數量全數退款，相應的無效交易就不會顯示 voidedQuantity，這表示該交易已全額退款。舉例來說，如果數量為 10 的購買交易退款 3 次，退款數量分別為 2、3 和 5，則會有 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 次查詢。(「1 天」是從太平洋時間的午夜算起。)
• 在任何 30 秒內提出 30 次查詢。

初始要求指南

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

• 使用 maxResults 參數的預設值。這樣一來，即使您當天的查詢配額全數用盡，也能擷取 6,000,000 筆已取消交易的詳細資料。
• 如果回應包含 nextPageToken 的值，請在下一個要求中將這個值指派給 token 參數。

最佳做法

注意： 除了使用這個 API，開發人員也應整合即時開發人員通知 (RTDN)。有了 RTDN，每當使用者在應用程式中的權利有異動 (包括取消購買)，您都會收到 Google 的通知。

在應用程式中使用這項 API 時，請注意，有許多原因會導致交易失效，而且沒有單一解決方案適用於所有情況。設計撤銷政策和策略時，請務必考量使用者需求。如要這麼做，可以採用下列建議做法：

• 請將這個 API 做為全面策略中的其中一項元素，用來解決不當行為。如果應用程式內購價格合理、應用程式設計可避免不良行為、使用者群體強大且排斥這類行為，以及使用者支援管道反應迅速且有效率，那麼撤銷應用程式內商品存取權通常會更有效。
• 請統一管理撤銷政策，確保所有使用者都能獲得公平待遇。
• 如要處理不當行為，建議建立分階段政策。舉例來說，如果使用者初犯，您可以先在應用程式中發出警告，如果使用者持續出現不當行為，再逐步加重處置。在萬不得已的情況下，您可以完全禁止使用者與應用程式互動。
• 推出或更新撤銷政策時，請透過應用程式的宣傳管道通知使用者。請給予使用者充足時間瞭解這些變更，再於應用程式中生效。
• 請向使用者公開透明地說明情況，並在採取行動時通知他們，例如撤銷他們對應用程式內商品的存取權。理想情況下，使用者應能對您的決定提出爭議，且這類爭議應獲得公平處理。
• 監控意見回饋表單和社群論壇，瞭解使用者做出不良行為的原因和方式。根據這些深入分析資料採取行動，做為第一道防線。