purchase.mp.microsoft.com/v8.0/b2b/orders/query
참고 항목
이 API는 환불된 제품을 검색하기 위해 Clawback 흐름의 일부로 더 이상 필요하거나 사용되지 않습니다. 최신 Clawback 서비스에 대한 자세한 내용은 서비스에서 환불 및 환불 관리를 참조하세요.
purchase.mp.microsoft.com/v8.0/b2b/orders/query API는 지난 90일 동안 사용자가 구매한 소모성 구매를 쿼리하는 기능을 게임 서비스에 제공합니다. 게임 서비스는 이 API를 사용하여 고객 지원 시나리오에 유용할 수 있는 ShortOrderID 필드를 포함하여 컬렉션 쿼리 결과에서 사용할 수 없는 일부 정보를 수집할 수 있습니다.
사전 요건
이 API를 사용하려면 다음이 필요합니다.
- 대상 URI 값이
https://onestore.microsoft.com인 Microsoft Entra ID 액세스 토큰 - 무료 제품을 부여하려는 사용자 ID를 나타내는 사용자 구매 ID 키
자세한 내용은 서비스 간 인증을 위한 사용자 Store ID 요청을 참조하세요.
또한 서비스에 표시하려는 제품은 파트너 센터에서 추가 구성이 필요합니다.
제품을 올바르게 구성하는 방법은 사용자 스토어 ID/Microsoft Entra ID 인증을 사용하여 제품을 보고 관리하는 데 필요한 추가 구성을 참조하세요.
참고 항목
제품 구성이 완료되어 파트너 센터를 통해 게시되지 않은 경우 구매 서비스에 대한 호출은 성공하지만 응답에 결과가 없습니다.
요청
요청 구문
| 메서드 | 요청 URI |
|---|---|
POST |
https://purchase.mp.microsoft.com/v8.0/b2b/orders/query |
요청 헤더
| 헤더 | 형식 | 설명 |
|---|---|---|
Authorization |
string |
필수.
Bearer
<
토큰> 양식의 Microsoft Entra ID 서비스 액세스 토큰입니다. |
Host |
string |
값 purchase.mp.microsoft.com(으)로 설정해야 합니다. |
Content-Length |
number |
요청 본문의 길이입니다. |
Content-Type |
string |
요청 및 응답 유형을 지정합니다. 현재 지원되는 유일한 값은 application/json입니다. |
요청 본문
| 매개 변수 | 형식 | 설명 | 필수 |
|---|---|---|---|
b2bKey |
string |
요청하는 사용자의 ID를 나타내는 사용자 구매 ID입니다. 사용자 저장소 ID 키를 참조하세요. | 예 |
lineItemStateFilter |
list<string> |
쿼리 결과에 반환할 항목 상태를 지정합니다. 유효한 값 목록은 광고 항목 상태를 참조하세요. | 아니요 |
sbx |
string |
결과의 범위를 지정해야 하는 샌드박스를 지정하는 UserStoreIds로 인증하기 위한 선택적 값입니다. 이 값이 없는 기본값은 RETAIL 샌드박스입니다. X-Token 인증에는 X-Token 내에 Sandbox가 지정되어 있으므로 이 값이 필요하지 않습니다. | 아니요 |
광고 항목 상태
| 값 | 설명 |
|---|---|
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 #. 컬렉션 및 기타 서비스에서 사용하는 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 카탈로그내의 제품에 대한 Microsoft Store ID입니다. 제품에 대한 Microsoft Store ID의 예는 9NBLGGH42CFD입니다. | 예 |
quantity |
number |
주문에서 구매한 항목의 수량입니다. | 예 |
skuId |
string |
Microsoft Store 카탈로그에 다중 제공 제품이 있는 경우 특정 SKU 식별자 SKU에 대한 Microsoft 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를 5번 구매했음을 알 수 있습니다.
그러나 이러한 구매 중 2개의 항목 상태는 Revoked이며, 이는 예제 게임 서비스에서 소비한 후 환불되었음을 의미합니다. 환불 이벤트가 발생할 때 추적하기 위해 purchase.mp.microsoft.com/v8.0/b2b/orders/query 사용하면 안 됩니다. 대신 서비스에서 환불 및 환불 관리에 설명된 Clawback 이벤트 서비스를 사용해야 합니다.