purchase.mp.microsoft.com/v7.0/purchases/grant

Use la API de compra de Microsoft Store para conceder una aplicación o un complemento gratuitos a la cuenta de un usuario. Solo los productos gratuitos se pueden conceder directamente a la cuenta de un usuario. Los intentos de concesión de productos de pago devuelven un error.

Requisitos previos

Revise los Requisitos previos para las API de servicio a servicio. Esta API solo admite el tipo de autenticación de Microsoft Entra ID. Si la configuración del producto no está publicada en Partner Center, la solicitud puede completarse correctamente pero no devolver ningún resultado.

Solicitud

Sintaxis de la solicitud

Método	URI de solicitud
`POST`	`https://purchase.mp.microsoft.com/v7.0/purchases/grant`

Encabezado de la solicitud

Encabezado	Tipo	Descripción
`Authorization`	`string`	Obligatorio. El token de acceso al servicio de Microsoft Entra ID con el formato `Bearer` <token>.
`Host`	`string`	Debe establecerse en el valor `purchase.mp.microsoft.com`.
`Content-Length`	`number`	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`	El identificador de disponibilidad del producto que se va a conceder desde el catálogo de Microsoft Store.	Sí
`b2bKey`	`string`	La clave de identificador de User Store que representa la identidad del usuario al que desea conceder un producto.	Sí
`devOfferId`	`string`	Un identificador de oferta especificado por el desarrollador que aparece en el elemento de la colección después de la compra.	No
`language`	`string`	El idioma del usuario.	Sí
`market`	`string`	El mercado del usuario.	Sí
`orderId`	`GUID`	Un 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`	El Store ID del producto en el catálogo de Microsoft Store. Un ejemplo de Store ID de un producto es 9NBLGGH42CFD.	Sí
`quantity`	`int`	La 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`	El Store ID de la SKU del producto en el catálogo de Microsoft Store. Un ejemplo de Store ID de una SKU es 0010.	Sí
`sbx`	`string`	Valor opcional para la autenticación con UserStoreIds que especifica el espacio aislado al que deben limitarse los resultados. Sin este valor, el valor predeterminado es el espacio aislado RETAIL. La autenticación con X-Token no necesita este valor, ya que el espacio aislado se especifica dentro del X-Token.	No

Ejemplo de solicitud

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

Respuesta

Cuerpo de la respuesta

Parámetro	Tipo	Descripción	Obligatorio
`clientContext`	`ClientContextV8`	La información contextual del cliente para el pedido. Se asigna al valor `clientID` del token de Microsoft Entra ID.	Sí
`createdtime`	`datetimeoffset`	La hora en que se creó el pedido.	Sí
`currencyCode`	`string`	El código de moneda de `totalAmount` y `totalTaxAmount`. No aplicable para los artículos gratuitos.	Sí
`friendlyName`	`string`	El nombre descriptivo del pedido. No aplicable para los pedidos realizados con 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`	El identificador de idioma del pedido (por ejemplo, “en”).	Sí
`market`	`string`	El identificador de mercado del pedido (por ejemplo, “US”).	Sí
`orderId`	`string`	Un identificador que identifica el pedido para un usuario concreto.	Sí
`orderLineItems`	`list<OrderLineItemV8>`	La lista de elementos de línea del pedido. Normalmente, hay un elemento de línea por pedido.	Sí
`orderState`	`string`	El estado del pedido. Los estados válidos son `Editing`, `CheckingOut`, `Pending`, `Purchased`, `Refunded`, `ChargedBack` y `Canceled`.	Sí
`orderValidityEndTime`	`string`	Cuándo finaliza el precio del pedido. No aplicable para las aplicaciones gratuitas.	Sí
`orderValidityStartTime`	`string`	Cuándo comienza el precio del pedido. No aplicable para las aplicaciones gratuitas.	Sí
`purchaser`	`IdentityV6`	Un objeto que describe la identidad del comprador.	Sí
`totalAmount`	`decimal`	El importe total de la compra de todos los artículos del pedido, impuestos incluidos.	Sí
`totalAmountBeforeTax`	`decimal`	El importe total de la compra de todos los artículos del pedido antes de impuestos.	Sí
`totalChargedToCsvTopOffPI`	`decimal`	Si se usan un instrumento de pago y un valor almacenado (CSV) independientes, el importe cargado al CSV.	Sí
`totalTaxAmount`	`decimal`	El importe total de impuestos de todos los elementos de línea.	Sí

El objeto ClientContext contiene los siguientes parámetros.

Parámetro	Tipo	Descripción	Obligatorio
`client`	`string`	El identificador del cliente que creó el pedido.	No

El objeto OrderLineItemV8 contiene los siguientes parámetros.

Parámetro	Tipo	Descripción	Obligatorio
`agent`	`IdentityV8`	El agente que editó por última vez el elemento de línea. Para obtener más información sobre este objeto, consulte la tabla siguiente.	No
`availabilityId`	`string`	El identificador de disponibilidad del producto que se va a comprar en el catálogo de Microsoft Store.	Sí
`beneficiary`	`IdentityV8`	La identidad del beneficiario del pedido.	No
`billingState`	`string`	El estado de facturación del pedido. Se establece en `Charged` cuando se completa.	No
`campaignId`	`string`	El identificador de campaña de este pedido.	No
`currencyCode`	`string`	El código de moneda que se usa para los detalles del precio.	Sí
`description`	`string`	Una descripción localizada del elemento de línea.	Sí
`devofferId`	`string`	El identificador de oferta del pedido concreto, si existe.	No
`fulfillmentDate`	`datetimeoffset`	La fecha en que se produjo el cumplimiento.	No
`fulfillmentState`	`string`	El estado del cumplimiento del artículo. Se establece en `Fulfilled` cuando se completa.	No
`isPIRequired`	`boolean`	Indica si se requiere un instrumento de pago para este elemento de línea.	Sí
`isTaxIncluded`	`boolean`	Indica si los impuestos están incluidos en los detalles del precio del artículo.	Sí
`legacyBillingOrderId`	`string`	El identificador de facturación heredado.	No
`lineItemId`	`string`	El identificador del elemento de línea del artículo en este pedido.	Sí
`listPrice`	`decimal`	El precio de lista del artículo en este pedido.	Sí
`productId`	`string`	El Store ID del producto que representa el elemento de línea en el catálogo de Microsoft Store. Un ejemplo de Store ID de un producto es 9NBLGGH42CFD.	Sí
`productType`	`string`	El tipo del producto. Los valores admitidos son `Durable`, `Application` y `UnmanagedConsumable`.	Sí
`quantity`	`int`	La cantidad del artículo pedido.	Sí
`retailPrice`	`decimal`	El precio de venta del artículo pedido.	Sí
`revenueRecognitionState`	`string`	El estado de reconocimiento de ingresos.	Sí
`skuId`	`string`	El Store ID de la SKU del elemento de línea en el catálogo de Microsoft Store. Un ejemplo de Store ID de una SKU es 0010.	Sí
`taxAmount`	`decimal`	El importe de impuestos del elemento de línea.	Sí
`taxType`	`string`	El tipo de impuesto de los impuestos aplicables.	Sí
`Title`	`string`	El título localizado del elemento de línea.	Sí
`totalAmount`	`decimal`	El importe total de la compra del elemento de línea, impuestos incluidos.	Sí

El objeto IdentityV8 contiene los siguientes parámetros.

Parámetro	Tipo	Descripción	Obligatorio
`identityType`	`string`	Contiene el valor `"pub"`.	Sí
`identityValue`	`string`	El valor de cadena del publisherUserId de la clave de identificador de User Store especificada.	Sí

Ejemplo de respuesta

Content-Length: 1203
Content-Type: application/json
MS-CorrelationId: fb2e69bc-f26a-4aab-a823-7586c19f5762
MS-RequestId: c1bc832c-f742-47e4-a76c-cf061402f698
MS-CV: XfrNWLQlEaux6Mt.8
MS-ServerId: 030032362
Date: Tue, 13 Oct 2019 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	Unauthorized	AuthenticationTokenInvalid	El token de acceso de Microsoft Entra ID no es válido. En algunos casos, los detalles de ServiceError contienen más información, por ejemplo, cuando el token ha expirado o falta la notificación appid.
401	Unauthorized	PartnerAadTicketRequired	No se pasó un token de acceso de Microsoft Entra ID al servicio en el encabezado de autorización.
401	Unauthorized	InconsistentClientId	La notificación `clientId` de la clave de identificador de User Store y el valor `appid` del token de acceso 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.

Microsoft Store APIs

Requisitos previos

Solicitud

Sintaxis de la solicitud

Encabezado de la solicitud

Cuerpo de la solicitud

Ejemplo de solicitud

Respuesta

Cuerpo de la respuesta

Ejemplo de respuesta

Códigos de error

Artículos relacionados

​Requisitos previos

​Solicitud

​Sintaxis de la solicitud

​Encabezado de la solicitud

​Cuerpo de la solicitud

​Ejemplo de solicitud

​Respuesta

​Cuerpo de la respuesta

​Ejemplo de respuesta

​Códigos de error

​Artículos relacionados

Requisitos previos

Solicitud

Sintaxis de la solicitud

Encabezado de la solicitud

Cuerpo de la solicitud

Ejemplo de solicitud

Respuesta

Cuerpo de la respuesta

Ejemplo de respuesta

Códigos de error

Artículos relacionados