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 ne sera 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 aux autres sources de données liées aux commandes, l'API Voided Purchases inclut les achats qui ont fait l'objet d'une rétrofacturation par les processeurs de paiement. Par conséquent, vous pouvez constater 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 les achats annulés que lorsqu'ils doivent être révoqués. Les développeurs peuvent utiliser cette API pour savoir quand prendre des mesures supplémentaires de leur côté. Toutefois, certains achats peuvent être remboursés au motif qu'ils n'ont jamais été confirmés par le développeur et qu'ils n'existent donc peut-être pas dans ses registres.

Obtenir l'accès

Pour utiliser l'API Voided Purchases, vous devez être autorisé à afficher les informations financières. Vous fournissez une 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 savoir comment obtenir 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 demande, 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 lorsque vous avez obtenu 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 facultatifs suivants dans votre requête :

startTime

Heure (en millisecondes depuis l'époque Unix) de l'achat annulé le plus ancien que vous souhaitez voir dans la réponse. Par défaut, startTime est défini sur "30 jours".

L'API ne peut afficher que les achats annulés au cours des 30 derniers jours. Les anciens achats annulés 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 voidedTimeMillis renvoyée dans la réponse.

endTime

Heure, en millisecondes depuis l'époque Unix, de l'achat annulé le plus récent 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 en fonction de la valeur voidedTimeMillis renvoyée dans la réponse.

maxResults

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

jeton

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

type

Type d'achats annulés qui s'affichent dans chaque réponse. Si la valeur est définie sur 0, seules les achats via l'application annulés seront renvoyés. Si la valeur est définie sur 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'abonnement annulés, vous devez passer à l'utilisation de orderId dans la réponse, qui identifie de manière unique les achats ponctuels et les abonnements. Sinon, vous recevrez plusieurs commandes d'abonnement avec le même PurchaseToken.

includeQuantityBasedPartialRefund

Indique si les achats annulés de remboursements partiels basés sur la quantité doivent être inclus. Ces remboursements ne s'appliquent qu'aux achats de quantités multiples. Si true, d'autres achats annulés peuvent être renvoyés avec voidedQuantity, ce qui indique la quantité remboursée d'un remboursement partiel basé sur la quantité. La valeur par défaut est false.

Remarque : Lorsque la quantité totale restante d'un achat est remboursée, l'achat annulé correspondant n'est pas associé à voidedQuantity, ce qui indique que l'achat a été intégralement remboursé. Par exemple, si un achat de quantité 10 est remboursé trois fois avec des quantités de 2, 3 et 5, trois achats seront annulés. Les deux premiers achats annulés auront un voidedQuantity de 2 et 3, tandis que le troisième achat annulé n'aura pas de voidedQuantity.

La réponse est une chaîne JSON qui contient la liste des achats annulés. Si le nombre de résultats est supérieur à celui 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 correspond à l'achat annulé le plus ancien.

{
  "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. (La 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 première requête API, vous pouvez récupérer toutes les données disponibles pour votre application. Bien que cela soit peu probable, ce processus peut épuiser votre quota quotidien. Pour obtenir des 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 pour le paramètre maxResults. Ainsi, si vous utilisez l'intégralité de votre quota de requêtes pour 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 s'intégrer aux notifications en temps réel pour les développeurs (RTDN). Grâce aux RTDN, vous recevez des notifications de Google chaque fois qu'un droit d'un utilisateur dans votre application est modifié, y compris lorsqu'un utilisateur annule un achat.

Lorsque vous utilisez cette API dans votre application, n'oubliez pas qu'un achat peut être annulé pour de nombreuses raisons et qu'aucune solution ne fonctionne dans tous les cas. Lorsque vous élaborez des règles et des stratégies de révocation, pensez aux utilisateurs. Pour ce faire, vous pouvez appliquer les bonnes pratiques suivantes :

• Utilisez cette API comme l'un des nombreux éléments d'une stratégie globale visant à résoudre les problèmes de comportement indésirable. La révocation de l'accès aux produits intégrés est généralement plus efficace lorsqu'elle est combiné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 base d'utilisateurs solide dont la culture rejette de tels comportements, et à des canaux d'assistance utilisateur réactifs et efficaces.
• Appliquez votre règlement sur la révocation de manière uniforme pour garantir l'équité pour tous les utilisateurs.
• En cas de comportement indésirable, envisagez de créer une règle par étapes. Par exemple, commencez par des avertissements dans l'application pour les premières infractions, puis intensifiez vos réponses si le comportement indésirable d'un utilisateur persiste. En dernier recours, vous pouvez empêcher un utilisateur d'interagir avec votre application.
• Lorsque vous mettez en place une règle de révocation et chaque fois que vous la modifiez, utilisez les canaux de communication de votre application pour informer vos utilisateurs des changements. Laissez à vos utilisateurs le temps de bien comprendre ces changements avant qu'ils ne prennent effet dans votre application.
• Soyez transparent avec vos utilisateurs et informez-les chaque fois que vous prenez une mesure, par exemple en révoquant leur accès à un produit intégré. Idéalement, les utilisateurs devraient pouvoir contester vos décisions, et ces contestations devraient être traitées de manière équitable.
• Surveillez les formulaires de commentaires et les forums de la communauté pour comprendre ce qui pousse les utilisateurs à adopter des comportements indésirables et comment ils s'y prennent. Utilisez ces insights comme première ligne de défense.