purchase.mp.microsoft.com/v8.0/b2b/orders/query

Esta API foi preterida para detecção de reembolsos. Em vez disso, use o serviço de eventos de Clawback, conforme descrito em Gerenciar reembolsos e estornos do seu serviço.

A API purchase.mp.microsoft.com/v8.0/b2b/orders/query permite que um serviço de jogo consulte as compras de consumíveis de um usuário dos últimos 90 dias. Ela também retorna campos que não estão disponíveis em uma consulta de Collections, como ShortOrderID para fluxos de trabalho de suporte.

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 API 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/v8.0/b2b/orders/query`

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
`b2bKey`	`string`	A User Purchase ID que representa a identidade do usuário para o qual você está fazendo a solicitação. Confira Chave de User Store ID.	Sim
`lineItemStateFilter`	`list<string>`	Especifica quais estados de item retornar nos resultados da consulta. Para obter uma lista de valores válidos, confira Estados de item de linha.	Não
`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

Estados de item de linha

Valor	Descrição
`Purchased`	Compra de consumível em estado ativo (válido). Esse estado inclui consumíveis com e sem fulfillment.
`Revoked`	Compra de consumível com fulfillment feito ou consumida pelo serviço de jogo e, posteriormente, reembolsada pelo usuário.
`Refunded`	Compra de consumível reembolsada ao usuário antes de ter o fulfillment feito ou ser consumida.

Exemplo de solicitação

POST https://purchase.mp.microsoft.com/v8.0/b2b/orders/query HTTP/1.1
Host: purchase.mp.microsoft.com
Authorization: Bearer [Microsoft Entra bearer token]
User-Agent: MicrosoftStoreServiceSample_1.21.9.0
Content-Type: application/json; charset=utf-8
Content-Length: 2032

{
  "b2bKey":"[UserPurchaseId]",
  "lineItemStateFilter": [
    "Purchased",
    "Revoked",
    "Refunded"],
  "sbx": "XDKS.1"
}

Resposta

Corpo da resposta

Parâmetro	Tipo	Descrição	Obrigatório
`items`	`list<PurchasedItem>`	Uma matriz de produtos do usuário especificado. Para obter mais informações, confira a tabela a seguir.	Sim

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

Parâmetro	Tipo	Descrição	Obrigatório
`orderId`	`GUID`	ID em formato longo do nº do pedido da compra. OrderID usada por Collections e outros serviços.	Sim
`shortOrderId`	`GUID`	ID em formato curto do nº do pedido da compra. Nº do pedido que o usuário final vê no histórico de compras e nos emails de confirmação. Os usuários fornecem essa ID à sua equipe de suporte para identificar a compra.	Não
`orderLineItems`	`list<OrderLineItem>`	Uma matriz de informações adicionais relacionadas ao consumível dentro da OrderId de compra do usuário. Para obter mais informações, confira a tabela a seguir.	Sim
`orderPurchasedDate`	`datetime`	A data e a hora UTC em que o consumível foi comprado.	Sim
`orderRefundedDate`	`datetime`	A data e a hora UTC em que o consumível foi reembolsado. Esse valor leva algumas horas para aparecer em um item reembolsado.	Não

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

Parâmetro	Tipo	Descrição	Obrigatório
`lineItemId`	`GUID`	Identifica o lineItem dentro do pedido de compra do consumível (os pedidos podem ter várias lineItemIds em cenários de carrinho de compras)	Sim
`lineItemState`	`string`	O estado desta compra de consumível específica. Confira Estados de item de linha.	Sim
`productId`	`string`	Também conhecida como Store ID do produto no catálogo da Microsoft Store. Um exemplo de Store ID de um produto é 9NBLGGH42CFD.	Sim
`quantity`	`number`	A quantidade do item quando comprado no pedido.	Sim
`skuId`	`string`	O identificador de SKU específico, se houver várias ofertas do produto no catálogo da Microsoft Store. Um exemplo de Store ID de um SKU é 0010.	Sim
`wasConsumableQuantityRevoked`	`bool`	Indica se foi possível remover a quantidade comprada da conta da loja do usuário quando o reembolso ocorreu.	Não

Exemplo de resposta

HTTP/1.1 200 OK
Content-Length: 1042
Content-Type: application/json
MS-CorrelationId: b5157f23-7f26-4e0b-8f06-07733bd09355
MS-RequestId: 2b0933bc-19f7-4f96-bb47-2602491fed1f
MS-CV: OAIoYIzDJkO2Knp.7
MS-ServerId: 1
Date: Tue, 30 Jun 2020 18:29:22 GMT
 
{
    "items": [
        {
            "orderId": "3c1ad7bc-b0c2-442c-aad4-46d8d0e0184e",
            "shortOrderId": "8483143756",
            "orderLineItems": [
                {
                    "lineItemId": "febdd51b-97aa-45fc-bf46-0120eacbf8aa",
                    "lineItemState": "Purchased",
                    "productId": "9MT5TGW893HV",
                    "quantity": 1,
                    "skuId": "0010",
                    "wasConsumableQuantityRevoked": false
                }
            ],
            "orderPurchasedDate": "2021-06-12T23:57:51.1415104+00:00"
        },
        {
            "orderId": "75bf81ec-7c31-46f9-9828-6ac61464e553",
            "shortOrderId": "3145294485",
            "orderLineItems": [
                {
                    "lineItemId": "ad7adfc5-be76-4548-aede-155084490044",
                    "lineItemState": "Purchased",
                    "productId": "9MT5TGW893HV",
                    "quantity": 1,
                    "skuId": "0010",
                    "wasConsumableQuantityRevoked": false
                }
            ],
            "orderPurchasedDate": "2021-06-13T23:57:51.1415104+00:00"
        },
        {
            "orderId": "b9d6d1fd-3e68-423b-85fa-feea1ee125b3",
            "shortOrderId": "7620137155",
            "orderLineItems": [
                {
                    "lineItemId": "eb565041-6e1f-4210-97a3-54a2ab80f49e",
                    "lineItemState": "Revoked",
                    "productId": "9MT5TGW893HV",
                    "quantity": 1,
                    "skuId": "0010",
                    "wasConsumableQuantityRevoked": false
                }
            ],
            "orderPurchasedDate": "2021-06-142T23:57:51.1415104+00:00",
            "orderRefundedDate": "2021-06-162T10:05:35.9634676+00:00"
        },
        {
            "orderId": "cda65a53-30b0-4e19-8ec1-c08219174e45",
            "shortOrderId": "5993204763",
            "orderLineItems": [
                {
                    "lineItemId": "a30b4285-c456-4486-8048-a9f5b5231b76",
                    "lineItemState": "Revoked",
                    "productId": "9MT5TGW893HV",
                    "quantity": 1,
                    "skuId": "0010",
                    "wasConsumableQuantityRevoked": false
                }
            ],
            "orderPurchasedDate": "2021-06-152T23:57:51.1415104+00:00",
            "orderRefundedDate": "2021-06-162T10:05:35.9634676+00:00"
        },
        {
            "orderId": "f1da6d12-8b0d-4dc1-8aca-c52fcece582a",
            "shortOrderId": "8768763421",
            "orderLineItems": [
                {
                    "lineItemId": "7da73274-b4bc-4a4f-bb93-e49618f7a7d7",
                    "lineItemState": "Purchased",
                    "productId": "9MT5TGW893HV",
                    "quantity": 1,
                    "skuId": "0010",
                    "wasConsumableQuantityRevoked": false
                }
            ],
            "orderPurchasedDate": "2021-06-16T23:57:51.1415104+00:00"
        }
    ]
}

Explicação do exemplo de resposta

Neste exemplo, o usuário comprou o consumível 9MT5TGW893HV cinco vezes. Duas compras estão como Revoked, o que significa que foram reembolsadas depois de serem consumidas. Para detecção de reembolsos quase em tempo real, use o fluxo de eventos de Clawback descrito em Gerenciar reembolsos e estornos do seu serviço.

Microsoft Store APIs

purchase.mp.microsoft.com/v8.0/b2b/orders/query

purchase.mp.microsoft.com/v8.0/b2b/orders/query

Pré-requisitos

Solicitação

Sintaxe da solicitação

Cabeçalho da solicitação

Corpo da solicitação

Estados de item de linha

Exemplo de solicitação

Resposta

Corpo da resposta

Exemplo de resposta

Explicação do exemplo de resposta

Artigos relacionados

​purchase.mp.microsoft.com/v8.0/b2b/orders/query

​Pré-requisitos

​Solicitação

​Sintaxe da solicitação

​Cabeçalho da solicitação

​Corpo da solicitação

​Estados de item de linha

​Exemplo de solicitação

​Resposta

​Corpo da resposta

​Exemplo de resposta

​Explicação do exemplo de resposta

​Artigos relacionados

purchase.mp.microsoft.com/v8.0/b2b/orders/query

Pré-requisitos

Solicitação

Sintaxe da solicitação

Cabeçalho da solicitação

Corpo da solicitação

Estados de item de linha

Exemplo de solicitação

Resposta

Corpo da resposta

Exemplo de resposta

Explicação do exemplo de resposta

Artigos relacionados