purchase.mp.microsoft.com/v8.0/b2b/orders/query
此 API 已弃用，不再用于退款检测。请改用 Clawback 事件服务，如从你的服务管理退款和拒付中所述。
purchase.mp.microsoft.com/v8.0/b2b/orders/query API 允许游戏服务查询用户在过去 90 天内的可消耗购买。它还会返回一些在 Collections 查询中不可用的字段，例如用于支持工作流的 ShortOrderID。
先决条件
请查看服务到服务 API 的先决条件。 此 API 仅支持 Microsoft Entra ID 身份验证类型。 如果产品配置未在合作伙伴中心发布，API 可能会成功但不返回任何结果。请求
请求语法
| 方法 | 请求 URI |
|---|---|
POST | https://purchase.mp.microsoft.com/v8.0/b2b/orders/query |
请求标头
| 标头 | 类型 | 说明 |
|---|---|---|
Authorization | string | 必需。形式为 Bearer <token> 的 Microsoft Entra ID 服务访问令牌。 |
Host | string | 必须设置为值 purchase.mp.microsoft.com。 |
Content-Length | number | 请求正文的长度。 |
Content-Type | string | 指定请求和响应类型。目前唯一支持的值是 application/json。 |
请求正文
| 参数 | 类型 | 说明 | 必需 |
|---|---|---|---|
b2bKey | string | 表示你正在请求的用户身份的 User Purchase ID。请参阅用户 Store ID 密钥。 | 是 |
lineItemStateFilter | list<string> | 指定要在查询结果中返回的项状态。有关有效值列表，请参阅行项状态。 | 否 |
sbx | string | 使用 UserStoreIds 进行身份验证时的可选值，用于指定结果应作用于的沙盒。若无此值，默认为 RETAIL 沙盒。X-Token 身份验证不需要此值，因为沙盒已在 X-Token 中指定。 | 否 |
行项状态
| 值 | 说明 |
|---|---|
Purchased | 处于活动（良好）状态的可消耗购买。此状态包括未履行和已履行的可消耗产品。 |
Revoked | 已由游戏服务履行或消耗，随后由用户退款的可消耗购买。 |
Refunded | 在履行或消耗之前已向用户退款的可消耗购买。 |
请求示例
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"
}
响应
响应正文
| 参数 | 类型 | 说明 | 必需 |
|---|---|---|---|
items | list<PurchasedItem> | 指定用户的产品数组。有关详细信息，请参阅下表。 | 是 |
PurchasedItem 对象包含以下参数。
| 参数 | 类型 | 说明 | 必需 |
|---|---|---|---|
orderId | GUID | 购买订单号的长格式 ID。Collections 和其他服务使用的 OrderID。 | 是 |
shortOrderId | GUID | 购买订单号的短格式 ID。最终用户在其购买历史和确认电子邮件中看到的订单号。用户向你的支持人员提供此 ID 以表示其购买。 | 否 |
orderLineItems | list<OrderLineItem> | 与用户购买 OrderId 中可消耗产品相关的其他信息数组。有关详细信息，请参阅下表。 | 是 |
orderPurchasedDate | datetime | 可消耗产品被购买的 UTC 日期和时间。 | 是 |
orderRefundedDate | datetime | 可消耗产品被退款的 UTC 日期和时间。此值需要几个小时才会显示在已退款项上。 | 否 |
OrderLineItem 对象包含以下参数。
| 参数 | 类型 | 说明 | 必需 |
|---|---|---|---|
lineItemId | GUID | 标识购买订单中可消耗产品的 lineItem（订单可能有多个 lineItemId 以适应购物车方案） | 是 |
lineItemState | string | 此特定可消耗购买的状态。请参阅行项状态。 | 是 |
productId | string | 也称为 Microsoft Store 目录中产品的 Store ID。产品的 Store ID 示例为 9NBLGGH42CFD。 | 是 |
quantity | number | 订单中购买该项时的数量。 | 是 |
skuId | string | 如果 Microsoft Store 目录中该产品有多个产品/服务的话，特定 SKU 的标识符。SKU 的 Store ID 示例为 0010。 | 是 |
wasConsumableQuantityRevoked | bool | 指示退款发生时是否能够从用户的商店帐户中移除所购数量。 | 否 |
响应示例
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"
}
]
}
响应示例说明
在此示例中，用户购买了可消耗产品9MT5TGW893HV 共五次。有两次购买为 Revoked，表示它们在被消耗_之后_被退款。要进行接近实时的退款检测，请使用从你的服务管理退款和拒付中所述的 Clawback 事件流。