Transição de uma nova subscrição comercial

Artigo
09/25/2024

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

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 de novas experiências comerciais.

Usado para atualizar a nova assinatura comercial de um cliente para uma assinatura de destino ou converter uma avaliação 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 qualificadas para obter os SKUs disponíveis para atualização. 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 elegibilidade 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 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 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 legado e NCE, o GDAP só é necessário para legado.

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	Type	Obrigatório	Description
ID do cliente-locatário	GUID	Y	Um GUID correspondente ao locatário do cliente.
ID da subscrição	GUID	Y	Um GUID correspondente à assinatura inicial.
elegibilidadeTipo	string	N	Descreve quando a transição deve ser executada; pode ser imediata ou agendada. A predefinição é `Immediate`.

Cabeçalhos do pedido

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

Corpo do pedido

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, esse método retornará uma lista das transições qualificadas para uma determinada 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 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 - o mapeamento de assinatura do AzureAD é necessário.	Erro LegacyCannotConvertSubscriptionId ao chamar 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, um dos seguintes motivos será retornado.

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

Descrição do erro	Código de erro
A subscrição não está ativa.	SubscriptionNotActive = 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.	SubscriptionTermDurationShorterThanSourceTermDuration = 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"
  }
}

Pós-transição

Publica uma solicitação de transição para um determinado cliente e assinatura. Retorna a transição com 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 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 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 (somente transição)
Directory Writer (transição com transferência de licença)

Nota

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

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	Type	Obrigatório	Description
ID do cliente-locatário	GUID	Y	Um GUID correspondente ao locatário do cliente.
ID da subscrição	GUID	Y	Um GUID correspondente à assinatura inicial.

Cabeçalhos do pedido

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

Corpo do pedido

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

Propriedade	Type	Obrigatório	Description
deCatalogItemId	string	Não	O item de catálogo do qual você está fazendo a transição.
fromSubscriptionId	string	Não	O ID da subscrição a partir do qual está a transitar.
toCatalogItemId	string	Sim	O item de catálogo para o qual você está fazendo a transição.
toSubscriptionId	string	Não	O ID da subscrição para o qual está a fazer a transição.
quantidade	integer	Sim	O número de licenças a serem transferidas.
termoDuração	string	Não	Especificar a duração da subscrição.
faturamentoCiclo	string	Não	Especificando o ciclo de faturamento da assinatura.
tipo de transição	string	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 bem-sucedido, esse método retorna um recurso de transição com seu status inicial.

Códigos de sucesso e erro de resposta

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

Partilhar via

Transição de uma nova subscrição comercial

Obter elegibilidade de transição

Pré-requisitos

Funções GDAP

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

Erros de elegibilidade

Erros de elegibilidade da subscrição

Exemplo de resposta

Pós-transição

Pré-requisitos

Funções GDAP

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