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

Esta API está en desuso para la detección de reembolsos. En su lugar, use el servicio de eventos de Clawback como se describe en Administración de reembolsos y contracargos desde su servicio.

La API purchase.mp.microsoft.com/v8.0/b2b/orders/query permite a un servicio de juego consultar las compras de consumibles de un usuario de los últimos 90 días. También devuelve campos que no están disponibles en una consulta de Collections, como ShortOrderID para flujos de trabajo de soporte técnico.

Requisitos previos

Revise los Requisitos previos para las APIs de servicio a servicio. Esta API solo admite el tipo de autenticación de Microsoft Entra ID. Si la configuración del producto no está publicada en Partner Center, la API puede completarse correctamente pero no devolver resultados.

Solicitud

Sintaxis de la solicitud

Método	URI de solicitud
`POST`	`https://purchase.mp.microsoft.com/v8.0/b2b/orders/query`

Encabezado de solicitud

Encabezado	Tipo	Descripción
`Authorization`	`string`	Obligatorio. El token de acceso de servicio de Microsoft Entra ID con el formato `Bearer <token>`.
`Host`	`string`	Debe establecerse en el valor `purchase.mp.microsoft.com`.
`Content-Length`	`number`	Longitud del cuerpo de la solicitud.
`Content-Type`	`string`	Especifica el tipo de solicitud y respuesta. Actualmente, el único valor admitido es `application/json`.

Cuerpo de la solicitud

Parámetro	Tipo	Descripción	Obligatorio
`b2bKey`	`string`	El identificador de compra de usuario (User Purchase ID) que representa la identidad del usuario para el que se realiza la solicitud. Consulte Clave de User Store ID.	Sí
`lineItemStateFilter`	`list<string>`	Especifica qué estados de artículo se devuelven en los resultados de la consulta. Para obtener una lista de los valores válidos, consulte Estados de los artículos de línea.	No
`sbx`	`string`	Valor opcional para la autenticación con UserStoreIds que especifica el sandbox al que se deben limitar los resultados. Sin este valor, el valor predeterminado es el sandbox RETAIL. La autenticación con X-Token no necesita este valor, ya que el sandbox se especifica dentro del X-Token.	No

Estados de los artículos de línea

Valor	Descripción
`Purchased`	Compra de consumible en estado activo (correcto). Este estado incluye consumibles consumidos y sin consumir.
`Revoked`	Compra de consumible consumida por el servicio de juego y reembolsada posteriormente por el usuario.
`Refunded`	Compra de consumible reembolsada al usuario antes de ser consumida.

Ejemplo de solicitud

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

Respuesta

Cuerpo de la respuesta

Parámetro	Tipo	Descripción	Obligatorio
`items`	`list<PurchasedItem>`	Matriz de productos del usuario especificado. Para obtener más información, consulte la tabla siguiente.	Sí

El objeto PurchasedItem contiene los parámetros siguientes.

Parámetro	Tipo	Descripción	Obligatorio
`orderId`	`GUID`	Identificador en formato largo del número de pedido de la compra. OrderID usado por Collections y otros servicios.	Sí
`shortOrderId`	`GUID`	Identificador en formato corto del número de pedido de la compra. Número de pedido que el usuario final ve en su historial de compras y en los correos electrónicos de confirmación. Los usuarios proporcionan este identificador a su personal de soporte técnico para representar su compra.	No
`orderLineItems`	`list<OrderLineItem>`	Matriz de información adicional relacionada con el consumible dentro del OrderId de compra del usuario. Para obtener más información, consulte la tabla siguiente.	Sí
`orderPurchasedDate`	`datetime`	Fecha y hora UTC en que se compró el consumible.	Sí
`orderRefundedDate`	`datetime`	Fecha y hora UTC en que se reembolsó el consumible. Este valor tarda unas horas en aparecer en un artículo reembolsado.	No

El objeto OrderLineItem contiene los parámetros siguientes.

Parámetro	Tipo	Descripción	Obligatorio
`lineItemId`	`GUID`	Identifica el lineItem dentro del pedido de compra del consumible (los pedidos pueden tener varios lineItemIds en escenarios de carro de la compra)	Sí
`lineItemState`	`string`	Estado de esta compra de consumible específica. Consulte Estados de los artículos de línea.	Sí
`productId`	`string`	También denominado Store ID del producto dentro del catálogo de Microsoft Store. Un ejemplo de Store ID de un producto es 9NBLGGH42CFD.	Sí
`quantity`	`number`	Cantidad del artículo cuando se compró en el pedido.	Sí
`skuId`	`string`	Identificador de SKU específico si hay varias ofertas del producto en el catálogo de Microsoft Store. Un ejemplo de Store ID de una SKU es 0010.	Sí
`wasConsumableQuantityRevoked`	`bool`	Indica si la cantidad comprada se pudo quitar de la cuenta de la Store del usuario cuando se produjo el reembolso.	No

Ejemplo de respuesta

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

Explicación del ejemplo de respuesta

En este ejemplo, el usuario compró el consumible 9MT5TGW893HV cinco veces. Dos compras están en estado Revoked, lo que significa que se reembolsaron después de ser consumidas. Para la detección de reembolsos casi en tiempo real, use el flujo de eventos de Clawback descrito en Administración de reembolsos y contracargos desde su servicio.

Microsoft Store APIs

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

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

Requisitos previos

Solicitud

Sintaxis de la solicitud

Encabezado de solicitud

Cuerpo de la solicitud

Estados de los artículos de línea

Ejemplo de solicitud

Respuesta

Cuerpo de la respuesta

Ejemplo de respuesta

Explicación del ejemplo de respuesta

Artículos relacionados

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

​Requisitos previos

​Solicitud

​Sintaxis de la solicitud

​Encabezado de solicitud

​Cuerpo de la solicitud

​Estados de los artículos de línea

​Ejemplo de solicitud

​Respuesta

​Cuerpo de la respuesta

​Ejemplo de respuesta

​Explicación del ejemplo de respuesta

​Artículos relacionados

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

Requisitos previos

Solicitud

Sintaxis de la solicitud

Encabezado de solicitud

Cuerpo de la solicitud

Estados de los artículos de línea

Ejemplo de solicitud

Respuesta

Cuerpo de la respuesta

Ejemplo de respuesta

Explicación del ejemplo de respuesta

Artículos relacionados