確認促銷資格
適用於
- 合作夥伴中心
適當的角色
- 系統管理代理人
注意
授權型服務的新商務體驗包含許多新功能,並可供所有 雲端解決方案提供者 (CSP) 使用。 如需詳細資訊,請參閱 新的商務體驗概觀。
元件者可以驗證客戶交易是否符合指定促銷的資格。 如果客戶交易符合指定促銷的資格,這個方法會 傳回 True 。 合作夥伴可以在提交交易之前先確認資格,以確保將套用促銷。
必要條件
- 認證,如合作夥伴中心驗證所述。 此案例支援使用獨立應用程式和 App+使用者認證進行驗證。
- 資格包括購買的產品 SKU 可用性、正在評估的促銷標識碼、交易的數量、期限和計費週期。
- 此 API 的節流速率上限為每個合作夥伴租使用者每分鐘 625 個要求(RPM)。 超過限制的呼叫會導致 HTTP 回應為 429。 如需節流的相關信息,請參閱 節流指引 。
REST 要求
要求語法
方法 | 要求 URI |
---|---|
POST | {baseURL}/v1/customers/{customerId}/promotionEligibilities HTTP/1.1 |
URI 參數
使用下列查詢參數可傳回可用的促銷。
名稱 | 類型 | 必要 | 描述 |
---|---|---|---|
customerId | string | Y | 此值是 GUID 格式的 customer-tenant-id,此識別碼可讓您用來指定客戶。 |
要求標頭
如需詳細資訊,請參閱合作夥伴中心 REST 標頭。
要求本文
Body 包含 PromotionEligibilitiesRequestItems 的集合。 下表描述 PromotionEligibilitiesRequestItem 的屬性。
屬性 | 型別 | 必要 | 描述 |
---|---|---|---|
catalogItemId | 字串 | Yes | 目錄項目識別碼。 |
數量 | int | Yes | 授權或實例的數目。 |
termDuration | Datetime | Yes | 詞彙持續時間的 ISO 8601 表示法。 目前的支援值為 P1M(一個月)、P1Y(一年)和 P3Y(三年)。 |
billingCycle | 字串 | Yes | 值,表示計費周期的類型。 |
promotionId | 字串 | No | 促銷項目標識碼。 |
要求範例
POST https://api.partnercenter.microsoft.com/v1/customers/46632f71-f052-4384-8f84-4cdb6c12c2a1/promotionEligibilities HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70a
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
X-Locale: en-US
// Request example with promotion ID input
{
"items": [
{
"catalogItemId": "CFQ7TTC0LH2Z:0002:CFQ7TTC0HRVK",
"quantity": 2400,
"termDuration": "P1Y",
"billingCycle": "Monthly",
"promotionId": "39NFJQT1PM6C:0005:39NFJQT1Q5L7"
}
]
}
POST https://api.partnercenter.microsoft.com/v1/customers/46632f71-f052-4384-8f84-4cdb6c12c2a1/promotionEligibilities HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70b
MS-CorrelationId: bbbb1111-cc22-3333-44dd-555555eeeeee
X-Locale: en-US
// Request example with no promotion ID input
{
"items": [
{
"id": "0",
"catalogItemId": "CFQ7TTC0HBSJ:0001:CFQ7TTC0JQH3",
"quantity": 300,
"termDuration": "P1M",
"billingCycle": "monthly"
}
]
}
REST 回應
如果提供 promotionId 且要求成功,這個方法會傳回資格結果的集合。 如果未提供 promotionId 且要求成功,此方法會傳回指定供應專案的所有促銷,以及每個促銷的對應客戶資格。
回應成功和錯誤碼
每個回應都有一個 HTTP 狀態代碼,指出成功或失敗,以及更多偵錯資訊。 使用網路追蹤工具來讀取此程式代碼、錯誤類型等等參數。 如需完整清單,請參閱錯誤碼。
資格錯誤類型和描述
如果資格檢查會根據促銷標識符來判斷要評估的產品 SKU,則資格會傳回 false。 系統會評估各種條件和條件約束,並傳回錯誤類型,以描述不符合資格的條件。
資格錯誤類型 | 資格錯誤描述 |
---|---|
InvalidCatalogItemId | 提供的 CatalogItemId 無效。 |
InvalidPromotion | 提供的升級無效。 |
PrerequisiteProductOwnership | 客戶不符合符合此促銷資格的必要產品擁有權需求。 |
RedemptionLimit | 已符合此促銷的兌換限制。 |
SeatCount | 所提供的數量不符合促銷的最低或最大座位需求。 |
OfferPurchasedPreviously | 此供應專案先前已為此客戶購買。 |
術語 | 提供的字詞不適用於促銷。 |
NoPromotionsAvailable | 目前沒有促銷。 |
回應範例
HTTP/1.1 200 OK
Content-Length: 138
Content-Type: application/json
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70a
Date: Fri, 26 Feb 2021 20:42:26 GMT
// Response example with promotion ID provided in the request
{
"totalCount": 1,
"items": [
{
"id": 0,
"catalogItemId": "CFQ7TTC0LH2Z:0002:CFQ7TTC0HRVK",
"quantity": 2400,
"billingCycle": "monthly",
"termDuration": "P1Y",
"eligibilities": [
{
"promotionId": "39NFJQT1PM6C:0005:39NFJQT1Q5L7",
"isEligible": false,
"errors": [
{
"minimumRequiredSeats": 1,
"maximumRequiredSeats": 2400,
"availableSeats": 500,
"type": "SeatCount",
"description": "The provided quantity does not satisfy the minimum or maximum seat requirements for the promotion."
}
]
}
],
"attributes": {
"objectType": "PromotionEligibilities"
}
}
],
"attributes": {
"objectType": "Collection"
}
}
HTTP/1.1 200 OK
Content-Length: 138
Content-Type: application/json
MS-CorrelationId: bbbb1111-cc22-3333-44dd-555555eeeeee
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70b
Date: Fri, 26 Feb 2021 20:42:26 GMT
// Response example with no promotion ID provided in the request
{
"totalCount": 1,
"items": [
{
"id": 0,
"catalogItemId": "CFQ7TTC0HBSJ:0001:CFQ7TTC0JQH3",
"quantity": 300,
"billingCycle": "monthly",
"termDuration": "P1M",
"eligibilities": [
{
"promotionId": "39NFJQT1XK5L:000J:39NFJQT1Q5D8",
"isEligible": true
},
{
"promotionId": "39NFJQT1XG89:0002:39NFJQT1Q5L2",
"isEligible": true
}
],
"attributes": {
"objectType": "PromotionEligibilities"
}
}
],
"attributes": {
"objectType": "Collection"
}
}