Conceder productos gratuitos
Usa este método en la API de compra de Microsoft Store para conceder una aplicación o complemento gratis (también conocido como producto desde la aplicación o IAP) a un usuario determinado.
Actualmente, solo puede conceder productos gratuitos. Si el servicio intenta usar este método para conceder un producto que no es gratuito, este método devolverá un error.
Requisitos previos
Para usar este método, necesitará:
- Un token de acceso de Azure AD que tiene el valor
https://onestore.microsoft.comde URI de audiencia . - Clave de identificador de Microsoft Store que representa la identidad del usuario para el que quiere conceder un producto gratuito.
Para obtener más información, consulte Administración de derechos de producto desde un servicio.
Solicitar
Sintaxis de la solicitud
| Método | URI de solicitud |
|---|---|
| POST | https://purchase.mp.microsoft.com/v6.0/purchases/grant |
Encabezado de solicitud
| Encabezado | Tipo | Descripción |
|---|---|---|
| Autorización | string | Necesario. Token de acceso de Azure AD con el formato Token<de portador>. |
| Host | string | Debe establecerse en el valor purchase.mp.microsoft.com. |
| Content-Length | number | Este encabezado especifica la longitud del cuerpo de la solicitud. |
| Content-Type | string | Especifica el tipo de solicitud y respuesta. Actualmente, el único valor admitido es application/json. |
Cuerpo de la solicitud
| Parámetro | Tipo | Descripción | Obligatorio |
|---|---|---|---|
| availabilityId | string | Identificador de disponibilidad del producto al que se va a conceder desde el catálogo de Microsoft Store. | Sí |
| b2bKey | string | Clave de identificador de Microsoft Store que representa la identidad del usuario para el que quiere conceder un producto. | Sí |
| devOfferId | string | Identificador de oferta especificado por el desarrollador que aparecerá en el elemento Colección después de la compra. | |
| language | string | Idioma del usuario. | Sí |
| market | string | Mercado del usuario. | Sí |
| orderId | guid | GUID generado para el pedido. Este valor es único para el usuario, pero no es necesario que sea único en todos los pedidos. | Sí |
| productId | string | Identificador de la Tienda del producto en el catálogo de Microsoft Store. Un ejemplo de Id. de la Tienda para un producto es 9NBLGGH42CFD. | Sí |
| cantidad | int | Cantidad que se va a comprar. Actualmente, el único valor admitido es 1. Si no se especifica, el valor predeterminado es 1. | No |
| skuId | string | Identificador de la Tienda para la SKU del producto en el catálogo de Microsoft Store. Un id. de tienda de ejemplo para una SKU es 0010. | Sí |
Ejemplo de solicitud
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",
}
Respuesta
Cuerpo de la respuesta
| Parámetro | Tipo | Descripción | Obligatorio |
|---|---|---|---|
| clientContext | ClientContextV6 | Información contextual del cliente para este pedido. Esto se asignará al valor clientID del token de Azure AD. | Sí |
| createdtime | datetimeoffset | Hora en que se creó el pedido. | Sí |
| currencyCode | string | Código de moneda para totalAmount y totalTaxAmount. N/A para artículos gratuitos. | Sí |
| friendlyName | string | Nombre descriptivo del pedido. N/A para pedidos realizados mediante la API de compra de Microsoft Store. | Sí |
| isPIRequired | boolean | Indica si se requiere un instrumento de pago (PI) como parte del pedido de compra. | Sí |
| language | string | Identificador de idioma del pedido (por ejemplo, "en"). | Sí |
| market | string | Identificador de mercado del pedido (por ejemplo, "EE. UU."). | Sí |
| orderId | string | Identificador que identifica el pedido de un usuario determinado. | Sí |
| orderLineItems | list<OrderLineItemV6> | Lista de elementos de línea para el pedido. Normalmente hay 1 elemento de línea por pedido. | Sí |
| orderState | string | Estado del pedido. Los estados válidos son Editing, CheckOut, Pending, Purchased, Refunded, ChargedBack y Cancelled. | Sí |
| orderValidityEndTime | string | La última vez que el precio del pedido es válido antes de enviarlo. N/A para aplicaciones gratuitas. | Sí |
| orderValidityStartTime | string | La primera vez que el precio del pedido es válido antes de enviarlo. N/A para aplicaciones gratuitas. | Sí |
| comprador | IdentityV6 | Objeto que describe la identidad del comprador. | Sí |
| totalAmount | decimal | Importe total de la compra de todos los artículos en el pedido, incluido el impuesto. | Sí |
| totalAmountBeforeTax | decimal | Importe total de la compra de todos los artículos en el pedido antes de impuestos. | Sí |
| totalChargedToCsvTopOffPI | decimal | Si usa un instrumento de pago independiente y un valor almacenado (CSV), la cantidad cargada a CSV. | Sí |
| totalTaxAmount | decimal | Importe total del impuesto para todos los artículos de línea. | Sí |
El objeto ClientContext contiene los parámetros siguientes.
| Parámetro | Tipo | Descripción | Obligatorio |
|---|---|---|---|
| client | string | Identificador de cliente que creó el pedido. | No |
El objeto OrderLineItemV6 contiene los parámetros siguientes.
| Parámetro | Tipo | Descripción | Obligatorio |
|---|---|---|---|
| agente | IdentityV6 | Agente que editó por última vez el elemento de línea. Para obtener más información sobre este objeto, vea la tabla siguiente. | No |
| availabilityId | string | Identificador de disponibilidad del producto que se va a comprar desde el catálogo de Microsoft Store. | Sí |
| beneficiario | IdentityV6 | La identidad del beneficiario de la orden. | No |
| billingState | string | Estado de facturación del pedido. Se establece en Cargado cuando se completa. | No |
| campaignId | string | Identificador de campaña para este pedido. | No |
| currencyCode | string | El código de moneda usado para los detalles del precio. | Sí |
| description | string | Descripción localizada del elemento de línea. | Sí |
| devofferId | string | Identificador de la oferta para el pedido determinado, si está presente. | No |
| fulfillmentDate | datetimeoffset | Fecha en que se produjo el cumplimiento. | No |
| fulfillmentState | string | Estado del cumplimiento de este elemento. Esto se establece en Completado cuando se completa. | No |
| isPIRequired | boolean | Indica si se requiere un instrumento de pago para este artículo de línea. | Sí |
| isTaxIncluded | boolean | Indica si el impuesto se incluye en los detalles de precios del artículo. | Sí |
| legacyBillingOrderId | string | Identificador de facturación heredado. | No |
| lineItemId | string | Identificador del elemento de línea para el elemento en este orden. | Sí |
| listPrice | decimal | Precio de lista del artículo en este orden. | Sí |
| productId | string | Identificador de la Tienda para el producto que representa el elemento de línea en el catálogo de Microsoft Store. Un ejemplo de Id. de la Tienda para un producto es 9NBLGGH42CFD. | Sí |
| productType | string | Tipo del producto. Los valores admitidos son Durable, Application y UnmanagedConsumable. | Sí |
| cantidad | int | Cantidad del artículo pedido. | Sí |
| retailPrice | decimal | Precio comercial del artículo pedido. | Sí |
| revenueRecognitionState | string | Estado de reconocimiento de ingresos. | Sí |
| skuId | string | Identificador de la Tienda para la SKU del elemento de línea en el catálogo de Microsoft Store. Un id. de tienda de ejemplo para una SKU es 0010. | Sí |
| taxAmount | decimal | Importe fiscal del artículo de línea. | Sí |
| taxType | string | Tipo de impuesto para los impuestos aplicables. | Sí |
| Título | string | Título localizado del elemento de línea. | Sí |
| totalAmount | decimal | Importe total de la compra del artículo de línea, incluido el impuesto. | Sí |
El objeto IdentityV6 contiene los parámetros siguientes.
| Parámetro | Tipo | Descripción | Obligatorio |
|---|---|---|---|
| identityType | string | Contiene el valor "pub". | Sí |
| identityValue | string | Valor de cadena del publisherUserId de la clave de identificador de Microsoft Store especificada. | Sí |
Ejemplo de respuesta
Content-Length: 1203
Content-Type: application/json
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
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
}
Códigos de error
| Código | Error | Código de error interno | Descripción |
|---|---|---|---|
| 401 | No autorizado | AuthenticationTokenInvalid | El token de acceso de Azure AD no es válido. En algunos casos, los detalles del ServiceError contendrán más información, como cuando el token ha expirado o falta la notificación appid . |
| 401 | No autorizado | PartnerAadTicketRequired | No se pasó un token de acceso de Azure AD al servicio en el encabezado de autorización. |
| 401 | No autorizado | InconsistentClientId | La notificación clientId de la clave de identificador de Microsoft Store en el cuerpo de la solicitud y la notificación appid del token de acceso de Azure AD en el encabezado de autorización no coinciden. |
| 400 | BadRequest | InvalidParameter | Los detalles contienen información sobre el cuerpo de la solicitud y qué campos tienen un valor no válido. |