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

Artigo
07/19/2024

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 de comércio, que só ocorrem na renovação. Esta API suporta novas subscrições de software e baseadas em licenças de comércio.

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.

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

Importante

Se você fizer uma alteração de médio prazo (imediata) antes da data de renovação, todas as alterações agendadas anteriormente agendadas para ocorrer na renovação serão excluídas.

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.
Uma ID do cliente (customer-tenant-id). Se você não souber a ID do cliente, poderá procurá-la no Partner Center selecionando o espaço de trabalho Clientes, 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. A ID da Microsoft é igual à 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:

Selecione um cliente.
Selecione a assinatura para a qual você deseja agendar alterações.
Habilite a renovação automática.
Escolha Gerenciar renovação.
Faça modificações na assinatura para ocorrer na renovação.
Selecione OK para fechar o painel lateral.
selecione Enviar para salvar as alterações.

Observação

As renovações são processadas após o último dia de um período, a partir das 12:00 UTC do dia seguinte. As renovações são processadas em uma fila e podem levar até 24 horas para serem processadas.

C#

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

Obtenha a assinatura por ID.
Obtenha a elegibilidade de transição para o tipo de elegibilidade de transição agendada.
Crie um objeto ScheduledNextTermInstructions e defina-o como a propriedade da assinatura.
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, onde a alteração agendada desejada é para um produto diferente:

Obtenha a assinatura por ID.
Obtenha a elegibilidade de transição para o tipo de elegibilidade de transição agendada.
Chame o método Patch() para atualizar a assinatura com as alterações agendadas.

Solicitação REST

Sintaxe da solicitação

Método	URI da solicitação
PATCH	{baseURL}/v1/customers/{customer-tenant-id}/subscriptions/{subscription-id} HTTP/1.1

Parâmetro do URI

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

Nome	Digitar	Obrigatória	Descrição
id de locatário do cliente	guid	Y	Um GUID correspondente ao cliente.
id da assinatura	guid	Y	Um GUID correspondente à assinatura.

Cabeçalhos da solicitação

Para obter mais informações, confira 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 ID de disponibilidade no final da venda com conversões (EndofSaleWithConversions) oferece:

GetTransitionEligibility para retornar CatalogItemID.

a. Certifique-se de definir o tipo de qualificação Agendado, caso contrário, o padrão será imediato.
Use CatalogItemID para extrair availabilityID.

Observação

Se você estiver usando GET Availabilities para determinar a disponibilidade para as instruções agendadasNextTerm e se todos os termos forem 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.

Campo	Type	Obrigatória	Descrição
agendadoPróximoTermInstruções	object	Y	Define as instruções do próximo período para a assinatura. A propriedade contém o `product` objeto e o `quantity` campo.

Exemplo de solicitação

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 Subscription no corpo da resposta.

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 outras informações de depuração. Use uma ferramenta de rastreamento de rede para ler esse código, tipo de erro e outros parâmetros. Para obter a lista completa, confira Códigos de Erro.

Exemplo de resposta

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

Compartilhar via

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

Pré-requisitos

Método do Partner Center

C#

Solicitação REST

Sintaxe da solicitação

Parâmetro do URI

Cabeçalhos da solicitação

Corpo da solicitação

Exemplo de solicitação

Resposta REST

Códigos de êxito e de erro de resposta

Exemplo de resposta

Comentários

Recursos adicionais