Comprobar idoneidad de la promoción

Artículo
09/27/2024

Se aplica a

Centro de partners

Roles adecuados

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

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

Compartir a través de