Voided Purchases API

Interfejs Google Play Voided Purchases API zapewnia listę zamówień powiązanych z zakupami unieważnionymi przez użytkownika. Możesz użyć informacji z tej listy, aby wdrożyć system unieważniania, który uniemożliwia użytkownikowi dostęp do usług z poziomu tych zamówień.

Ten interfejs API dotyczy jednorazowych zamówień w aplikacji i subskrypcji aplikacji.

Zakup można unieważnić na kilka sposobów:

• Użytkownik prosi o zwrot środków za zamówienie.
• Użytkownik anuluje zamówienie.
• Obciążono zwrot środków za zamówienie.

• Deweloper anuluje zamówienie lub zwraca środki.

  Uwaga: w interfejsie Voided Purchases API widoczne są tylko anulowane zamówienia. Jeśli deweloper zwróci środki za zakup bez ustawiania opcji anulowania, zamówienie nie zostanie zwrócone przez interfejs API.

• Google anuluje zamówienie lub zwraca środki.

Używając tego interfejsu API, możesz zapewnić wszystkim użytkownikom swojej aplikacji bardziej zrównoważone i uczciwe korzystanie z nich, zwłaszcza jeśli jest to gra.

Uwaga: w przeciwieństwie do innych źródeł danych związanych z zamówieniami interfejs Voided Purchases API uwzględnia zakupy, których koszty są zwracane przez firmy obsługujące płatności. Dlatego możesz zauważyć rozbieżności między informacjami z tego interfejsu API a informacjami z innych źródeł danych związanych z zamówieniami.

Uwaga: interfejs Voided Purchases API zwraca unieważnione zakupy tylko wtedy, gdy trzeba je anulować. Deweloperzy mogą użyć tego interfejsu API, aby wskazać, kiedy należy podjąć dodatkowe działania.

Uzyskiwanie dostępu

Aby korzystać z interfejsu Voided Purchases API, musisz mieć uprawnienia do wyświetlania informacji finansowych. Autoryzację przeprowadzasz za pomocą klienta OAuth lub konta usługi. Jeśli korzystasz z konta usługi, włącz na tym koncie uprawnienie „Wyświetlanie raportów finansowych”.

Więcej informacji o uzyskiwaniu autoryzowanego dostępu do interfejsów Google Play Developer API znajdziesz w tych przewodnikach:

• Konfigurowanie klientów dostępu do interfejsu API
• Dodawanie użytkowników konta dewelopera i zarządzanie uprawnieniami

Wyświetlanie unieważnionych zakupów

Aby poprosić o listę unieważnionych zakupów, użyj metody GET. Podaj w żądaniu pełną nazwę pakietu aplikacji, np. com.google.android.apps.maps, oraz token autoryzacji otrzymany podczas uzyskiwania dostępu do interfejsu API.

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

Możesz też zawrzeć w żądaniu te parametry (opcjonalnie):

startTime

Czas (w milisekundach) od czasu uniksowego czasu najstarszego unieważnionego zakupu, który powinien być widoczny w odpowiedzi. Domyślnie wartość startTime jest ustawiona na 30 dni temu.

Interfejs API może wyświetlać tylko unieważnione zakupy, które miały miejsce w ciągu ostatnich 30 dni. Starsze unieważnione zakupy nie zostaną uwzględnione w odpowiedzi, niezależnie od wartości podanej w polu startTime.

Uwaga: unieważnione zakupy w odpowiedzi są filtrowane na podstawie czasu, w którym interfejs API uznał dany rekord jako unieważniony, a nie według wartości voidedTimeMillis zwróconej w odpowiedzi.

endTime

Czas (w milisekundach) od epoki uniksowej ostatniego unieważnionego zakupu, który chcesz zobaczyć w odpowiedzi. Domyślnie endTime jest ustawiona na aktualną godzinę.

Uwaga: zakupy unieważnione w odpowiedzi są filtrowane na podstawie czasu, w którym interfejs API uznał dany rekord jako unieważniony, a nie według wartości voidedTimeMillis zwróconej w odpowiedzi.

maxResults

Maksymalna liczba unieważnionych zakupów pojawiających się w każdej odpowiedzi. Domyślnie ta wartość wynosi 1000. Pamiętaj, że maksymalna wartość tego parametru też wynosi 1000.

token

Token kontynuacji z poprzedniej odpowiedzi, który umożliwia wyświetlenie większej liczby wyników.

Niestandardowy typ treści

Typ unieważnionych zakupów, które pojawiają się w każdej odpowiedzi. Jeśli ustawisz wartość 0, zwracane będą tylko unieważnione zakupy w aplikacji. Jeśli ustawisz wartość 1, zwrócone zostaną zarówno unieważnione zakupy w aplikacji, jak i unieważnione subskrypcje. Wartość domyślna to 0.

Uwaga: zanim poprosisz o unieważnione zakupy subskrypcji, musisz użyć w odpowiedzi parametru orderId, który jednoznacznie identyfikuje jednorazowe zakupy i subskrypcje. W przeciwnym razie otrzymasz wiele zamówień subskrypcji z tym samym tokenem zakupu.

includeQuantityBasedPartialRefund

Określa, czy uwzględniać anulowane zakupy w przypadku częściowych zwrotów środków na podstawie ilości, które mają zastosowanie tylko w przypadku zakupu większej liczby sztuk produktu. Jeśli jest ustawiona wartość true, dodatkowe anulowane zakupy mogą zostać zwrócone z wartością voidedQuantity, która wskazuje kwotę zwrotu środków w przypadku częściowego zwrotu środków na podstawie ilości. Wartością domyślną jest false.

Uwaga: gdy zwracamy środki za pozostałą część zakupu, odpowiadający unieważnionemu zakupowi nie będzie widoczna wartość voidedQuantity, co oznacza, że zakup został w pełni zwrócony. Jeśli na przykład otrzymasz zwrot środków za zakup 10 sztuk w przypadku liczby 2, 3 i 5 produktów, zostaną one unieważnione. Pierwsze 2 unieważnione zakupy będą miały wartość voidedQuantity równą 2 i 3. Trzeci zakup unieważniony nie będzie miał wartości voidedQuantity.

Odpowiedź jest ciągiem tekstowym JSON zawierającym listę unieważnionych zakupów. Jeśli liczba wyników jest większa niż liczba określona w parametrze żądania maxResults, odpowiedź zawiera wartość nextPageToken, którą możesz przekazać w kolejnym żądaniu, aby wyświetlić więcej wyników. Pierwszy wynik na liście to najstarszy unieważniony zakup.

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

Limity

Voided Purchases API ustalają następujące limity dla poszczególnych pakietów:

• 6000 zapytań dziennie. (Dzień zaczyna się i kończy o północy czasu pacyficznego).
• 30 zapytań w dowolnym 30-sekundowym okresie.

Wskazówki dotyczące żądań wstępnych

Podczas wstępnego żądania do interfejsu API możesz chcieć pobrać wszystkie dostępne dane dotyczące aplikacji. Chociaż jest to mało prawdopodobne, proces ten może wyczerpać Twój dzienny limit. Aby uzyskać dane o unieważnionych zakupach w bezpieczniejszy i bardziej spójny sposób, postępuj zgodnie z tymi sprawdzonymi metodami:

• Użyj wartości domyślnej dla parametru maxResults. Dzięki temu, jeśli wykorzystasz cały limit zapytań na jeden dzień, możesz pobrać szczegóły 6 000 000 unieważnionych zakupów.
• Jeśli odpowiedź zawiera wartość nextPageToken, przypisz ją do parametru token w kolejnym żądaniu.

Sprawdzone metody

Uwaga: oprócz korzystania z tego interfejsu API deweloperzy powinni też przeprowadzić integrację z powiadomieniami w czasie rzeczywistym dla deweloperów (RTDN). Dzięki RTDN będziesz otrzymywać od Google powiadomienia za każdym razem, gdy zmienią się uprawnienia użytkownika w Twojej aplikacji, w tym gdy użytkownik anuluje zakup.

Gdy korzystasz z tego interfejsu API w swojej aplikacji, pamiętaj, że zakup może być unieważniony z wielu powodów i że nie ma jednego rozwiązania, które sprawdzi się we wszystkich przypadkach. Podczas tworzenia zasad i strategii unieważniania musisz pamiętać o swoich użytkownikach. Aby to osiągnąć, możesz zastosować te zalecane metody:

• Używaj tego interfejsu API jako jednego z wielu elementów kompleksowej strategii rozwiązywania problemów z niepożądanymi zachowaniami. Odwołanie dostępu do produktów w aplikacji jest zwykle skuteczniejsze, gdy jest połączone z aplikacją, która ma rozsądne ceny za zakupy w aplikacji, projekt aplikacji zniechęcający do niepożądanych zachowań, silna grupa użytkowników, którzy odrzucają takie zachowania, oraz szybko i wydajnie dostępny kanał obsługi klienta.
• Kontroluj zasady unieważniania w jednolity sposób, aby wszyscy użytkownicy byli uczciwi.
• W przypadku niepożądanych zachowań warto utworzyć zasady stopniowe. Zacznij na przykład od ostrzeżeń o wczesnych działaniach w aplikacji, a potem eskaluj odpowiedzi w miarę, jak użytkownik będzie kontynuować niepożądane zachowanie. W ostateczności możesz w ogóle uniemożliwić użytkownikowi interakcję z aplikacją.
• Gdy wprowadzisz zasadę unieważniania danych i każdej z nich ją aktualizujesz, informuj użytkowników o zmianach za pomocą kanałów komunikacji w aplikacji. Daj użytkownikom czas na zapoznanie się ze zmianami, zanim zaczną obowiązywać w aplikacji.
• Informuj użytkowników o każdym działaniu, np. anulowaniu dostępu do produktu w aplikacji. W miarę możliwości użytkownicy powinni mieć możliwość kwestionowania Twoich decyzji, a takie spory powinny być rozpatrywane sprawiedliwie.
• Sprawdzaj formularze opinii i fora społeczności, aby dowiedzieć się, co skłania użytkowników do zachowań niepożądanych i jak to robią. Wykorzystaj te spostrzeżenia jako pierwszą linię obrony.