> ## 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/v8.0/purchases/grant

> API purchases/grant v8 da Microsoft Store que permite que um serviço de jogo conceda um aplicativo ou complemento gratuito diretamente à conta de um usuário usando autenticação do Microsoft Entra ID.

Use a API de compra da Microsoft Store para conceder um aplicativo ou complemento gratuito à conta de um usuário.

Somente produtos gratuitos podem ser concedidos diretamente à conta de um usuário.
Tentativas de concessão de produtos pagos retornam um erro.

## Pré-requisitos

Revise os [Pré-requisitos para APIs de serviço a serviço](https://learn.microsoft.com/reference/service-to-service-nav#prerequisites-for-service-to-service-apis).

Esta API oferece suporte somente ao tipo de autenticação Microsoft Entra ID.

Se a configuração do produto não estiver publicada no Partner Center, a chamada poderá ter êxito, mas não retornar resultados.

## Solicitação

### Sintaxe da solicitação

| Método | URI da solicitação |
| - | - |
| `POST` | `https://purchase.mp.microsoft.com/v7.0/purchases/grant` |

### Cabeçalho da solicitação

| Cabeçalho | Tipo | Descrição |
| - | - | - |
| `Authorization` | `string` | Obrigatório. O token de acesso de serviço do Microsoft Entra ID no formato `Bearer` \<*token*>. |
| `Host` | `string` | Deve ser definido com o valor `purchase.mp.microsoft.com`. |
| `Content-Length` | `number` | O comprimento do corpo da solicitação. |
| `Content-Type` | `string` | Especifica o tipo de solicitação e de resposta. Atualmente, o único valor com suporte é `application/json`. |

### Corpo da solicitação

| Parâmetro | Tipo | Descrição | Obrigatório |
| - | - | - | - |
| `availabilityId` | `string` | A ID de disponibilidade do produto a ser concedido do catálogo da Microsoft Store. | Sim |
| `b2bKey` | `string` | A [chave de User Store ID](https://learn.microsoft.com/reference/xstore-requesting-a-userstoreid#step-4-create-a-user-store-id-key) que representa a identidade do usuário ao qual você deseja conceder um produto. | Sim |
| `devOfferId` | `string` | Uma ID de oferta especificada pelo desenvolvedor que aparece no item de Collection após a compra. | Não |
| `language` | `string` | O idioma do usuário. | Sim |
| `market` | `string` | O mercado do usuário. | Sim |
| `orderId` | `GUID` | Um GUID gerado para o pedido. Esse valor é exclusivo para o usuário, mas não precisa ser exclusivo entre todos os pedidos. | Sim |
| `productId` | `string` | A [Store ID](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#store-ids) do [produto](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#products-skus-and-availabilities) no catálogo da Microsoft Store. Um exemplo de Store ID de um produto é 9NBLGGH42CFD. | Sim |
| `quantity` | `int` | A quantidade a ser comprada. Atualmente, o único valor com suporte é 1. Se não for especificado, o padrão será 1. | Não |
| `skuId` | `string` | A [Store ID](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#store-ids) do [SKU](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#products-skus-and-availabilities) do produto no catálogo da Microsoft Store. Um exemplo de Store ID de um SKU é 0010. | Sim |
| `sbx` | `string` | Valor opcional para autenticação com UserStoreIds que especifica a área restrita à qual os resultados devem se limitar. Sem esse valor, o padrão é a área restrita RETAIL. A autenticação por X-Token não precisa desse valor, pois a área restrita é especificada no X-Token. | Não |

### Exemplo de solicitação

```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"
}
```

## Resposta

### Corpo da resposta

| Parâmetro | Tipo | Descrição | Obrigatório |
| - | - | - | - |
| `clientContext` | `ClientContextV8` | As informações contextuais do cliente para o pedido. Atribuído ao valor `clientID` do token do Microsoft Entra ID. | Sim |
| `createdtime` | `datetimeoffset` | A hora em que o pedido foi criado. | Sim |
| `currencyCode` | `string` | O código de moeda de `totalAmount` e `totalTaxAmount`. N/A para itens gratuitos. | Sim |
| `friendlyName` | `string` | O nome amigável do pedido. N/A para pedidos feitos usando a API de compra da Microsoft Store. | Sim |
| `isPIRequired` | `boolean` | Indica se um meio de pagamento (PI) é necessário como parte do pedido de compra. | Sim |
| `language` | `string` | A ID de idioma do pedido (por exemplo, "en"). | Sim |
| `market` | `string` | A ID de mercado do pedido (por exemplo, "US"). | Sim |
| `orderId` | `string` | Uma ID que identifica o pedido de um usuário específico. | Sim |
| `orderLineItems` | `list<OrderLineItemV8>` | A lista de itens de linha do pedido. Normalmente, há um item de linha por pedido. | Sim |
| `orderState` | `string` | O estado do pedido. Os estados válidos são `Editing`, `CheckingOut`, `Pending`, `Purchased`, `Refunded`, `ChargedBack` e `Canceled`. | Sim |
| `orderValidityEndTime` | `string` | Quando o preço do pedido termina; N/A para aplicativos gratuitos. | Sim |
| `orderValidityStartTime` | `string` | Quando o preço do pedido começa; N/A para aplicativos gratuitos. | Sim |
| `purchaser` | `IdentityV6` | Um objeto que descreve a identidade do comprador. | Sim |
| `totalAmount` | `decimal` | O valor total da compra de todos os itens do pedido, incluindo impostos. | Sim |
| `totalAmountBeforeTax` | `decimal` | O valor total da compra de todos os itens do pedido antes dos impostos. | Sim |
| `totalChargedToCsvTopOffPI` | `decimal` | Se estiver usando um meio de pagamento separado e valor armazenado (CSV, valores separados por vírgula), o valor cobrado do CSV. | Sim |
| `totalTaxAmount` | `decimal` | O valor total de impostos de todos os itens de linha. | Sim |

O objeto `ClientContext` contém os parâmetros a seguir.

| Parâmetro | Tipo | Descrição | Obrigatório |
| - | - | - | - |
| `client` | `string` | A ID do cliente que criou o pedido. | Não |

O objeto `OrderLineItemV8` contém os parâmetros a seguir.

| Parâmetro | Tipo | Descrição | Obrigatório |
| - | - | - | - |
| `agent` | `IdentityV8` | O agente que editou o item de linha pela última vez. Para obter mais informações sobre esse objeto, confira a tabela a seguir. | Não |
| `availabilityId` | `string` | A ID de disponibilidade do produto a ser comprado do catálogo da Microsoft Store. | Sim |
| `beneficiary` | `IdentityV8` | A identidade do beneficiário do pedido. | Não |
| `billingState` | `string` | O estado de cobrança do pedido. Definido como `Charged` quando concluído. | Não |
| `campaignId` | `string` | A ID da campanha deste pedido. | Não |
| `currencyCode` | `string` | O código de moeda usado para os detalhes de preço. | Sim |
| `description` | `string` | Uma descrição localizada do item de linha. | Sim |
| `devofferId` | `string` | A ID da oferta do pedido específico, se houver. | Não |
| `fulfillmentDate` | `datetimeoffset` | A data em que o fulfillment ocorreu. | Não |
| `fulfillmentState` | `string` | O estado do fulfillment do item. Definido como `Fulfilled` quando concluído. | Não |
| `isPIRequired` | `boolean` | Indica se um meio de pagamento é necessário para este item de linha. | Sim |
| `isTaxIncluded` | `boolean` | Indica se os impostos estão incluídos nos detalhes de preço do item. | Sim |
| `legacyBillingOrderId` | `string` | A ID de cobrança herdada. | Não |
| `lineItemId` | `string` | A ID do item de linha do item neste pedido. | Sim |
| `listPrice` | `decimal` | O preço de tabela do item neste pedido. | Sim |
| `productId` | `string` | A [Store ID](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#store-ids) do [produto](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#products-skus-and-availabilities) que representa o item de linha no catálogo da Microsoft Store. Um exemplo de Store ID de um produto é 9NBLGGH42CFD. | Sim |
| `productType` | `string` | O tipo do produto. Os valores com suporte são `Durable`, `Application` e `UnmanagedConsumable`. | Sim |
| `quantity` | `int` | A quantidade do item pedido. | Sim |
| `retailPrice` | `decimal` | O preço de varejo do item pedido. | Sim |
| `revenueRecognitionState` | `string` | O estado de reconhecimento de receita. | Sim |
| `skuId` | `string` | A [Store ID](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#store-ids) do [SKU](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#products-skus-and-availabilities) do item de linha no catálogo da Microsoft Store. Um exemplo de Store ID de um SKU é 0010. | Sim |
| `taxAmount` | `decimal` | O valor do imposto do item de linha. | Sim |
| `taxType` | `string` | O tipo de imposto dos impostos aplicáveis. | Sim |
| `Title` | `string` | O título localizado do item de linha. | Sim |
| `totalAmount` | `decimal` | O valor total da compra do item de linha, incluindo impostos. | Sim |

O objeto `IdentityV8` contém os parâmetros a seguir.

| Parâmetro | Tipo | Descrição | Obrigatório |
| - | - | - | - |
| `identityType` | `string` | Contém o valor `"pub"`. | Sim |
| `identityValue` | `string` | O valor de cadeia de caracteres do *publisherUserId* da chave de User Store ID especificada. | Sim |

### Exemplo de resposta

```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 erro

| Código | Erro | Código de erro interno | Descrição |
| - | - | - | - |
| 401 | Unauthorized | AuthenticationTokenInvalid | O token de acesso do Microsoft Entra ID é inválido. Em alguns casos, os detalhes de ServiceError contêm mais informações, como quando o token expirou ou a declaração *appid* está ausente. |
| 401 | Unauthorized | PartnerAadTicketRequired | Um token de acesso do Microsoft Entra ID não foi passado ao serviço no cabeçalho de autorização. |
| 401 | Unauthorized | InconsistentClientId | A declaração `clientId` na chave de User Store ID e o `appid` no token de acesso não correspondem. |
| 400 | BadRequest | InvalidParameter | Os detalhes contêm informações sobre o corpo da solicitação e quais campos têm um valor inválido. |

## Artigos relacionados

[Gerenciar produtos dos seus serviços](https://learn.microsoft.com/reference/service-to-service-nav)

[Solicitar uma User Store ID para autenticação de serviço a serviço](https://learn.microsoft.com/reference/xstore-requesting-a-userstoreid)

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


## Related topics

- [purchase.mp.microsoft.com/v8.0/purchases/grant](/reference/microsoft-store-apis/xstore-v8-grant.md)
- [purchase.mp.microsoft.com/v8.0/b2b/orders/query](/reference/microsoft-store-apis/xstore-v8-clawbackv1.md)
- [purchase.mp.microsoft.com/v8.0/b2b/recurrences/query](/reference/microsoft-store-apis/xstore-v8-recurrence-query.md)