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

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. 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 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 do produto 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 do SKU 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

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 do produto 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 do SKU 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

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.

Porting

Build Paths

Pré-requisitos

Solicitação

Sintaxe da solicitação

Cabeçalho da solicitação

Corpo da solicitação

Exemplo de solicitação

Resposta

Corpo da resposta

Exemplo de resposta

Códigos de erro

Artigos relacionados

​Pré-requisitos

​Solicitação

​Sintaxe da solicitação

​Cabeçalho da solicitação

​Corpo da solicitação

​Exemplo de solicitação

​Resposta

​Corpo da resposta

​Exemplo de resposta

​Códigos de erro

​Artigos relacionados

Pré-requisitos

Solicitação

Sintaxe da solicitação

Cabeçalho da solicitação

Corpo da solicitação

Exemplo de solicitação

Resposta

Corpo da resposta

Exemplo de resposta

Códigos de erro

Artigos relacionados