Afficher en anglais

Partage via

Vérifier l’admissibilité de la promotion

  • Article

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

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

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