purchase.mp.microsoft.com/v8.0/b2b/orders/query
이 API는 환불 검색에서 더 이상 사용되지 않습니다. 대신 서비스에서 환불 및 지불 거절 관리에 설명된 대로 Clawback 이벤트 서비스를 사용하세요.
purchase.mp.microsoft.com/v8.0/b2b/orders/query API를 사용하면 게임 서비스가 지난 90일 동안의 사용자 소모품 구매를 쿼리할 수 있습니다. 또한 지원 워크플로에 대한 ShortOrderID와 같이 Collections 쿼리에서는 사용할 수 없는 필드도 반환합니다.
필수 구성 요소
서비스 간 API의 필수 구성 요소를 검토하세요. 이 API는 Microsoft Entra ID 인증 유형만 지원합니다. 파트너 센터에서 제품 구성이 게시되지 않은 경우 API는 성공하지만 결과가 반환되지 않을 수 있습니다.요청
요청 구문
| Method | Request URI |
|---|---|
POST | https://purchase.mp.microsoft.com/v8.0/b2b/orders/query |
요청 헤더
| Header | Type | Description |
|---|---|---|
Authorization | string | 필수. Bearer <token> 형식의 Microsoft Entra ID 서비스 액세스 토큰입니다. |
Host | string | 값 purchase.mp.microsoft.com으로 설정해야 합니다. |
Content-Length | number | 요청 본문의 길이입니다. |
Content-Type | string | 요청 및 응답 형식을 지정합니다. 현재 지원되는 유일한 값은 application/json입니다. |
요청 본문
| Parameter | Type | Description | Required |
|---|---|---|---|
b2bKey | string | 요청 대상 사용자의 ID를 나타내는 사용자 구매 ID입니다. 사용자 저장소 ID 키를 참조하세요. | 예 |
lineItemStateFilter | list<string> | 쿼리 결과에서 반환할 항목 상태를 지정합니다. 유효한 값 목록은 라인 항목 상태를 참조하세요. | 아니요 |
sbx | string | UserStoreIds로 인증할 때 결과의 범위를 지정할 샌드박스를 지정하는 선택적 값입니다. 이 값이 없는 기본값은 RETAIL 샌드박스입니다. X-Token 인증은 샌드박스가 X-Token 내에 지정되므로 이 값이 필요하지 않습니다. | 아니요 |
라인 항목 상태
| Value | Description |
|---|---|
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"
}
응답
응답 본문
| Parameter | Type | Description | Required |
|---|---|---|---|
items | list<PurchasedItem> | 지정된 사용자에 대한 제품 배열입니다. 자세한 내용은 다음 표를 참조하세요. | 예 |
PurchasedItem 개체에는 다음 매개 변수가 포함됩니다.
| Parameter | Type | Description | Required |
|---|---|---|---|
orderId | GUID | 구매 주문 번호의 긴 형식 ID입니다. Collections 및 기타 서비스에서 사용되는 OrderID입니다. | 예 |
shortOrderId | GUID | 구매 주문 번호의 짧은 형식 ID입니다. 최종 사용자가 구매 기록과 확인 이메일에서 보게 되는 주문 번호입니다. 사용자는 이 ID를 지원 담당자에게 제공하여 구매를 나타냅니다. | 아니요 |
orderLineItems | list<OrderLineItem> | 사용자로부터의 구매 OrderId 내 소모품과 관련된 추가 정보의 배열입니다. 자세한 내용은 다음 표를 참조하세요. | 예 |
orderPurchasedDate | datetime | 소모품을 구매한 UTC 날짜 및 시간입니다. | 예 |
orderRefundedDate | datetime | 소모품이 환불된 UTC 날짜 및 시간입니다. 이 값은 환불된 항목에 표시되기까지 몇 시간이 걸립니다. | 아니요 |
OrderLineItem 개체에는 다음 매개 변수가 포함됩니다.
| Parameter | Type | Description | Required |
|---|---|---|---|
lineItemId | GUID | 소모품에 대한 구매 주문 내의 lineItem을 식별합니다(주문은 장바구니 시나리오를 위해 여러 lineItemId를 가질 수 있음). | 예 |
lineItemState | string | 이 특정 소모품 구매의 상태입니다. 라인 항목 상태를 참조하세요. | 예 |
productId | string | Microsoft Store 카탈로그 내에서 제품의 스토어 ID라고도 합니다. 제품에 대한 스토어 ID의 예는 9NBLGGH42CFD입니다. | 예 |
quantity | number | 주문에서 구매했을 때의 항목 수량입니다. | 예 |
skuId | string | Microsoft Store 카탈로그에 제품의 여러 제공 항목이 있는 경우의 특정 SKU 식별자입니다. SKU에 대한 스토어 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을 5번 구매했습니다. 두 개의 구매는 Revoked인데, 이는 소비된 이후에 환불되었음을 의미합니다. 거의 실시간 환불 검색을 위해서는 서비스에서 환불 및 지불 거절 관리에 설명된 Clawback 이벤트 플로우를 사용하세요.