Skip to main content
Les API Collections Query constituent le principal moyen pour les services de déterminer l’état de propriété et de droits d’un utilisateur. Par rapport aux API XStore côté client, les requêtes de service à service prennent en charge des scénarios plus larges au niveau de l’éditeur ainsi que des architectures de services centralisées. Les résultats des API Collections incluent uniquement les produits directement possédés par l’utilisateur cible ou sur lesquels il dispose directement d’un droit. Les droits partagés valides sur le client ne sont pas retournés dans les réponses de service à service. Pour plus d’informations sur les scénarios de partage, consultez Modèle de partage de produits pour les jeux. Cet article vous aide à comprendre les API Query et à les intégrer grâce aux sections suivantes :
Consultez les Prérequis pour les API de service à service. Si les produits ne sont pas correctement configurés pour votre type d’authentification, les appels peuvent réussir mais ne retourner aucun résultat.

​
Sélection de l’API Collections Query adaptée à vos besoins

Il existe deux versions de Collections Query : b2bLicensePreview (v8) et publisherQuery (v9). Dans la plupart des cas, utilisez publisherQuery, car ses paramètres de requête sont simplifiés et il prend en charge l’état XBOX Game Pass. Utilisez b2bLicensePreview lorsque vous avez besoin de comportements hérités, comme la prise en charge de LegacyProductId.
Bien qu’il n’existe pas d’URI v9 équivalent pour la fonctionnalité de consommation, vous pouvez utiliser publisherQuery et l’URI de consommation v8 ensemble sans problème.

​
Comprendre les droits satisfaisants dans la réponse

Un utilisateur peut disposer d’un droit sur un produit directement (achat/utilisation d’un code) ou indirectement (bundle/abonnement). Si le droit est indirect, le tableau satisfiedByProductIds contient le ou les ProductId dont provient le droit. Exemple : un utilisateur a acheté le bundle Deluxe Edition d’un jeu. L’appel des API Query affiche dans le résultat le produit du jeu ainsi que tous les produits inclus dans le bundle. Chacun de ces éléments contient le ProductID du bundle Deluxe Edition dans sa liste satisfiedByProductIds.

​
Comprendre les éléments en double dans la réponse

Vous pouvez voir plusieurs éléments avec le même ProductId/SKU lorsque les utilisateurs disposent de plusieurs sources de droits. Les différences apparaissent généralement dans des champs tels que acquisitionType, les dates et satisfiedByProductIds. Définissez excludeDuplicates sur true pour regrouper plusieurs sources de droits en un seul élément correspondant au droit de propriété le plus direct, dans l’ordre suivant :
  • Achat direct / utilisation d’un code
  • Satisfait par un bundle acheté directement
  • Satisfait par un abonnement
  • Satisfait par un achat promotionnel (par exemple : Games With Gold)
Si les doublons proviennent de la même source (par exemple, des périodes d’abonnement Active et Expired), un seul élément est retourné (même si excludeDuplicates est désactivé), selon la priorité d’état suivante :
  • Active
  • Invalid (en cas de plusieurs droits invalides, l’élément invalidé le plus récemment est retourné)
  • Revoked
Les scénarios de doublons courants et leurs résultats sont présentés dans le tableau suivant.

​
Exemple

Un utilisateur achète le jeu A et l’extension B, puis achète plus tard un Season Pass qui inclut également l’extension B. La réponse peut contenir deux entrées pour l’extension B : l’achat direct et le droit satisfait par le Season Pass. Si excludeDuplicates est true, seule l’entrée de l’achat direct est retournée.

​
Documentation de référence des API

​
Voir aussi

Vue d’ensemble du commerce Gérer les produits depuis vos services Référence de l’API XStore
Last modified on October 6, 2026