purchase.mp.microsoft.com/v8.0/purchases/grant

Utilisez l’API d’achat du Microsoft Store pour accorder une application ou un module complémentaire gratuit au compte d’un utilisateur. Seuls les produits gratuits peuvent être accordés directement au compte d’un utilisateur. Les tentatives d’octroi de produits payants retournent une erreur.

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, les appels peuvent 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/v7.0/purchases/grant`

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` <jeton>.
`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
`availabilityId`	`string`	L’ID de disponibilité du produit à accorder à partir du catalogue du Microsoft Store.	Oui
`b2bKey`	`string`	La clé User Store ID qui représente l’identité de l’utilisateur auquel vous souhaitez accorder un produit.	Oui
`devOfferId`	`string`	Un ID d’offre spécifié par le développeur qui apparaît dans l’article de la collection après l’achat.	Non
`language`	`string`	La langue de l’utilisateur.	Oui
`market`	`string`	Le marché de l’utilisateur.	Oui
`orderId`	`GUID`	Un GUID généré pour la commande. Cette valeur est unique pour l’utilisateur, mais elle n’a pas besoin d’être unique parmi toutes les commandes.	Oui
`productId`	`string`	Le Store ID du produit dans le catalogue du Microsoft Store. Un exemple de Store ID de produit est 9NBLGGH42CFD.	Oui
`quantity`	`int`	La quantité à acheter. Actuellement, la seule valeur prise en charge est 1. Si elle n’est pas spécifiée, la valeur par défaut est 1.	Non
`skuId`	`string`	Le Store ID de la SKU du produit dans le catalogue du Microsoft Store. Un exemple de Store ID de SKU est 0010.	Oui
`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

Exemple de requête

POST https://purchase.mp.microsoft.com/v7.0/purchases/grant HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJK...
Content-Length: 1863
Content-Type: application/json

{
    "b2bKey" : "eyJ0eXAiOiJK...",
    "availabilityId" : "9RT7C09D5J3W",
    "productId" : "9NBLGGH5WVP6",
    "skuId" : "0010",
    "language" : "en-us",
    "market" : "us",
    "orderId" : "3eea1529-611e-4aee-915c-345494e4ee76",
    "sbx" : "XDKS.1"
}

Réponse

Corps de la réponse

Paramètre	Type	Description	Obligatoire
`clientContext`	`ClientContextV8`	Les informations contextuelles du client pour la commande. Attribué à la valeur `clientID` du jeton Microsoft Entra ID.	Oui
`createdtime`	`datetimeoffset`	L’heure à laquelle la commande a été créée.	Oui
`currencyCode`	`string`	Le code de devise pour `totalAmount` et `totalTaxAmount`. Sans objet pour les articles gratuits.	Oui
`friendlyName`	`string`	Le nom convivial de la commande. Sans objet pour les commandes passées au moyen de l’API d’achat du Microsoft Store.	Oui
`isPIRequired`	`boolean`	Indique si un instrument de paiement (PI) est requis dans le cadre du bon de commande.	Oui
`language`	`string`	L’ID de langue de la commande (par exemple, “en”).	Oui
`market`	`string`	L’ID de marché de la commande (par exemple, “US”).	Oui
`orderId`	`string`	Un ID qui identifie la commande pour un utilisateur particulier.	Oui
`orderLineItems`	`list<OrderLineItemV8>`	La liste des articles de ligne de la commande. En général, il y a un article de ligne par commande.	Oui
`orderState`	`string`	L’état de la commande. Les états valides sont `Editing`, `CheckingOut`, `Pending`, `Purchased`, `Refunded`, `ChargedBack` et `Canceled`.	Oui
`orderValidityEndTime`	`string`	Moment où la tarification de la commande prend fin; sans objet pour les applications gratuites.	Oui
`orderValidityStartTime`	`string`	Moment où la tarification de la commande commence; sans objet pour les applications gratuites.	Oui
`purchaser`	`IdentityV6`	Un objet qui décrit l’identité de l’acheteur.	Oui
`totalAmount`	`decimal`	Le montant total de l’achat de tous les articles de la commande, taxes incluses.	Oui
`totalAmountBeforeTax`	`decimal`	Le montant total de l’achat de tous les articles de la commande, avant taxes.	Oui
`totalChargedToCsvTopOffPI`	`decimal`	En cas d’utilisation d’un instrument de paiement distinct et d’une valeur stockée (CSV), le montant facturé à la valeur stockée.	Oui
`totalTaxAmount`	`decimal`	Le montant total des taxes pour tous les articles de ligne.	Oui

L’objet ClientContext contient les paramètres suivants.

Paramètre	Type	Description	Obligatoire
`client`	`string`	L’ID du client qui a créé la commande.	Non

L’objet OrderLineItemV8 contient les paramètres suivants.

Paramètre	Type	Description	Obligatoire
`agent`	`IdentityV8`	L’agent qui a modifié l’article de ligne en dernier. Pour plus d’informations sur cet objet, consultez le tableau suivant.	Non
`availabilityId`	`string`	L’ID de disponibilité du produit à acheter à partir du catalogue du Microsoft Store.	Oui
`beneficiary`	`IdentityV8`	L’identité du bénéficiaire de la commande.	Non
`billingState`	`string`	L’état de facturation de la commande. Défini sur `Charged` une fois terminée.	Non
`campaignId`	`string`	L’ID de campagne de cette commande.	Non
`currencyCode`	`string`	Le code de devise utilisé pour les détails de prix.	Oui
`description`	`string`	Une description localisée de l’article de ligne.	Oui
`devofferId`	`string`	L’ID d’offre de la commande particulière, s’il est présent.	Non
`fulfillmentDate`	`datetimeoffset`	La date à laquelle l’exécution a eu lieu.	Non
`fulfillmentState`	`string`	L’état de l’exécution de l’article. Défini sur `Fulfilled` une fois terminée.	Non
`isPIRequired`	`boolean`	Indique si un instrument de paiement est requis pour cet article de ligne.	Oui
`isTaxIncluded`	`boolean`	Indique si les taxes sont incluses dans les détails de prix de l’article.	Oui
`legacyBillingOrderId`	`string`	L’ancien ID de facturation.	Non
`lineItemId`	`string`	L’ID d’article de ligne de l’article dans cette commande.	Oui
`listPrice`	`decimal`	Le prix courant de l’article dans cette commande.	Oui
`productId`	`string`	Le Store ID du produit qui représente l’article de ligne dans le catalogue du Microsoft Store. Un exemple de Store ID de produit est 9NBLGGH42CFD.	Oui
`productType`	`string`	Le type du produit. Les valeurs prises en charge sont `Durable`, `Application` et `UnmanagedConsumable`.	Oui
`quantity`	`int`	La quantité de l’article commandé.	Oui
`retailPrice`	`decimal`	Le prix de détail de l’article commandé.	Oui
`revenueRecognitionState`	`string`	L’état de comptabilisation des revenus.	Oui
`skuId`	`string`	Le Store ID de la SKU de l’article de ligne dans le catalogue du Microsoft Store. Un exemple de Store ID de SKU est 0010.	Oui
`taxAmount`	`decimal`	Le montant des taxes pour l’article de ligne.	Oui
`taxType`	`string`	Le type de taxe pour les taxes applicables.	Oui
`Title`	`string`	Le titre localisé de l’article de ligne.	Oui
`totalAmount`	`decimal`	Le montant total de l’achat de l’article de ligne, taxes incluses.	Oui

L’objet IdentityV8 contient les paramètres suivants.

Paramètre	Type	Description	Obligatoire
`identityType`	`string`	Contient la valeur `"pub"`.	Oui
`identityValue`	`string`	La valeur de chaîne du publisherUserId de la clé User Store ID spécifiée.	Oui

Exemple de réponse

Content-Length: 1203
Content-Type: application/json
MS-CorrelationId: fb2e69bc-f26a-4aab-a823-7586c19f5762
MS-RequestId: c1bc832c-f742-47e4-a76c-cf061402f698
MS-CV: XfrNWLQlEaux6Mt.8
MS-ServerId: 030032362
Date: Tue, 13 Oct 2019 21:21:51 GMT

{
    "clientContext": {
        "client": "86b78998-d05a-487b-b380-6c738f6553ea"
    },
    "createdTime": "2015-10-13T21:21:51.1863494+00:00",
    "currencyCode": "USD",
    "isPIRequired": false,
    "language": "en-us",
    "market": "us",
    "orderId": "3eea1529-611e-4aee-915c-345494e4ee76",
    "orderLineItems": [{
        "availabilityId": "9RT7C09D5J3W",
        "beneficiary": {
            "identityType": "pub",
            "identityValue": "user1"
        },
        "billingState": "Charged",
        "currencyCode": "USD",
        "description": "Jewels, Jewels, Jewels - Consumable 2",
        "fulfillmentDate": "2015-10-13T21:21:51.639478+00:00",
        "fulfillmentState": "Fulfilled",
        "isPIRequired": false,
        "isTaxIncluded": true,
        "lineItemId": "2814d758-3ee3-46b3-9671-4fb3bdae9ffe",
        "listPrice": 0.0,
        "payments": [],
        "productId": "9NBLGGH5WVP6",
        "productType": "UnmanagedConsumable",
        "quantity": 1,
        "retailPrice": 0.0,
        "revenueRecognitionState": "None",
        "skuId": "0010",
        "taxAmount": 0.0,
        "taxType": "NoApplicableTaxes",
        "title": "Jewels, Jewels, Jewels - Consumable 2",
        "totalAmount": 0.0
    }],
    "orderState": "Purchased",
    "orderValidityEndTime": "2015-10-14T21:21:51.1863494+00:00",
    "orderValidityStartTime": "2015-10-13T21:21:51.1863494+00:00",
    "purchaser": {
        "identityType": "pub",
        "identityValue": "user1"
    },
    "testScenarios": "None",
    "totalAmount": 0.0,
    "totalTaxAmount": 0.0
}

Codes d’erreur

Code	Erreur	Code d’erreur interne	Description
401	Unauthorized	AuthenticationTokenInvalid	Le jeton d’accès Microsoft Entra ID n’est pas valide. Dans certains cas, les détails de ServiceError contiennent plus d’informations, par exemple lorsque le jeton est expiré ou que la revendication appid est manquante.
401	Unauthorized	PartnerAadTicketRequired	Aucun jeton d’accès Microsoft Entra ID n’a été transmis au service dans l’en-tête d’autorisation.
401	Unauthorized	InconsistentClientId	La revendication `clientId` de la clé User Store ID et l’`appid` du jeton d’accès ne correspondent pas.
400	BadRequest	InvalidParameter	Les détails contiennent des informations sur le corps de la requête et sur les champs dont la valeur n’est pas valide.

Articles connexes

Gérer les produits à partir de vos services Demande d’un User Store ID pour l’authentification de service à service Renouveler une clé Microsoft Store ID

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

Prérequis

Requête

Syntaxe de la requête

En-tête de la requête

Corps de la requête

Exemple de requête

Réponse

Corps de la réponse

Exemple de réponse

Codes d’erreur

Articles connexes

​Prérequis

​Requête

​Syntaxe de la requête

​En-tête de la requête

​Corps de la requête

​Exemple de requête

​Réponse

​Corps de la réponse

​Exemple de réponse

​Codes d’erreur

​Articles connexes

Prérequis

Requête

Syntaxe de la requête

En-tête de la requête

Corps de la requête

Exemple de requête

Réponse

Corps de la réponse

Exemple de réponse

Codes d’erreur

Articles connexes