API acquisti annullati

L'API Google Play Voided Purchases fornisce un elenco di ordini associati ad acquisti annullati da un utente. Puoi utilizzare le informazioni di questo elenco per implementare un sistema di revoca che impedisca all'utente di accedere ai prodotti di questi ordini.

Questa API si applica agli ordini in-app una tantum e agli abbonamenti alle app.

Un acquisto può essere annullato nei seguenti modi:

  • L'utente richiede un rimborso per il suo ordine.
  • L'utente annulla l'ordine.
  • Un ordine viene stornato.
  • Lo sviluppatore annulla o rimborsa l'ordine.

  • Google annulla o rimborsa l'ordine.

Utilizzando questa API, contribuisci a creare un'esperienza più equilibrata ed equa per tutti gli utenti della tua app, in particolare se si tratta di un gioco.

Ottenere l'accesso

Per utilizzare l'API Voided Purchases, devi disporre dell'autorizzazione per visualizzare le informazioni finanziarie. Fornisci l'autorizzazione utilizzando un client OAuth o un service account. Se utilizzi un service account, attiva l'autorizzazione "Visualizza report finanziari" all'interno di questo account.

Per scoprire di più su come ottenere l'accesso autorizzato alle API Google Play Developer, consulta le seguenti guide:

Visualizzare gli acquisti annullati

Utilizza il metodo GET per richiedere un elenco degli acquisti annullati. Nella richiesta, includi il nome del pacchetto completo della tua app, ad esempio com.google.android.apps.maps, e il token di autorizzazione che hai ricevuto quando hai ottenuto l'accesso all'API.

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

Puoi anche includere i seguenti parametri nella richiesta, ognuno dei quali è facoltativo:

startTime

L'ora, in millisecondi dall'epoca Unix, del più vecchio acquisto annullato che vuoi visualizzare nella risposta. Per impostazione predefinita, startTime è impostato su 30 giorni fa.

L'API può mostrare solo gli acquisti annullati avvenuti negli ultimi 30 giorni. Gli acquisti annullati meno recenti non sono inclusi nella risposta, indipendentemente dal valore che hai fornito per startTime.

endTime

L'ora, in millisecondi dall'epoca di Unix, dell'ultimo acquisto annullato che vuoi visualizzare nella risposta. Per impostazione predefinita, endTime è impostato sull'ora corrente.

maxResults
Il numero massimo di acquisti annullati visualizzati in ogni risposta. Per impostazione predefinita, questo valore è 1000. Tieni presente che il valore massimo per questo parametro è anche 1000.
token
Un token di continuazione di una risposta precedente, che ti consente di visualizzare altri risultati.
tipo

Il tipo di acquisti annullati visualizzati in ogni risposta. Se impostato su 0, verranno restituiti solo gli acquisti in-app annullati. Se impostato su 1, verranno restituiti sia gli acquisti in-app annullati che gli acquisti di abbonamenti annullati. Il valore predefinito è 0.

includeQuantityBasedPartialRefund

Se includere gli acquisti annullati di rimborsi parziali basati sulla quantità, che sono applicabili solo agli acquisti di più quantità. Se true, potrebbero essere restituiti ulteriori acquisti annullati con voidedQuantity che indica la quantità rimborsata di un rimborso parziale basato sulla quantità. Il valore predefinito è false.

La risposta è una stringa JSON che contiene un elenco di acquisti annullati. Se i risultati sono più numerosi del numero specificato nel parametro di richiesta maxResults, la risposta include un valore nextPageToken, che puoi passare a una richiesta successiva per visualizzare altri risultati. Il primo risultato nell'elenco mostra l'acquisto annullato più vecchio.

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

Quote

L'API Acquisti annullati imposta le seguenti quote per pacchetto:

  • 6000 query al giorno. La giornata inizia e termina a mezzanotte del fuso orario del Pacifico.
  • 30 query in un periodo di 30 secondi.

Linee guida per le richieste iniziali

Durante la richiesta API iniziale, potresti voler recuperare tutti i dati disponibili per la tua app. Anche se improbabile, questo processo potrebbe esaurire la quota giornaliera. Per ottenere i dati sugli acquisti annullati in modo più sicuro e coerente, segui queste best practice:

  • Utilizza il valore predefinito per il parametro maxResults. In questo modo, se utilizzi l'intera quota di query per un giorno, puoi recuperare i dettagli di 6.000.000 di acquisti annullati.
  • Se una risposta include un valore per nextPageToken, assegna questo valore al parametro token durante la richiesta successiva.

Best practice

Quando utilizzi questa API nella tua app, ricorda che ci sono molti motivi per annullare un acquisto e che non esiste una soluzione unica che funzioni in tutti i casi. Quando progetti le tue norme e strategie di revoca, devi tenere conto dei tuoi utenti. Per farlo, puoi applicare queste pratiche consigliate:

  • Utilizza questa API come uno dei tanti elementi di una strategia completa per affrontare comportamenti indesiderati. La revoca dell'accesso ai prodotti in-app è in genere più efficace se combinata con un'app che offre prezzi ragionevoli per gli acquisti in-app, un design dell'app che scoraggia comportamenti indesiderati, una base utenti solida la cui cultura rifiuta tali comportamenti e canali di assistenza utenti reattivi ed efficienti.
  • Amministra le norme di revoca in modo uniforme per garantire l'equità per tutti gli utenti.
  • Quando affronti un comportamento indesiderato, valuta la possibilità di creare una policy a fasi. Ad esempio, inizia con avvisi in-app per le prime violazioni, poi aumenta le tue risposte man mano che il comportamento indesiderato di un utente continua. Come ultima risorsa, puoi impedire a un utente di interagire con la tua app.
  • Quando introduci una norma di revoca e ogni volta che la aggiorni, utilizza i canali di comunicazione della tua app per informare gli utenti delle modifiche. Dai ai tuoi utenti il tempo di comprendere chiaramente queste modifiche prima che entrino in vigore nella tua app.
  • Sii trasparente con i tuoi utenti e informali ogni volta che intraprendi un'azione, ad esempio la revoca dell'accesso a un prodotto in-app. Idealmente, gli utenti dovrebbero essere in grado di contestare le tue decisioni e queste contestazioni dovrebbero essere trattate in modo equo.
  • Monitora i moduli di feedback e i forum della community per capire cosa spinge gli utenti a comportarsi in modo indesiderato e come mettono in atto questo comportamento. Agisci in base a questi approfondimenti come prima linea di difesa.