> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> API purchases/grant de Microsoft Store v8 que permite al servicio de un juego conceder una aplicación o un complemento gratuitos directamente a la cuenta de un usuario mediante la autenticación de Microsoft Entra ID.

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](/es/publishing/xstore-commerce/xstore-authenticating-service.md).

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](/es/publishing/xstore-commerce/xstore-requesting-userstoreid.md#step-4-create-a-user-store-id-key) 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](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#store-ids) del [producto](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#products-skus-and-availabilities) 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](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#store-ids) de la [SKU](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#products-skus-and-availabilities) 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

```syntax theme={null}
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](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#store-ids) del [producto](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#products-skus-and-availabilities) 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](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#store-ids) de la [SKU](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#products-skus-and-availabilities) 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

```syntax theme={null}
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. |

## Artículos relacionados

[Administrar productos desde sus servicios](/es/publishing/xstore-commerce/xstore-authenticating-service.md)

[Solicitar un identificador de User Store para la autenticación de servicio a servicio](/es/publishing/xstore-commerce/xstore-requesting-userstoreid.md)

[Renovar una clave de identificador de Microsoft Store](https://learn.microsoft.com/reference/xstore-renew-a-user-store-id-key)


## Related topics

- [APIs de servicio de Microsoft Store (contenido)](/es/reference/microsoft-store-apis/xstore-nav.md)
- [purchase.mp.microsoft.com/v8.0/b2b/orders/query](/es/reference/microsoft-store-apis/xstore-v8-clawbackv1.md)
- [purchase.mp.microsoft.com/v8.0/b2b/clawback/sastoken](/es/reference/microsoft-store-apis/xstore-v8-clawbackv2-sastoken.md)
- [Solicitud de un User Store ID desde su servicio con tokens X u OAuth 2.0](/es/publishing/xstore-commerce/xstore-requesting-userstoreid-oauth.md)
- [Renovación de una clave de User Store ID](/es/publishing/xstore-commerce/xstore-renew-userstoreid.md)