purchase.mp.microsoft.com/v8.0/b2b/orders/query

Cette API est dépréciée pour la détection des remboursements. Utilisez plutôt le service d’événements Clawback, comme décrit dans Gestion des remboursements et des rétrofacturations à partir de votre service.

L’API purchase.mp.microsoft.com/v8.0/b2b/orders/query permet à un service de jeu d’interroger les achats de consommables d’un utilisateur des 90 derniers jours. Elle retourne également des champs non disponibles dans une requête Collections, comme ShortOrderID, pour les flux de travail de soutien.

Prérequis

Consultez Prérequis pour les API de service à service. Cette API prend uniquement en charge le type d’authentification Microsoft Entra ID. Si la configuration du produit n’est pas publiée dans Partner Center, l’API peut réussir, mais ne retourner aucun résultat.

Requête

Syntaxe de la requête

Méthode	URI de la requête
`POST`	`https://purchase.mp.microsoft.com/v8.0/b2b/orders/query`

En-tête de la requête

En-tête	Type	Description
`Authorization`	`string`	Obligatoire. Le jeton d’accès de service Microsoft Entra ID sous la forme `Bearer <token>`.
`Host`	`string`	Doit être défini sur la valeur `purchase.mp.microsoft.com`.
`Content-Length`	`number`	La longueur du corps de la requête.
`Content-Type`	`string`	Spécifie le type de la requête et de la réponse. Actuellement, la seule valeur prise en charge est `application/json`.

Corps de la requête

Paramètre	Type	Description	Obligatoire
`b2bKey`	`string`	L’ID d’achat de l’utilisateur (User Purchase ID) qui représente l’identité de l’utilisateur pour lequel vous effectuez la requête. Consultez Clé User Store ID.	Oui
`lineItemStateFilter`	`list<string>`	Spécifie les états d’article à retourner dans les résultats de la requête. Pour obtenir la liste des valeurs valides, consultez États des articles de ligne.	Non
`sbx`	`string`	Valeur facultative pour l’authentification avec des UserStoreIds qui spécifie le bac à sable auquel les résultats doivent être limités. Sans cette valeur, le bac à sable RETAIL est utilisé par défaut. L’authentification X-Token n’a pas besoin de cette valeur, car le bac à sable est spécifié dans le X-Token.	Non

États des articles de ligne

Valeur	Description
`Purchased`	Achat de consommable dans un état actif (valide). Cet état inclut les consommables exécutés et non exécutés.
`Revoked`	Achat de consommable exécuté ou consommé par le service de jeu, puis remboursé à l’utilisateur.
`Refunded`	Achat de consommable remboursé à l’utilisateur avant d’avoir été exécuté ou consommé.

Exemple de requête

POST https://purchase.mp.microsoft.com/v8.0/b2b/orders/query HTTP/1.1
Host: purchase.mp.microsoft.com
Authorization: Bearer [Microsoft Entra bearer token]
User-Agent: MicrosoftStoreServiceSample_1.21.9.0
Content-Type: application/json; charset=utf-8
Content-Length: 2032

{
  "b2bKey":"[UserPurchaseId]",
  "lineItemStateFilter": [
    "Purchased",
    "Revoked",
    "Refunded"],
  "sbx": "XDKS.1"
}

Réponse

Corps de la réponse

Paramètre	Type	Description	Obligatoire
`items`	`list<PurchasedItem>`	Tableau des produits de l’utilisateur spécifié. Pour plus d’informations, consultez le tableau suivant.	Oui

L’objet PurchasedItem contient les paramètres suivants.

Paramètre	Type	Description	Obligatoire
`orderId`	`GUID`	ID long du numéro de commande de l’achat. OrderID utilisé par Collections et d’autres services.	Oui
`shortOrderId`	`GUID`	ID court du numéro de commande de l’achat. Numéro de commande que l’utilisateur final voit dans son historique d’achats et dans ses courriels de confirmation. Les utilisateurs fournissent cet ID à votre personnel de soutien pour désigner leur achat.	Non
`orderLineItems`	`list<OrderLineItem>`	Tableau d’informations supplémentaires liées au consommable dans l’OrderId d’achat de l’utilisateur. Pour plus d’informations, consultez le tableau suivant.	Oui
`orderPurchasedDate`	`datetime`	Date et heure UTC de l’achat du consommable.	Oui
`orderRefundedDate`	`datetime`	Date et heure UTC du remboursement du consommable. Cette valeur prend quelques heures à apparaître sur un article remboursé.	Non

L’objet OrderLineItem contient les paramètres suivants.

Paramètre	Type	Description	Obligatoire
`lineItemId`	`GUID`	Identifie le lineItem dans le bon de commande du consommable (les commandes peuvent comporter plusieurs lineItemIds dans les scénarios de panier d’achat)	Oui
`lineItemState`	`string`	État de cet achat de consommable particulier. Consultez États des articles de ligne.	Oui
`productId`	`string`	Également appelé Store ID du produit dans le catalogue du Microsoft Store. Un exemple de Store ID de produit est 9NBLGGH42CFD.	Oui
`quantity`	`number`	Quantité de l’article au moment de l’achat dans la commande.	Oui
`skuId`	`string`	Identificateur de SKU particulier s’il existe plusieurs offres du produit dans le catalogue du Microsoft Store. Un exemple de Store ID de SKU est 0010.	Oui
`wasConsumableQuantityRevoked`	`bool`	Indique si la quantité achetée a pu être retirée du compte Store de l’utilisateur au moment du remboursement.	Non

Exemple de réponse

HTTP/1.1 200 OK
Content-Length: 1042
Content-Type: application/json
MS-CorrelationId: b5157f23-7f26-4e0b-8f06-07733bd09355
MS-RequestId: 2b0933bc-19f7-4f96-bb47-2602491fed1f
MS-CV: OAIoYIzDJkO2Knp.7
MS-ServerId: 1
Date: Tue, 30 Jun 2020 18:29:22 GMT
 
{
    "items": [
        {
            "orderId": "3c1ad7bc-b0c2-442c-aad4-46d8d0e0184e",
            "shortOrderId": "8483143756",
            "orderLineItems": [
                {
                    "lineItemId": "febdd51b-97aa-45fc-bf46-0120eacbf8aa",
                    "lineItemState": "Purchased",
                    "productId": "9MT5TGW893HV",
                    "quantity": 1,
                    "skuId": "0010",
                    "wasConsumableQuantityRevoked": false
                }
            ],
            "orderPurchasedDate": "2021-06-12T23:57:51.1415104+00:00"
        },
        {
            "orderId": "75bf81ec-7c31-46f9-9828-6ac61464e553",
            "shortOrderId": "3145294485",
            "orderLineItems": [
                {
                    "lineItemId": "ad7adfc5-be76-4548-aede-155084490044",
                    "lineItemState": "Purchased",
                    "productId": "9MT5TGW893HV",
                    "quantity": 1,
                    "skuId": "0010",
                    "wasConsumableQuantityRevoked": false
                }
            ],
            "orderPurchasedDate": "2021-06-13T23:57:51.1415104+00:00"
        },
        {
            "orderId": "b9d6d1fd-3e68-423b-85fa-feea1ee125b3",
            "shortOrderId": "7620137155",
            "orderLineItems": [
                {
                    "lineItemId": "eb565041-6e1f-4210-97a3-54a2ab80f49e",
                    "lineItemState": "Revoked",
                    "productId": "9MT5TGW893HV",
                    "quantity": 1,
                    "skuId": "0010",
                    "wasConsumableQuantityRevoked": false
                }
            ],
            "orderPurchasedDate": "2021-06-142T23:57:51.1415104+00:00",
            "orderRefundedDate": "2021-06-162T10:05:35.9634676+00:00"
        },
        {
            "orderId": "cda65a53-30b0-4e19-8ec1-c08219174e45",
            "shortOrderId": "5993204763",
            "orderLineItems": [
                {
                    "lineItemId": "a30b4285-c456-4486-8048-a9f5b5231b76",
                    "lineItemState": "Revoked",
                    "productId": "9MT5TGW893HV",
                    "quantity": 1,
                    "skuId": "0010",
                    "wasConsumableQuantityRevoked": false
                }
            ],
            "orderPurchasedDate": "2021-06-152T23:57:51.1415104+00:00",
            "orderRefundedDate": "2021-06-162T10:05:35.9634676+00:00"
        },
        {
            "orderId": "f1da6d12-8b0d-4dc1-8aca-c52fcece582a",
            "shortOrderId": "8768763421",
            "orderLineItems": [
                {
                    "lineItemId": "7da73274-b4bc-4a4f-bb93-e49618f7a7d7",
                    "lineItemState": "Purchased",
                    "productId": "9MT5TGW893HV",
                    "quantity": 1,
                    "skuId": "0010",
                    "wasConsumableQuantityRevoked": false
                }
            ],
            "orderPurchasedDate": "2021-06-16T23:57:51.1415104+00:00"
        }
    ]
}

Explication de l’exemple de réponse

Dans cet exemple, l’utilisateur a acheté le consommable 9MT5TGW893HV cinq fois. Deux achats sont à l’état Revoked, ce qui signifie qu’ils ont été remboursés après avoir été consommés. Pour une détection des remboursements en temps quasi réel, utilisez le flux d’événements Clawback décrit dans Gestion des remboursements et des rétrofacturations à partir de votre service.

Articles connexes

Gestion des produits consommables à partir de votre service Gestion des remboursements et des rétrofacturations à partir de votre service Gérer les produits à partir de vos services Authentification de votre service avec les API du Microsoft Store Utilisation de publisherQuery (Collections v9) pour interroger les produits et les droits d’utilisation d’un utilisateur

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

purchase.mp.microsoft.com/v8.0/b2b/orders/query

purchase.mp.microsoft.com/v8.0/b2b/orders/query

Prérequis

Requête

Syntaxe de la requête

En-tête de la requête

Corps de la requête

États des articles de ligne

Exemple de requête

Réponse

Corps de la réponse

Exemple de réponse

Explication de l’exemple de réponse

Articles connexes

​purchase.mp.microsoft.com/v8.0/b2b/orders/query

​Prérequis

​Requête

​Syntaxe de la requête

​En-tête de la requête

​Corps de la requête

​États des articles de ligne

​Exemple de requête

​Réponse

​Corps de la réponse

​Exemple de réponse

​Explication de l’exemple de réponse

​Articles connexes

purchase.mp.microsoft.com/v8.0/b2b/orders/query

Prérequis

Requête

Syntaxe de la requête

En-tête de la requête

Corps de la requête

États des articles de ligne

Exemple de requête

Réponse

Corps de la réponse

Exemple de réponse

Explication de l’exemple de réponse

Articles connexes