Agendar alterações para uma nova assinatura de comércio usando APIs do Partner Center

Aplica-se a: Partner Center

Este artigo descreve como você pode usar a API do Partner Center para agendar alterações para uma nova assinatura comercial, que só ocorrem na renovação. Essa API dá suporte a assinaturas de software e baseadas em licenças de novo comércio.

A criação de alterações agendadas permite que você modifique sua assinatura, automaticamente, quando ocorrer a próxima renovação. Ao programar alterações, você pode optar por aumentar ou diminuir o número de licenças, modificar o prazo e a frequência de cobrança e até mesmo optar por atualizar o SKU. As alterações de agendamento permitem que você faça modificações em sua assinatura na renovação, em vez de imediatamente durante o período atual.

Pré-requisitos

• Credenciais, conforme descrito em Autenticação do Partner Center. Esse cenário dá suporte à autenticação com credenciais autônomas de Aplicativo e Aplicativo+Usuário.

• Uma ID do cliente (customer-tenant-id). Se você não souber a ID do cliente, poderá procurá-la no Partner Center selecionando a área de trabalho Clientes, depois o cliente na lista de clientes e, em seguida, Conta. Na página Conta do cliente, procure a ID da Microsoft na seção Informações da Conta do Cliente. O ID da Microsoft é o mesmo que o ID do cliente (customer-tenant-id).

• Uma ID de assinatura.

• A renovação automática está habilitada na assinatura.

Método do Partner Center

Para agendar alterações para uma assinatura no Partner Center:

1. Selecione um cliente.

2. Selecione a assinatura para a qual você deseja agendar alterações.

3. Ative a renovação automática.

4. Selecione Gerenciar renovação.

5. Faça alterações na assinatura para que entrem em vigor na renovação.

6. Selecione OK para fechar o painel lateral.

7. selecione Enviar para salvar as alterações.

C#

Para agendar alterações para a assinatura de um cliente:

1. Obtenha a assinatura por ID.
2. Obtenha a qualificação de transição para o tipo de qualificação de transição agendado.
3. Crie um objeto ScheduledNextTermInstructions e defina-o como a propriedade da assinatura.
4. Chame o método Patch() para atualizar a assinatura com as alterações agendadas.

var selectedSubscription = subscriptionOperations.Get();
selectedSubscription.ScheduledNextTermInstructions = new ScheduledNextTermInstructions
{
    Product = new ProductTerm
    {
        ProductId = changeToProductId,
        SkuId = changeToSkuId,
        AvailabilityId = changeToAvailabilityId,
        BillingCycle = changeToBillingCycle,
        TermDuration = changeToTermDuration,
    },
    Quantity = changeToQuantity,
    customTermEndDate = DateTime,
};
var updatedSubscription = subscriptionOperations.Patch(selectedSubscription);

Para agendar alterações para a assinatura de um cliente, em que a alteração agendada desejada é para um produto diferente:

1. Obtenha a assinatura por ID.
2. Obtenha a qualificação de transição para o tipo de qualificação de transição agendado.
3. Chame o método Patch() para atualizar a assinatura com as alterações agendadas.

Solicitação REST

Sintaxe da solicitação

Parâmetro URI

Esta tabela lista os parâmetros de consulta necessários para chamar a API.

Cabeçalhos da solicitação

Para mais informações, consulte os cabeçalhos REST do Partner Center.

Corpo da solicitação

Um recurso de assinatura completo é necessário no corpo da solicitação, com a scheduledNextTermInstructions propriedade definida. Para agendar alterações para sua assinatura, verifique se a propriedade AutoRenewEnabled está definida como true.

Para a ID de disponibilidade no final da venda com ofertas de conversões (EndofSaleWithConversions):

1. GetTransitionEligibility para retornar CatalogItemID.

   a. Lembre-se de definir o tipo de qualificação agendado, caso contrário, o padrão é imediato.

2. Use CatalogItemID para então extrair availabilityID.

Se você estiver usando GET Availabilities para determinar a disponibilidade para as instruções scheduledNextTerm e se todos os prazos tiverem o estado EOS, você receberá uma lista vazia. A melhor maneira de determinar caminhos válidos é chamar a API GetTransitionEligibilty para retornar as opções válidas.

Usando scheduledActions para definir as instruções do próximo período (alterações programadas)

Os termos de serviço estendidos introduzem uma nova maneira de definir instruções de fim de prazo. O novo constructo scheduledActions permite aos parceiros uma única maneira de definir atualizações de próximo prazo, incluindo cancelamento, renovação para termos de serviço estendidos ou renovação para outras metas de fim de prazo. Os parceiros podem definir as instruções de scheduledActions RenewToNewTerm em vez das scheduledNextTermInstructions usadas anteriormente. Mais informações sobre o uso de scheduledActions para definir instruções para o próximo período de vigência podem ser encontradas na documentação sobre o prazo de serviço estendido.

Os parceiros que usam scheduledActions também devem evitar passar scheduledNextTermInstructions quando fizerem atualizações em assinaturas elegíveis para períodos de serviço estendidos. Os parceiros podem optar por fornecer os dois, mas devem perceber que somente scheduledActions são considerados. Os parceiros podem continuar a passar apenas scheduledNextTermInstructions para definir as instruções para o próximo período.

Solicitar usando ações agendadas

{
  "autoRenewEnabled": true,
  "scheduledActions": [
    {
      "scheduledType": "TermEnd",
      "actionType": "RenewToNewTerm",
      "instructions": {
        "product": {
          "productId": "CFQ7TTC0LHXH",
          "skuId": "0001",
          "availabilityId": "CFQ7TTC0LHXH",
          "billingCycle": "annual",
          "termDuration": "P1Y",
          "promotionId": "39NFJQT20KJ2:0001:39NFJQT1Q5KK"
        },
        "quantity": 25,
        "customTermEndDate": "2027-11-31T23:59:59.000Z"
      }
    }
  ]
}

Resposta usando ações agendadas

{
  "autoRenewEnabled": true,
  "scheduledNextTermInstructions" : {
     "product": {
        "productId": "CFQ7TTC0LHXH",
        "skuId": "0001",
        "availabilityId": "CFQ7TTC0LHXH",
        "billingCycle": "annual",
        "termDuration": "P1Y",
        "promotionId": "39NFJQT20KJ2:0001:39NFJQT1Q5KK"
      },
      "quantity": 25,
      "customTermEndDate": "2027-11-31T23:59:59.000Z"
  },
  "scheduledActions":   "scheduledActions": [
    {
      "scheduledType": "TermEnd",
      "actionType": "RenewToNewTerm",
      "instructions": {
        "product": {
          "productId": "CFQ7TTC0LHXH",
          "skuId": "0001",
          "availabilityId": "CFQ7TTC0LHXH",
          "billingCycle": "annual",
          "termDuration": "P1Y",
          "promotionId": "39NFJQT20KJ2:0001:39NFJQT1Q5KK"
        },
        "quantity": 25,
        "customTermEndDate": "2027-11-31T23:59:59.000Z"
      }
    }
  ]
}

Usando scheduledActions para configurar transições na data de aniversário

Algumas SKUs trienais selecionadas com equipes podem ser agendadas para transição no aniversário do período.

Solicitar usando ações agendadas

{ 
    "id": "c10138d2-083b-4330-cf0d-6565dfaf22be", 
    "offerId": "CFQ7TTC0ZSXT:0001:CFQ7TTC0K85Z", 
    … 
    "scheduledActions": [ 
        { 
            "scheduleType": "CustomDate", // currently supported - EndOfTerm
            "actionType": "Transition", // currently supported - RenewToNewTerm, RenewToExtendedServiceTerm, Cancel 
            "effectiveDate": "2026-08-01", 
            "instructions": { 
                "product": { 
                    "productId": "CFQ7TTC0ZSXT", 
                    "skuId": "0001", 
                    "availabilityId": "CFQ7TTC0K8B0", 
                    "billingCycle": "monthly", 
                    "termDuration": "P1M" 
                }, 
            } 
        } 
    ] 
} 

Solicitação com instruções agendadas para o próximo período

PATCH https://api.partnercenter.microsoft.com/v1/customers/<customer-tenant-id>/subscriptions/<subscription-id> HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: ca7c39f7-1a80-43bc-90d8-ee7d1cad3831
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
If-Match: <etag>
Content-Type: application/json
Content-Length: 1029
Expect: 100-continue
Connection: Keep-Alive

{
    "id": "6e7aa601-629e-461b-8933-0898c3cc3c7c",
    "offerId": "DZH318Z0BXWC:0001:DZH318Z0BMJX",
    "offerName": "offer Name",
    "friendlyName": "friendly Name",
    "quantity": 1,
    "customTermEndDate": "2019-01-09T00:21:45.9263727",
    "unitType": "License(s)",
    "hasPurchasableAddons": false,
    "creationDate": "2019-01-04T01:00:12.6647304Z",
    "effectiveStartDate": "2019-01-09T00:21:45.9263727+00:00",
    "commitmentEndDate": "2019-02-08T00:21:45.9263727+00:00",
    "status": "active",
    "autoRenewEnabled": true,
    "scheduledNextTermInstructions": { 
      "product": { 
         "productId":  "DG7GMGF0DVSV", 
         "skuId":  "000P", 
         "availabilityId":  "DG7GMGF0F3Q9", 
         "billingCycle":  "Annual", 
         "termDuration":  "P3Y",
         "promotionId": "39NFJQT1PFPJ:000H:39NFJQT1Q5DK"
        }, 
      "quantity":  1 
      "customTermEndDate" : "2019-01-09T00:21:45.9263727",
     },  // original value = null 
    "isTrial": false,
    "billingType": "license",
    "billingCycle": "monthly",
    "termDuration": "P1M",
    "refundOptions": [{
        "type": "Full",
        "expiresAt": "2019-01-10T00:21:45.9263727+00:00"
    }],
    "isMicrosoftProduct": false,
    "partnerId": "",
    "contractType": "subscription",
    "publisherName": "publisher Name",
    "orderId": "ImxjLNL4_fOc-2KoyOxGTZcrlIquzls11",
    "attributes": {"objectType": "Subscription"},
}

Resposta REST

Se a solicitação for bem-sucedida, esse método retornará as propriedades atualizadas do recurso de assinatura no corpo da resposta.

Códigos de erro e êxito de resposta

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

Resposta com instruções agendadas para o próximo período

HTTP/1.1 200 OK
Content-Length: 1322
Content-Type: application/json; charset=utf-8
MS-RequestId: ca7c39f7-1a80-43bc-90d8-ee7d1cad3831
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
X-Locale: en-US

{
    "id": "6e7aa601-629e-461b-8933-0898c3cc3c7c",
    "offerId": "DZH318Z0BXWC:0001:DZH318Z0BMJX",
    "offerName": "offer Name",
    "friendlyName": "friendly Name",
    "quantity": 1,
    "customTermEndDate": "2019-01-09T00:21:45.9263727",
    "unitType": "License(s)",
    "hasPurchasableAddons": false,
    "creationDate": "2019-01-04T01:00:12.6647304Z",
    "effectiveStartDate": "2019-01-09T00:21:45.9263727+00:00",
    "commitmentEndDate": "2019-02-08T00:21:45.9263727+00:00",
    "status": "active",
    "autoRenewEnabled": true,
    "scheduledNextTermInstructions": { 
      "product": { 
         "productId":  "DG7GMGF0DVSV", 
         "skuId":  "000P", 
         "availabilityId":  "DG7GMGF0F3Q9", 
         "billingCycle":  "Annual", 
         "termDuration":  "P3Y",
         "promotionId": "39NFJQT1PFPJ:000H:39NFJQT1Q5DK"
        }, 
      "quantity":  1 
      "customTermEndDate": "2019-01-09T00:21:45.9263727",
     },  // original value = null 
    "isTrial": false,
    "billingType": "license",
    "billingCycle": "monthly",
    "termDuration": "P1M",
    "refundOptions": [{
        "type": "Full",
        "expiresAt": "2019-01-10T00:21:45.9263727+00:00"
    }],
    "isMicrosoftProduct": false,
    "partnerId": "",
    "contractType": "subscription",
    "publisherName": "publisher Name",
    "orderId": "ImxjLNL4_fOc-2KoyOxGTZcrlIquzls11",
    "attributes": {"objectType": "Subscription"},
}