Verificar elegibilidade da promoção

Aplica-se a

• Partner Center

Funções apropriadas

• Agente administrativo

Os participantes podem verificar se uma transação de cliente é elegível para uma determinada promoção. Esse método retorna True se a transação do cliente for qualificada para uma determinada promoção. Os parceiros podem verificar a elegibilidade antes de enviar uma transação para garantir que a promoção será aplicada.

Pré-requisitos

• Credenciais conforme descrito na autenticação do Partner Center. Este cenário oferece suporte à autenticação com credenciais autônomas de Aplicativo e Aplicativo+Usuário.
• A elegibilidade inclui a disponibilidade de sku do produto comprado, o ID da promoção que está sendo avaliado, a quantidade, a duração do prazo e o ciclo de faturamento da transação.
• A taxa de limitação para esta API é de no máximo 625 solicitações por minuto (RPM) por locatário parceiro. As chamadas que excederem o limite resultarão na resposta http de 429. Consulte as diretrizes de limitação para obter informações sobre limitação.

Pedido REST

Sintaxe da solicitação

Parâmetro URI

Use os seguintes parâmetros de consulta para retornar as promoções disponíveis.

Cabeçalhos do pedido

Para obter mais informações, consulte Cabeçalhos REST do Partner Center.

Corpo do pedido

Body inclui uma coleção de PromotionEligibilitiesRequestItems. Esta tabela descreve as propriedades de um PromotionEligibilitiesRequestItem.

Exemplo de solicitação

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

Resposta do REST

Se um promotionId for fornecido e a solicitação for bem-sucedida, esse método retornará uma coleção de resultados de qualificação. Se promotionId não for fornecido e a solicitação for bem-sucedida, esse método retornará todas as promoções disponíveis para a oferta especificada e a elegibilidade do cliente correspondente para cada promoção.

Códigos de sucesso e erro de resposta

Cada resposta vem com um código de status HTTP que indica sucesso ou falha e mais informações de depuração. Use uma ferramenta de rastreamento de rede para ler esse código, tipo de erro e mais parâmetros. Para obter a lista completa, consulte Códigos de erro.

Tipos de erros de elegibilidade e descrições

A elegibilidade retornará false se as verificações de elegibilidade determinarem que o SKU do produto que está sendo avaliado em relação ao ID da promoção não estiver alinhado. Várias condições e restrições são avaliadas e tipos de erro de retorno para descrever as condições não atendidas para a elegibilidade.

Exemplo de resposta

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