Auf Englisch lesen

Freigeben über

Überprüfen der Berechtigung für eine Promotion

  • Artikel

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

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