Voided Purchases API

Interfejs Google Play Voided Purchases API udostępnia listę zamówień powiązanych z zakupami, które użytkownik anulował. Informacje z tej listy możesz wykorzystać do wdrożenia systemu wycofywania, który uniemożliwi użytkownikowi dostęp do produktów z tych zamówień.

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

Zakup można anulować na te sposoby:

• Użytkownik prosi o zwrot środków za zamówienie.
• Użytkownik anuluje zamówienie.
• Zamówienie zostało obciążone zwrotnie.

• Deweloper anuluje zamówienie lub zwraca za nie środki.

  Uwaga: w interfejsie API anulowanych zakupów będą widoczne tylko anulowane zamówienia. Jeśli deweloper zwróci środki za zakup bez ustawienia opcji wycofania,
  interfejs API nie zwróci zamówienia.

• Google anuluje zamówienie lub zwraca środki.

Korzystając z tego interfejsu API, możesz zapewnić bardziej zrównoważone i sprawiedliwe wrażenia wszystkim użytkownikom aplikacji, 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, w przypadku których firmy obsługujące płatności dokonały zwrotu środków. Dlatego możesz zauważyć niespójności między informacjami z tego interfejsu API a informacjami z innych źródeł danych związanych z zamówieniami.

Uwaga: interfejs API anulowanych zakupów zwraca anulowane zakupy tylko wtedy, gdy trzeba je cofnąć. Deweloperzy mogą używać tego interfejsu API jako wskazówki, kiedy podjąć dodatkowe działania po swojej stronie. Jednak niektóre zakupy mogą zostać zwrócone z powodu braku potwierdzenia zakupu przez dewelopera, a w związku z tym mogą nie istnieć w jego rejestrach.

Uzyskiwanie dostępu

Aby korzystać z interfejsu Voided Purchases API, musisz mieć uprawnienia do wyświetlania informacji finansowych. Autoryzację możesz zapewnić za pomocą klienta OAuth lub konta usługi. Jeśli używasz konta usługi, włącz na nim 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 anulowanych zakupów

Aby poprosić o listę anulowanych zakupów, użyj metody GET. W żądaniu podaj w pełni kwalifikowaną nazwę pakietu aplikacji, np. com.google.android.apps.maps, oraz token autoryzacji, który został Ci przyznany 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

W prośbie możesz też uwzględnić te parametry (każdy z nich jest opcjonalny):

startTime

Czas w milisekundach od epoki systemu Unix, w którym nastąpił najstarszy anulowany zakup, który chcesz zobaczyć w odpowiedzi. Domyślnie wartość startTime jest ustawiona na 30 dni temu.

Interfejs API może wyświetlać tylko anulowane zakupy, które zostały dokonane w ciągu ostatnich 30 dni. Starsze anulowane zakupy nie są uwzględniane w odpowiedzi niezależnie od wartości podanej w przypadku parametru startTime.

Uwaga: unieważnione zakupy w odpowiedzi są filtrowane na podstawie czasu, w którym dany rekord jest uznawany przez interfejs API za unieważniony, a nie na podstawie wartości voidedTimeMillis zwracanej w odpowiedzi.

endTime

Czas (w milisekundach od epoki systemu Unix) najnowszego anulowanego zakupu, który chcesz zobaczyć w odpowiedzi. Domyślnie endTime jest ustawiona na bieżący czas.

Uwaga: unieważnione zakupy w odpowiedzi są filtrowane na podstawie czasu, w którym dany rekord jest uznawany za unieważniony przez interfejs API, a nie na podstawie wartości voidedTimeMillis zwracanej w odpowiedzi.

maxResults

Maksymalna liczba anulowanych zakupów, które pojawiają się w każdej odpowiedzi. Domyślnie ta wartość wynosi 1000. Pamiętaj, że maksymalna wartość tego parametru to również 1000.

token

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

typ

Rodzaj anulowanych zakupów, które pojawiają się w każdej odpowiedzi. Jeśli wartość jest ustawiona na 0, zwracane będą tylko anulowane zakupy w aplikacji. Jeśli wartość tego parametru to 1, zwracane będą zarówno anulowane zakupy w aplikacji, jak i anulowane subskrypcje. Wartość domyślna to 0.

Uwaga: zanim poprosisz o otrzymywanie informacji o anulowanych zakupach subskrypcji, musisz zacząć używać w odpowiedzi identyfikatora orderId, który jednoznacznie identyfikuje zakupy jednorazowe 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 za zamówienia z większą liczbą produktów, które mają zastosowanie tylko do zakupów z większą liczbą produktów. Jeśli true, można zwrócić dodatkowe anulowane zakupy z parametrem voidedQuantity, który wskazuje liczbę produktów objętych częściowym zwrotem środków. Wartością domyślną jest false.

Uwaga: gdy zwracana jest pozostała łączna liczba produktów z zakupu, odpowiedni anulowany zakup nie będzie miał symbolu voidedQuantity, który sygnalizuje, że zakup został w pełni zwrócony. Jeśli na przykład zakup 10 sztuk zostanie zwrócony 3 razy w ilościach 2, 3 i 5, będą 3 anulowane zakupy. Pierwsze 2 anulowane zakupy będą miały wartości voidedQuantity 2 i 3, a trzeci anulowany zakup nie będzie miał wartości voidedQuantity.

Odpowiedź to ciąg znaków JSON zawierający listę anulowanych zakupów. Jeśli wyników jest więcej 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 anulowany 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

Interfejs Voided Purchases API ma te 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.

Wytyczne dotyczące początkowych próśb

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

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

Sprawdzone metody

Uwaga: oprócz korzystania z tego interfejsu API deweloperzy powinni zintegrować go z powiadomieniami w czasie rzeczywistym dla deweloperów. Dzięki powiadomieniom w czasie rzeczywistym dla deweloperów otrzymujesz od Google powiadomienia o każdej zmianie uprawnień użytkownika w Twojej aplikacji, w tym o unieważnieniu zakupu.

Pamiętaj, że podczas korzystania z tego interfejsu API w aplikacji istnieje wiele powodów unieważnienia zakupu i nie ma jednego rozwiązania, które działałoby we wszystkich przypadkach. Podczas projektowania zasad i strategii wycofywania certyfikatów należy pamiętać o użytkownikach. Aby to zrobić, możesz zastosować te zalecane praktyki:

• Używaj tego interfejsu API jako jednego z wielu elementów kompleksowej strategii przeciwdziałania niepożądanym zachowaniom. Cofanie dostępu do produktów w aplikacji jest zwykle skuteczniejsze, gdy jest połączone z aplikacją, która ma rozsądne ceny zakupów w aplikacji, projekt aplikacji zniechęcający do niepożądanych zachowań, dużą bazę użytkowników, których kultura odrzuca takie zachowania, oraz responsywne i wydajne kanały obsługi klienta.
• Stosuj zasady wycofywania w jednolity sposób, aby zapewnić sprawiedliwość wszystkim użytkownikom.
• W przypadku niepożądanych zachowań rozważ utworzenie zasady etapowej. Na przykład zacznij od ostrzeżeń w aplikacji w przypadku pierwszych naruszeń, a następnie eskaluj swoje reakcje, jeśli niepożądane zachowanie użytkownika będzie się powtarzać. W ostateczności możesz całkowicie uniemożliwić użytkownikowi korzystanie z aplikacji.
• Gdy wprowadzisz zasady wycofania i za każdym razem, gdy je zaktualizujesz, poinformuj użytkowników o zmianach za pomocą kanałów komunikacji aplikacji. Daj użytkownikom czas na zapoznanie się ze zmianami, zanim zostaną one wprowadzone w aplikacji.
• Zachowaj przejrzystość wobec użytkowników i informuj ich o każdym podjętym działaniu, np. o cofnięciu dostępu do produktu w aplikacji. Użytkownicy powinni mieć możliwość kwestionowania Twoich decyzji, a takie spory powinny być rozpatrywane w sprawiedliwy sposób.
• Monitoruj formularze opinii i fora społeczności, aby dowiedzieć się, co skłania użytkowników do niepożądanych zachowań i jak to robią. Wykorzystuj te informacje jako pierwszą linię obrony.