Comprobar idoneidad de la promoción

  • Artículo

Se aplica a

  • Centro de partners

Roles adecuados

  • Administrador global
  • Agente de administración

Nota:

Las nuevas experiencias comerciales para los servicios basados en licencias incluyen muchas funcionalidades nuevas y están disponibles para todos los Proveedores de soluciones en la nube (CSP). Para más información, consulte Introducción a las nuevas experiencias comerciales.

Los participantes pueden comprobar si una transacción de cliente es apta para una promoción determinada. Este método devuelve True si la transacción del cliente es apta para una promoción determinada. Los partners pueden comprobar la idoneidad antes de enviar una transacción para asegurarse de que se aplicará la promoción.

Requisitos previos

  • Credenciales tal como se describen en el artículo Autenticación del Centro de partners. Este escenario admite la autenticación con credenciales de aplicación independiente y app+usuario.
  • La idoneidad incluye la disponibilidad de SKU del producto comprada, el identificador de promoción que se va a evaluar, la cantidad, la duración del plazo y el ciclo de facturación de la transacción.
  • La velocidad de limitación de esta API es un máximo de 625 solicitudes por minuto (RPM) por inquilino del asociado. Las llamadas que superan el límite darán lugar a la respuesta http de 429. Consulte la guía de limitación para obtener información sobre la limitación.

Solicitud REST

Sintaxis de la solicitud

Método URI de solicitud
POST {baseURL}/v1/customers/{customerId}/promotionEligibilities HTTP/1.1

Parámetro de URI

Use los siguientes parámetros de consulta para devolver promociones disponibles.

Nombre Type Obligatorio Descripción
Customerid string Y El valor es un elemento customer-tenant-id con formato de GUID, que es un identificador que te permite especificar un cliente.

Encabezados de solicitud

Para obtener más información, consulta Encabezados REST del Centro de partners.

Cuerpo de la solicitud

Body incluye una colección de PromotionEligibilitiesRequestItems. En esta tabla se describen las propiedades de un objeto PromotionEligibilitiesRequestItem.

Propiedad Type Obligatorio Descripción
catalogItemId string Sí Identificador del elemento de catálogo.
cantidad int Sí Número de licencias o instancias.
termDuration DateTime Sí Representación ISO 8601 de la duración del término. Los valores admitidos actuales son P1M (un mes), P1Y (un año) y P3Y (tres años).
billingCycle string Sí Valor que indica el tipo de ciclo de facturación.
promotionId string No Identificador del elemento de promoción.

Ejemplo de solicitud

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

Respuesta REST

Si se proporciona un valor de promotionId y la solicitud se realiza correctamente, este método devuelve una colección de resultados de idoneidad. Si no se proporciona promotionId y la solicitud se realiza correctamente, este método devuelve todas las promociones disponibles para la oferta especificada y la idoneidad del cliente correspondiente para cada promoción.

Códigos de error y de respuesta correctos

Cada respuesta incluye un código de estado HTTP que indica éxito o error y más información de depuración. Use una herramienta de seguimiento de red para leer este código, tipo de error y más parámetros. Para obtener la lista completa, consulte Códigos de error.

Tipos y descripciones de errores de idoneidad

La idoneidad devolverá false si las comprobaciones de idoneidad determinan la SKU del producto que se va a evaluar con respecto al identificador de promoción no se alinean. Se evalúan varias condiciones y restricciones y devuelven tipos de error para describir las condiciones que no se cumplen para la idoneidad.

Tipo de error de idoneidad Descripción del error de idoneidad
InvalidCatalogItemId CatalogItemId proporcionado no es válido.
InvalidPromotion La promoción proporcionada no es válida.
PrerequisiteProductOwnership El cliente no cumple los requisitos previos de propiedad del producto para poder optar a esta promoción.
RedemptionLimit Se ha cumplido el límite de canje para esta promoción.
SeatCount La cantidad proporcionada no cumple los requisitos mínimos o máximos de asiento para la promoción.
OfferPurchasedPreviously Esta oferta se ha comprado anteriormente para este cliente.
Término El término proporcionado no es aplicable a la promoción.
NoPromotionsAvailable No hay promociones disponibles en este momento.

Ejemplo de respuesta

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