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

Utilisez l’API d’achat 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 renvoient 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, l’appel 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/v7.0/purchases/grant`

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` <jeton>.
`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
`availabilityId`	`string`	ID de disponibilité du produit à accorder à partir du catalogue du Microsoft Store.	Oui
`b2bKey`	`string`	Clé d’ID Store utilisateur qui représente l’identité de l’utilisateur auquel vous souhaitez accorder un produit.	Oui
`devOfferId`	`string`	ID d’offre spécifié par le développeur qui apparaît dans l’élément de collection après l’achat.	Non
`language`	`string`	Langue de l’utilisateur.	Oui
`market`	`string`	Marché de l’utilisateur.	Oui
`orderId`	`GUID`	GUID généré pour la commande. Cette valeur est unique pour l’utilisateur, mais elle n’a pas besoin d’être unique pour toutes les commandes.	Oui
`productId`	`string`	ID Store du produit dans le catalogue du Microsoft Store. Exemple d’ID Store pour un produit : 9NBLGGH42CFD.	Oui
`quantity`	`int`	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`	ID Store de la SKU du produit dans le catalogue du Microsoft Store. Exemple d’ID Store pour une SKU : 0010.	Oui
`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

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`	Informations contextuelles du client pour la commande. Affecté à la valeur `clientID` du jeton Microsoft Entra ID.	Oui
`createdtime`	`datetimeoffset`	Heure de création de la commande.	Oui
`currencyCode`	`string`	Code de devise pour `totalAmount` et `totalTaxAmount`. Non applicable pour les éléments gratuits.	Oui
`friendlyName`	`string`	Nom convivial de la commande. Non applicable pour les commandes passées à l’aide de l’API d’achat Microsoft Store.	Oui
`isPIRequired`	`boolean`	Indique si un instrument de paiement (PI) est requis dans le cadre du bon de commande.	Oui
`language`	`string`	ID de langue de la commande (par exemple, « en »).	Oui
`market`	`string`	ID de marché de la commande (par exemple, « US »).	Oui
`orderId`	`string`	ID qui identifie la commande pour un utilisateur particulier.	Oui
`orderLineItems`	`list<OrderLineItemV8>`	Liste des lignes de commande. En règle générale, il y a une ligne par commande.	Oui
`orderState`	`string`	État de la commande. Les états valides sont `Editing`, `CheckingOut`, `Pending`, `Purchased`, `Refunded`, `ChargedBack` et `Canceled`.	Oui
`orderValidityEndTime`	`string`	Date de fin de la tarification de la commande ; non applicable pour les applications gratuites.	Oui
`orderValidityStartTime`	`string`	Date de début de la tarification de la commande ; non applicable pour les applications gratuites.	Oui
`purchaser`	`IdentityV6`	Objet qui décrit l’identité de l’acheteur.	Oui
`totalAmount`	`decimal`	Montant total de l’achat de tous les éléments de la commande, taxes comprises.	Oui
`totalAmountBeforeTax`	`decimal`	Montant total de l’achat de tous les éléments de la commande, hors taxes.	Oui
`totalChargedToCsvTopOffPI`	`decimal`	En cas d’utilisation d’un instrument de paiement distinct et d’une valeur stockée (CSV, comma-separated value), montant facturé à la valeur stockée.	Oui
`totalTaxAmount`	`decimal`	Montant total des taxes pour toutes les lignes de commande.	Oui

L’objet ClientContext contient les paramètres suivants.

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

L’objet OrderLineItemV8 contient les paramètres suivants.

Paramètre	Type	Description	Obligatoire
`agent`	`IdentityV8`	Agent qui a modifié la ligne de commande en dernier. Pour plus d’informations sur cet objet, consultez le tableau suivant.	Non
`availabilityId`	`string`	ID de disponibilité du produit à acheter à partir du catalogue du Microsoft Store.	Oui
`beneficiary`	`IdentityV8`	Identité du bénéficiaire de la commande.	Non
`billingState`	`string`	État de facturation de la commande. Défini sur `Charged` une fois terminé.	Non
`campaignId`	`string`	ID de campagne de cette commande.	Non
`currencyCode`	`string`	Code de devise utilisé pour les détails du prix.	Oui
`description`	`string`	Description localisée de la ligne de commande.	Oui
`devofferId`	`string`	ID d’offre de la commande concernée, le cas échéant.	Non
`fulfillmentDate`	`datetimeoffset`	Date à laquelle le traitement a eu lieu.	Non
`fulfillmentState`	`string`	État du traitement de l’élément. Défini sur `Fulfilled` une fois terminé.	Non
`isPIRequired`	`boolean`	Indique si un instrument de paiement est requis pour cette ligne de commande.	Oui
`isTaxIncluded`	`boolean`	Indique si les taxes sont incluses dans les détails de tarification de l’élément.	Oui
`legacyBillingOrderId`	`string`	ID de facturation hérité.	Non
`lineItemId`	`string`	ID de ligne de commande de l’élément dans cette commande.	Oui
`listPrice`	`decimal`	Prix catalogue de l’élément dans cette commande.	Oui
`productId`	`string`	ID Store du produit qui représente la ligne de commande dans le catalogue du Microsoft Store. Exemple d’ID Store pour un produit : 9NBLGGH42CFD.	Oui
`productType`	`string`	Type du produit. Les valeurs prises en charge sont `Durable`, `Application` et `UnmanagedConsumable`.	Oui
`quantity`	`int`	Quantité commandée de l’élément.	Oui
`retailPrice`	`decimal`	Prix de vente de l’élément commandé.	Oui
`revenueRecognitionState`	`string`	État de la comptabilisation des revenus.	Oui
`skuId`	`string`	ID Store de la SKU de la ligne de commande dans le catalogue du Microsoft Store. Exemple d’ID Store pour une SKU : 0010.	Oui
`taxAmount`	`decimal`	Montant des taxes pour la ligne de commande.	Oui
`taxType`	`string`	Type de taxe pour les taxes applicables.	Oui
`Title`	`string`	Titre localisé de la ligne de commande.	Oui
`totalAmount`	`decimal`	Montant total de l’achat de la ligne de commande, taxes comprises.	Oui

L’objet IdentityV8 contient les paramètres suivants.

Paramètre	Type	Description	Obligatoire
`identityType`	`string`	Contient la valeur `"pub"`.	Oui
`identityValue`	`string`	Valeur de chaîne du publisherUserId issue de la clé d’ID Store utilisateur 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 a 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é d’ID Store utilisateur 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 les champs dont la valeur n’est pas valide.

Articles connexes

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

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