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 accorder que des produits gratuits. Si votre service tente d’utiliser cette méthode pour accorder un produit qui n’est pas gratuit, cette méthode retourne une erreur.

Prérequis

Pour utiliser cette méthode, vous aurez besoin des éléments suivants :

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

Pour plus d’informations, consultez Gérer les droits de 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 au format porteur<jeton>.
Host string Doit être défini sur la valeur purchase.mp.microsoft.com.
Longueur-contenu nombre Longueur du corps de la demande.
Content-Type string Spécifie le type de demande 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 pour lequel vous souhaitez accorder un produit. Oui
devOfferId string ID d’offre spécifié par le développeur qui apparaîtra dans l’élément collection après l’achat.
langage string Langue de l’utilisateur. Oui
market string Le marché de l’utilisateur. Oui
orderId guid GUID généré pour l’ordre. Cette valeur est unique pour l’utilisateur, mais elle n’est pas nécessaire pour être unique dans toutes les commandes. Oui
productId string ID store du produit dans le catalogue 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 store de la référence SKU du produit dans le catalogue du Microsoft Store. Un exemple d’ID store 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

Corps de réponse

Paramètre Type Description Obligatoire
clientContext ClientContextV6 Informations contextuelles du client pour cette commande. Cette opération est affectée à la valeur clientID à partir du jeton Azure AD. Oui
createdtime datetimeoffset Heure de création de l’ordre. Oui
currencyCode string Code monétaire pour totalAmount et totalTaxAmount. N/A pour les éléments gratuits. Oui
friendlyName string Nom convivial de la commande. N/A pour les commandes effectuées à l’aide de l’API d’achat du Microsoft Store. Oui
isPIRequired booléen Indique si un instrument de paiement (PI) est requis dans le cadre du bon de commande. Oui
langage string ID de langue de l’ordre (par exemple, « en »). Oui
market string ID de marché de la commande (par exemple, « US »). Oui
orderId string ID qui identifie l’ordre d’un utilisateur particulier. Oui
orderLineItems list<OrderLineItemV6> Liste des éléments de ligne de la commande. En règle générale, il y a 1 élément de ligne par commande. Oui
orderState string État de l’ordre. Les états valides sont La modification, la vérification, l’attente, l’achat, le remboursement, le débit facturé et l’annulation. Oui
orderValidityEndTime string La dernière fois que la tarification de la commande est valide avant son envoi. N/A pour les applications gratuites. Oui
orderValidityStartTime string La première fois que la tarification de la commande est valide avant son envoi. N/A pour les applications gratuites. Oui
acheteur IdentityV6 Objet qui décrit l’identité de l’acheteur. Oui
totalAmount decimal Montant total de l’achat de tous les articles de la commande, y compris la taxe. Oui
totalAmountBeforeTax decimal Montant total de l’achat de tous les articles dans la commande avant taxe. Oui
totalChargedToCsvTopOffPI decimal Si vous utilisez un instrument de paiement distinct et une valeur stockée (CSV), le montant facturé au format CSV. Oui
totalTaxAmount decimal Montant total de la taxe pour tous les articles de ligne. Oui

L’objet ClientContext contient les paramètres suivants.

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

L’objet OrderLineItemV6 contient les paramètres suivants.

Paramètre Type Description Obligatoire
agent IdentityV6 Agent qui a modifié l’élément de ligne pour la dernière fois. Pour plus d’informations sur cet objet, consultez le tableau ci-dessous. Non
availabilityId string ID de disponibilité du produit à acheter dans le catalogue du Microsoft Store. Oui
bénéficiaire IdentityV6 Identité du bénéficiaire de la commande. Non
billingState string État de facturation de la commande. Cette valeur est facturée lorsque vous avez terminé. Non
campaignId string ID de campagne pour cette commande. Non
currencyCode string Code monétaire utilisé pour les détails du prix. Oui
description string Description localisée de l’élément de ligne. Oui
devofferId string ID de l’offre pour l’ordre particulier, le cas échéant. Non
fulfillmentDate datetimeoffset Date à laquelle l’exécution s’est produite. Non
fulfillmentState string État de l’exécution de cet élément. Cette valeur est définie sur Remplie une fois terminée. Non
isPIRequired booléen Indique si un instrument de paiement est requis pour cet élément de ligne. Oui
isTaxIncluded booléen Indique si la taxe est incluse dans les détails de tarification de l’article. Oui
legacyBillingOrderId string ID de facturation hérité. Non
lineItemId string ID d’élément de ligne de l’élément dans cet ordre. Oui
listPrice decimal Prix de liste de l’article dans cet ordre. Oui
productId string ID store du produit qui représente l’élément de ligne dans le catalogue microsoft Store. Un exemple d’ID Store 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’élément commandé. Oui
retailPrice decimal Prix de vente au détail de l’article commandé. Oui
revenueRecognitionState string État de reconnaissance des revenus. Oui
skuId string ID store pour la référence SKU de l’élément de ligne dans le catalogue du Microsoft Store. Un exemple d’ID store pour une référence SKU est 0010. Oui
taxAmount decimal Montant de la taxe pour l’élément de ligne. Oui
taxType string Type de taxe pour les taxes applicables. Oui
Titre string Titre localisé de l’élément de ligne. Oui
totalAmount decimal Montant total de l’achat de l’article de ligne, y compris la taxe. Oui

L’objet IdentityV6 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 à 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 ServiceError contiennent plus d’informations, par exemple lorsque le jeton a expiré 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 concernant le corps de la requête et les champs qui ont une valeur non valide.