Vérifier l’admissibilité de la promotion

Article
09/27/2024

S’applique à

Espace partenaires

Rôles appropriés

Agent administrateur

Remarque

Les nouvelles expériences commerciales pour les services basés sur des licences incluent de nombreuses nouvelles fonctionnalités et sont disponibles pour tous les Fournisseur de solutions Cloud (CSP). Pour plus d’informations, consultez la Vue d’ensemble des nouvelles expériences commerciales.

Les parteurs peuvent vérifier si une transaction client est éligible à une promotion donnée. Cette méthode retourne True si la transaction client est éligible à une promotion donnée. Les partenaires peuvent vérifier l’éligibilité avant de soumettre une transaction pour s’assurer que la promotion sera appliquée.

Prérequis

Informations d’identification, comme décrit dans Authentification auprès de l’Espace partenaires. Ce scénario prend en charge l’authentification avec les informations d’identification d’application et d’application+utilisateur autonomes.
L’éligibilité inclut la disponibilité de la référence du produit achetée, l’ID de promotion évalué, la quantité, la durée du terme et cycle de facturation de la transaction.
Taux de limitation pour cette API un maximum de 625 requêtes par minute (RPM) par locataire partenaire. Les appels qui dépassent la limite entraînent la réponse http de 429. Consultez les conseils de limitation pour plus d’informations sur la limitation.

Demande REST

Syntaxe de la requête

Method	URI de demande
POST	{baseURL}/v1/customers/{customerId}/promotionEligibilities HTTP/1.1

Paramètre d’URI

Utilisez les paramètres de requête suivants pour retourner les promotions disponibles.

Nom	Type	Requise	Description
customerId	string	Y	La valeur est un paramètre customer-tenant-id au format GUID, à savoir un identificateur qui vous permet de spécifier un client.

En-têtes de requête

Pour plus d’informations, consultez En-têtes REST de l’Espace Partenaires.

Corps de la demande

Body inclut une collection de PromotionEligibilitiesRequestItems. Ce tableau décrit les propriétés d’un Objet PromotionEligibilitiesRequestItem.

Propriété	Type	Requise	Description
catalogItemId	string	Oui	Identificateur de l’élément de catalogue.
quantité	int	Oui	Nombre de licences ou d’instances.
termDuration	Date/Heure	Oui	Représentation ISO 8601 de la durée du terme. Les valeurs prises en charge actuelles sont P1M (un mois), P1Y (un an) et P3Y (trois ans).
billingCycle	string	Oui	Valeur qui indique le type de cycle de facturation.
promotionId	string	Non	Identificateur de l’élément de promotion.

Exemple de requête

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

Réponse REST

Si un id de promotion est fourni et que la demande réussit, cette méthode retourne une collection de résultats d’éligibilité. Si promotionId n’est pas fourni et que la demande réussit, cette méthode retourne toutes les promotions disponibles pour l’offre spécifiée et l’éligibilité du client correspondant pour chaque promotion.

Codes d’erreur et de réussite de la réponse

Chaque réponse est fournie avec un code d’état HTTP qui indique la réussite ou l’échec et plus d’informations de débogage. Utilisez un outil de suivi réseau pour lire ce code, le type d’erreur et d’autres paramètres. Pour obtenir la liste complète, consultez Codes d’erreur.

Types et descriptions des erreurs d’éligibilité

L’éligibilité retourne false si les vérifications d’éligibilité déterminent la référence SKU du produit évaluée par rapport à l’ID de promotion ne s’alignent pas. Diverses conditions et contraintes sont évaluées et retournent des types d’erreurs pour décrire les conditions non remplies pour l’éligibilité.

Type d’erreur d’éligibilité	Description de l’erreur d’éligibilité
InvalidCatalogItemId	CatalogItemId fourni n’est pas valide.
InvalidPromotion	La promotion fournie n’est pas valide.
PrerequisiteProductOwnership	Le client ne répond pas aux exigences de propriété de produit requises pour pouvoir bénéficier de cette promotion.
RedemptionLimit	La limite d’échange pour cette promotion a été respectée.
SeatCount	La quantité fournie ne répond pas aux exigences minimales ou maximales en matière de siège pour la promotion.
OfferPurchasedPreviously	Cette offre a été achetée précédemment pour ce client.
Terme	Le terme fourni n’est pas applicable à la promotion.
NoPromotionsAvailable	Il n’y a pas de promotions disponibles pour l’instant.

Exemple de réponse

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

Partager via