API acquisti annullati

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

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

Un acquisto può essere annullato nei seguenti modi:

• L'utente richiede il rimborso dell'ordine.
• L'utente annulla il suo ordine.
• Un ordine viene riaddebitato.

• Lo sviluppatore annulla o rimborsa l'ordine.

  Nota: solo gli ordini revocati verranno mostrati nell'API Voided Purchases. Se uno sviluppatore rimborsa un acquisto senza impostare l'opzione di revoca, l'ordine non verrà restituito dall'API.

• 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 l'app è un gioco.

Nota: a differenza di altre origini dati relative agli ordini, l'API Voided Purchases include gli acquisti che vengono riaddebitati dagli elaboratori dei pagamenti. Pertanto, potresti notare incoerenze tra le informazioni di questa API e quelle di altre origini dati relative agli ordini.

Nota: l'API Voided Purchases restituisce gli acquisti annullati solo quando devono essere revocati. Gli sviluppatori possono usare questa API per indicare quando intraprendere ulteriori azioni da parte loro.

Ottenere l'accesso

Per utilizzare l'API Voided Purchases, devi disporre dell'autorizzazione per visualizzare le informazioni finanziarie. Puoi fornire l'autorizzazione utilizzando un client OAuth o un account di servizio. Se utilizzi un account di servizio, abilita l'autorizzazione "Visualizza rapporti finanziari" in questo account.

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

• Configurazione dei client di accesso API
• Aggiungere utenti all'account sviluppatore e gestire le autorizzazioni

Visualizzazione degli acquisti annullati

Utilizza il metodo GET per richiedere un elenco degli acquisti annullati. Nella richiesta, includi il nome completo del pacchetto 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

Nella richiesta puoi anche includere i seguenti parametri, ognuno dei quali è facoltativo:

startTime

Il tempo, in millisecondi dall'epoca Unix, dell'acquisto annullato meno recente che vuoi visualizzare nella risposta. Per impostazione predefinita, startTime è impostato su 30 giorni fa.

L'API può mostrare solo gli acquisti annullati che sono stati effettuati negli ultimi 30 giorni. Gli acquisti precedenti annullati non sono inclusi nella risposta, a prescindere dal valore che hai fornito per startTime.

Nota: gli acquisti annullati all'interno della risposta vengono filtrati in base al momento in cui un determinato record viene considerato come annullato dall'API, non dal valore di voidedTimeMillis restituito nella risposta.

endTime

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

Nota: gli acquisti annullati all'interno della risposta vengono filtrati in base al momento in cui un determinato record viene considerato come annullato dall'API, non in base al valore di voidedTimeMillis restituito nella risposta.

maxResults

Il numero massimo di acquisti annullati che appaiono in ogni risposta. Per impostazione predefinita, questo valore è 1000. Tieni presente che anche il valore massimo di questo parametro è 1000.

token

Un token di continuazione di una risposta precedente, che consente di visualizzare più risultati.

digita

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

Nota: prima di richiedere di ricevere acquisti di abbonamenti annullati, devi passare a utilizzare orderId nella risposta che identifica in modo univoco gli acquisti una tantum e gli abbonamenti. In caso contrario, riceverai più ordini di abbonamento con lo stesso PurchaseToken.

La risposta è una stringa JSON che contiene un elenco di acquisti annullati. Se sono presenti più risultati rispetto al 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 meno recente.

{
  "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 Voided Purchases 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 iniziale dell'API, potresti voler recuperare tutti i dati disponibili per la tua app. Anche se è improbabile, questo processo potrebbe esaurire la tua quota giornaliera. Per ottenere i dati sugli acquisti annullati in un 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 acquisti annullati.
• Se una risposta include un valore per nextPageToken, assegna questo valore al parametro token alla prossima richiesta.

Best practice

Nota: oltre a utilizzare questa API, gli sviluppatori dovrebbero integrare le Notifiche in tempo reale per lo sviluppatore (RTDN). Con RTDN, ricevi notifiche da Google ogni volta che viene apportata una modifica al diritto di un utente all'interno della tua app, incluso quando un utente annulla un acquisto.

Quando utilizzi questa API nella tua app, ricorda che ci sono molti motivi per annullare un acquisto e che non esiste un'unica soluzione che funzioni in tutti i casi. È necessario tenere presenti gli utenti quando si progettano le strategie e i criteri di revoca. Per farlo, puoi applicare queste pratiche consigliate:

• Utilizza questa API come uno dei numerosi elementi in una strategia completa per risolvere i comportamenti indesiderati. La revoca dell'accesso ai prodotti in-app di solito è più efficace se abbinata a un'app che ha prezzi ragionevoli per gli acquisti in-app, a un design dell'app che scoraggia comportamenti indesiderati, a una solida base utenti la cui cultura rifiuta tali comportamenti e a canali di assistenza utenti reattivi ed efficienti.
• Amministrare in modo uniforme i criteri di revoca per garantire l'equità a tutti gli utenti.
• Valuta la possibilità di creare un criterio temporaneo per risolvere i comportamenti indesiderati. Ad esempio, inizia con gli avvisi in-app per le infrazioni iniziali, quindi riassegna le tue risposte man mano che continua il comportamento indesiderato di un utente. Come ultima alternativa possibile, puoi impedire a un utente di interagire con la tua app.
• Quando introduci una norma sulla revoca e ogni volta che la aggiorni, utilizza i canali di promozione della tua app per informare gli utenti delle modifiche. Concedi agli utenti il tempo per comprendere chiaramente queste modifiche prima che vengano applicate nella tua app.
• Sii trasparente con i tuoi utenti e informali ogni volta che intervieni, 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 controversie devono essere trattate in modo equo.
• Monitora i moduli di feedback e i forum della community per capire cosa spinge gli utenti a comportarsi in modi indesiderati e come adottano questo comportamento. Agire su queste informazioni come prima linea di difesa.