Предоставление бесплатных продуктов

Статья
07/05/2024

Используйте этот метод в API покупки в Microsoft Store, чтобы предоставить пользователю бесплатное приложение или надстройку (также известное как продукт в приложении или IAP).

В настоящее время вы можете предоставлять только бесплатные продукты. Если служба пытается использовать этот метод для предоставления продукта, который не является бесплатным, этот метод вернет ошибку.

Необходимые компоненты

Чтобы использовать этот метод, вам потребуется:

Маркер доступа Azure AD, имеющий значение https://onestore.microsoft.comURI аудитории.
Ключ идентификатора Microsoft Store, представляющий удостоверение пользователя, для которого требуется предоставить бесплатный продукт.

Дополнительные сведения см. в разделе "Управление правами на продукты из службы".

Запросить

Синтаксис запроса

Способ	URI запроса
POST	`https://purchase.mp.microsoft.com/v6.0/purchases/grant`

Заголовок запроса

Верхний колонтитул	Тип	Описание
Авторизация	строка	Обязательный. Маркер доступа Azure AD в маркере> носителя<формы.
Хост	строка	Необходимо задать значение purchase.mp.microsoft.com.
content-length: 0	number	Длина текста запроса.
Тип контента	строка	Указывает тип запроса и ответа. В настоящее время единственным поддерживаемым значением является application/json.

Текст запроса

Параметр	Тип	Описание	Обязательное поле
availabilityId	строка	Идентификатор доступности продукта, который будет предоставлен из каталога Microsoft Store.	Да
b2bKey	строка	Ключ идентификатора Microsoft Store, представляющий удостоверение пользователя, для которого требуется предоставить продукт.	Да
devOfferId	строка	Указанный разработчиком идентификатор предложения, который появится в элементе коллекции после покупки.
язык	string	Язык пользователя.	Да
на рынок	строка	Рынок пользователя.	Да
orderId	guid	Идентификатор GUID, созданный для заказа. Это значение должно быть уникальным для пользователя, но оно не обязательно должно быть уникальным для всех заказов.	Да
productId	строка	Идентификатор Магазина для продукта в каталоге Microsoft Store. Пример идентификатора магазина для продукта — 9NBLGGH42CFD.	Да
quantity	INT	Количество для покупки. В настоящее время единственным поддерживаемым значением является 1. Если значение аргумента не указано, то по умолчанию принимается 1.	No
skuId	строка	Идентификатор Магазина для номера SKU продукта в каталоге Microsoft Store. Пример идентификатора магазина для номера SKU — 0010.	Да

Пример запроса

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

Текст ответа

Параметр	Тип	Описание	Обязательное поле
clientContext	ClientContextV6	Контекстные сведения клиента для этого заказа. Это будет назначено значению clientID из токена Azure AD.	Да
createdtime	datetimeoffset	Время создания заказа.	Да
currencyCode	строка	Код валюты для totalAmount и totalTaxAmount. N/A для бесплатных элементов.	Да
friendlyName	строка	Понятное имя заказа. N/A для заказов, сделанных с помощью API покупки в Microsoft Store.	Да
isPIRequired	boolean	Указывает, требуется ли инструмент оплаты (PI) в рамках заказа на покупку.	Да
язык	string	Идентификатор языка для заказа (например, "en").	Да
на рынок	строка	Идентификатор рынка заказа (например, "США").	Да
orderId	строка	Идентификатор, определяющий порядок для конкретного пользователя.	Да
orderLineItems	list<OrderLineItemV6>	Список элементов строки для заказа. Обычно для каждого заказа имеется 1 элемент строки.	Да
orderState	строка	Состояние заказа. Допустимые состояния: изменение, проверка, ожидание, покупка, возврат, возврат, возврат и отмена.	Да
orderValidityEndTime	строка	Последний раз, когда цена заказа действительна перед отправкой. N/A для бесплатных приложений.	Да
orderValidityStartTime	строка	Первый раз, когда цена заказа действительна перед отправкой. N/A для бесплатных приложений.	Да
покупатель	IdentityV6	Объект, описывающий удостоверение покупателя.	Да
totalAmount	десятичное	Общая сумма покупки всех элементов в заказе, включая налог.	Да
totalAmountBeforeTax	десятичное	Общая сумма покупки всех элементов в заказе до уплаты налогов.	Да
totalChargedToCsvTopOffPI	десятичное	Если используется отдельный инструмент оплаты и сохраненное значение (CSV), сумма взимается в CSV- файл.	Да
totalTaxAmount	десятичное	Общая сумма налога для всех элементов строки.	Да

Объект ClientContext содержит следующие параметры.

Параметр	Тип	Описание	Обязательное поле
клиент	строка	Идентификатор клиента, создавший заказ.	No

Объект OrderLineItemV6 содержит следующие параметры.

Параметр	Тип	Описание	Обязательное поле
агент	IdentityV6	Агент, который последний раз редактировал элемент строки. Дополнительные сведения об этом объекте см. в таблице ниже.	No
availabilityId	строка	Идентификатор доступности продукта, который необходимо приобрести из каталога Microsoft Store.	Да
бенефициар	IdentityV6	Удостоверение бенефициара заказа.	No
billingState	строка	Состояние выставления счетов заказа. Это значение имеет значение Charged при завершении.	No
campaignId	строка	Идентификатор кампании для этого заказа.	No
currencyCode	строка	Код валюты, используемый для получения сведений о цене.	Да
описание	строка	Локализованное описание элемента строки.	Да
devofferId	строка	Идентификатор предложения для определенного заказа, если он присутствует.	No
выполнениеDate	datetimeoffset	Дата выполнения.	No
fulfillmentState	строка	Состояние выполнения этого элемента. При завершении задано значение "Выполнено ".	No
isPIRequired	boolean	Указывает, требуется ли для этого элемента строки инструмент оплаты.	Да
isTaxIncluded	boolean	Указывает, включен ли налог в сведения о ценах элемента.	Да
legacyBillingOrderId	строка	Устаревший идентификатор выставления счетов.	No
lineItemId	строка	Идентификатор элемента строки для элемента в этом порядке.	Да
listPrice	десятичное	Цена по списку элемента в этом порядке.	Да
productId	строка	Идентификатор Магазина для продукта, представляющего элемент строки в каталоге Microsoft Store. Пример идентификатора магазина для продукта — 9NBLGGH42CFD.	Да
productType	строка	Тип продукта. Поддерживаемые значения: устойчивые, приложения и неуправляемые.	Да
quantity	INT	Количество упорядоченного элемента.	Да
retailPrice	десятичное	Розничная цена заказанного элемента.	Да
revenueRecognitionState	строка	Состояние распознавания доходов.	Да
skuId	строка	Идентификатор магазина для SKU элемента строки в каталоге Microsoft Store. Пример идентификатора магазина для номера SKU — 0010.	Да
taxAmount	десятичное	Сумма налога для элемента строки.	Да
taxType	строка	Тип налога для применимых налогов.	Да
Заголовок	string	Локализованное название элемента строки.	Да
totalAmount	десятичное	Общая сумма покупки элемента линии, включая налог.	Да

Объект IdentityV6 содержит следующие параметры.

Параметр	Тип	Описание	Обязательное поле
identityType	строка	Содержит значение pub.	Да
identityValue	строка	Строковое значение издателяUserId из указанного ключа идентификатора Microsoft Store.	Да

Пример ответа

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
}

Коды ошибок

Код	Ошибка	Код внутренней ошибки	Description
401	Не авторизовано	AuthenticationTokenInvalid	Недопустимый маркер доступа Azure AD. В некоторых случаях сведения о ServiceError будут содержать дополнительные сведения, например, когда срок действия маркера истек или утверждение appid отсутствует.
401	Не авторизовано	PartnerAadTicketRequired	Маркер доступа Azure AD не был передан службе в заголовке авторизации.
401	Не авторизовано	НесогласованныйClientId	Утверждение clientId в ключе идентификатора Microsoft Store в тексте запроса и утверждение appid в маркере доступа Azure AD в заголовке авторизации не совпадает.
400	BadRequest	InvalidParameter	Сведения содержат сведения о тексте запроса и о том, какие поля имеют недопустимое значение.

Поделиться через

Предоставление бесплатных продуктов

Необходимые компоненты

Запросить

Синтаксис запроса

Заголовок запроса

Текст запроса

Пример запроса

Response

Текст ответа

Пример ответа

Коды ошибок

Обратная связь

Дополнительные ресурсы

Поделиться через

Предоставление бесплатных продуктов

Необходимые компоненты

Запросить

Синтаксис запроса

Заголовок запроса

Текст запроса

Пример запроса

Response

Текст ответа

Пример ответа

Коды ошибок

См. также

Обратная связь

Дополнительные ресурсы