Verificare l'idoneità per la promozione

Articolo
03/20/2024

Si applica a

Centro per i partner

Ruoli appropriati

Amministratore globale
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.

Corpo della richiesta

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

Proprietà	Type	Obbligatorio	Descrizione
catalogItemId	string	Sì	Identificatore dell'elemento del catalogo.
quantity	int	Sì	Numero di licenze o istanze.
termDuration	DateTime	Sì	Rappresentazione ISO 8601 della durata del termine. I valori supportati correnti sono P1M (un mese), P1Y (un anno) e P3Y (tre anni).
billingCycle	string	Sì	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: 81b08ffe-4cf8-49cd-82db-5c2fb0a8e132
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: 81b08ffe-4cf8-49cd-82db-5c2fb0a8e133
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: 81b08ffe-4cf8-49cd-82db-5c2fb0a8e132
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: 81b08ffe-4cf8-49cd-82db-5c2fb0a8e133
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"
    }
}

Condividi tramite