販売促進の適格性を確認する

[アーティクル]
03/20/2024

適用対象

パートナーセンター

適切なロール

全体管理者
管理エージェント

Note

ライセンスベースのサービスの新しいコマースエクスペリエンスには、多くの新機能が含まれており、すべてのクラウドソリューションプロバイダー (CSP) で利用できます。詳細については、新しいコマースエクスペリエンスの概要を参照してください。

パーターは、顧客トランザクションが特定のプロモーションの対象であるかどうかを確認できます。顧客トランザクションが特定の プロモーションの対象である場合、このメソッドは True を 返します。パートナーは、プロモーションが適用されることを確認するために、トランザクションを送信する前に適格性を確認できます。

前提条件

パートナーセンターの認証に関するページで説明している資格情報。このシナリオでは、スタンドアロンアプリとアプリ + ユーザーの両方の資格情報を使った認証がサポートされています。
適格性には、購入した製品 SKU の可用性、評価対象のプロモーション ID、数量、期間、トランザクションの支払いサイクルが含まれます。
この API の調整率は、パートナーテナントあたり 1 分あたり最大 625 要求 (RPM) です。制限を超える呼び出しでは、http 応答は 429 になります。調整の詳細については、調整ガイダンスを参照してください。

REST 要求

要求の構文

認証方法	要求 URI
投稿	{baseURL}/v1/customers/{customerId}/promotionEligibilities HTTP/1.1

URI パラメーター

使用可能なプロモーションを返すには、次のクエリパラメーターを使用します。

名前	タイプ	Required	説明
Customerid	string	年	この値は、顧客を指定できるようにする識別子である、GUID 形式の customer-tenant-id です。

要求ヘッダー

詳細については、「パートナーセンター REST ヘッダー」を参照してください。

要求本文

本文には、PromotionEligibilitiesRequestItems のコレクションが含まれています。次の表では、PromotionEligibilitiesRequestItem のプロパティについて説明します。

プロパティ	タイプ	Required	説明
catalogItemId	string	はい	カタログアイテム識別子。
数量	int	はい	ライセンスまたはインスタンスの数。
termDuration	DateTime	はい	期間の ISO 8601 表現。現在サポートされている値は、P1M (1 か月)、P1Y (1 年)、P3Y (3 年) です。
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	このオファーは、この顧客に対して以前に購入されています。
用語	指定された用語は、プロモーションには適用されません。
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"
    }
}