> ## Documentation Index > Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Gestion des produits consommables à partir de votre service > Décrit comment créer un système robuste qui gère les consommables dans votre service de jeu, y compris la gestion des remboursements d'articles consommés demandés par les utilisateurs. Pour les économies basées sur les consommables, utilisez un service principal de confiance pour valider et gérer les transactions. Les appels de service à service sont plus sécuritaires et plus fiables que l'exécution gérée par le client, qui peut être affectée par la falsification ou par la perte de réseau. Cet article montre comment gérer les consommables et rapprocher les remboursements afin de réduire la fraude et les pertes de revenus. Pour gérer les produits consommables et traiter les remboursements, appelez les API du Microsoft Store suivantes à partir de votre service. Consultez les pages de documentation pour obtenir des précisions sur l'appel et l'analyse des résultats. | API du Microsoft Store | Fonction | | - | - | | [collections.mp.microsoft.com/v8.0/collections/consume](/fr-CA/reference/microsoft-store-apis/xstore-v8-consume) | Consommer ou exécuter un produit consommable que possède l'utilisateur. | | [purchase.mp.microsoft.com/v8.0/b2b/orders/query](/fr-CA/reference/microsoft-store-apis/xstore-v8-clawbackv1) | Bons de commande : signale les achats de consommables effectués par l'utilisateur au cours des 90 derniers jours. | | [purchase.mp.microsoft.com/v8.0/b2b/clawback/sastoken](/fr-CA/reference/microsoft-store-apis/xstore-v8-clawbackv2-sastoken) | Fournit un jeton SAS utilisé pour interroger la file de messages du service d'événements Clawback afin d'obtenir les événements de remboursement liés à vos produits. | **Limitation du sandbox :** lors de la consommation de produits consommables gérés par le développeur dans un sandbox de développement, seule l'authentification par jeton XSTS est prise en charge. L'authentification par User Store ID ou par Microsoft Entra ID ne fonctionne pas pour les appels de consommation de consommables gérés par le développeur dans les environnements sandbox. Planifiez vos tests en conséquence. Pour plus d'informations, consultez la [section Prérequis de l'API Consume](/fr-CA/reference/microsoft-store-apis/xstore-v8-consume#prerequisites). ## Utilisation de la bibliothèque .NET Microsoft.StoreServices et de l'exemple Pour illustrer les principes et les flux décrits dans cet article, consultez l'exemple Microsoft.StoreServices, qui fournit : * L'utilisation de la bibliothèque Microsoft.StoreServices pour gérer l'authentification et effectuer les appels aux services du Microsoft Store. * Un exemple de logique pour gérer les produits consommables, suivre les demandes de consommation en attente, rapprocher les achats remboursés, renouveler les User Store ID expirés, et plus encore. * Un guide de configuration qui comprend les étapes de cet article sur la façon de configurer et de mettre en place votre Microsoft Entra ID pour cette méthode d'authentification. * [Microsoft.StoreServices (GitHub)](https://github.com/microsoft/Microsoft-Store-Services) * [Exemple Microsoft.StoreServices (GitHub)](https://github.com/microsoft/Microsoft-Store-Services-Sample) ## Gestion des consommables ### Structure recommandée d'un service de gestion des consommables Utilisez un flux serveur unique pour valider la propriété, exécuter l'utilisation et rapprocher les remboursements. La structure suivante rend ces responsabilités explicites et sécuritaires en cas de nouvelle tentative. | Étape | Action du service | | - | - | | Réception des demandes | Recevoir les demandes des clients pour utiliser ou acheter des articles avec une monnaie consommable. | | Authentification | S'authentifier auprès des API des services du Microsoft Store. | | Vérification des soldes | Valider le solde de l'utilisateur pour les produits consommables du Store. | | Exécution | Consommer ou exécuter la quantité requise à partir du solde de l'utilisateur. | | Sécurité des nouvelles tentatives | Suivre les demandes de consommation en attente et réessayer de façon sécuritaire lorsque des réponses sont perdues. | | Octroi du solde | Octroyer le solde du produit acheté au compte de l'utilisateur. | | Journalisation des transactions | Tenir une base de données de suivi des transactions de consommation et d'octroi liées à l'utilisateur. | | Réponse au client | Retourner les résultats des transactions ou les articles octroyés au client de jeu. | | Rapprochement | Traiter les transactions de consommables remboursées et appliquer des mesures correctives. | ### Gestion du solde de l'utilisateur dans votre service par rapport au Microsoft Store Les produits consommables gérés par le Store peuvent être entièrement gérés dans votre service de jeu en consommant tout solde non nul dans le Microsoft Store. Le solde de consommables de l'utilisateur peut aussi être géré par le Microsoft Store, la quantité n'étant consommée que lorsqu'elle est utilisée pour des articles dans le jeu. Les produits consommables gérés par le développeur, en revanche, doivent être gérés dans un service de jeu. Consultez [Choisir le bon type de produit](/fr-CA/publishing/xstore-commerce/xstore-choosing-product-type) pour plus d'informations sur les consommables gérés par le développeur par rapport à ceux gérés par le Microsoft Store. L'approche la plus courante consiste à suivre le solde effectif de monnaie de l'utilisateur dans votre service. Dans cette conception, votre service interroge les soldes de consommables non nuls, les consomme et crédite l'équivalent en monnaie du jeu au compte de l'utilisateur. Ce flux réduit les appels répétés aux API du Store après l'exécution, simplifie la gestion multiplateforme des soldes et offre aux équipes de soutien un système central pour les ajustements de solde. Configuration typique : configurez chaque palier de monnaie comme un consommable distinct géré par le Store qui octroie une quantité de `1` par achat, puis associez chaque produit à sa valeur dans le jeu. Exemple : un consommable « 500 pièces » fait passer la quantité dans le Store à `1`; après la consommation, la quantité dans le Store revient à `0` et votre service crédite 500 pièces. Les consommables gérés par le Store peuvent octroyer la valeur complète directement à la quantité du Store lors de l'achat (par exemple, 500 par achat). Dans ce modèle, le Store suit la croissance du solde et votre service déduit la quantité lorsque les utilisateurs dépensent de la monnaie dans le jeu. Toutefois, placer tous les paliers comme SKU sous un même ID de produit limite certaines fonctionnalités, comme les prix promotionnels propres à un palier et les jetons d'échange 5x5. Consultez [Meilleures pratiques pour offrir de la monnaie dans le jeu](/fr-CA/publishing/xstore-commerce/xstore-consumables#best-practices-for-offering-in-game-currency). ### Utiliser les TrackingId comme système redondant de validation de la consommation Incluez un `TrackingId` dans chaque demande de consommation. Si une réponse est perdue, réessayez avec les mêmes `TrackingId`, utilisateur, `productId` et quantité pour confirmer si la consommation initiale a réussi. Cette nouvelle tentative empêche les doubles octrois tout en permettant des nouvelles tentatives sécuritaires. Le flux suivant présente un modèle de consommation sécuritaire en cas de nouvelle tentative. Le produit A (500 pièces dans le jeu) est un consommable configuré pour octroyer une quantité de 1 dans le Store. 1. L'utilisateur achète le produit A et possède maintenant une quantité de `1` pour le produit lors de l'appel au service de requête. 2. Le service du jeu interroge le solde de consommables de l'utilisateur au moyen de l'API de requête du Microsoft Store et constate que le solde de l'utilisateur est de `1`. 3. Le service du jeu génère un TrackingID, crée une demande de consommation pour consommer une unité du produit et ajoute les informations de la demande à une liste de transactions en attente. 4. Le service du jeu envoie la demande à l'API de consommation du Microsoft Store. 5. Le service du jeu ne reçoit pas de réponse de l'API de consommation (perte de paquets réseau, panne de service, panne de courant, etc.). À ce stade, le service ne peut pas confirmer si la transaction a été effectuée. Interroger uniquement l'inventaire peut être ambigu si l'utilisateur a racheté le produit pendant la panne. Utilisez la liste des transactions en attente et réessayez avec les mêmes valeurs de demande. 6. Le service du jeu détermine quand il doit réessayer la demande de consommation. 7. Le service du jeu recrée la demande de consommation avec les mêmes utilisateur, ProductId, TrackingId et quantité. 8. Le service du jeu envoie la demande à l'API de consommation du Microsoft Store. 9. Le service du jeu reçoit une réponse indiquant que la demande a réussi et que le nouveau solde de l'utilisateur est de « 0 ». 10. Le service du jeu ajoute 500 pièces au solde de monnaie de l'utilisateur suivi sur le serveur. 11. Le service du jeu retire la demande de consommation de la liste des transactions en attente, puisque l'article a été consommé et vérifié, et que l'utilisateur a reçu la bonne monnaie du jeu dans le service. ### Comportement de l'API Consume du Microsoft Store lors de la vérification de demandes de transaction antérieures Si une demande arrive avec des valeurs différentes, l'API la traite comme une nouvelle demande de consommation. Si l'API détecte une nouvelle tentative avec les mêmes `TrackingId`, utilisateur, quantité et `productId`, elle ne consomme pas une deuxième fois. Elle retourne plutôt une réponse réussie avec le solde restant actuel. Grâce à ce comportement, la relecture d'une demande ayant expiré est sécuritaire tant que les valeurs de la demande sont identiques. Si vous utilisez l'authentification X-Token pour l'API de consommation, vous pouvez mettre à jour et obtenir un nouveau X-Token, à condition que le nouveau X-Token concerne le même utilisateur XBOX que la demande précédente. ### Atténuer la fraude liée aux retours et aux remboursements de consommables à l'aide du service d'événements Clawback Pour aider à prévenir les abus et les retours ou remboursements frauduleux de produits consommables, votre service doit utiliser le service d'événements Clawback. Clawback permet à votre service de recevoir des événements lorsqu'un produit consommable est retourné ou remboursé. Votre service doit alors retirer la valeur ajoutée au compte de l'utilisateur pour ce consommable. Pour agir sur les événements Clawback, assurez-vous d'utiliser l'option `"includeOrderIds": TRUE` dans votre demande de consommation à [collections.mp.microsoft.com/v8.0/collections/consume](/fr-CA/reference/microsoft-store-apis/xstore-v8-consume). Votre service doit stocker les données des transactions de consommation provenant des réponses de l'API à l'aide des variables suivantes : | Variable | Source | Description | | - | - | - | | `Key / Unique ID` | \[OrderID]:\[LineItemID]:\[ProductID]:\[TrackingId] | Incluez `ProductID`, car les ensembles peuvent réutiliser les mêmes `OrderID` et `LineItemID` pour différents produits. Si votre consommable octroie une quantité supérieure à `1`, incluez `TrackingId` pour distinguer les opérations de consommation individuelles. | | `ProductId` | ProductId de la demande de consommation | Comme les mêmes orderID et orderLineItemID peuvent être partagés entre différents produits octroyés au moyen de l'achat d'un ensemble, vous devez aussi suivre le ProductID de l'article consommé. | | `UserId` | UserId utilisé par votre système pour identifier l'utilisateur qui reçoit la valeur du consommable | Les événements Clawback ne fournissent pas de userId; vous devez donc suivre l'utilisateur qui reçoit le contenu dans votre système pour pouvoir prendre des mesures de rapprochement. | | `OrderID` | orderTransactions -> orderId (lors de l'utilisation de "includeOrderIds": true dans la demande /consume) | ID du bon de commande de l'utilisateur utilisé pour exécuter tout ou partie de la demande de consommation. Exemple : ID lié à l'achat de l'ensemble du panier. | | `LineItemID` | orderTransactions -> orderLineItemId (lors de l'utilisation de "includeOrderIds": true dans la demande /consume) | ID représentant un produit unique dans le bon de commande de l'utilisateur utilisé pour exécuter la demande de consommation. Exemple : ID lié à un article unique du panier lors de l'achat. | | `Qty` | orderTransactions -> quantityConsumed (lors de l'utilisation de "includeOrderIds": true dans la demande /consume) | Quantité de la demande exécutée par cet OrderId / LineItemId précis. Remarque : devrait être 1 dans la configuration standard d'un consommable, mais peut être supérieure à 1 si votre consommable est configuré pour octroyer une quantité supérieure à 1 à chaque achat. | | `Status` | État actuel de la transaction de consommation dans votre système, pour votre propre suivi | Utile pour indiquer quand une transaction de consommation est rapprochée avec un événement Clawback. Nécessaire aussi pour les rétrofacturations et les annulations de rétrofacturation. Par exemple, si un article est révoqué à la suite du rapprochement d'un événement Chargeback, vous pouvez annuler l'action plus tard si un événement ChargebackReversal se produit. | Mettez en place cette base de données de suivi tôt, de préférence avant l'intégration à la file Clawback. Les données recueillies tôt vous donnent un historique des transactions pour le rapprochement futur et une base de référence propre pour mesurer les effets du traitement Clawback. Pour plus d'informations, consultez [Gestion des remboursements et des rétrofacturations à partir de votre service](/fr-CA/publishing/xstore-commerce/xstore-managing-refunds). ## Voir aussi [Vue d'ensemble du commerce](/fr-CA/publishing/xstore-commerce/xstore-commerce-overview) [Écosystèmes basés sur les consommables](/fr-CA/publishing/xstore-commerce/xstore-consumables) [Gestion des remboursements et des rétrofacturations à partir de votre service](/fr-CA/publishing/xstore-commerce/xstore-managing-refunds) [API de service du Microsoft Store](/fr-CA/reference/microsoft-store-apis/index) [Bibliothèque Microsoft.StoreServices (GitHub)](https://github.com/microsoft/Microsoft-Store-Services) [Exemple Microsoft.StoreServices (GitHub)](https://github.com/microsoft/Microsoft-Store-Services-Sample) ## Related topics - [XR-014 Données des joueurs et informations personnelles](/fr/publishing/certification/xr/xr-014.md) - [Guide de certification étape par étape](/fr-CA/publishing/game-publishing/concepts/certification/certification-guide.md) - [Guide des BVT de certification pour PC](/fr-CA/publishing/game-publishing/concepts/certification/certification-pc-bvt-guide.md) - [Guide des BVT de certification pour console](/fr-CA/publishing/game-publishing/concepts/certification/certification-console-bvt-guide.md) - [Intégration des partenaires XBOX : accès et publication](/fr/home/onboarding.md)