Ofereça produtos gratuitos

2025-06-10

Use esse método na API de compra da Microsoft Store para conceder um aplicativo ou complemento gratuito (também conhecido como produto no aplicativo ou IAP) a um determinado usuário.

Atualmente, você só pode conceder produtos gratuitos. Se o serviço tentar usar esse método para conceder um produto que não é gratuito, esse método retornará um erro.

Pré-requisitos

Para usar esse método, você precisará:

Um token de acesso do Azure AD que possui o valor URI do público-alvo https://onestore.microsoft.com.
Uma chave de ID da Microsoft Store que representa a identidade do usuário para o qual você deseja conceder um produto gratuito.

Para obter mais informações, consulte Gerir direitos de produtos a partir de um serviço.

Solicitação

Sintaxe da solicitação

Método	Solicitar URI
Publicação	`https://purchase.mp.microsoft.com/v6.0/purchases/grant`

Cabeçalho da solicitação

Cabeçalho	Tipo	Descrição
Autorização	corda	Obrigatório O token de acesso do Azure AD no formato Bearer<token>.
Anfitrião	corda	Deve ser definido com o valor purchase.mp.microsoft.com.
Tamanho do conteúdo	número	O comprimento do corpo do pedido.
Tipo de conteúdo	corda	Especifica o tipo de solicitação e resposta. Atualmente, o único valor suportado é application/json.

Corpo de solicitação

Parâmetro	Tipo	Descrição	Obrigatório
Id de disponibilidade	corda	O ID de disponibilidade do produto a ser concedido a partir do catálogo da Microsoft Store.	Sim
b2bChave	corda	A chave de ID da Microsoft Store que representa a identidade do usuário para o qual você deseja conceder um produto.	Sim
devOfferId	corda	Um ID de oferta especificado pelo desenvolvedor que aparecerá no item Coleção após a compra.
Idioma	corda	O idioma do usuário.	Sim
mercado	corda	O mercado do utilizador.	Sim
ID do Pedido	Identificador Globalmente Único (GUID)	Um GUID gerado para o pedido. Esse valor deve ser exclusivo para o usuário, mas não é necessário que seja exclusivo em todos os pedidos.	Sim
productId	corda	O ID da loja para o produto no catálogo da Microsoft Store. Um exemplo de ID de loja para um produto é 9NBLGGH42CFD.	Sim
quantidade	Int	A quantidade a comprar. Atualmente, o único valor suportado é 1. Se não for especificado, o padrão será 1.	Não
skuId	corda	O ID da loja para o SKU do produto no catálogo da Microsoft Store. Um exemplo de ID de loja para uma SKU é 0010.	Sim

Exemplo de solicitação

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

Resposta

Corpo da resposta

Parâmetro	Tipo	Descrição	Obrigatório
contexto do cliente	ClientContextV6	Informações contextuais do cliente para este pedido. Isso será atribuído ao clientID valor do token do Azure AD.	Sim
data de criação	datetimeoffset	A hora em que a ordem foi criada.	Sim
código da moeda	corda	Código de moeda para o montante total e o montante total de impostos . Não aplicável para itens gratuitos.	Sim
Nome amigável	corda	O nome amigável para a ordem. N/D para pedidos realizados usando a API de compra da Microsoft Store.	Sim
éPIObrigatório	Booleano	Indica se um instrumento de pagamento (PI) é necessário como parte da ordem de compra.	Sim
Idioma	corda	O ID de idioma do pedido (por exemplo, "en").	Sim
mercado	corda	A identificação de mercado da ordem (por exemplo, "EUA").	Sim
ID do Pedido	corda	Um ID que identifica a ordem de um usuário específico.	Sim
orderLineItems	lista<OrderLineItemV6>	A lista de itens do pedido. Normalmente, há uma linha de item por pedido.	Sim
orderState	corda	O estado da ordem. Os estados válidos são de Edição, de Verificação, de Pendência, de Compra, de Reembolso, de Estorno, e de Cancelamento.	Sim
tempoFinalDeValidadeDoPedido	corda	A última vez que o preço do pedido é válido antes de ser enviado. N/D para aplicações gratuitas.	Sim
horaDeInícioDaValidadeDoPedido	corda	O preço do pedido é válido antes de ser enviado pela primeira vez. N/D para aplicações gratuitas.	Sim
comprador	IdentidadeV6	Um objeto que descreve a identidade do comprador.	Sim
Montante Total	decimais	O valor total da compra de todos os itens no pedido, incluindo impostos.	Sim
valorTotalAntesDeImpostos	decimais	Valor total de compra de todos os itens no pedido antes de impostos.	Sim
totalCobradoCsvTopOffPI	decimais	Se utilizar um instrumento de pagamento separado e um valor armazenado (CSV), o montante será cobrado do CSV.	Sim
valorTotalDeImposto	decimais	O valor total do imposto para todas as linhas de itens.	Sim

O objeto ClientContext contém os seguintes parâmetros.

Parâmetro	Tipo	Descrição	Obrigatório
cliente	corda	O ID do cliente que criou o pedido.	Não

O objeto OrderLineItemV6 contém os seguintes parâmetros.

Parâmetro	Tipo	Descrição	Obrigatório
agente	IdentidadeV6	O agente que editou o item de linha pela última vez. Para obter mais informações sobre esse objeto, consulte a tabela abaixo.	Não
Id de disponibilidade	corda	A ID de disponibilidade do produto a ser comprado no catálogo da Microsoft Store.	Sim
beneficiário	IdentidadeV6	A identidade do beneficiário da encomenda.	Não
billingState	corda	O estado de faturamento do pedido. Isso é definido como Charged quando concluído.	Não
ID de campanha	corda	O identificador da campanha para este pedido.	Não
código da moeda	corda	O código de moeda usado para detalhes de preço.	Sim
descrição	corda	Uma descrição localizada do item de linha.	Sim
devofferId	corda	O ID da oferta para o pedido específico, se disponível.	Não
Data de cumprimento	datetimeoffset	A data em que ocorreu o cumprimento.	Não
Estado de cumprimento	corda	O estado do cumprimento deste item. Isto é definido como Cumprido quando estiver concluído.	Não
isPIRequired	Booleano	Indica se um instrumento de pagamento é necessário para este item de linha.	Sim
impostoIncluído	Booleano	Indicado se o imposto está incluído nos detalhes de preço do item.	Sim
ID de Pedido de Faturação Legado	corda	O código de faturamento herdado.	Não
lineItemId	corda	O ID do item de linha para o item nesta ordem.	Sim
preço de lista	decimais	O preço de tabela do item nesta encomenda.	Sim
productId	corda	A ID do Store para o de produto que representa o item de linha no catálogo da Microsoft Store. Um exemplo de ID de loja para um produto é 9NBLGGH42CFD.	Sim
tipoDeProduto	corda	O tipo do produto. Os valores suportados são Durable, Applicatione UnmanagedConsumable.	Sim
quantidade	Int	A quantidade do item encomendado.	Sim
preço de retalho	decimais	O preço de venda ao público do artigo encomendado.	Sim
receitasReconhecimentoEstado	corda	O estado de reconhecimento de receitas.	Sim
skuId	corda	O ID da loja para o SKU do artigo de linha no catálogo da Microsoft Store. Um exemplo de ID de loja para uma SKU é 0010.	Sim
valor do imposto	decimais	O valor do imposto para o item de linha.	Sim
Tipo de Imposto	corda	O tipo de imposto para os impostos aplicáveis.	Sim
Título	corda	O título localizado do item de linha.	Sim
Montante Total	decimais	O valor total da compra do item de linha, incluindo impostos.	Sim

O objeto IdentityV6 contém os seguintes parâmetros.

Parâmetro	Tipo	Descrição	Obrigatório
tipo de identidade	corda	Contém o valor "pub".	Sim
identityValue	corda	O valor da cadeia de caracteres do publisherUserId da chave de ID da Microsoft Store especificada.	Sim

Exemplo de resposta

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 erro

Código	Erro	Código de erro interno	Descrição
401	Não autorizado	Token de Autenticação Inválido	O token de acesso do Azure AD é inválido. Em alguns casos, os detalhes do ServiceError conterão mais informações, como quando o token expirou ou a reivindicação appid está em falta.
401	Não autorizado	ParceiroAadTicketNecessário	Um token de acesso do Azure AD não foi passado para o serviço no cabeçalho de autorização.
401	Não autorizado	InconsistentClientId (ID de Cliente Inconsistente)	A declaração clientId na chave de ID da Microsoft Store no corpo da solicitação e a declaração appid no token de acesso do Azure AD no cabeçalho de autorização não coincidem.
400	Pedido Inválido	ParâmetroInválido	Os detalhes contêm informações sobre o corpo da solicitação e quais campos têm um valor inválido.