Efetuar a transição de uma nova subscrição comercial

Aplica-se a: Centro de Parceiros | Centro de Parceiros operado pela 21Vianet | Centro de Parceiros para a Nuvem Microsoft para o Governo dos EUA

Funções apropriadas

  • Agente administrativo

Esses métodos suportam assinaturas de fontes de comércio tradicionais e novas.

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 das novas experiências de comércio.

Usado para atualizar a assinatura comercial recém-adquirida por um cliente para uma assinatura de destino ou converter uma avaliação do NCE em uma assinatura paga. Para fazer a transição de uma assinatura, duas solicitações de API precisam ser feitas. Primeiro GET transições elegíveis para obter os SKUs disponíveis para upgrade. Em seguida, transição POST para executar a transição.

Obter elegibilidade de transição

Devolve uma lista de transições elegíveis para um determinado cliente, subscrição e tipo solicitado. Também retorna a elegibilidade de atualização da assinatura de destino. As elegibilidades de transição podem incluir ofertas que estão no estado EndofSaleWithConversions.

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 a identificação do cliente, pode procurá-la no Partner Center, selecionando a área de trabalho Clientes e, em seguida, o cliente na lista de clientes, e depois em Conta. Na página da Conta do Cliente, procure a Microsoft ID na secção de Informações da Conta do Cliente. O ID Microsoft é o mesmo que o ID cliente (customer-tenant-id).

  • Um ID de assinatura para a assinatura inicial.

Funções GDAP

Você precisará de pelo menos uma das seguintes funções GDAP:

  • Leitor de Diretórios
  • Leitor Global

Nota

Embora essa API esteja disponível para sistemas antigos e NCE, o GDAP só é necessário para sistemas antigos.

Pedido REST

Sintaxe da solicitação

Método URI do pedido
GET {baseURL}/v1/customers/{customer-tenant-id}/subscriptions/{subscription-id}/transitionEligibilities?eligibilityType={imediato, agendado} HTTP/1.1

Parâmetro URI

Use os seguintes parâmetros de consulta para retornar transições qualificadas.

Nome Tipo Obrigatório Descrição
ID do cliente-arrendatário GUID Y Um GUID (Identificador Global Único) correspondente ao inquilino do cliente.
ID da subscrição GUID Y Um identificador GUID correspondente à assinatura inicial.
tipoDeElegibilidade string N Descreve quando a transição deve ser executada; pode ser imediata ou agendada. A predefinição é Immediate.

Cabeçalhos de requisição

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

Corpo de solicitação

Nenhuma

Exemplo de solicitação

GET https://api.partnercenter.microsoft.com/v1/customers/{customer-tenant-id}/subscriptions/{subscription-id}/transitionEligibilities?eligibilityType=immediate 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

Resposta do REST

Se for bem-sucedido, este método retornará uma lista das transições elegíveis para a assinatura dada 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 mais 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.

Erros de elegibilidade

Descrições de erros e significado.

Descrição do erro Significado
A assinatura não pode ser transferida - a assinatura de origem não está ativa. Substatus original não ativo
A assinatura não pode ser transferida - a assinatura de origem ainda não foi provisionada. O sub FulfillmentState original não foi bem-sucedido
O tipo de transição não é compatível - é necessário o mapeamento de subscrição do AzureAD. Erro de LegacyCannotConvertSubscriptionId ao utilizar GetSubscriptionUpgradeConflicts
O tipo de transição não é compatível - existem subscrições conflitantes para transferência de licenças. Se qualquer serviço do Microsoft Entra tiver IDs de assinatura de uma assinatura diferente, adicione-o à lista de conflitos (inclui compras feitas com fluxo de compra herdado ou moderno)

Erros de elegibilidade da subscrição

Se uma assinatura de destino não estiver qualificada para ser atualizada, uma das seguintes razões será apresentada.

As listas vazias serão retornadas se a assinatura de origem for uma avaliação ou se o tipo de elegibilidade for especificado como Agendado. Você só pode fazer a transição para uma assinatura existente com uma transição imediata (também conhecida como "a meio do período"), e não com uma alteração programada.

Descrição do erro Código de erro
A subscrição não está ativa. SubscriçãoNãoAtiva = 1
A subscrição está dentro da janela de cancelamento. SubscriptionInCancellationWindow = 2
A duração do prazo da subscrição é mais curta do que a duração da subscrição de origem. SubscriçãoPrazoDuraçãoMenorQueDuraçãoPrazoOrigem = 3
A data de término do prazo da assinatura é anterior à data de término do termo da assinatura de origem. A data de término do prazo da assinatura é anterior à data de término do termo da assinatura de origem. = 4

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

{
  "totalCount": 2,
  "items": [
    {
      "operationId": "1caf8ec7-62cc-4ab5-b35d-572d2a62974c",
      "catalogItemId": "CFQ7TTC0KZCR:0001:CFQ7TTC0K71H",
      "title": "Microsoft 365 E5 Test Sku Title",
      "description": "Microsoft 365 E5 Test Sku Description",
      "quantity": 1,
      "subscriptionEligibilities": [
        {
          "isEligible": false,
          "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
          "subscriptionFriendlyName": "Microsoft 365 Business Premium",
          "subscriptionTermDuration": "P1M",
          "subscriptionBillingCycle": "monthly",
          "errors": [
            {
              "code": 3,
              "description": "The subscription's term duration is shorter than the source subscription's term duration."
            }
          ]
        },
        {
          "isEligible": true,
          "subscriptionId": "bbbb1b1b-cc2c-dd3d-ee4e-ffffff5f5f5f",
          "subscriptionFriendlyName": "Microsoft 365 Business Premium",
          "subscriptionTermDuration": "P1Y",
          "subscriptionBillingCycle": "monthly",
          "errors": []
        }
      ],
      "eligibilities": [
        {
          "isEligible": true,
          "transitionType": "transition_only",
          "errors": []
        },
        {
          "isEligible": false,
          "transitionType": "transition_with_license_transfer",
          "errors": [
            {
              "code": 3,
              "description": "Subscription cannot be transitioned because there are conflicting services."
            }
          ]
        }
      ],
      "attributes": {
        "objectType": "TransitionEligibility"
      }
    },
    {
      "operationId": "1caf8ec7-62cc-4ab5-b35d-572d2a62974c",
      "catalogItemId": "CFQ7TTC0L4M3:0001:CFQ7TTC0K78T",
      "title": "Business Premium Test Sku Title",
      "description": "Business Premium Test Sku Description",
      "quantity": 1,
      "eligibilities": [
        {
          "isEligible": false,
          "transitionType": "transition_with_license_transfer",
          "errors": [
            {
              "code": 3,
              "description": "Subscription cannot be transitioned because there are conflicting services."
            }
          ]
        }
      ],
      "attributes": {
        "objectType": "TransitionEligibility"
      }
    }
  ],
  "attributes": {
    "objectType": "Collection"
  }
}

Exemplo de resposta para datas permitidas na transição

Alguns SKUs com uma duração de três anos com Teams permitem aos parceiros na Europa transitar para SKUs sem Teams. Estas transições só podem ocorrer nas datas de aniversário, conforme definido no resultado de elegibilidade da transição e pelas datas permitidas.

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

{ 
    "totalCount": 1, 
    "items": [ 
        { 
            "catalogItemId": "CFQ7TTBZZR6H:001L:CFQ7TTC0K994", 
            "title": "Microsoft 365 E7 - 3 year", 
            "description": "Microsoft 365 E5, Microsoft 365 Copilot, Agent 365, and Entra Suite. This per-user licensed suite of products offers customers the latest, most advanced, productivity, security, and AI for user and user's agents.", 
            "quantity": 100, 
            "subscriptionEligibilities": [], 
            "transitionAllowedDates": ["2026-08-01T00:00:00Z", "2027-08-01T00:00:00Z"],  // This field will show up only if applicable 
            "eligibilities": [ 
                { 
                    "isEligible": true, 
                    "transitionType": "transition_only", 
                    "errors": [] 
                }, 
                { 
                    "isEligible": true, 
                    "transitionType": "transition_with_license_transfer", 
                    "errors": [] 
                } 
            ], 
            "attributes": { 
                "objectType": "TransitionEligibility" 
            } 
        }] 
}

Pós-transição

Publica uma solicitação de transição para um determinado cliente e assinatura. Retorna a transição com o seu status inicial.

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 a identificação do cliente, pode procurá-la no Partner Center, selecionando a área de trabalho Clientes e, em seguida, o cliente na lista de clientes, e depois em Conta. Na página da Conta do Cliente, procure a Microsoft ID na secção de Informações da Conta do Cliente. O ID Microsoft é o mesmo que o ID cliente (customer-tenant-id).

  • Um ID de assinatura para a assinatura inicial.

Funções GDAP

Você precisará de pelo menos uma das seguintes funções GDAP:

  • Leitor de diretório ou leitor global (apenas para transição)
  • Directory Writer (transição com transferência de licença)

Nota

Embora essa API esteja disponível para sistemas antigos e NCE, o GDAP só é necessário para sistemas antigos.

Pedido REST

Sintaxe da solicitação

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

Parâmetro URI

Use os seguintes parâmetros de consulta para executar uma transição.

Nome Tipo Obrigatório Descrição
ID do cliente-arrendatário GUID Y Um GUID (Identificador Global Único) correspondente ao inquilino do cliente.
ID da subscrição GUID Y Um identificador GUID correspondente à assinatura inicial.

Cabeçalhos de requisição

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

Corpo de solicitação

Esta tabela descreve as propriedades de Transição no corpo da solicitação.

Propriedade Tipo Obrigatório Descrição
deIdDoItemDoCatálogo cadeia (de caracteres) Não O item de catálogo do qual você está fazendo a transição.
fromSubscriptionId cadeia (de caracteres) Não O ID da subscrição a partir do qual está a transitar.
paraIdentificadorDeItemDeCatálogo cadeia (de caracteres) Sim O item de catálogo para o qual você está fazendo a transição.
toSubscriptionId cadeia (de caracteres) Não O ID da subscrição para o qual está a fazer a transição.
quantidade número inteiro Sim O número de licenças a serem transferidas.
duração do termo cadeia (de caracteres) Não Especificar a duração da subscrição.
ciclo de faturação cadeia (de caracteres) Não Especificando o ciclo de faturamento da assinatura.
tipo de transição cadeia (de caracteres) Sim O tipo de transição. Valores possíveis - transition_only, transition_with_license_transfer.

Exemplo de solicitação

POST https://api.partnercenter.microsoft.com/v1/customers/{customerId}/subscriptions/{subscriptionId}/transitions 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

{
    "fromCatalogItemId": "CFQ7TTC0LF8Q:0001:CFQ7TTC0K39X",
    "fromSubscriptionId": "e487e8dc-421e-4275-cb42-3c1c8daccf70",
    "toCatalogItemId": "CFQ7TTC0LF8R:0001:CFQ7TTC0KCSV",
    "toSubscriptionId": "0af52192-4a2a-4364-d25b-c8ecab3a5697",
    "quantity": 2,
    "termDuration": "P1M",
    "billingCycle": "Monthly",
    "transitionType": "transition_only"
}

Resposta do REST

Se for bem-sucedido, este método devolve um recurso de transição com o seu estado inicial.

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 outros parâmetros. Para obter a lista completa, consulte Códigos de erro.

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

{
    "fromCatalogItemId": "CFQ7TTC0LF8Q:0001:CFQ7TTC0K39X",
    "fromSubscriptionId": "e487e8dc-421e-4275-cb42-3c1c8daccf70",
    "toCatalogItemId": "CFQ7TTC0LF8R:0001:CFQ7TTC0KCSV",
    "toSubscriptionId": "0af52192-4a2a-4364-d25b-c8ecab3a5697",
    "quantity": 2,
    "termDuration": "P1M",
    "billingCycle": "Monthly",
    "transitionType": "transition_only"
    "Events": [
        {
            "name": "Conversion",
            "status": "Started ",
            "timestamp": "2021-01-08T18:01:14.7488618Z",
            "attributes":
            {
                "objectType": "TransitionEvent"
            }
        }
    ],
    "attributes":
    {
        "objectType": "Transition" 
    }
}
  • Last updated on