Compartilhar via

Conceder produtos gratuitos

  • Artigo

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 este método, você precisará de:

  • Um token de acesso do Azure AD que tem o valor https://onestore.microsoft.comdo URI da audiência.
  • 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 Gerenciar direitos de produto de um serviço.

Solicitar

Sintaxe da solicitação

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

Cabeçalho da solicitação

Cabeçalho Tipo Descrição
Autorização string Obrigatório. O token de acesso do Azure AD no Token<de portador> do formulário.
Host string Deve ser definido com o valor purchase.mp.microsoft.com.
Content-Length número O tamanho do corpo da solicitação.
Tipo de conteúdo string Especifica o tipo de solicitação e 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 concedida do catálogo da Microsoft Store. Sim
b2bChave string A chave de ID da Microsoft Store que representa a identidade do usuário para o qual você deseja conceder um produto. Sim
devOfferId string Uma ID de oferta especificada pelo desenvolvedor que aparecerá no item Coleção após a compra.
linguagem 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 deve ser exclusivo para o usuário, mas não precisa ser exclusivo em todos os pedidos. Sim
productId string A ID da Loja do produto no catálogo da Microsoft Store. Um exemplo de ID da loja para um produto é 9NBLGGH42CFD. Sim
quantity int A quantidade a ser comprada. Atualmente, o único valor suportado é 1. Se não for especificado, o padrão será 1. Não
skuId string A ID da Loja para o SKU do produto no catálogo da Microsoft Store. Um exemplo de ID da loja para um 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
clientContext ClientContextV6 Informações contextuais do cliente para este pedido. Isso será atribuído ao valor clientID do token do Azure AD. Sim
tempo criado datetimeoffset A hora em que o pedido foi criado. Sim
currencyCode string Código de moeda para 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 instrumento de pagamento (PI) é necessário como parte da ordem de compra. Sim
linguagem string A ID do idioma do pedido (por exemplo, "en"). Sim
market string O ID de mercado da ordem (por exemplo, "US"). Sim
orderId string Um ID que identifica o pedido de um usuário específico. Sim
orderLineItems listar<OrderLineItemV6> A lista de itens de linha para o pedido. Normalmente, há 1 item de linha por pedido. Sim
Estado da ordem string O estado da ordem. Os estados válidos são Editando, Check-out, Pendente, Comprado, Reembolsado, Estorno e Cancelado. Sim
orderValidityEndTime string A última vez que o preço do pedido é válido antes de ser enviado. N/A para aplicativos gratuitos. Sim
orderValidityStartTime string A primeira vez que o preço do pedido é válido antes de ser enviado. N/A para aplicativos gratuitos. Sim
comprador IdentidadeV6 Um objeto que descreve a identidade do comprador. Sim
totalAmount decimal O valor total da compra de todos os itens no pedido, incluindo impostos. Sim
totalAmountBeforeTax decimal Valor total da compra de todos os itens no pedido antes de impostos. Sim
totalChargedToCsvTopOffPI decimal Se estiver usando um instrumento de pagamento e valor armazenado (CSV) separados, o valor cobrado do CSV. Sim
totalTaxAmount decimal O valor total do imposto para 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 O ID do cliente que criou o pedido. Não

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

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
availabilityId string 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 ordem. Não
billingState string O estado de faturamento do pedido. Isso é definido como Cobrado quando concluído. Não
campaignId string O ID da campanha para este pedido. Não
currencyCode string O código da moeda usado para detalhes de preço. Sim
descrição string Uma descrição localizada do item de linha. Sim
devofferId string A ID da oferta para o pedido específico, se presente. Não
data de cumprimento datetimeoffset A data em que ocorreu o cumprimento. Não
estado de cumprimento string O estado do cumprimento deste item. Isso é definido como Cumprido quando concluído. Não
isPIRequired boolean Indica se um instrumento de pagamento é necessário para essa partida individual. Sim
isTaxIncluded boolean Indicado se o imposto está incluído nos detalhes de preço do item. Sim
legacyBillingOrderId string O ID de cobrança herdado. Não
lineItemId string O código do item de linha para o item nesta ordem. Sim
listPreço decimal O preço sugerido do item nesta ordem. Sim
productId string A ID da Loja do produto que representa o item de linha no catálogo da Microsoft Store. Um exemplo de ID da loja para 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
varejoPreço decimal O preço de varejo do item pedido. Sim
revenueRecognitionState string O estado de reconhecimento de receita. Sim
skuId string A ID da Loja para o SKU do item de linha no catálogo da Microsoft Store. Um exemplo de ID da loja para um SKU é 0010. Sim
taxMontante decimal O valor do imposto para o item de linha. Sim
taxType string O tipo de imposto para os impostos aplicáveis. Sim
Título 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 IdentityV6 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 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 do Erro

Código Erro Código de erro interno Descrição
401 Não Autorizado AuthenticationTokenInvalid 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 declaração appid está ausente.
401 Não Autorizado PartnerAadTicketRequired 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 InconsistenteClientId 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 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.