Voided Purchases API

Google Play Voided Purchases API 提供一份訂單清單 與使用者作廢的購買交易有關您可以運用 執行撤銷系統，防止使用者 存取這些訂單中的產品

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

購買交易的作廢方式如下：

• 使用者申請退回訂單款項。
• 使用者取消訂單。
• 訂單遭到交易退單。

• 開發人員取消訂單或申請退回訂單款項。

  注意： Voided Purchases API 只會顯示已撤銷的訂單。 如果開發人員辦理退款時未設定撤銷選項， API 不會傳回這筆訂單。

• Google 取消訂單或申請退回訂單款項。

有了 API，您就能為應用程式的所有使用者打造更平衡公平的環境，特別是遊戲應用程式。

注意： 不同於其他訂單相關資料來源，Voided Purchases API 包括付款處理方已退費的購買交易。因此 這個 API 和這個 API 的資訊 來自其他訂單相關資料來源的資訊。

注意： Voided Purchases API 只會在需要時傳回作廢的購買交易 已撤銷。開發人員可以使用這個 API 做為何時 並採取進一步行動不過，部分購買項目可能會退款 開發人員未確認購買交易，且 因此可能不會出現在開發人員的記錄中。

取得存取權限

如要使用 Voided Purchases API，你必須具備查看該 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 明確識別一次性購買和訂閱項目。否則， 以同一個 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 針對個別套件設定下列配額：

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

初始要求指南

在最初的 API 要求期間，您可能會想擷取 雖然這個程序不太可能用盡，但還是有可能用盡每日配額。目的地： 以更加安全且一致的方式取得作廢的購物資料，請遵循下列 最佳做法：

• 使用 maxResults 參數的預設值。這樣一來，如果您使用 一天整天的查詢配額，您可以擷取 6,000,000 個 交易作廢。
• 如果回應包含 nextPageToken 的值，請將這個值指派給該 token 參數。

最佳做法

注意： 除了使用這個 API 以外，開發人員也必須與 即時開發人員通知 (RTDN)。 透過 RTDN，每當有 在應用程式中的使用者授權變更，包括 作廢。

在應用程式中使用這個 API 時，請留意 而且沒有任何一種解決方案 設計撤銷授權時，請務必考量使用者的需求 政策和策略並採用下列建議做法：

• 運用這個 API 做為全方位策略中的多項元素 非預期行為一般來說，撤銷應用程式內商品的存取權通常更有效 搭配應用程式內購買，而且價格合理 勸阻不當行為的應用程式設計，這類忠實的使用者群 企業文化拒絕這類行為，以及迅速且高效率的使用者支援 頻道。
• 請統一管理撤銷政策，確保所有使用者都能享有公平的體驗。
• 考慮建立階段性政策來解決不想要的行為。適用對象 比如，先從應用程式內發出早期違規警告，再提報 導致系統持續回應不恰當的行為。萬不得已的情況下， 讓使用者完全無法與應用程式互動
• 導入撤銷政策時，每次更新政策時，請使用 應用程式的推廣管道，通知使用者相關異動。為使用者提供 在變更對應用程式生效前，事先瞭解有哪些變更。
• 請在您採取行動 (例如： 撤銷他們對應用程式內商品的存取權。理想情況下 對決策提出爭議，因此這類爭議應獲得公正的處理。
• 監控意見回饋表單和社群論壇，瞭解使用者開啟內容的原因 或他們如何做出這類行為針對以下項目採取行動 將深入分析結果視為第一道防線