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 au cours des 90 derniers jours. Elle renvoie également des champs non disponibles dans une requête Collections, tels que ShortOrderID pour les workflows de support.

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 renvoyer aucun résultat.

Requête

Syntaxe de la requête

Méthode	URI de 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. Jeton d’accès au service Microsoft Entra ID au format `Bearer <token>`.
`Host`	`string`	Doit être défini sur la valeur `purchase.mp.microsoft.com`.
`Content-Length`	`number`	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`	ID d’achat utilisateur qui représente l’identité de l’utilisateur pour lequel vous effectuez la requête. Consultez Clé d’ID Store utilisateur.	Oui
`lineItemStateFilter`	`list<string>`	Spécifie les états d’élément à renvoyer dans les résultats de la requête. Pour obtenir la liste des valeurs valides, consultez États des lignes de commande.	Non
`sbx`	`string`	Valeur facultative pour l’authentification avec des UserStoreIds qui spécifie le sandbox auquel les résultats doivent être limités. Sans cette valeur, le sandbox RETAIL est utilisé par défaut. L’authentification X-Token n’a pas besoin de cette valeur, car le sandbox est spécifié dans le X-Token.	Non

États des lignes de commande

Valeur	Description
`Purchased`	Achat de consommable dans un état actif (valide). Cet état inclut les consommables traités et non traités.
`Revoked`	Achat de consommable traité ou consommé par le service de jeu, puis remboursé ultérieurement à l’utilisateur.
`Refunded`	Achat de consommable remboursé à l’utilisateur avant d’avoir été traité 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 de produits pour 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 au format long du numéro de commande de l’achat. OrderID utilisé par Collections et d’autres services.	Oui
`shortOrderId`	`GUID`	ID au format 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 les e-mails de confirmation. Les utilisateurs fournissent cet ID à votre équipe de support pour identifier leur achat.	Non
`orderLineItems`	`list<OrderLineItem>`	Tableau d’informations supplémentaires relatives 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 auxquelles le consommable a été acheté.	Oui
`orderRefundedDate`	`datetime`	Date et heure UTC auxquelles le consommable a été remboursé. Cette valeur met quelques heures à apparaître sur un élément remboursé.	Non

L’objet OrderLineItem contient les paramètres suivants.

Paramètre	Type	Description	Obligatoire
`lineItemId`	`GUID`	Identifie la ligne de commande (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 spécifique. Consultez États des lignes de commande.	Oui
`productId`	`string`	Également appelé ID Store du produit dans le catalogue du Microsoft Store. Exemple d’ID Store pour un produit : 9NBLGGH42CFD.	Oui
`quantity`	`number`	Quantité de l’élément lors de son achat dans la commande.	Oui
`skuId`	`string`	Identificateur de SKU spécifique si le produit comporte plusieurs offres dans le catalogue du Microsoft Store. Exemple d’ID Store pour une SKU : 0010.	Oui
`wasConsumableQuantityRevoked`	`bool`	Indique si la quantité achetée a pu être retirée du compte Store de l’utilisateur lors 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 quasiment en temps 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 Microsoft Store Utilisation de publisherQuery (Collections v9) pour interroger les produits et les droits 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 lignes de commande

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 lignes de commande

​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 lignes de commande

Exemple de requête

Réponse

Corps de la réponse

Exemple de réponse

Explication de l’exemple de réponse

Articles connexes