API giao dịch mua bị vô hiệu

Voided Purchases API trên Google Play cung cấp danh sách các đơn đặt hàng liên kết với các giao dịch mua mà người dùng đã vô hiệu. Bạn có thể sử dụng thông tin trong danh sách này để triển khai một hệ thống thu hồi ngăn người dùng truy cập vào các sản phẩm qua các đơn đặt hàng đó.

API này áp dụng cho các đơn đặt hàng trong ứng dụng một lần và Gói thuê bao ứng dụng.

Một giao dịch mua có thể được vô hiệu theo các cách sau:

  • Người dùng yêu cầu hoàn tiền cho đơn đặt hàng.
  • Người dùng huỷ đơn đặt hàng.
  • Đơn đặt hàng được hoàn tiền.
  • Nhà phát triển huỷ hoặc hoàn tiền cho đơn đặt hàng.

  • Google huỷ hoặc hoàn tiền cho đơn đặt hàng.

Bằng cách sử dụng API này, bạn có thể tạo ra trải nghiệm cân bằng và công bằng hơn cho tất cả người dùng ứng dụng, đặc biệt nếu ứng dụng của bạn là một trò chơi.

Nhận quyền truy cập

Để làm việc với API Giao dịch mua vô hiệu, bạn cần có quyền xem thông tin tài chính. Bạn uỷ quyền bằng cách sử dụng ứng dụng OAuth hoặc tài khoản dịch vụ. Nếu bạn đang sử dụng tài khoản dịch vụ, hãy bật quyền "Xem báo cáo tài chính" trong tài khoản này.

Để tìm hiểu thêm về cách lấy quyền truy cập được cấp phép vào API Nhà phát triển Google Play, hãy xem những hướng dẫn sau:

Xem các giao dịch mua bị vô hiệu

Sử dụng phương thức GET để yêu cầu danh sách các giao dịch mua vô hiệu. Trong yêu cầu của bạn, hãy cung cấp tên gói đủ điều kiện cho ứng dụng (chẳng hạn như com.google.android.apps.maps) và mã thông báo uỷ quyền mà bạn nhận được khi có được quyền truy cập vào API.

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

Bạn cũng có thể đưa các thông số sau đây vào yêu cầu của mình, mỗi thông số này là không bắt buộc:

startTime

Thời gian, tính bằng mili giây kể từ Thời gian bắt đầu của hệ thống Unix, của giao dịch mua vô hiệu cũ nhất mà bạn muốn thấy trong phản hồi. Theo mặc định, startTime được đặt thành 30 ngày trước.

API này chỉ có thể hiện các giao dịch mua vô hiệu xảy ra trong 30 ngày qua. Các giao dịch mua cũ vô hiệu sẽ không được đưa vào phản hồi, bất kể bạn đã cung cấp giá trị nào cho startTime.

endTime

Thời gian tính bằng mili giây kể từ Thời gian bắt đầu của hệ thống Unix của giao dịch mua vô hiệu mới nhất mà bạn muốn thấy trong phản hồi. Theo mặc định, endTime được đặt thành thời gian hiện tại.

maxResults
Số lượng giao dịch mua vô hiệu tối đa xuất hiện trong mỗi câu trả lời. Theo mặc định, giá trị này là 1000. Xin lưu ý rằng giá trị tối đa cho thông số này cũng là 1000.
mã thông báo
Mã thông báo tiếp tục từ phản hồi trước đó, giúp bạn xem thêm kết quả.
loại

Loại giao dịch mua vô hiệu xuất hiện trong mỗi phản hồi. Nếu bạn đặt chính sách này thành 0, thì hệ thống sẽ chỉ trả lại các giao dịch mua hàng trong ứng dụng vô hiệu. Nếu bạn đặt giá trị này là 1, thì cả giao dịch mua hàng trong ứng dụng vô hiệu và giao dịch mua gói thuê bao vô hiệu đều sẽ bị trả lại. Giá trị mặc định là 0.

includeQuantityBasedPartialRefund

Liệu có bao gồm các giao dịch mua vô hiệu hoàn tiền một phần theo số lượng hay không (chỉ áp dụng cho giao dịch mua số lượng nhiều). Nếu giá trị là true, các giao dịch mua bổ sung vô hiệu có thể được trả lại bằng thuộc tính voidedQuantity. Mã này cho biết số tiền hoàn lại của giao dịch hoàn tiền một phần theo số lượng. Giá trị mặc định là false.

Phản hồi là một chuỗi JSON chứa danh sách các giao dịch mua vô hiệu. Nếu có nhiều kết quả hơn số lượng kết quả được chỉ định trong tham số yêu cầu maxResults, thì phản hồi sẽ bao gồm giá trị nextPageToken mà bạn có thể truyền vào yêu cầu tiếp theo để xem thêm kết quả. Kết quả đầu tiên trong danh sách cho thấy giao dịch mua vô hiệu cũ nhất.

{
  "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"
    },
  ]
}

Hạn mức

Voided Purchases API đặt các hạn mức sau trên cơ sở từng gói:

  • 6000 lượt truy vấn mỗi ngày. (Ngày bắt đầu và kết thúc lúc nửa đêm theo giờ Thái Bình Dương.)
  • 30 truy vấn trong khoảng thời gian 30 giây bất kỳ.

Nguyên tắc đối với yêu cầu ban đầu

Trong yêu cầu API ban đầu, có thể bạn sẽ muốn tìm nạp tất cả dữ liệu có sẵn cho ứng dụng của mình. Mặc dù không có khả năng xảy ra nhưng quá trình này có thể sử dụng hết hạn mức hằng ngày của bạn. Để thu thập dữ liệu về các giao dịch mua vô hiệu theo cách an toàn và nhất quán hơn, hãy làm theo các phương pháp hay nhất sau:

  • Sử dụng giá trị mặc định cho tham số maxResults. Bằng cách đó, nếu sử dụng toàn bộ hạn mức truy vấn trong một ngày, bạn có thể truy xuất thông tin chi tiết của 6.000.000 giao dịch mua vô hiệu.
  • Nếu phản hồi có chứa giá trị của nextPageToken, hãy chỉ định giá trị này cho tham số token trong yêu cầu tiếp theo.

Những phương pháp hay nhất

Khi sử dụng API này trong ứng dụng, hãy nhớ rằng có nhiều lý do để vô hiệu hoá giao dịch mua và không có một giải pháp duy nhất nào phù hợp cho mọi trường hợp. Bạn nên lưu ý đến người dùng khi thiết kế các chiến lược và chính sách thu hồi. Để làm như vậy, bạn có thể áp dụng các phương pháp được đề xuất sau:

  • Hãy sử dụng API này làm một trong nhiều yếu tố trong chiến lược toàn diện để giải quyết hành vi không mong muốn. Việc thu hồi quyền truy cập vào sản phẩm trong ứng dụng thường hiệu quả hơn khi được kết hợp với một ứng dụng có mức giá hợp lý để mua hàng trong ứng dụng, thiết kế ứng dụng ngăn cản hành vi không mong muốn, cơ sở người dùng vững mạnh có văn hoá từ chối những hành vi đó cũng như kênh hỗ trợ người dùng thích ứng và hiệu quả.
  • Quản lý thống nhất chính sách thu hồi để đảm bảo công bằng cho tất cả người dùng.
  • Hãy cân nhắc tạo chính sách theo giai đoạn để xử lý hành vi không mong muốn. Ví dụ: hãy bắt đầu bằng các cảnh báo trong ứng dụng về các hành vi phạm tội sớm, sau đó chuyển phản hồi của bạn lên cấp cao hơn khi hành vi không mong muốn của người dùng vẫn tiếp diễn. Khi không còn cách nào khác, bạn có thể ngăn người dùng tương tác với ứng dụng của mình.
  • Khi bạn đưa ra chính sách thu hồi và mỗi lần bạn cập nhật chính sách này, hãy sử dụng các kênh tiếp cận của ứng dụng để thông báo cho người dùng về các thay đổi này. Hãy cho người dùng thời gian để hiểu rõ những thay đổi này trước khi chúng có hiệu lực trong ứng dụng của bạn.
  • Hãy minh bạch với người dùng và thông báo cho họ bất cứ khi nào bạn thực hiện hành động, chẳng hạn như thu hồi quyền truy cập của họ vào một sản phẩm trong ứng dụng. Tốt nhất là người dùng có thể kháng nghị quyết định của bạn và các tranh chấp như vậy phải được xử lý công bằng.
  • Theo dõi các biểu mẫu phản hồi và diễn đàn cộng đồng để tìm hiểu những điều khiến người dùng hành xử theo cách không mong muốn và cách họ thực hiện những hành vi như vậy. Hãy dựa vào những thông tin chi tiết này như một tuyến phòng vệ đầu tiên.