Octroyer des produits gratuits
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. |