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 đặ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 từ danh sách này để triển khai hệ thống thu hồi nhằm 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 các đơn đặt hàng trong ứng dụng và gói thuê bao một lần.

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.

  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 cho một giao dịch mua mà không đặt tuỳ chọn thu hồi, thì API sẽ không trả về đơ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.

Lưu ý: Không giống như các nguồn dữ liệu khác liên quan đến đơn đặt hàng, Voided Purchases API (API Giao dịch mua vô hiệu) bao gồm cả những giao dịch mua bị công ty xử lý thanh toán tính phí lại. Do đó, bạn có thể thấy thông tin từ API này không nhất quán với thông tin từ các nguồn dữ liệu khác liên quan đến đơn đặt hàng.

Lưu ý: Voided Purchases API chỉ trả về các giao dịch mua vô hiệu khi cần thu hồi. Nhà phát triển có thể sử dụng API này làm chỉ báo về thời điểm thực hiện hành động bổ sung ở phía họ. Tuy nhiên, một số giao dịch mua có thể được hoàn tiền với lý do là nhà phát triển chưa bao giờ xác nhận giao dịch mua đó và do đó, giao dịch đó có thể không tồn tại trong hồ sơ của nhà phát triển.

Có được quyền truy cập

Để sử dụng Voided Purchases API, bạn cần có quyền xem thông tin tài chính. Bạn cung cấp quyền uỷ quyền bằ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 có được quyền truy cập được uỷ quyền vào API dành cho Nhà phát triển của Google Play, hãy xem các hướng dẫn sau:

• Thiết lập ứng dụng truy cập API
• Thêm người dùng vào tài khoản nhà phát triển và quản lý các quyền

Xem 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 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ã uỷ quyền mà bạn nhận được khi được 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ể thêm các tham số sau vào yêu cầu của mình, mỗi tham số đều 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 bị vô hiệu hoá lâu 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 chỉ có thể cho thấy những 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ũ không được đưa vào phản hồi, bất kể giá trị mà bạn đã cung cấp cho startTime.

Lưu ý: Các giao dịch mua vô hiệu trong phản hồi được lọc dựa trên thời điểm API coi một bản ghi nhất định là vô hiệu, chứ không phải theo giá trị của voidedTimeMillis được trả về trong phản hồi.

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 bị vô hiệu hoá gần đây nhất mà bạn muốn xem trong phản hồi. Theo mặc định, endTime được đặt thành thời gian hiện tại.

Lưu ý: Các giao dịch mua vô hiệu trong phản hồi được lọc dựa trên thời điểm API coi một bản ghi nhất định là vô hiệu, chứ không phải theo giá trị voidedTimeMillis được trả về trong phản hồi.

maxResults

Số lượng giao dịch mua bị 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ừ mộ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 bạn đặt giá trị này thành 0, chỉ những giao dịch mua vô hiệu trong ứng dụng mới được trả về. Nếu được đặt thành 1, cả giao dịch mua hàng vô hiệu trong ứng dụng và giao dịch mua gói thuê bao vô hiệu đều sẽ được trả về. Giá trị mặc định là 0.

Lưu ý: Trước khi yêu cầu nhận các giao dịch mua gói thuê bao bị vô hiệu, bạn phải chuyển sang sử dụng orderId trong phản hồi. Mã này xác định duy nhất các giao dịch mua một lần và gói thuê bao. Nếu không, bạn sẽ nhận được nhiều đơn đặt hàng thuê bao có cùng PurchaseToken.

includeQuantityBasedPartialRefund

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

Lưu ý: Khi tổng số lượng còn lại của một giao dịch mua được hoàn tiền, giao dịch mua tương ứng bị vô hiệu sẽ không có voidedQuantity. Đây là tín hiệu cho biết giao dịch mua đã được hoàn tiền đầy đủ. Ví dụ: nếu một giao dịch mua có số lượng là 10 được hoàn tiền 3 lần với số lượng lần lượt là 2, 3 và 5, thì sẽ có 3 giao dịch mua bị huỷ. Hai giao dịch mua bị vô hiệu đầu tiên sẽ có voidedQuantity là 2 và 3, trong khi giao dịch mua bị vô hiệu thứ ba sẽ không có voidedQuantity.

Phản hồi là một chuỗi JSON chứa danh sách các giao dịch mua bị vô hiệu. Nếu có nhiều kết quả hơn số lượng đượ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 một 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 lâu 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 từng gói:

• 6.000 lượt truy vấn mỗi ngày. (Một 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 đối với yêu cầu ban đầu

Trong yêu cầu API ban đầu, bạn có thể 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ể làm cạn kiệt hạn mức hằng ngày của bạn. Để lấy dữ liệu về giao dịch mua bị 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 hết 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 một phản hồi có chứa giá trị cho nextPageToken, hãy chỉ định giá trị này cho tham số token trong yêu cầu tiếp theo của bạn.

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

Lưu ý: Ngoài việc sử dụng API này, nhà phát triển nên tích hợp với Thông báo theo thời gian thực dành cho nhà phát triển (RTDN). Với RTDN, bạn sẽ nhận được thông báo từ Google mỗi khi có thay đổi về quyền của người dùng trong ứng dụng của bạn, kể cả khi người dùng huỷ giao dịch mua.

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á một giao dịch mua và không có giải pháp nào phù hợp cho tất cả các trường hợp. Bạn nên nghĩ đến người dùng khi xây dựng chiến lược và chính sách thu hồi. Để làm điều này, bạn có thể áp dụng các phương pháp đề xuất sau:

• Hãy sử dụng API này như một trong nhiều yếu tố trong một 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 kết hợp với một ứng dụng có giá hợp lý cho các giao dịch mua hàng trong ứng dụng, một thiết kế ứng dụng ngăn chặn hành vi không mong muốn, một cơ sở người dùng mạnh mẽ có văn hoá từ chối hành vi đó và các kênh hỗ trợ người dùng hiệu quả và phản hồi nhanh.
• Áp dụng chính sách thu hồi một cách nhất quán để đảm bảo tính công bằng cho tất cả người dùng.
• Hãy cân nhắc việc tạo một 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ảnh báo trong ứng dụng đối với các hành vi vi phạm ban đầu, sau đó tăng mức phản hồi nếu người dùng tiếp tục có hành vi không mong muố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 giới thiệu một chính sách thu hồi và mỗi khi bạn cập nhật chính sách đó, 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ề những thay đổi. 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ể khiếu nại quyết định của bạn và những trường hợp khiếu nại đó phải được xử lý một cách công bằng.
• Theo dõi biểu mẫu phản hồi và diễn đàn cộng đồng để hiểu rõ điều gì 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 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 hàng rào bảo vệ đầu tiên.