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

Nota

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 (Provedor de Soluções na Nuvem). Para obter mais informações, consulte Visão geral de novas experiências comerciais.

A criação de alterações agendadas permite-lhe modificar a sua subscrição, automaticamente, quando ocorrer a próxima renovação. 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 cobrança 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 intermediária (imediata) antes da data de renovação, todas as alterações agendadas que foram agendadas anteriormente para ocorrer na renovação serão excluídas.

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.
Um ID de cliente (customer-tenant-id). Se não souber o ID do cliente, pode procurá-lo no Partner Center selecionando a área de trabalho Clientes e, em seguida, 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 é a mesma que a ID do cliente (customer-tenant-id).
Um ID de subscrição.
A renovação automática está ativada na subscrição.

Método do Partner Center

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

Selecione um cliente.
Selecione a subscrição para a qual pretende agendar alterações.
Habilite a renovação automática.
Selecione 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.

Nota

As renovações são processadas após o último dia de um prazo, começando às 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 subscrição por ID.
Obtenha elegibilidade de transição para o tipo de elegibilidade de transição agendada.
Crie um objeto ScheduledNextTermInstructions e defina-o como 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 subscrição por ID.
Obtenha 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.

Pedido REST

Sintaxe da solicitação

Método	URI do pedido
REMENDO	{baseURL}/v1/customers/{customer-tenant-id}/subscriptions/{subscription-id} HTTP/1.1

Parâmetro URI

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

Nome	Type	Obrigatório	Description
ID do cliente-locatário	GUID	Y	Um GUID correspondente ao cliente.
ID da subscrição	GUID	Y	Um GUID correspondente à assinatura.

Cabeçalhos do pedido

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

Corpo do pedido

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 elegibilidade Agendado, caso contrário, o padrão será imediato.
Use CatalogItemID para extrair availabilityID.

Nota

Se você estiver usando GET Availabilities para determinar a disponibilidade para as instruções agendadas NextTerm e se todos os termos estiverem no 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ório	Description
agendadoPróximoTermoInstruções	objeto	Y	Define as próximas instruções de termo 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 do REST

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

Códigos de sucesso e 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, consulte 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"},
}

Partilhar via

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

Pré-requisitos

Método do Partner Center

C#

Pedido REST

Sintaxe da solicitação

Parâmetro URI

Cabeçalhos do pedido

Corpo do pedido

Exemplo de solicitação

Resposta do REST

Códigos de sucesso e erro de resposta

Exemplo de resposta

Comentários

Recursos adicionais