purchase.mp.microsoft.com/v8.0/purchases/grant
Microsoft Store 구매 API를 사용하여 특정 사용자에게 무료 앱 또는 추가 기능(앱에서 바로 구매 제품 또는 IAP라고도 함)을 부여할 수 있습니다.
현재 무료 제품만 부여할 수 있습니다. 서비스에서 유료 제품을 부여하려고 하면 오류가 반환됩니다.
필수 조건
참고 항목
현재 구매 API는 XSTS 토큰 인증을 지원하지 않습니다.
이 API를 사용하려면 다음이 필요합니다.
- 대상 URI 값이
https://onestore.microsoft.com인 Microsoft Entra ID 액세스 토큰 - 무료 제품을 부여하려는 사용자 ID를 나타내는 사용자 구매 ID 키
자세한 내용은 서비스 간 인증을 위한 사용자 Store ID 요청을 참조하세요.
또한 서비스에 표시하려는 제품은 파트너 센터에서 추가 구성이 필요합니다.
제품을 올바르게 구성하는 방법은 사용자 Store ID/Microsoft Entra ID 인증이 있는 제품을 보고 관리하는 데 필요한 추가 구성을 참조하세요.
참고 항목
제품 구성이 완료되어 파트너 센터를 통해 게시되지 않은 경우 구매 서비스에 대한 호출은 성공하지만 응답에 결과가 없습니다.
요청
요청 구문
| 메서드 | 요청 URI |
|---|---|
POST |
https://purchase.mp.microsoft.com/v7.0/purchases/grant |
요청 헤더
| 헤더 | 형식 | 설명 |
|---|---|---|
Authorization |
string |
필수.
Bearer
<
토큰> 양식의 Microsoft Entra ID 서비스 액세스 토큰입니다. |
Host |
string |
값 purchase.mp.microsoft.com(으)로 설정해야 합니다. |
Content-Length |
number |
요청 본문의 길이입니다. |
Content-Type |
string |
요청 및 응답 유형을 지정합니다. 현재 지원되는 유일한 값은 application/json입니다. |
요청 본문
| 매개 변수 | 형식 | 설명 | 필수 |
|---|---|---|---|
availabilityId |
string |
Microsoft Store 카탈로그에서 권한을 부여할 제품의 가용성 ID입니다. | 예 |
b2bKey |
string |
제품의 권한을 부여하려는 사용자의 ID를 나타내는 사용자 Microsoft Store ID 키입니다. | 예 |
devOfferId |
string |
구매 후 컬렉션 항목에 표시되는 개발자가 지정한 제품 ID입니다. | 아니요 |
language |
string |
사용자의 언어. | 예 |
market |
string |
사용자의 지역/국가입니다. | 예 |
orderId |
GUID |
주문에 대해 생성된 GUID입니다. 이 값은 사용자에 대해 고유하지만 모든 주문에서 고유할 필요는 없습니다. | 예 |
productId |
string |
Microsoft Store 카탈로그의 제품에 대한 Microsoft Store ID입니다. 제품에 대한 Microsoft Store ID의 예는 9NBLGGH42CFD입니다. | 예 |
quantity |
int |
구매할 수량입니다. 현재, 1 값만 지원됩니다. 지정되지 않은 경우 기본값은 1입니다. | 아니요 |
skuId |
string |
Microsoft Store 카탈로그의 제품 SKU에 대한 Microsoft Store ID입니다. SKU에 대한 Microsoft Store ID의 예는 0010입니다. | 예 |
sbx |
string |
결과의 범위를 지정해야 하는 샌드박스를 지정하는 UserStoreIds로 인증하기 위한 선택적 값입니다. 이 값이 없는 기본값은 RETAIL 샌드박스입니다. X-Token 인증에는 X-Token 내에 Sandbox가 지정되어 있으므로 이 값이 필요하지 않습니다. | 아니요 |
요청 예제
POST https://purchase.mp.microsoft.com/v7.0/purchases/grant HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJK...
Content-Length: 1863
Content-Type: application/json
{
"b2bKey" : "eyJ0eXAiOiJK...",
"availabilityId" : "9RT7C09D5J3W",
"productId" : "9NBLGGH5WVP6",
"skuId" : "0010",
"language" : "en-us",
"market" : "us",
"orderId" : "3eea1529-611e-4aee-915c-345494e4ee76",
"sbx" : "XDKS.1"
}
응답
응답 본문
| 매개 변수 | 형식 | 설명 | 필수 |
|---|---|---|---|
clientContext |
ClientContextV8 |
이 주문에 대한 클라이언트 문맥 정보입니다. 이 정보는 Microsoft Entra ID 토큰의 clientID 값에 할당됩니다. | 예 |
createdtime |
datetimeoffset |
주문한 시간입니다. | 예 |
currencyCode |
string |
totalAmount 및 totalTaxAmount에 대한 통화 코드. 무료 항목의 경우 해당되지 않습니다. |
예 |
friendlyName |
string |
주문의 식별 이름입니다. Microsoft Store 구매 API를 사용하여 생성된 주문에 대해서는 N/A입니다. | 예 |
isPIRequired |
boolean |
결제 방법(PI)이 구매 주문의 일부로 필요한지를 나타냅니다. | 예 |
language |
string |
주문에 대한 언어 ID입니다(예: "en"). | 예 |
market |
string |
주문에 대한 지역/국가 ID입니다(예: "US"). | 예 |
orderId |
string |
특정 사용자의 주문을 식별하는 ID입니다. | 예 |
orderLineItems |
list<OrderLineItemV8> |
주문에 대한 품목 목록입니다. 일반적으로 주문 당 하나의 줄 항목이 있습니다. | 예 |
orderState |
string |
주문 상태입니다. 유효한 상태는 Editing, CheckingOut, Pending, Purchased, Refunded, ChargedBack 및 Canceled입니다. |
예 |
orderValidityEndTime |
string |
주문서 제출 전에 주문 가격 설정이 유효한 마지막 시간입니다. 무료 앱의 경우 해당되지 않습니다. | 예 |
orderValidityStartTime |
string |
주문서 제출 전에 주문 가격 설정이 유효한 처음 시간입니다. 무료 앱의 경우 해당되지 않습니다. | 예 |
purchaser |
IdentityV6 |
구매자의 ID를 설명하는 개체입니다. | 예 |
totalAmount |
decimal |
세금을 포함한 모든 주문 항목의 총 구매 금액입니다. | 예 |
totalAmountBeforeTax |
decimal |
세금을 포함하지 않은 모든 주문 항목의 총 구매 금액입니다. | 예 |
totalChargedToCsvTopOffPI |
decimal |
별도의 결제 방법이나 저장된 값(쉼표로 구분된 값(CSV))을 사용하는 경우 CSV로 청구되는 금액입니다. | 예 |
totalTaxAmount |
decimal |
모든 품목에 대한 세금의 총 금액입니다. | 예 |
ClientContext 개체에는 다음 매개 변수가 포함됩니다.
| 매개 변수 | 형식 | 설명 | 필수 |
|---|---|---|---|
client |
string |
주문한 클라이언트의 ID입니다. | 아니요 |
OrderLineItemV8 개체에는 다음 매개 변수가 포함됩니다.
| 매개 변수 | 형식 | 설명 | 필수 |
|---|---|---|---|
agent |
IdentityV8 |
품목을 마지막으로 편집한 에이전트입니다. 이 개체에 대한 자세한 내용은 다음 표를 참조하세요. | 아니요 |
availabilityId |
string |
Microsoft Store 카탈로그에서 구매할 제품의 가용성 ID입니다. | 예 |
beneficiary |
IdentityV8 |
주문 수취인 ID입니다. | 아니요 |
billingState |
string |
주문의 청구 상태입니다. 완료되면 이 상태가 Charged(으)로 설정됩니다. |
아니요 |
campaignId |
string |
이 주문에 대한 캠페인 ID입니다. | 아니요 |
currencyCode |
string |
가격 세부 정보에 사용되는 통화 코드입니다. | 예 |
description |
string |
품목에 대한 지역화된 설명입니다. | 예 |
devofferId |
string |
특정 주문이 있을 경우 제품 ID입니다. | 아니요 |
fulfillmentDate |
datetimeoffset |
처리된 날짜입니다. | 아니요 |
fulfillmentState |
string |
이 품목의 처리 상태입니다. 완료되면 이 상태가 Fulfilled(으)로 설정됩니다. |
아니요 |
isPIRequired |
boolean |
이 품목에 결제 방법이 필요한지를 나타냅니다. | 예 |
isTaxIncluded |
boolean |
해당 품목의 가격에 세금이 포함되는지를 나타냅니다. | 예 |
legacyBillingOrderId |
string |
레거시 청구 ID입니다. | 아니요 |
lineItemId |
string |
이 주문의 품목에 대한 품목 ID입니다. | 예 |
listPrice |
decimal |
이 주문에 있는 품목의 정가입니다. | 예 |
productId |
string |
Microsoft Store 카탈로그에서 품목을 나타내는 제품에 대한 Microsoft Store ID입니다. 제품에 대한 Microsoft Store ID의 예는 9NBLGGH42CFD입니다. | 예 |
productType |
string |
제품 유형입니다. 지원되는 값은 Durable, Application 및 UnmanagedConsumable입니다. |
예 |
quantity |
int |
주문한 품목의 수량입니다. | 예 |
retailPrice |
decimal |
주문 품목의 소매 가격입니다. | 예 |
revenueRecognitionState |
string |
수익 인식 상태입니다. | 예 |
skuId |
string |
Microsoft Store 카탈로그에서 품목을 나타내는 SKU에 대한 Microsoft Store ID입니다. SKU에 대한 Microsoft Store ID의 예는 0010입니다. | 예 |
taxAmount |
decimal |
품목에 대한 세금 금액입니다. | 예 |
taxType |
string |
해당 세금에 대한 세금 유형입니다. | 예 |
Title |
string |
품목의 지역화된 제목입니다. | 예 |
totalAmount |
decimal |
세금을 포함한 품목의 총 구매 금액입니다. | 예 |
IdentityV8 개체에는 다음 매개 변수가 포함됩니다.
| 매개 변수 | 형식 | 설명 | 필수 |
|---|---|---|---|
identityType |
string |
"pub" 값을 포함합니다. |
예 |
identityValue |
string |
지정된 사용자 Microsoft Store ID 키에 있는 publisherUserId의 문자열 값입니다. | 예 |
응답 예제
Content-Length: 1203
Content-Type: application/json
MS-CorrelationId: fb2e69bc-f26a-4aab-a823-7586c19f5762
MS-RequestId: c1bc832c-f742-47e4-a76c-cf061402f698
MS-CV: XfrNWLQlEaux6Mt.8
MS-ServerId: 030032362
Date: Tue, 13 Oct 2019 21:21:51 GMT
{
"clientContext": {
"client": "86b78998-d05a-487b-b380-6c738f6553ea"
},
"createdTime": "2015-10-13T21:21:51.1863494+00:00",
"currencyCode": "USD",
"isPIRequired": false,
"language": "en-us",
"market": "us",
"orderId": "3eea1529-611e-4aee-915c-345494e4ee76",
"orderLineItems": [{
"availabilityId": "9RT7C09D5J3W",
"beneficiary": {
"identityType": "pub",
"identityValue": "user1"
},
"billingState": "Charged",
"currencyCode": "USD",
"description": "Jewels, Jewels, Jewels - Consumable 2",
"fulfillmentDate": "2015-10-13T21:21:51.639478+00:00",
"fulfillmentState": "Fulfilled",
"isPIRequired": false,
"isTaxIncluded": true,
"lineItemId": "2814d758-3ee3-46b3-9671-4fb3bdae9ffe",
"listPrice": 0.0,
"payments": [],
"productId": "9NBLGGH5WVP6",
"productType": "UnmanagedConsumable",
"quantity": 1,
"retailPrice": 0.0,
"revenueRecognitionState": "None",
"skuId": "0010",
"taxAmount": 0.0,
"taxType": "NoApplicableTaxes",
"title": "Jewels, Jewels, Jewels - Consumable 2",
"totalAmount": 0.0
}],
"orderState": "Purchased",
"orderValidityEndTime": "2015-10-14T21:21:51.1863494+00:00",
"orderValidityStartTime": "2015-10-13T21:21:51.1863494+00:00",
"purchaser": {
"identityType": "pub",
"identityValue": "user1"
},
"testScenarios": "None",
"totalAmount": 0.0,
"totalTaxAmount": 0.0
}
오류 코드
| 코드 | 오류 | 내부 오류 코드 | 설명 |
|---|---|---|---|
| 401 | Unauthorized | AuthenticationTokenInvalid | Microsoft Entra ID 액세스 토큰이 잘못되었습니다. ServiceError의 세부 정보에 토큰이 만료되거나 appid 클레임이 누락되는 경우와 같은 자세한 정보가 포함되는 경우도 있습니다. |
| 401 | Unauthorized | PartnerAadTicketRequired | Microsoft Entra ID 액세스 토큰이 인증 헤더의 서비스에 전달되지 않았습니다. |
| 401 | Unauthorized | InconsistentClientId | 요청 본문에 있는 사용자 Store ID 키의 clientId 클레임과 인증 헤더에 있는 Microsoft Entra ID 액세스 토큰의 appid 클레임이 일치하지 않습니다. |
| 400 | BadRequest | InvalidParameter | 요청 본문에 대한 정보 및 어떤 필드에 잘못된 값이 있는지에 대한 정보가 세부 사항에 포함됩니다. |