무료 제품 부여

아티클
03/13/2024

Microsoft Store 구매 API에서 이 메서드를 사용하여 지정된 사용자에게 무료 앱 또는 추가 기능(앱 내 구매 제품 또는 IAP라고도 함)에 대한 권한을 부여합니다.

현재 무료 제품에 대한 권한만 부여할 수 있습니다. 서비스에서 이 메서드를 사용하여 무료가 아닌 제품에 대한 권한을 부여하려고 하면 이 메서드는 오류를 반환합니다.

필수 조건

이 메서드를 사용하려면 다음이 필요합니다.

대상 URI 값이 https://onestore.microsoft.com인 Azure AD 액세스 토큰입니다.
Microsoft Store ID 키는 무상 제품 권한을 부여하려는 사용자의 ID를 나타냅니다.

자세한 정보는 서비스에서 제품 권리 유형 관리하기를 참조하세요.

요청

요청 구문

메서드	요청 URI
게시	`https://purchase.mp.microsoft.com/v6.0/purchases/grant`

요청 헤더

헤더	형식	설명
권한 부여	string	필수. Bearer<토큰> 형식의 Azure AD 액세스 토큰.
Host	문자열	purchase.mp.microsoft.com 값으로 설정해야 합니다.
Content-Length	수	요청 본문의 길이입니다.
Content-Type	문자열	요청 및 응답 형식을 지정합니다. 현재 유일하게 지원되는 값은 application/json입니다.

요청 본문

매개 변수	형식	설명	필수
availabilityId	문자열	Microsoft Store 카탈로그에서 권한을 부여할 제품의 가용성 ID입니다.	예
b2bKey	문자열	제품의 권한을 부여하려는 사용자의 ID를 나타내는 Microsoft Store ID 키입니다.	예
devOfferId	문자열	구매 후 컬렉션 항목에 표시되는 개발자가 지정한 제품 ID입니다.
language	문자열	사용자의 언어입니다.	예
시장	문자열	사용자의 시장입니다.	예
orderId	guid	주문에 대해 생성된 GUID입니다. 이 값은 사용자에 대해 고유하지만 모든 주문에서 고유할 필요는 없습니다.	예
productId	문자열	Microsoft Store 카탈로그의 제품에 대한 Store ID입니다. 제품에 대한 Microsoft Store ID의 예는 9NBLGGH42CFD입니다.	예
quantity	int	구매할 수량입니다. 현재, 1 값만 지원됩니다. 지정되지 않은 경우 기본값은 1입니다.	아니요
skuId	문자열	Microsoft Store 카탈로그의 제품 SKU에 대한 Store ID입니다. SKU에 대한 Microsoft Store ID의 예는 0010입니다.	예

요청 예시

POST https://purchase.mp.microsoft.com/v6.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",
}

응답

응답 본문

매개 변수	형식	설명	필수
clientContext	ClientContextV6	이 주문에 대한 클라이언트 문맥 정보입니다. 이 정보는 Azure AD 토큰의 clientID 값에 할당됩니다.	예
createdtime	datetimeoffset	주문이 만들어진 시간입니다.	예
currencyCode	문자열	totalAmount 및 totalTaxAmount의 통화 코드입니다. 무료 항목의 경우 해당되지 않습니다.	예
friendlyName	문자열	주문의 식별 이름입니다. Microsoft Store 구매 API를 사용하여 생성된 주문에 대해서는 해당되지 않습니다.	예
isPIRequired	boolean	결제 방법(PI)이 구매 주문의 일부로 필요한지를 나타냅니다.	예
language	문자열	주문에 대한 언어 ID입니다(예: "en").	예
시장	문자열	주문에 대한 시장 ID입니다(예: "US").	예
orderId	문자열	특정 사용자의 주문을 식별하는 ID입니다.	예
orderLineItems	list<OrderLineItemV6>	주문에 대한 품목 목록입니다. 일반적으로 주문 당 하나의 라인 항목이 있습니다.	예
orderState	문자열	주문 상태입니다. 유효한 상태로는 Editing, CheckingOut, Pending, Purchased, Refunded, ChargedBack 및 Cancelled가 있습니다.	예
orderValidityEndTime	문자열	주문서 제출 전 주문 가격 설정이 유효한 마지막 시간입니다. 무료 앱의 경우 해당되지 않습니다.	예
orderValidityStartTime	문자열	주문서 제출 전 주문 가격 설정이 유효한 처음 시간입니다. 무료 앱의 경우 해당되지 않습니다.	예
구매자	IdentityV6	구매자의 ID를 설명하는 개체입니다.	예
totalAmount	진수	세금을 포함한 모든 주문 항목의 총 구매 금액입니다.	예
totalAmountBeforeTax	진수	세금을 제외한 모든 주문 항목의 총 구매 금액입니다.	예
totalChargedToCsvTopOffPI	진수	별도의 결제 방법이나 저장된 값(CSV)을 사용하는 경우, CSV로 청구되는 금액입니다.	예
totalTaxAmount	진수	모든 품목에 대한 세금의 총 금액입니다.	예

ClientContext 개체는 다음의 매개 변수를 포함합니다.

매개 변수	형식	설명	필수
클라이언트	문자열	주문한 클라이언트의 ID입니다.	아니요

OrderLineItemV6 개체는 다음의 매개 변수를 포함합니다.

매개 변수	형식	설명	필수
에이전트	IdentityV6	항목을 마지막으로 편집한 에이전트입니다. 이 개체에 대한 자세한 정보는 아래의 테이블을 참조하세요.	아니요
availabilityId	문자열	Microsoft Store 카탈로그에서 구매할 제품의 가용성 ID입니다.	예
beneficiary	IdentityV6	주문 수취인 ID입니다.	아니요
billingState	문자열	주문의 청구 상태입니다. 완료되면 Charged로 설정됩니다.	아니요
campaignId	문자열	이 주문에 대한 캠페인 ID입니다.	아니요
currencyCode	문자열	가격 세부 정보에 사용되는 통화 코드입니다.	예
설명	문자열	라인 항목에 대한 지역화된 설명입니다.	예
devofferId	문자열	특정 주문이 있을 경우의 제품 ID입니다.	아니요
fulfillmentDate	datetimeoffset	처리된 날짜입니다.	아니요
fulfillmentState	문자열	이 항목의 처리 상태입니다. 완료되면 Fulfilled로 설정됩니다.	아니요
isPIRequired	boolean	이 항목에 결제 방법이 필요한지를 나타냅니다.	예
isTaxIncluded	boolean	해당 항목의 가격에 세금이 포함되는지를 나타냅니다.	예
legacyBillingOrderId	문자열	레거시 청구 ID입니다.	아니요
lineItemId	문자열	이 주문의 항목에 대한 라인 항목 ID입니다.	예
listPrice	진수	이 주문에 있는 항목의 정가입니다.	예
productId	문자열	Microsoft Store 카탈로그에서 품목을 나타내는 제품에 대한 Store ID입니다. 제품에 대한 Microsoft Store ID의 예는 9NBLGGH42CFD입니다.	예
productType	문자열	제품의 유형입니다. 지원되는 값은 Durable, Application 및 UnmanagedConsumable입니다.	예
quantity	int	주문한 품목의 수량입니다.	예
retailPrice	진수	주문 품목의 소매 가격입니다.	예
revenueRecognitionState	문자열	수익 인식 상태입니다.	예
skuId	문자열	Microsoft Store 카탈로그에서 품목을 나타내는 SKU에 대한 Store ID입니다. SKU에 대한 Microsoft Store ID의 예는 0010입니다.	예
taxAmount	진수	품목에 대한 세금 금액입니다.	예
taxType	문자열	해당 세금에 대한 세금 유형입니다.	예
Title	문자열	품목의 지역화된 제목입니다.	예
totalAmount	진수	세금을 포함한 품목의 총 구매 금액입니다.	예

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

매개 변수	형식	설명	필수
identityType	문자열	"pub" 값을 포함합니다.	예
identityValue	문자열	지정된 Microsoft Store ID 키에 있는 publisherUserId의 문자열 값입니다.	예

응답 예시

Content-Length: 1203
Content-Type: application/json
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
MS-RequestId: c1bc832c-f742-47e4-a76c-cf061402f698
MS-CV: XjfuNWLQlEuxj6Mt.8
MS-ServerId: 030032362
Date: Tue, 13 Oct 2015 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	Azure AD 액세스 토큰이 잘못되었습니다. ServiceError의 세부 정보에 토큰이 만료되거나 appid 클레임이 누락되는 경우와 같은 자세한 정보가 포함되는 경우도 있습니다.
401	Unauthorized	PartnerAadTicketRequired	Azure AD 액세스 토큰이 권한 부여 헤더의 서비스에 전달되지 않았습니다.
401	Unauthorized	InconsistentClientId	요청 본문에서 Microsoft Store ID 키의 clientId 클레임과 권한 부여 헤더에서 Azure AD 액세스 토큰의 appid 클레임이 일치하지 않습니다.
400	BadRequest	InvalidParameter	요청 본문에 대한 정보 및 어떤 필드에 잘못된 값이 있는지에 대한 정보가 세부 사항에 포함됩니다.

다음을 통해 공유

무료 제품 부여

필수 조건

요청

요청 구문

요청 헤더

요청 본문

요청 예시

응답

응답 본문

응답 예시

오류 코드

피드백

추가 리소스

다음을 통해 공유

무료 제품 부여

필수 조건

요청

요청 구문

요청 헤더

요청 본문

요청 예시

응답

응답 본문

응답 예시

오류 코드

관련 항목

피드백

추가 리소스