purchase.mp.microsoft.com/v7.0/purchases/grant

Microsoft Store 구매 API를 사용하여 무료 앱 또는 추가 기능을 사용자 계정에 부여합니다. 무료 제품만 사용자 계정에 직접 부여할 수 있습니다. 유료 제품에 대한 부여 시도는 오류를 반환합니다.

필수 구성 요소

서비스 간 API의 필수 구성 요소를 검토하세요. 이 API는 Microsoft Entra ID 인증 유형만 지원합니다. 제품 구성이 Partner Center에 게시되지 않은 경우, 요청은 성공하지만 결과가 반환되지 않을 수 있습니다.

요청

요청 구문

메서드	요청 URI
`POST`	`https://purchase.mp.microsoft.com/v7.0/purchases/grant`

요청 헤더

헤더	형식	설명
`Authorization`	`string`	필수입니다. `Bearer` <token> 형식의 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를 나타내는 User Store ID 키입니다.	예
`devOfferId`	`string`	구매 후 Collection 항목에 표시되는 개발자 지정 제안 ID입니다.	아니요
`language`	`string`	사용자의 언어입니다.	예
`market`	`string`	사용자의 시장입니다.	예
`orderId`	`GUID`	주문에 대해 생성된 GUID입니다. 이 값은 사용자에 대해 고유하지만, 모든 주문에서 고유할 필요는 없습니다.	예
`productId`	`string`	Microsoft Store 카탈로그에 있는 제품의 Store ID입니다. 제품의 Store ID 예는 9NBLGGH42CFD입니다.	예
`quantity`	`int`	구매할 수량입니다. 현재 지원되는 유일한 값은 1입니다. 지정하지 않으면 기본값은 1입니다.	아니요
`skuId`	`string`	Microsoft Store 카탈로그에 있는 제품 SKU의 Store ID입니다. SKU의 Store ID 예는 0010입니다.	예
`sbx`	`string`	UserStoreId로 인증할 때 결과의 범위를 지정할 샌드박스를 지정하는 선택적 값입니다. 이 값이 없으면 기본값은 RETAIL 샌드박스입니다. X-Token 인증은 샌드박스가 X-Token 내에 지정되므로 이 값이 필요하지 않습니다.	아니요

요청 예제

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를 사용하여 생성된 주문에는 해당되지 않습니다.	예
`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 카탈로그에서 품목을 나타내는 제품의 Store ID입니다. 제품의 Store ID 예는 9NBLGGH42CFD입니다.	예
`productType`	`string`	제품의 유형입니다. 지원되는 값은 `Durable`, `Application`, `UnmanagedConsumable`입니다.	예
`quantity`	`int`	주문한 항목의 수량입니다.	예
`retailPrice`	`decimal`	주문한 항목의 소매 가격입니다.	예
`revenueRecognitionState`	`string`	수익 인식 상태입니다.	예
`skuId`	`string`	Microsoft Store 카탈로그에 있는 품목 SKU의 Store ID입니다. SKU의 Store ID 예는 0010입니다.	예
`taxAmount`	`decimal`	품목의 세금 금액입니다.	예
`taxType`	`string`	해당 세금의 세금 유형입니다.	예
`Title`	`string`	품목의 지역화된 제목입니다.	예
`totalAmount`	`decimal`	세금을 포함한 품목의 총 구매 금액입니다.	예

IdentityV8 개체에는 다음 매개 변수가 포함됩니다.

매개 변수	형식	설명	필수
`identityType`	`string`	`"pub"` 값을 포함합니다.	예
`identityValue`	`string`	지정된 User 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 액세스 토큰이 잘못되었습니다. 토큰이 만료되었거나 appid 클레임이 없는 경우와 같이 ServiceError 세부 정보에 추가 정보가 포함되는 경우도 있습니다.
401	Unauthorized	PartnerAadTicketRequired	Microsoft Entra ID 액세스 토큰이 권한 부여 헤더로 서비스에 전달되지 않았습니다.
401	Unauthorized	InconsistentClientId	User Store ID 키의 `clientId` 클레임과 액세스 토큰의 `appid`가 일치하지 않습니다.
400	BadRequest	InvalidParameter	세부 정보에 요청 본문 및 잘못된 값을 가진 필드에 관한 정보가 포함되어 있습니다.

Microsoft Store APIs

필수 구성 요소

요청

요청 구문

요청 헤더

요청 본문

요청 예제

응답

응답 본문

응답 예제

오류 코드

관련 문서

​필수 구성 요소

​요청

​요청 구문

​요청 헤더

​요청 본문

​요청 예제

​응답

​응답 본문

​응답 예제

​오류 코드

​관련 문서

필수 구성 요소

요청

요청 구문

요청 헤더

요청 본문

요청 예제

응답

응답 본문

응답 예제

오류 코드

관련 문서