프로모션 자격 확인

아티클
09/27/2024

적용 대상

파트너 센터

적절한 역할

관리 에이전트

참고 항목

라이선스 기반 서비스에 대한 새로운 상거래 환경에는 많은 새로운 기능이 포함되며 모든 CSP(클라우드 솔루션 공급자)에서 사용할 수 있습니다. 자세한 내용은 새 상거래 환경 개요를 참조하세요.

파트러는 고객 트랜잭션이 지정된 프로모션에 적합한지 확인할 수 있습니다. 이 메서드는 고객 트랜잭션이 지정된 프로모션에 적합한 경우 True를 반환합니다. 파트너는 거래를 제출하기 전에 자격을 확인하여 프로모션이 적용되도록 할 수 있습니다.

필수 조건

자격 증명(파트너 센터 인증에서 설명). 이 시나리오는 독립 실행형 앱과 App+사용자 자격 증명을 모두 사용하여 인증을 지원합니다.
자격에는 구매한 제품 sku 가용성, 평가 중인 프로모션 ID, 거래 수량, 기간 및 청구 주기 포함됩니다.
이 API에 대한 제한 속도는 파트너 테넌트당 분당 최대 625개 요청(RPM)입니다. 제한을 초과하는 호출은 429의 http 응답을 생성합니다. 제한에 대한 자세한 내용은 제한 지침을 참조하세요.

REST 요청

요청 구문

메서드	요청 URI
POST	{baseURL}/v1/customers/{customerId}/promotionEligibilities HTTP/1.1

URI 매개 변수

다음 쿼리 매개 변수를 사용하여 사용 가능한 승격을 반환합니다.

속성	Type	필수	설명
customerId	string	Y	값은 GUID 형식의 customer-tenant-id이며, 이는 고객을 지정할 수 있는 식별자입니다.

요청 헤더

자세한 내용은 파트너 센터 REST 헤더를 참조하세요.

요청 본문

본문에는 PromotionEligibilitiesRequestItems 컬렉션이 포함됩니다. 이 표에서는 PromotionEligibilitiesRequestItem에 대한 속성을 설명합니다.

속성	형식	필수	설명
catalogItemId	string	예	카탈로그 항목 식별자입니다.
quantity	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: 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 상태 코드가 함께 제공됩니다. 네트워크 추적 도구를 사용하여 이 코드, 오류 유형 및 기타 매개 변수를 읽습니다. 전체 목록은 오류 코드를 참조하세요.

자격 오류 유형 및 설명

자격 검사에서 프로모션 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: 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"
    }
}

다음을 통해 공유