验证促销资格

项目
09/27/2024

适用于

合作伙伴中心

相应的角色

管理员代理

注意

基于许可证的服务的新商业体验涵盖许多新功能，可供所有云解决方案提供商 (CSP) 使用。有关详细信息，请参阅新商业体验概述。

参与方可以验证客户交易是否符合给定促销的条件。如果客户交易符合给定促销条件，则此方法返回 True 。合作伙伴可以在提交交易之前验证资格，以确保将应用促销。

先决条件

合作伙伴中心身份验证中所述的凭据。此方案支持使用独立应用和 App+User 凭据进行身份验证。
资格包括购买的产品 SKU 可用性、正在评估的促销 ID、交易的数量、期限和计费周期。
此 API 的限制速率上限为每个合作伙伴租户每分钟 625 个请求（RPM）。超出限制的调用将导致 http 响应为 429。有关限制的信息，请参阅限制指南。

REST 请求

请求语法

方法	请求 URI
POST	{baseURL}/v1/customers/{customerId}/promotionEligibibility HTTP/1.1

URI 参数

使用以下查询参数返回可用的促销。

名称	类型	必需	说明
customerId	string	Y	该值是 GUID 格式的 customer-tenant-id，是一个用于指定客户的标识符。

请求标头

有关详细信息，请参阅合作伙伴中心 REST 标头。

请求正文

Body 包括 PromotionEligibibilityRequestItems 的集合。下表描述了 PromotionEligibibilityRequestItem 的属性。

properties	类型	必需	说明
catalogItemId	string	是	目录项标识符。
quantity	int	是	许可证或实例数。
termDuration	DateTime	是	术语持续时间的 ISO 8601 表示形式。当前支持的值为 P1M（一个月）、P1Y（一年）和 P3Y（三年）。
billingCycle	string	是	指示计费周期类型的值。
promotionId	string	否	促销项标识符。

请求示例

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: 81b08ffe-4cf8-49cd-82db-5c2fb0a8e132
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: 81b08ffe-4cf8-49cd-82db-5c2fb0a8e133
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 状态代码，指示成功或失败以及更多的调试信息。使用网络跟踪工具读取此代码、错误类型和其他参数。有关完整列表，请参阅错误代码。

资格错误类型和说明

如果资格检查确定根据促销 ID 评估的产品 SKU 不一致，资格将返回 false。评估各种条件和约束并返回错误类型，以描述不符合资格的条件。

资格错误类型	资格错误说明
InvalidCatalogItemId	提供的 CatalogItemId 无效。
InvalidPromotion	提供的促销无效。
PrerequisiteProductOwnership	客户不符合符合此促销条件的先决条件产品所有权要求。
RedemptionLimit	已满足此促销的兑换限制。
SeatCount	提供的数量不符合促销的最低或最大座位要求。
OfferPurchasedPreviously	此产品/服务以前已为此客户购买。
Term	提供的术语不适用于促销。
NoPromotionsAvailable	目前没有促销。

响应示例

HTTP/1.1 200 OK
Content-Length: 138
Content-Type: application/json
MS-CorrelationId: 81b08ffe-4cf8-49cd-82db-5c2fb0a8e132
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: 81b08ffe-4cf8-49cd-82db-5c2fb0a8e133
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"
    }
}

通过