API Voided Purchases

L'API Voided Purchases de Google Play fournit la liste des commandes associées aux achats qu'un utilisateur a annulés. Vous pouvez utiliser les informations de cette liste pour implémenter un système de révocation qui empêche l'utilisateur d'accéder aux produits de ces commandes.

Cette API s'applique aux commandes et abonnements ponctuels effectués via une application.

Un achat peut être annulé pour les raisons suivantes :

• L'utilisateur demande le remboursement de sa commande.
• L'utilisateur annule sa commande.
• Une commande est rejetée.

• Le développeur annule ou rembourse la commande.

  Remarque :Seules les commandes annulées seront affichées dans l'API Voided Purchases. Si un développeur rembourse un achat sans définir l'option de révocation, la commande n'est pas renvoyée par l'API.

• Google annule ou rembourse la commande.

En utilisant cette API, vous contribuez à créer une expérience plus équilibrée et équitable pour tous les utilisateurs de votre application, en particulier s'il s'agit d'un jeu.

Remarque :Contrairement à d'autres sources de données liées aux commandes, l'API Voided Purchases inclut les achats facturés par les sociétés de traitement des paiements. Par conséquent, il se peut que vous constatiez des incohérences entre les informations de cette API et celles d'autres sources de données liées aux commandes.

Remarque :L'API Voided Purchases ne renvoie des achats annulés que lorsqu'ils doivent être révoqués. Les développeurs peuvent utiliser cette API pour indiquer quand ils doivent prendre des mesures supplémentaires.

Obtenir l'accès

Pour utiliser l'API Voided Purchases, vous devez être autorisé à consulter les informations financières. Vous accordez l'autorisation à l'aide d'un client OAuth ou d'un compte de service. Si vous utilisez un compte de service, activez l'autorisation "Afficher les rapports financiers" dans ce compte.

Pour en savoir plus sur l'obtention d'un accès autorisé aux API Google Play Developer, consultez les guides suivants:

• Configurer les clients d'accès à l'API
• Ajouter des utilisateurs à un compte de développeur et gérer les autorisations

Afficher les achats annulés

Utilisez la méthode GET pour demander la liste des achats annulés. Dans votre requête, incluez le nom de package complet de votre application (par exemple, com.google.android.apps.maps) et le jeton d'autorisation que vous avez reçu lors de l'accès à l'API.

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

Vous pouvez également inclure les paramètres suivants dans votre requête, chacun étant facultatif:

startTime

Durée, en millisecondes écoulées depuis l'epoch Unix, du plus ancien achat annulé que vous souhaitez voir dans la réponse. Par défaut, startTime est défini sur il y a 30 jours.

L'API ne peut afficher que les achats annulés qui ont eu lieu au cours des 30 derniers jours. Les achats annulés plus anciens ne sont pas inclus dans la réponse, quelle que soit la valeur que vous avez fournie pour startTime.

Remarque:Les achats annulés dans la réponse sont filtrés en fonction de l'heure à laquelle un enregistrement donné est considéré comme annulé par l'API, et non en fonction de la valeur de voidedTimeMillis renvoyée dans la réponse.

endTime

Durée, en millisecondes écoulées depuis l'epoch Unix, du dernier achat annulé que vous souhaitez voir dans la réponse. Par défaut, endTime est défini sur l'heure actuelle.

Remarque:Les achats annulés dans la réponse sont filtrés en fonction de l'heure à laquelle un enregistrement donné est considéré comme annulé par l'API, et non selon la valeur de voidedTimeMillis renvoyée dans la réponse.

maxResults

Nombre maximal d'achats annulés qui apparaissent dans chaque réponse. Par défaut, cette valeur est de 1 000. Notez que la valeur maximale de ce paramètre est également 1 000.

jeton

Jeton de continuation d'une réponse précédente, ce qui vous permet d'afficher plus de résultats.

type

Type d'achats annulés qui apparaissent dans chaque réponse. Si la valeur est 0, seuls les achats via une application annulés sont renvoyés. Si la valeur est 1, les achats via une application et les abonnements annulés sont renvoyés. La valeur par défaut est 0.

Remarque:Avant de demander à recevoir les achats d'abonnements annulés, vous devez utiliser "orderId" dans la réponse, qui identifie de manière unique les achats et abonnements ponctuels. Sinon, vous recevrez plusieurs commandes d'abonnement avec le même purchaseToken.

La réponse est une chaîne JSON qui contient une liste des achats annulés. Si le nombre de résultats dépasse le nombre spécifié dans le paramètre de requête maxResults, la réponse inclut une valeur nextPageToken, que vous pouvez transmettre dans une requête ultérieure pour afficher plus de résultats. Le premier résultat de la liste indique le plus ancien achat annulé.

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

Quotas

L'API Voided Purchases définit les quotas suivants par package:

• 6 000 requêtes par jour. (Une journée commence et se termine à minuit, heure du Pacifique.)
• 30 requêtes sur une période de 30 secondes.

Consignes pour les demandes initiales

Lors de votre requête API initiale, vous pouvez récupérer toutes les données disponibles pour votre application. Bien que peu probable, ce processus risque d'épuiser votre quota quotidien. Pour obtenir les données sur les achats annulés de manière plus sûre et plus cohérente, suivez ces bonnes pratiques:

• Utilisez la valeur par défaut du paramètre maxResults. Ainsi, si vous utilisez l'intégralité de votre quota de requêtes pendant une journée, vous pouvez récupérer les détails de 6 000 000 d'achats annulés.
• Si une réponse inclut une valeur pour nextPageToken, attribuez cette valeur au paramètre token lors de votre prochaine requête.

Bonnes pratiques

Remarque :En plus d'utiliser cette API, les développeurs doivent intégrer les notifications en temps réel pour les développeurs (RTDN). Avec les notifications RTDN, vous recevez des notifications de Google en cas de modification des droits d'accès d'un utilisateur dans votre application, y compris lorsqu'un utilisateur annule un achat.

Lorsque vous utilisez cette API dans votre application, n'oubliez pas qu'il existe de nombreuses raisons d'annuler un achat et qu'il n'existe pas de solution unique qui fonctionne dans tous les cas. Vous devez garder vos utilisateurs à l'esprit lorsque vous concevez vos politiques et stratégies de révocation. Pour ce faire, vous pouvez appliquer les pratiques recommandées suivantes:

• Utilisez cette API comme l'un des nombreux éléments d'une stratégie complète permettant de remédier aux comportements indésirables. Révoquer l'accès aux produits intégrés est généralement plus efficace lorsqu'elle est associée à une application proposant des prix raisonnables pour les achats via l'application, une conception d'application qui décourage les comportements indésirables, une forte base d'utilisateurs dont la culture rejette un tel comportement, et des canaux d'assistance utilisateur réactifs et efficaces.
• Administrer votre règle de révocation de manière uniforme pour assurer l'impartialité de tous les utilisateurs.
• Envisagez de créer une règle par étapes pour traiter les comportements indésirables. Par exemple, commencez par des avertissements dans l'application pour les infractions précoces, puis escaladez vos réponses lorsque le comportement indésirable d'un utilisateur se poursuit. En dernier recours, vous pouvez empêcher un utilisateur d'interagir avec votre application.
• Lorsque vous introduisez une règle de révocation et que vous la mettez à jour, utilisez les canaux de communication de votre application pour informer les utilisateurs des modifications. Donnez à vos utilisateurs le temps de comprendre clairement ces modifications avant qu'elles ne prennent effet dans votre application.
• Soyez transparent avec vos utilisateurs et informez-les chaque fois que vous prenez des mesures, comme révoquer leur accès à un produit intégré. Idéalement, les utilisateurs doivent pouvoir contester vos décisions. Ces contestations doivent être traitées de manière équitable.
• Surveillez les formulaires de commentaires et les forums communautaires pour comprendre ce qui incite les utilisateurs à se comporter de manière indésirable et comment ils s'y prennent. Agissez sur ces informations comme une première ligne de défense.