Verificare l'idoneità per la promozione

Si applica a

  • Centro per i partner

Ruoli appropriati

  • Agente amministratore

Nota

Le nuove esperienze commerciali per i servizi basati su licenza includono molte nuove funzionalità e sono disponibili per tutti i provider di soluzioni cloud. Per altre informazioni, vedere la panoramica delle nuove esperienze commerciali.

I parter possono verificare se una transazione cliente è idonea per una determinata promozione. Questo metodo restituisce True se la transazione del cliente è idonea per una determinata promozione. I partner possono verificare l'idoneità prima di inviare una transazione per assicurarsi che venga applicata la promozione.

Prerequisiti

  • Credenziali descritte in Autenticazione del Centro per i partner. Questo scenario supporta l'autenticazione con le credenziali app autonome e App+Utente.
  • L'idoneità include la disponibilità dello SKU del prodotto acquistata, l'ID promozione valutato, la quantità, la durata del periodo e il ciclo di fatturazione della transazione.
  • Velocità di limitazione per questa API per un massimo di 625 richieste al minuto (RPM) per tenant partner. Le chiamate che superano il limite genereranno la risposta HTTP 429. Per informazioni sulla limitazione delle richieste, vedere indicazioni sulla limitazione.

Richiesta REST

Sintassi della richiesta

metodo URI della richiesta
POST {baseURL}/v1/customers/{customerId}/promotionEligibilities HTTP/1.1

Parametro URI

Usare i parametri di query seguenti per restituire promozioni disponibili.

Nome Digita Obbligatorio Descrizione
customerId string Y Il valore è customer-tenant-id con formato GUID, un identificatore che consente di specificare un cliente.

Intestazioni delle richieste

Per altre informazioni, vedi Intestazioni REST del Centro per i partner.

Testo della richiesta

Body include una raccolta di PromotionEligibilitiesRequestItems. Questa tabella descrive le proprietà di un oggetto PromotionEligibilitiesRequestItem.

Proprietà Type Obbligatorio Descrizione
catalogItemId string Identificatore dell'elemento del catalogo.
quantity int Numero di licenze o istanze.
termDuration DateTime Rappresentazione ISO 8601 della durata del termine. I valori supportati correnti sono P1M (un mese), P1Y (un anno) e P3Y (tre anni).
billingCycle string Valore che indica il tipo di ciclo di fatturazione.
promotionId string No Identificatore dell'elemento promozionale.

Esempio di richiesta

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

Risposta REST

Se viene fornito un promotionId e la richiesta ha esito positivo, questo metodo restituisce una raccolta di risultati di idoneità. Se promotionId non viene fornito e la richiesta ha esito positivo, questo metodo restituisce tutte le promozioni disponibili per l'offerta specificata e l'idoneità del cliente corrispondente per ogni promozione.

Codici di errore e di esito della risposta

Ogni risposta viene fornita con un codice di stato HTTP che indica l'esito positivo o negativo e altre informazioni di debug. Usare uno strumento di traccia di rete per leggere questo codice, il tipo di errore e altri parametri. Per l'elenco completo, vedi Codici di errore.

Tipi e descrizioni degli errori di idoneità

L'idoneità restituirà false se i controlli di idoneità determinano che lo SKU del prodotto valutato rispetto all'ID promozione non è allineato. Diverse condizioni e vincoli vengono valutati e restituiscono tipi di errore per descrivere le condizioni non soddisfatte per l'idoneità.

Tipo di errore di idoneità Descrizione dell'errore di idoneità
InvalidCatalogItemId CatalogItemId specificato non è valido.
InvalidPromotion L'innalzamento di livello specificato non è valido.
PrerequisitoProductOwnership Il cliente non soddisfa i requisiti di proprietà del prodotto prerequisiti per essere idonei per questa promozione.
RiscattoLimit Il limite di riscatto per questa promozione è stato raggiunto.
SeatCount La quantità fornita non soddisfa i requisiti minimi o massimi per la promozione.
OfferPurchasedPreviously Questa offerta è stata acquistata in precedenza per questo cliente.
Termine Il termine specificato non è applicabile per la promozione.
NoPromotionsAvailable Al momento non sono disponibili promozioni.

Risposta di esempio

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