purchase.mp.microsoft.com/v8.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 目錄授與之產品的可用性識別碼。	是
`b2bKey`	`string`	代表您要授與產品之使用者身分識別的 User Store ID 金鑰。	是
`devOfferId`	`string`	開發人員指定的供應項目識別碼，會在購買後出現在 Collection 項目中。	否
`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`	使用 UserStoreIds 進行驗證時的選用值，用來指定結果應限定的沙箱。若沒有此值，預設為 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`	訂單的語言識別碼 (例如 “en”)。	是
`market`	`string`	訂單的市場識別碼 (例如 “US”)。	是
`orderId`	`string`	識別特定使用者之訂單的識別碼。	是
`orderLineItems`	`list<OrderLineItemV8>`	訂單的明細項目清單。一般而言，每筆訂單有一個明細項目。	是
`orderState`	`string`	訂單的狀態。有效狀態為 `Editing`、`CheckingOut`、`Pending`、`Purchased`、`Refunded`、`ChargedBack` 和 `Canceled`。	是
`orderValidityEndTime`	`string`	訂單定價結束的時間，免費應用程式不適用。	是
`orderValidityStartTime`	`string`	訂單定價開始的時間，免費應用程式不適用。	是
`purchaser`	`IdentityV6`	描述購買者身分識別的物件。	是
`totalAmount`	`decimal`	訂單中所有項目的含稅購買總金額。	是
`totalAmountBeforeTax`	`decimal`	訂單中所有項目的稅前購買總金額。	是
`totalChargedToCsvTopOffPI`	`decimal`	如果使用不同的付款方式和儲值 (逗號分隔值 (CSV))，則為向 CSV 收取的金額。	是
`totalTaxAmount`	`decimal`	所有明細項目的稅額總計。	是

ClientContext 物件包含下列參數。

參數	類型	描述	必要
`client`	`string`	建立訂單的用戶端識別碼。	否

OrderLineItemV8 物件包含下列參數。

參數	類型	描述	必要
`agent`	`IdentityV8`	最後編輯明細項目的代理程式。如需此物件的詳細資訊，請參閱下表。	否
`availabilityId`	`string`	要從 Microsoft Store 目錄購買之產品的可用性識別碼。	是
`beneficiary`	`IdentityV8`	訂單受益人的身分識別。	否
`billingState`	`string`	訂單的計費狀態。完成時設定為 `Charged`。	否
`campaignId`	`string`	此訂單的行銷活動識別碼。	否
`currencyCode`	`string`	用於價格詳細資料的貨幣代碼。	是
`description`	`string`	明細項目的當地語系化描述。	是
`devofferId`	`string`	特定訂單的供應項目識別碼 (如果有的話)。	否
`fulfillmentDate`	`datetimeoffset`	發生履行的日期。	否
`fulfillmentState`	`string`	項目的履行狀態。完成時設定為 `Fulfilled`。	否
`isPIRequired`	`boolean`	指出此明細項目是否需要付款方式。	是
`isTaxIncluded`	`boolean`	指出項目的定價詳細資料中是否包含稅金。	是
`legacyBillingOrderId`	`string`	舊版計費識別碼。	否
`lineItemId`	`string`	此訂單中項目的明細項目識別碼。	是
`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 存取權杖無效。在某些情況下，ServiceError 詳細資料會包含更多資訊，例如權杖已過期或缺少 appid 宣告時。
401	Unauthorized	PartnerAadTicketRequired	未在授權標頭中將 Microsoft Entra ID 存取權杖傳遞給服務。
401	Unauthorized	InconsistentClientId	User Store ID 金鑰中的 `clientId` 宣告與存取權杖中的 `appid` 不相符。
400	BadRequest	InvalidParameter	詳細資料包含與要求本文相關的資訊，以及哪些欄位具有無效值。

從您的服務管理產品要求 User Store ID 以進行服務對服務驗證更新 Microsoft Store ID 金鑰

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

必要條件

要求

要求語法

要求標頭

要求本文

要求範例

回應

回應本文

回應範例

錯誤碼

相關文章

​必要條件

​要求

​要求語法

​要求標頭

​要求本文

​要求範例

​回應

​回應本文

​回應範例

​錯誤碼

​相關文章

必要條件

要求

要求語法

要求標頭

要求本文

要求範例

回應

回應本文

回應範例

錯誤碼

相關文章