Überprüfen der Berechtigung für eine Promotion

Artikel
09/27/2024

Gilt für

Partner Center

Geeignete Rollen

Administrator-Agent

Hinweis

Die neuen Commerce-Umgebungen für lizenzbasierte Dienste enthalten zahlreiche neue Funktionen und stehen allen Cloud Solution Providern (CSP) zur Verfügung. Weitere Informationen finden Sie in der Übersicht über neue Commerce-Erfahrungen.

Teiler können überprüfen, ob eine Kundentransaktion für eine bestimmte Aktion berechtigt ist. Diese Methode gibt True zurück, wenn die Kundentransaktion für eine bestimmte Aktion berechtigt ist. Partner können die Berechtigung überprüfen, bevor Sie eine Transaktion übermitteln, um sicherzustellen, dass die Aktion angewendet wird.

Voraussetzungen

Anmeldeinformationen, wie unter Partner Center-Authentifizierung beschrieben. Dieses Szenario unterstützt die Authentifizierung mit eigenständigen App- und App+Benutzeranmeldeinformationen.
Die Berechtigung umfasst die erworbene Produkt-Sku-Verfügbarkeit, die bewertete Angebots-ID, die Menge, die Laufzeit und Abrechnungszeitraum der Transaktion.
Die Einschränkungsrate für diese API beträgt maximal 625 Anforderungen pro Minute (RPM) pro Partnermandanten. Aufrufe, die den Grenzwert überschreiten, führen zu der HTTP-Antwort von 429. Informationen zur Drosselung finden Sie unter Drosselungsleitfaden .

REST-Anforderung

Anforderungssyntax

Methode	Anforderungs-URI
POST	{baseURL}/v1/customers/{customerId}/promotionEligibilities HTTP/1.1

URI-Parameter

Verwenden Sie die folgenden Abfrageparameter, um verfügbare Werbeaktionen zurückzugeben.

Name	Type	Erforderlich	Beschreibung
customerId	string	Y	Der Wert ist eine als GUID formatierte customer-tenant-id, bei der es sich um einen Bezeichner handelt, mit dem Sie einen Kunden angeben können.

Anforderungsheader

Weitere Informationen finden Sie unter Partner Center-REST-Header.

Anforderungstext

Der Text enthält eine Sammlung von PromotionEligibilitiesRequestItems. Diese Tabelle beschreibt die Eigenschaften für ein PromotionEligibilitiesRequestItem.This table describes the properties for a PromotionEligibilitiesRequestItem.

Eigenschaft	Type	Erforderlich	Beschreibung
catalogItemId	Zeichenfolge	Ja	Der Katalogelementbezeichner.
Menge	int	Ja	Die Anzahl der Lizenzen oder Instanzen.
termDuration	DateTime	Ja	Eine ISO 8601-Darstellung der Dauer des Begriffs. Die aktuellen unterstützten Werte sind P1M (ein Monat), P1Y (ein Jahr) und P3Y (drei Jahre).
billingCycle	Zeichenfolge	Ja	Der Wert, der den Typ des Abrechnungszeitraum angibt.
promotionId	Zeichenfolge	No	Der Bezeichner des Heraufaufsufungselements.

Anforderungsbeispiel

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-Antwort

Wenn eine promotionId bereitgestellt wird und die Anforderung erfolgreich ist, gibt diese Methode eine Sammlung von Berechtigungsergebnissen zurück. Wenn "promotionId" nicht angegeben wird und die Anforderung erfolgreich ist, gibt diese Methode alle Für das angegebene Angebot und die entsprechende Kundenberechtigung für jede Werbeaktion zurück.

Erfolgs- und Fehlercodes der Antwort

Jede Antwort enthält einen HTTP-Statuscode, der Erfolg oder Fehler und weitere Debuginformationen angibt. Verwenden Sie ein Netzwerkablaufverfolgungstool, um diesen Code, fehlertyp und weitere Parameter zu lesen. Die vollständige Liste findest du unter Partner-API: REST-Fehlercodes.

Berechtigungsfehlertypen und Beschreibungen

Die Berechtigung gibt "false" zurück, wenn die Berechtigungsprüfungen bestimmen, dass die Produkt-SKU, die anhand der Angebots-ID ausgewertet wird, nicht ausgerichtet ist. Verschiedene Bedingungen und Einschränkungen werden ausgewertet und geben Fehlertypen zurück, um die Bedingungen zu beschreiben, die für die Berechtigung nicht erfüllt sind.

Berechtigungsfehlertyp	Beschreibung des Berechtigungsfehlers
InvalidCatalogItemId	Die bereitgestellte CatalogItemId ist ungültig.
InvalidPromotion	Die bereitgestellte Aktion ist ungültig.
PrerequisiteProductOwnership	Der Kunde erfüllt nicht die erforderlichen Produktbesitzanforderungen, um für diese Werbeaktion berechtigt zu sein.
RedemptionLimit	Das Einlösungslimit für diese Aktion wurde erreicht.
SeatCount	Die angegebene Menge erfüllt nicht die Mindest- oder Maximalplatzanforderungen für die Aktion.
OfferPurchasedPreviously	Dieses Angebot wurde zuvor für diesen Kunden erworben.
Begriff	Der angegebene Begriff gilt nicht für die Werbeaktion.
NoPromotionsAvailable	Derzeit sind keine Werbeaktionen verfügbar.

Beispielantwort

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

Teilen über