Octroyer des produits gratuits

  • Article

Utilisez cette méthode dans l’API d’achat du Microsoft Store pour accorder une application ou un module complémentaire gratuit (également appelé produit in-app ou IAP) à un utilisateur donné.

Actuellement, vous ne pouvez octroyer que des produits gratuits. Si votre service tente d’utiliser cette méthode pour octroyer un produit qui n’est pas gratuit, cette méthode retourne une erreur.

Prérequis

Pour utiliser cette méthode, vous devez disposer des éléments suivants :

  • Jeton d’accès Azure AD qui a la valeur https://onestore.microsoft.comd’URI d’audience .
  • Une clé d’ID du Microsoft Store qui représente l’identité de l’utilisateur auquel vous souhaitez accorder un produit gratuit.

Pour plus d’informations, consultez Gérer les droits d’utilisation d’un produit à partir d’un service.

Requête

Syntaxe de la requête

Méthode URI de demande
POST https://purchase.mp.microsoft.com/v6.0/purchases/grant

En-tête de requête

En-tête Type Description
Autorisation string Obligatoire. Jeton d’accès Azure AD sous la formeJeton> du porteur<.
Host string Doit être défini sur la valeur purchase.mp.microsoft.com.
Content-Length nombre Longueur du corps de la demande.
Content-Type string Spécifie le type de requête et de réponse. Actuellement, la seule valeur prise en charge est application/json.

Corps de la demande

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 du Microsoft Store 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 s’affiche dans l’élément de collection après l’achat.
langage string Langue de l’utilisateur. Oui
market string Marché de l’utilisateur. Oui
orderId guid GUID généré pour la commande. Cette valeur doit être propre à l’utilisateur, mais il n’est pas impératif qu’elle soit unique dans toutes les commandes. Oui
productId string ID store du produit dans le catalogue du Microsoft Store. Un exemple d’ID store pour un produit est 9NBLGGH42CFD. Oui
quantité int Quantité à acheter. Actuellement, la seule valeur prise en charge est 1. Si cet argument n'est pas spécifié, la valeur par défaut est 1. Non
skuId string ID du Store pour la référence SKU du produit dans le catalogue du Microsoft Store. Un exemple d’ID de magasin pour une référence SKU est 0010. Oui

Exemple de requête

POST https://purchase.mp.microsoft.com/v6.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",
}

response

Response body

Paramètre Type Description Obligatoire
clientContext ClientContextV6 Informations contextuelles client de cette commande. Ce paramètre est affecté à la valeur clientID du jeton Azure AD. Oui
createdtime datetimeoffset Heure de création de la commande. Oui
currencyCode string Code devise pour totalAmount et totalTaxAmount. Non applicable pour les articles gratuits. Oui
friendlyName string Nom convivial de la commande. N/A pour les commandes passées à l’aide de l’API d’achat du Microsoft Store. Oui
isPIRequired boolean Indique si un instrument de paiement (PI) est nécessaire dans le cadre de la commande d’achat. Oui
langage string ID de langue de la commande (par exemple, « fr »). Oui
market string ID de marché de la commande (par exemple, « FR »). Oui
orderId string ID qui identifie la commande d’un utilisateur particulier. Oui
orderLineItems list<OrderLineItemV6> Liste des articles de la commande. En règle générale, il y a un article par commande. Oui
orderState string État de la commande. Les états valides sont Editing, CheckingOut, Pending, Purchased, Refunded, ChargedBack et Cancelled. Oui
orderValidityEndTime string Dernière fois que la tarification de la commande a été valide avant sa soumission. Non applicable pour les applications gratuites. Oui
orderValidityStartTime string Première fois que la tarification de la commande a été valide avant sa soumission. Non applicable pour les applications gratuites. Oui
purchaser IdentityV6 Objet qui décrit l’identité de l’acheteur. Oui
totalAmount Décimal Montant total d’achat TTC de tous les articles de la commande. Oui
totalAmountBeforeTax Décimal Montant total d’achat HT de tous les articles de la commande. Oui
totalChargedToCsvTopOffPI Décimal Si vous utilisez un instrument de paiement (PI) et une valeur de stockage (CSV) distincts, le montant est facturé au format CSV. Oui
totalTaxAmount Décimal Montant total des taxes de tous les articles. Oui

L’objet ClientContext contient les paramètres ci-dessous.

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

L’objet OrderLineItemV6 contient les paramètres ci-dessous.

Paramètre Type Description Obligatoire
agent IdentityV6 Dernier agent à avoir modifié l’article. Pour plus d’informations sur cet objet, voir le tableau ci-dessous. Non
availabilityId string ID de disponibilité du produit à acheter dans le catalogue du Microsoft Store. Oui
beneficiary IdentityV6 Identité du bénéficiaire de la commande. Non
billingState string État de facturation de la commande. Défini sur Charged lorsque la commande est terminée. Non
campaignId string ID campagne de cette commande. Non
currencyCode string Code de devise utilisé pour les détails de prix. Oui
description string Description localisée de l’article. Oui
devofferId string ID d’offre de la commande particulière, le cas échéant. Non
fulfillmentDate datetimeoffset Date du traitement de la commande. Non
fulfillmentState string État du traitement de la commande de cet article. Défini sur Fulfilled lorsque le traitement est effectué. Non
isPIRequired boolean Indique si un instrument de paiement est requis pour cet article. Oui
isTaxIncluded boolean Indique si les taxes sont comprises dans les détails de la tarification de l’article. Oui
legacyBillingOrderId string ID de facturation hérité. Non
lineItemId string ID de l’article de cette commande. Oui
listPrice Décimal Prix catalogue de l’article de cette commande. Oui
productId string ID store du produit qui représente l’élément de ligne dans le catalogue du Microsoft Store. Un exemple d’ID de magasin pour un produit est 9NBLGGH42CFD. Oui
productType string Type du produit. Les valeurs prises en charge sont Durable, Application et UnmanagedConsumable. Oui
quantité int Quantité de l’article commandé. Oui
retailPrice Décimal Prix de vente au détail de l’article commandé. Oui
revenueRecognitionState string État de prise en compte de revenu. Oui
skuId string ID store pour la référence SKU de l’élément de ligne dans le catalogue microsoft Store. Un exemple d’ID de magasin pour une référence SKU est 0010. Oui
taxAmount Décimal Montant des taxes de l’article. Oui
taxType string Type de taxe pour les taxes applicables. Oui
Intitulé string Titre localisé de l’article. Oui
totalAmount Décimal Montant total TTC d’achat de l’article. Oui

L’objet IdentityV6 contient les paramètres ci-dessous.

Paramètre Type Description Obligatoire
identityType string Contient la valeur "pub". Oui
identityValue string Valeur de chaîne de publisherUserId à partir de la clé d’ID du Microsoft Store 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: XjfuNWLQlEuxj6Mt.8
MS-ServerId: 030032362
Date: Tue, 13 Oct 2015 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 Error Code d’erreur interne Description
401 Non autorisé AuthenticationTokenInvalid Le jeton d’accès Azure AD n’est pas valide. Dans certains cas, les détails de l’erreur ServiceError contiennent plus d’informations, par exemple lorsque le jeton est arrivé à expiration ou que la revendication appid est manquante.
401 Non autorisé PartnerAadTicketRequired Un jeton d’accès Azure AD n’a pas été transmis au service dans l’en-tête d’autorisation.
401 Non autorisé InconsistentClientId La revendication clientId dans la clé d’ID du Microsoft Store dans le corps de la demande et la revendication appid dans le jeton d’accès Azure AD dans l’en-tête d’autorisation ne correspondent pas.
400 BadRequest InvalidParameter Les détails contiennent des informations relatives au corps de la requête et aux champs comprenant une valeur non valide.