Sprawdź uprawnienia do promocji

Artykuł
03/07/2025

Dotyczy

Centrum partnerskie

Odpowiednie role

Agent administracyjny

Uwaga

Nowe doświadczenia handlowe dla usług opartych na licencjach obejmują wiele nowych funkcji i są dostępne dla wszystkich Dostawców Rozwiązań w Chmurze (CSP - Cloud Solution Providers). Aby uzyskać więcej informacji, zobacz przegląd nowych doświadczeń handlowych.

Parterzy mogą sprawdzić, czy transakcja klienta kwalifikuje się do danej promocji. Ta metoda zwraca True, jeśli transakcja klienta kwalifikuje się do danej promocji. Partnerzy mogą zweryfikować uprawnienia przed przesłaniem transakcji, aby upewnić się, że promocja zostanie zastosowana.

Wymagania wstępne

Dane uwierzytelniające zgodnie z opisem w uwierzytelnianiu w Centrum Partnerów. Ten scenariusz obsługuje uwierzytelnianie zarówno autonomicznych poświadczeń aplikacji, jak i poświadczeń aplikacji+użytkownika.
Uprawnienia obejmują zakupioną dostępność jednostki SKU produktu, szacowany identyfikator promocji, ilość, czas trwania terminu i cykl rozliczeniowy transakcji.
Szybkość ograniczania dla tego interfejsu API wynosi maksymalnie 625 żądań na minutę (RPM) dla dzierżawy partnera. Wywołania, które przekraczają limit, spowodują odpowiedź HTTP 429. Aby uzyskać informacje na temat ograniczania przepustowości, zobacz wskazówki dotyczące ograniczania przepustowości.

Żądanie REST

Składnia żądania

Metoda	Identyfikator URI żądania
POST	{baseURL}/v1/customers/{customerId}/promotionEligibilities HTTP/1.1

Parametr identyfikatora URI

Użyj następujących parametrów zapytania, aby zwrócić dostępne promocje.

Nazwisko	Typ	Wymagane	opis
customerId	string	Y	Wartość jest identyfikatorem GUID w formacie customer-tenant-id, który jest identyfikatorem umożliwiającym określenie klienta.

Nagłówki żądań

Aby uzyskać więcej informacji, zobacz Nagłówki REST Centrum Partnerskiego.

Treść żądania

Treść zawiera kolekcję PromotionEligibilitiesRequestItems. W tej tabeli opisano właściwości elementu PromotionEligibilitiesRequestItem.

Właściwość	Typ	Wymagane	opis
catalogItemId	string	Tak	Identyfikator elementu wykazu.
ilość	int	Tak	Liczba licencji lub wystąpień.
czas trwania	Znacznik czasu	Tak	Reprezentacja ISO 8601 czasu trwania okresu. Bieżące obsługiwane wartości to P1M (jeden miesiąc), P1Y (jeden rok) i P3Y (trzy lata).
billingCycle	string	Tak	Wartość wskazująca typ cyklu rozliczeniowego.
identyfikator promocji	sznurek	Nie	Identyfikator elementu promocyjnego.

Przykład żądania

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"
        }
    ]
}

Odpowiedź REST

Jeśli podano identyfikator promocji i żądanie zakończy się powodzeniem, ta metoda zwraca kolekcję wyników kwalifikowalności. Jeśli wartość promotionId nie zostanie podana i żądanie zakończy się powodzeniem, ta metoda zwraca wszystkie promocje dostępne dla określonej oferty oraz odpowiednie uprawnienia klienta do każdej promocji.

Kody sukcesu i błędów odpowiedzi

Każda odpowiedź zawiera kod stanu HTTP, który wskazuje powodzenie lub niepowodzenie i więcej informacji o debugowaniu. Użyj narzędzia do śledzenia sieci, aby odczytać ten kod, typ błędu i inne parametry. Aby zobaczyć pełną listę, zobacz Kody błędów.

Typy błędów dotyczące kwalifikowalności i ich opisy

Uprawnienie zwróci wartość false, jeśli sprawdzanie uprawnień określi, że jednostka SKU produktu oceniana względem identyfikatora promocji nie jest zgodna. Różne warunki i ograniczenia są oceniane, a zwracane typy błędów opisują warunki niespełnione dla kwalifikowalności.

Typ błędu kwalifikowalności	Opis błędu kwalifikowalności
InvalidCatalogItemId	Podany identyfikator CatalogItemId jest nieprawidłowy.
NieprawidłowaPromocja	Podana promocja jest nieprawidłowa.
WłasnośćWymaganegoProduktu	Klient nie spełnia wymagań wstępnych dotyczących własności produktu, aby kwalifikować się do tej promocji.
LimitOdkupienia	Osiągnięto limit wykupu dla tej promocji.
LiczbaMiejsc	Podana ilość nie spełnia minimalnych ani maksymalnych wymagań dotyczących miejsca w promocji.
Oferta zakupiona wcześniej	Ta oferta została zakupiona wcześniej dla tego klienta.
Termin	Podany termin nie ma zastosowania do promocji.
Brak dostępnych promocji	Obecnie nie ma dostępnych promocji.

Przykład odpowiedzi

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"
    }
}

Udostępnij za pośrednictwem