Compartir a través de

Comprobar idoneidad de la promoción

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 Tipo 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 Tipo Obligatorio Descripción
catalogItemId cuerda / cadena Sí Identificador del elemento de catálogo.
cantidad Int Sí Número de licencias o instancias.
duración del término Fecha y hora 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).
ciclo de facturación cuerda / cadena Sí Valor que indica el tipo de ciclo de facturación.
promotionId cuerda / cadena 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
Id de Artículo de Catálogo Inválido CatalogItemId proporcionado no es válido.
Promoción inválida La promoción proporcionada no es válida.
PropiedadDeProductoPrerequisito El cliente no cumple los requisitos previos de propiedad del producto para poder optar a esta promoción.
Límite de Redención Se ha cumplido el límite de canje para esta promoción.
Capacidad de Asientos La cantidad proporcionada no cumple los requisitos mínimos o máximos de asiento para la promoción.
OfertaCompradaPreviamente Esta oferta se ha comprado anteriormente para este cliente.
OfertasCompradasPreviamente Esta oferta no se puede comprar porque el cliente tiene una de las SKU enumeradas como no válidas.
Término El término proporcionado no es aplicable a la promoción.
No hay promociones disponibles 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"
    }
}

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, 20 June 2025 20:42:26 GMT

// Response example for OffersPurchasedPreviously error. This error is relevant to the June 9, 2025 three-year enterprise SKU promotions.
{
    "totalCount": 1,
    "items": [
        {
            "id": 0,
            "catalogItemId": "39NFJQT1PM6C:0005:39NFJQT1Q5L7",
            "quantity": 300,
            "billingCycle": "Annual",
            "termDuration": "P3M",
            "eligibilities": [
                {
                    "promotionId": "39NFJQT1PM6C:0005:39NFJQT1Q5L7",
                    "isEligible": false,
                    "errors": [
                            {                      
                            "type": "OffersPurchasedPreviously",
                            "description": " has been purchased previously for this customer."
			                              "exlcudedProductsTerms":[
                                  {
                                      "bigId": "CFQ7TTC0MBMD/0002",
                                      "termDuration": "P1Y"
                        	         },
                   		             {
                        	             "bigId": "CFQ7TTC0MBMD/0002",
			                                   "termDuration": "P3Y"
                        	         },
                   		             {
                        	              "bigId": "CFQ7TTC0MBMD/0004",
				                                   "termDuration": "P1Y"
                                  }
                               ]
                            }
 		                 ]
                }

            "attributes": {
                "objectType": "PromotionEligibilities"
            }
        }
    ],
    "attributes": {
        "objectType": "Collection"
    }
}