Sprawdź uprawnienia do promocji

Artykuł
09/27/2024

Dotyczy

Centrum partnerskie

Odpowiednie role

Agent administracyjny

Uwaga

Nowe środowiska handlowe dla usług opartych na licencjach obejmują wiele nowych funkcji i są dostępne dla wszystkich Dostawca rozwiązań w chmurze (CSP). Aby uzyskać więcej informacji, zobacz omówienie nowych środowisk handlowych.

Parterzy mogą sprawdzić, czy transakcja klienta kwalifikuje się do danej promocji. Ta metoda zwraca wartość 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

Poświadczenia zgodnie z opisem w temacie Uwierzytelnianie w Centrum partnerskim. Ten scenariusz obsługuje uwierzytelnianie zarówno przy użyciu autonomicznych poświadczeń aplikacji, jak i aplikacji i 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

Method	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	Type	Wymagania	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ść	Type	Wymagania	opis
catalogItemId	string	Tak	Identyfikator elementu wykazu.
ilość	int	Tak	Liczba licencji lub wystąpień.
termDuration	Data/godzina	Tak	Reprezentacja iso 8601 czasu trwania terminu. 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	string	Nie	Identyfikator elementu podwyższania poziomu.

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 powodzenia 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 uzyskać pełną listę, zobacz Kody błędów.

Typy błędów i opisy uprawnień

Uprawnienia będą zwracać 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 i zwracają typy błędów, aby opisać warunki, które nie zostały spełnione dla uprawnień.

Typ błędu kwalifikowalności	Opis błędu kwalifikowalności
InvalidCatalogItemId	Podany identyfikator CatalogItemId jest nieprawidłowy.
InvalidPromotion	Podana promocja jest nieprawidłowa.
PrerequisiteProductOwnership	Klient nie spełnia wymagań wstępnych dotyczących własności produktu, aby kwalifikować się do tej promocji.
RedemptionLimit	Osiągnięto limit wykupu dla tej promocji.
SeatCount	Podana ilość nie spełnia minimalnych ani maksymalnych wymagań dotyczących miejsca w promocji.
OfertaPurchasedPreviously	Ta oferta została zakupiona wcześniej dla tego klienta.
Termin	Podany termin nie ma zastosowania do promocji.
NoPromotionsAvailable	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