Verificar elegibilidade da promoção
Aplica-se a
- Partner Center
Funções apropriadas
- Administrador global
- Agente de administração
Observação
As novas experiências de comércio para serviços baseados em licença incluem muitos recursos novos e estão disponíveis para todos os CSPs (provedores de soluções em nuvem). Para obter mais informações, confira a visão geral das novas experiências de comércio.
Os participantes podem verificar se uma transação do cliente é elegível para uma determinada promoção. Esse método retornará 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 em Autenticação do Partner Center. Esse cenário oferece suporte à autenticação com credenciais autônomas de Aplicativo e Aplicativo+Usuário.
- A qualificação inclui a disponibilidade do sku do produto adquirido, 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 essa 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.
Solicitação REST
Sintaxe da solicitação
Método | URI da solicitação |
---|---|
POST | {baseURL}/v1/customers/{customerId}/promotionEligibilities HTTP/1.1 |
Parâmetro do URI
Use os parâmetros de consulta a seguir para retornar promoções disponíveis.
Nome | Digitar | Obrigatória | Descrição |
---|---|---|---|
customerId | cadeia de caracteres | Y | O valor é um customer-tenant-id formatado pelo GUID, que é um identificador que permite que você especifique um cliente. |
Cabeçalhos da solicitação
Para obter mais informações, confira Cabeçalhos REST do Partner Center.
Corpo da solicitação
Body inclui uma coleção de PromotionEligibilitiesRequestItems. Esta tabela descreve as propriedades de um PromotionEligibilitiesRequestItem.
Propriedade | Type | Obrigatória | Descrição |
---|---|---|---|
catalogItemId | string | Yes | O identificador de item de catálogo. |
quantity | int | Yes | O número de licenças ou instâncias. |
prazoDuração | Datetime | Yes | Uma representação ISO 8601 da duração do termo. Os valores atuais suportados são P1M (um mês), P1Y (um ano) e P3Y (três anos). |
billingCycle | string | Yes | O valor que indica o tipo de ciclo de faturamento. |
promotionId | string | Não | O identificador do item de promoção. |
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: 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"
}
]
}
Resposta 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 êxito e de 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, confira Códigos de Erro.
Tipos e descrições de erros de elegibilidade
A elegibilidade retornará false se as verificações de qualificação 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 retornam tipos de erro para descrever as condições não atendidas para a elegibilidade.
Tipo de erro de elegibilidade | Descrição do erro de elegibilidade |
---|---|
InvalidCatalogItemId | O CatalogItemId fornecido é inválido. |
InvalidPromotion | A promoção fornecida é inválida. |
PrerequisiteProductOwnership | O cliente não atende aos requisitos de propriedade do produto pré-requisito para ser elegível para esta promoção. |
RedemptionLimit | O limite de resgate para esta promoção foi cumprido. |
SeatCount | A quantidade fornecida não satisfaz os requisitos mínimos ou máximos de assentos para a promoção. |
OfferPurchasedPreviously | Esta oferta foi comprada anteriormente para este cliente. |
Termo | O termo fornecido não é aplicável para a promoção. |
NãoPromoçõesDisponível | Não há promoções disponíveis no momento. |
Exemplo de resposta
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"
}
}
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de