Fazer a transição de uma assinatura de novo comércio

Aplica-se a: Partner Center | Partner Center operado pela 21Vianet | Partner Center para Microsoft Cloud for US Government

Funções apropriadas

  • Agente de administração

Esses métodos dão suporte a assinaturas de origem de novo comércio e tradicional.

Observação

As novas experiências de comércio para serviços baseados em licença incluem muitos novos recursos e estão disponíveis para todos os CSPs (Provedores de Soluções na Nuvem). Para obter mais informações, consulte visão geral das novas experiências de comércio.

Usados para fazer a atualização da assinatura de novo comércio para uma assinatura de destino do cliente ou converter uma versão de avaliação do NCE em uma assinatura paga. Para fazer a transição de uma assinatura, duas solicitações de API precisam ser feitas. Primeiras transições GET qualificadas para obter as SKUs disponíveis para atualização. Em seguida, faça a transição via POST para executar a transição.

Obter elegibilidades de transição

Retorna uma lista de transições qualificadas para um determinado cliente, assinatura e tipo solicitado. Também retorna a elegibilidade para upgrade da assinatura de destino. As qualificações de transição podem incluir ofertas que estão no estado EndofSaleWithConversions.

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

  • Uma 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
  • Global Reader

Observação

Embora esta API esteja disponível para o modelo legado e para o NCE, o GDAP é necessário apenas para o modelo legado.

Solicitação REST

Sintaxe da solicitação

Método URI de solicitação
GET {baseURL}/v1/customers/{customer-tenant-id}/subscriptions/{subscription-id}/transitionEligibilities?eligibilityType={immediate, scheduled} HTTP/1.1

Parâmetro do URI

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

Nome Tipo Obrigatória Descrição
ID do locatário do cliente guid Y Um GUID correspondente ao locatário do cliente.
id da assinatura guid Y Um GUID correspondente à assinatura inicial.
eligibilityType cadeia de caracteres N Descreve quando a transição deve ser executada; pode ser imediato ou programado. O padrão é Immediate.

Cabeçalhos da solicitação

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

Corpo da solicitação

Nenhum

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 REST

Se bem-sucedido, esse método retornará uma lista das transições qualificadas para a assinatura fornecida 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 êxito 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 ver a lista completa, consulte Códigos de erro.

Erros de elegibilidade

Descrições e significado de erros.

Descrição do erro Significado
A assinatura não pode ser transicionada – a assinatura de origem não está ativa. Status original da assinatura inativo
A assinatura não pode ser transicionada – a assinatura de origem ainda não foi provisionada. O FulfillmentState da assinatura original não é bem-sucedido
O tipo de transição não é compatível – o mapeamento de assinatura do AzureAD é necessário. Erro LegacyCannotConvertSubscriptionId ao chamar o GetSubscriptionUpgradeConflicts
O tipo de transição não é compatível – existem assinaturas conflitantes para transferência de licença. Se algum 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 assinatura

Se uma assinatura de destino não estiver qualificada para ser atualizada, um dos motivos a seguir será retornado.

Listas vazias serão retornadas se a assinatura de origem for uma avaliação ou se o eligibilityType for especificado como Agendado. Você só pode fazer a transição para uma assinatura existente com uma transição imediata (também conhecida como "intermediária"), não uma alteração agendada.

Descrição do erro Código do erro
A assinatura não está ativa. SubscriptionNotActive = 1
A assinatura está dentro da janela de cancelamento. SubscriptionInCancellationWindow = 2
A duração do termo da assinatura é menor do que a duração do prazo da assinatura de origem. SubscriptionTermDurationShorterThanSourceTermDuration = 3
A data de término do prazo da assinatura é antes da data de término do prazo da assinatura de origem. A data de término do prazo da assinatura é antes da data de término do prazo 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 de transição

Alguns SKUs de três anos com equipes permitem que os parceiros na Europa se transfiram para SKUs sem equipes. Essas transições só podem ocorrer nas datas de aniversário, conforme definido no resultado de elegibilidade da transição e nas 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

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

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

  • Uma 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)

Observação

Embora esta API esteja disponível para o modelo legado e para o NCE, o GDAP é necessário apenas para o modelo legado.

Solicitação REST

Sintaxe da solicitação

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

Parâmetro do URI

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

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

Cabeçalhos da solicitação

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

Corpo da solicitação

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

Propriedade Tipo Obrigatória Descrição
fromCatalogItemId cadeia Não O item de catálogo do qual você está fazendo a transição.
fromSubscriptionId cadeia Não A ID da assinatura da qual você está migrando.
toCatalogItemId cadeia Sim O item de catálogo para o qual você está fazendo a transição.
toSubscriptionId cadeia Não A ID da assinatura para a qual você está fazendo a transição.
quantidade inteiro Sim O número de licenças a serem transferidas.
termDuration cadeia Não Especificar a duração do prazo da assinatura.
ciclo de faturamento cadeia Não Especificando o ciclo de cobrança da assinatura.
transitionType cadeia 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 REST

Se for bem-sucedida, este método retorna um recurso Transition com seu status inicial.

Códigos de êxito e de erro de resposta

Cada resposta vem com um código de status HTTP que indica êxito 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 ver 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