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

API giao dịch mua vô hiệu trên Google Play cung cấp danh sách các đơn 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 từ danh sách này để triển khai hệ thống thu hồi ngăn người dùng truy cập vào sản phẩm từ các đơn đặt hàng đó.

API này áp dụng cho đơn đặt hàng một lần trong ứng dụng và Đăng ký ứng dụng.

Giao dịch mua có thể 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 hủy hoặc hoàn tiền cho đơn đặt hàng. Lưu ý: Chỉ những đơn đặt hàng bị thu hồi mới được hiển thị trong API giao dịch mua vô hiệu. Nếu nhà phát triển hoàn tiền mà không đặt tùy chọn thu hồi, đơn đặt hàng sẽ không hiển thị trong API.
  • 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 cấp 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 "Xem báo cáo tài chính" quyền trong tài khoản này.

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

Xem các giao dịch mua 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, hãy thêm 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ấp 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 tham số sau vào yêu cầu, mỗi tham số là không bắt buộc:

thời gian bắt đầu

Thời gian, tính bằng mili giây kể từ khoảng thời gian bắt đầu của hệ thống, của giao dịch mua vô hiệu cũ 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 chỉ có thể hiển thị các giao dịch mua vô hiệu đã xảy ra trong 30 ngày qua. Các giao dịch mua vô hiệu cũ sẽ không được đưa vào phản hồi, bất kể giá trị bạn đã cung cấp cho startTime là bao nhiêu.

thời gian kết thúc

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

maxresults
Số giao dịch mua vô hiệu tối đa xuất hiện trong mỗi phản hồi. Theo mặc định, giá trị này là 1000. Xin lưu ý rằng giá trị tối đa cho tham 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 đó cho phé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 đặt thành 0, chỉ những giao dịch mua hàng trong ứng dụng không có hiệu lực sẽ được trả về. Nếu đặt thành 1, cả giao dịch mua vô hiệu trong ứng dụng và giao dịch mua gói thuê bao vô hiệu sẽ được trả về. Giá trị mặc định là 0.

Phản hồi là một chuỗi JSON chứa danh sách giao dịch mua vô hiệu. Nếu có nhiều kết quả hơn số đượ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ể chuyển vào một yêu cầu sau đó để 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

API giao dịch mua vô hiệu đặt các hạn mức sau đây cho mỗi gói:

  • 6.000 lượt truy vấn mỗi ngày. (Ngày bắt đầu và kết thúc vào 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 dành cho yêu cầu ban đầu

Trong yêu cầu API ban đầu, bạn có thể cầ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 chắc, nhưng quy trình này có thể đã làm hết hạn mức hằng ngày của bạn. Để thu thập dữ liệu giao dịch mua vô hiệu theo cách an toàn, nhất quán hơn, hãy làm theo những phương pháp hay nhất sau:

  • Hãy 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 chứa một giá trị cho nextPageToken, hãy gán giá trị này cho thông số token trong yêu cầu tiếp theo.

Các phương pháp hay nhất

Khi bạn xác định cách sử dụng API này trong ứng dụng, hãy nhớ rằng có nhiều lý do để vô hiệu hoá một giao dịch mua và không có giải pháp nào phù hợp trong mọi trường hợp. Bạn nên lưu ý người dùng khi thiết kế 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 đề xuất sau:

  • Sử dụng API này như một trong nhiều phần tử trong một chiến lược toàn diện để xử lý những hành vi không mong muốn. Việc thu hồi quyền truy cập vào các sản phẩm trong ứng dụng thường hiệu quả hơn khi 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, một thiết kế ứng dụng không khuyến khích hành vi không mong muốn, cơ sở người dùng mạnh mẽ và văn hoá từ chối hành vi đó cùng các kênh hỗ trợ người dùng hiệu quả và phản hồi nhanh.
  • Quản lý chính sách thu hồi của bạn một cách thống nhất để đảm bảo sự 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 khi giải quyết hành vi không mong muốn. Ví dụ: bắt đầu bằng các cảnh báo trong ứng dụng cho hành vi phạm tội sớm, sau đó chuyển phản hồi của bạn khi hành vi không mong muốn của người dùng tiếp tục. Phương án cuối cùng là bạn có thể ngăn người dùng tương tác với ứng dụng.
  • Khi bạn đưa ra một chính sách thu hồi và mỗi lần cập nhật chính sách đó, hãy sử dụng các kênh liên hệ của ứng dụng để thông báo cho người dùng về các thay đổi đó. Cho người dùng thời gian để nắm 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 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. Lý tưởng nhất là người dùng có thể kháng nghị quyết định của bạn và những kháng nghị đó sẽ đượ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 để hiểu những yếu tố thúc đẩy người dùng thực hiện hành vi không mong muốn và cách họ thực hiện hành vi đó. Hãy hành động dựa trên những thông tin chi tiết này như một tuyến phòng vệ đầu tiên.