적용 대상
- 파트너 센터
적절한 역할
- 관리 에이전트
참고
라이선스 기반 서비스에 대한 새로운 상거래 환경에는 많은 새로운 기능이 포함되며 모든 CSP(클라우드 솔루션 공급자)에서 사용할 수 있습니다. 자세한 내용은 새 상거래 환경 개요를 참조하세요.
파트러는 고객 트랜잭션이 지정된 프로모션에 적합한지 확인할 수 있습니다. 이 메서드는 고객 트랜잭션이 지정된 프로모션에 적합한 경우 True를 반환합니다. 파트너는 거래를 제출하기 전에 자격을 확인하여 프로모션이 적용되도록 할 수 있습니다.
필수 조건
- 설명된 자격 증명은 파트너 센터 인증에서 확인할 수 있습니다. 이 시나리오는 독립 실행형 앱과 App+사용자 자격 증명을 모두 사용하여 인증을 지원합니다.
- 자격에는 구매한 제품 sku 가용성, 평가 중인 프로모션 ID, 거래 수량, 기간 및 청구 주기 포함됩니다.
- 이 API에 대한 제한 속도는 파트너 테넌트당 분당 최대 625개 요청(RPM)입니다. 제한을 초과하는 호출은 429의 http 응답을 생성합니다. 제한에 대한 자세한 내용은 제한 지침을 참조하세요.
REST 요청
요청 구문
| 메서드 | 요청 URI |
|---|---|
| POST | {baseURL}/v1/customers/{customerId}/promotionEligibilities HTTP/1.1 |
URI 매개 변수
다음 쿼리 매개 변수를 사용하여 사용 가능한 승격을 반환합니다.
| 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| customerId | string | Y | 값은 GUID 형식의 customer-tenant-id이며, 이는 고객을 지정할 수 있는 식별자입니다. |
요청 헤더
자세한 내용은 파트너 센터 REST 헤더를 참조하세요.
요청 본문
본문에는 PromotionEligibilitiesRequestItems의 컬렉션이 포함되어 있습니다. 이 표는 PromotionEligibilitiesRequestItem의 속성을 설명합니다.
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
| 카탈로그항목ID | 문자열 | 예 | 카탈로그 항목 식별자입니다. |
| 수량 | 정수 | 예 | 라이선스 또는 인스턴스 수입니다. |
| 계약 기간 | 날짜시간 | 예 | 용어의 기간에 대한 ISO 8601 표현입니다. 현재 지원되는 값은 P1M(1개월), P1Y(1년) 및 P3Y(3년)입니다. |
| 빌링사이클 | 문자열 | 예 | 청구 주기 형식을 나타내는 값입니다. |
| promotionId | 문자열 | 아니요 | 프로모션 아이템 식별자입니다. |
요청 예제
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로 반환됩니다. 자격에 대해 충족되지 않는 조건을 설명하기 위해 다양한 조건 및 제약 조건이 평가되고 오류 유형을 반환합니다.
| 자격 오류 유형 | 자격 오류 설명 |
|---|---|
| 유효하지 않은 카탈로그 항목 ID | 제공된 CatalogItemId가 잘못되었습니다. |
| 유효하지 않은 프로모션 | 제공된 승격이 잘못되었습니다. |
| 전제조건 제품 소유권 | 고객은 이 프로모션에 적합한 필수 구성 요소 제품 소유권 요구 사항을 충족하지 않습니다. |
| 상환 한도 | 이 프로모션에 대한 상환 한도가 충족되었습니다. |
| 좌석 수 | 제공된 수량은 프로모션에 대한 최소 또는 최대 좌석 요구 사항을 충족하지 않습니다. |
| 이전에 구매한 혜택 | 이 제품은 이전에 이 고객을 위해 구입했습니다. |
| 이전에 구매한 제안 | 고객에게 부적격으로 나열된 SKU 중 하나가 있으므로 이 제품을 구매할 수 없습니다. |
| 용어 | 제공된 용어는 프로모션에 적용되지 않습니다. |
| 프로모션을 사용할 수 없습니다. | 현재는 프로모션을 사용할 수 없습니다. |
응답 예제
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"
}
}
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, 20 June 2025 20:42:26 GMT
// Response example for OffersPurchasedPreviously error. This error is relevant to the June 9, 2025 three-year enterprise SKU promotions.
{
"totalCount": 1,
"items": [
{
"id": 0,
"catalogItemId": "39NFJQT1PM6C:0005:39NFJQT1Q5L7",
"quantity": 300,
"billingCycle": "Annual",
"termDuration": "P3M",
"eligibilities": [
{
"promotionId": "39NFJQT1PM6C:0005:39NFJQT1Q5L7",
"isEligible": false,
"errors": [
{
"type": "OffersPurchasedPreviously",
"description": " has been purchased previously for this customer."
"exlcudedProductsTerms":[
{
"bigId": "CFQ7TTC0MBMD/0002",
"termDuration": "P1Y"
},
{
"bigId": "CFQ7TTC0MBMD/0002",
"termDuration": "P3Y"
},
{
"bigId": "CFQ7TTC0MBMD/0004",
"termDuration": "P1Y"
}
]
}
]
}
"attributes": {
"objectType": "PromotionEligibilities"
}
}
],
"attributes": {
"objectType": "Collection"
}
}