purchase.mp.microsoft.com/v8.0/b2b/orders/query
此 API 已淘汰，不再用於退款偵測。請改用收回事件服務，如從您的服務管理退款和退單中所述。
purchase.mp.microsoft.com/v8.0/b2b/orders/query API 可讓遊戲服務查詢使用者過去 90 天內的消耗品購買。它也會傳回 Collections 查詢中沒有的欄位，例如用於支援工作流程的 ShortOrderID。
必要條件
請檢閱服務對服務 API 的必要條件。 此 API 僅支援 Microsoft Entra ID 驗證類型。 如果產品設定未在 Partner Center 中發佈，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。請參閱 User 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 | 購買訂單號碼的完整格式識別碼。Collections 和其他服務所使用的 OrderID。 | 是 |
shortOrderId | GUID | 購買訂單號碼的簡短格式識別碼。終端使用者在其購買記錄和確認電子郵件中看到的訂單號碼。使用者會向您的支援人員提供此識別碼來代表其購買。 | 否 |
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 | 指出發生退款時，是否能夠從使用者的 Store 帳戶中移除所購買的數量。 | 否 |
回應範例
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，表示它們是在消耗之後才退款。如需近乎即時的退款偵測，請使用從您的服務管理退款和退單中所述的收回事件流程。