APIs de assinatura de atendimento de SaaS v2 no marketplace comercial da Microsoft

Artigo
11/08/2024

Este artigo descreve a versão 2 das APIs de assinatura de cumprimento de SaaS.

Observação

Para poder chamar APIs de assinatura de atendimento de SaaS, você deve criar um token de autorização do editor usando a ID de recurso correta. Saiba como obter o token de autorização do editor

Resolver uma assinatura comprada

O ponto de extremidade de resolução permite que o distribuidor troque o token de identificação de compra do marketplace comercial (chamado de token em Adquirido, mas ainda não ativado) por uma ID de assinatura de SaaS adquirida persistente e seus detalhes.

Quando um cliente é redirecionado para a URL da página de aterrissagem do parceiro, o token de identificação do cliente é passado como o parâmetro de token nessa chamada de URL. O parceiro deve usar o token e fazer uma solicitação para resolvê-lo. A resposta da API de resolução contém a ID de assinatura de SaaS e outros detalhes para identificar exclusivamente a compra. O token fornecido com a chamada de URL da página de destino é válido por 24 horas. Se o token recebido tiver expirado, recomendamos que você forneça as seguintes diretrizes ao usuário final:

"Não foi possível identificar a compra. Reabra essa assinatura de SaaS no portal do Azure ou no Centro de Administração do Microsoft 365 e selecione "Configurar conta" ou "Gerenciar conta" novamente."

Chamar a API Resolve retorna detalhes e status de assinatura para assinaturas de SaaS em todos os status com suporte.

Postar `https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>`

Parâmetros de consulta:

Parâmetro	Valor
`ApiVersion`	Use 2018-08-31.

Cabeçalhos de solicitação:

Parâmetro	Valor
`content-type`	`application/json`
`x-ms-requestid`	Um valor de cadeia de caracteres exclusivo para acompanhamento da solicitação do cliente, preferencialmente um GUID. Se esse valor não for fornecido, um será gerado e fornecido nos cabeçalhos de resposta.
`x-ms-correlationid`	Um valor de cadeia de caracteres exclusiva para a operação no cliente. Esse parâmetro correlaciona todos os eventos da operação do cliente com eventos no lado do servidor. Se esse valor não for fornecido, um será gerado e fornecido nos cabeçalhos de resposta
`authorization`	Um token de acesso exclusivo que identifica o distribuidor que está fazendo a chamada à API. O formato é `"Bearer <access_token>"` quando o valor do token é recuperado pelo editor, conforme explicado em Obter um token com base no aplicativo Microsoft Entra.
`x-ms-marketplace-token`	O parâmetro de token de identificação de compra a ser resolvido. O token é passado na chamada da URL da página de aterrissagem quando o cliente é redirecionado para o site do parceiro de SaaS (por exemplo: `https://contoso.com/signup?token=<token><authorization_token>`). O valor do token que está sendo codificado faz parte do URL da página de destino, portanto, ele precisa ser decodificado antes de ser usado como um parâmetro nesta chamada de API. Aqui está um exemplo de uma cadeia de caracteres codificada na URL: `contoso.com/signup?token=ab%2Bcd%2Fef`, em que token é `ab%2Bcd%2Fef`. O mesmo token decodificado é: `Ab+cd/ef`

Códigos de resposta:

Código: 200 retorna identificadores de assinatura de SaaS exclusivos com base no x-ms-marketplace-token fornecido.

Exemplo de corpo da resposta:

{
  "id": "<guid>", // purchased SaaS subscription ID
  "subscriptionName": "Contoso Cloud Solution", // SaaS subscription name
  "offerId": "offer1", // purchased offer ID
  "planId": "silver", // purchased offer's plan ID
  "quantity": 20, // number of purchased seats, might be empty if the plan is not per seat
  "subscription": { // full SaaS subscription details, see Get Subscription APIs response body for full description
    "id": "<guid>",
    "publisherId": "contoso",
    "offerId": "offer1",
    "name": "Contoso Cloud Solution",
    "saasSubscriptionStatus": " PendingFulfillmentStart ",
    "beneficiary": {
      "emailId": "test@test.com",
      "objectId": "<guid>",
      "tenantId": "<guid>",
      "puid": "<ID of the user>"
    },
    "purchaser": {
      "emailId": "test@test.com",
      "objectId": "<guid>",
      "tenantId": "<guid>",
      "puid": "<ID of the user>"
    },
    "planId": "silver",
    "term": {
      "termUnit": "P1M",
      "startDate": "2022-03-07T00:00:00Z", //This field is only available after the saas subscription is active.
      "endDate": "2022-04-06T00:00:00Z" //This field is only available after the saas subscription is active.
    },
      "autoRenew": true/false,
    "isTest": true/false,
    "isFreeTrial": false,
    "allowedCustomerOperations": <CSP purchases>["Read"] <All Others> ["Delete", "Update", "Read"],
      "sandboxType": "None",
      "lastModified": "0001-01-01T00:00:00", //[Deprecated] Do not use.
      "quantity": 5,
    "sessionMode": "None"
  }
}

Código: 400 Solicitação incorreta. x-ms-marketplace-token está ausente, malformado, inválido ou expirou.

Código: 403 Proibido. O token de autorização é inválido, expirou ou não foi fornecido. A solicitação está tentando acessar uma assinatura SaaS para uma oferta que foi publicada com uma ID de aplicativo do Microsoft Entra diferente daquela usada para criar o token de autorização.

Esse erro geralmente é um sintoma de erros na realização do registro de SaaS.

Código: 500 Erro interno do servidor. Repita a chamada à API. Se o problema persistir, contate o Suporte da Microsoft.

Ativar uma assinatura

Após a configuração da conta de SaaS para o usuário final, o distribuidor deve chamar a API ativar assinatura no lado da Microsoft. O cliente não é cobrado, a menos que essa chamada à API seja bem-sucedida.

Postar `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>`

Parâmetros de consulta:

Parâmetro	Valor
`ApiVersion`	Use 2018-08-31.
`subscriptionId`	O identificador exclusivo da assinatura SaaS adquirida. Essa ID é obtida depois de resolver o token de autorização do marketplace comercial usando a API de resolução.

Cabeçalhos de solicitação:

Parâmetro	Valor
`content-type`	`application/json`
`x-ms-requestid`	Um valor de cadeia de caracteres exclusivo para acompanhamento da solicitação do cliente, preferencialmente um GUID. Se esse valor não for fornecido, um será gerado e fornecido nos cabeçalhos de resposta.
`x-ms-correlationid`	Um valor de cadeia de caracteres exclusiva para a operação no cliente. Essa cadeia de caracteres correlaciona todos os eventos da operação do cliente com eventos no lado do servidor. Se esse valor não for fornecido, um será gerado e fornecido nos cabeçalhos de resposta.
`authorization`	Um token de acesso exclusivo que identifica o distribuidor que está fazendo a chamada à API. O formato é `"Bearer <access_token>"` quando o valor do token é recuperado pelo editor, conforme explicado em Obter um token com base no aplicativo Microsoft Entra.

Códigos de resposta:

Código: 200 Solicitação para atualizar a assinatura e marcar como "Inscrito" é recebida. Os ISVs (Fornecedores Independentes de Software) podem verificar o status da assinatura após alguns minutos (leia a operação Get para verificar o status da assinatura). Isso fornece a resposta definitiva se a assinatura foi atualizada com êxito. A falha na assinatura envia automaticamente um webhook "Cancelar assinatura".

Não há corpo de resposta para esta chamada.

Código: 400 Solicitação incorreta: falha na validação.

A assinatura SaaS está no estado Suspenso .

Esse erro geralmente é um sintoma de erros na realização do registro de SaaS.

Código: 404 não encontrado. A assinatura de SaaS está no estado assinatura cancelada.

Código: 500 Erro interno do servidor. Repita a chamada à API. Se o problema persistir, contate o Suporte da Microsoft.

Obter a lista de todas as assinaturas

Essa API recupera a lista de todas as assinaturas de SaaS adquiridas de todas as ofertas que o distribuidor publica no marketplace comercial. As assinaturas de SaaS em todos os status possíveis são retornadas. As assinaturas de SaaS não assinadas também são retornadas porque essas informações não são excluídas no lado da Microsoft.

A API retorna resultados paginados de 100 por página.

Obter `https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>`

Parâmetros de consulta:

Parâmetro	Valor
`ApiVersion`	Use 2018-08-31.
`continuationToken`	Parâmetro opcional. Para recuperar a primeira página de resultados, deixe em branco. Use o valor retornado no parâmetro `@nextLink` para recuperar a página seguinte.

Cabeçalhos de solicitação:

Parâmetro	Valor
`content-type`	`application/json`
`x-ms-requestid`	Um valor de cadeia de caracteres exclusivo para acompanhamento da solicitação do cliente, preferencialmente um GUID. Se esse valor não for fornecido, um será gerado e fornecido nos cabeçalhos de resposta.
`x-ms-correlationid`	Um valor de cadeia de caracteres exclusiva para a operação no cliente. Esse parâmetro correlaciona todos os eventos da operação do cliente com eventos no lado do servidor. Se esse valor não for fornecido, um será gerado e fornecido nos cabeçalhos de resposta.
`authorization`	Um token de acesso exclusivo que identifica o distribuidor que está fazendo a chamada à API. O formato é `"Bearer <access_token>"` quando o valor do token é recuperado pelo editor, conforme explicado em Obter um token com base no aplicativo Microsoft Entra.

Códigos de resposta:

Código: 200 retorna a lista de todas as assinaturas de todas as ofertas feitas por esse distribuidor, com base no token de autorização do distribuidor.

Exemplo de corpo da resposta:

{
  "subscriptions": [
    {
      "id": "<guid>", // purchased SaaS subscription ID
      "name": "Contoso Cloud Solution", // SaaS subscription name
      "publisherId": "contoso", // publisher ID
      "offerId": "offer1", // purchased offer ID
      "planId": "silver", // purchased plan ID
      "quantity": 10, // purchased amount of seats, is empty if plan is not per seat
      "beneficiary": { // email address, user ID and tenant ID for which SaaS subscription was purchased.
        "emailId": " test@contoso.com",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "purchaser": { // email address, user ID and tenant ID that purchased the SaaS subscription. These could be different from beneficiary information for reseller (CSP) purchase
        "emailId": " test@contoso.com",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "term": { // The period for which the subscription was purchased.
        "startDate": "2022-03-04T00:00:00Z", //format: YYYY-MM-DD. This is the date when the subscription was activated by the ISV and the billing started. This field is only available after the saas subscription is active.
        "endDate": "2022-04-03T00:00:00Z", // This is the last day the subscription is valid. Unless stated otherwise, the automatic renew happens the next day. This field is only available after the saas subscription is active.
        "termUnit": "P1M" // where P1M is monthly and P1Y is yearly. Also reflected in the startDate and endDate values
      },
      "autoRenew": true,
      "allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
      "sessionMode": "None", // not relevant
      "isFreeTrial": true, // true - the customer subscription is currently in free trial, false - the customer subscription is not currently in free trial. (Optional field -– if not returned, the value is false.)
      "isTest": false, // not relevant
      "sandboxType": "None", // not relevant
      "saasSubscriptionStatus": "Subscribed" // Indicates the status of the operation. Can be one of the following: PendingFulfillmentStart, Subscribed, Suspended or Unsubscribed.
    },
    // next SaaS subscription details, might be a different offer
    {
      "id": "<guid1>",
      "name": "Contoso Cloud Solution1",
      "publisherId": "contoso",
      "offerId": "offer2",
      "planId": "gold",
      "quantity": "",
      "beneficiary": {
        "emailId": " test@contoso.com",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "purchaser": {
        "emailId": "purchase@csp.com ",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "term": {
        "startDate": "2019-05-31", /This field is only available after the saas subscription is active.
        "endDate": "2020-04-30",  //This field is only available after the saas subscription is active.
        "termUnit": "P1Y"
      },
      "autoRenew": false,
      "allowedCustomerOperations": ["Read"],
      "sessionMode": "None",
      "isFreeTrial": false,
      "isTest": false,
      "sandboxType": "None",
      "saasSubscriptionStatus": "Suspended"
    }
  ],
  "@nextLink": "https:// https://marketplaceapi.microsoft.com/api/saas/subscriptions/?continuationToken=%5b%7b%22token%22%3a%22%2bRID%3a%7eYeUDAIahsn22AAAAAAAAAA%3d%3d%23RT%3a1%23TRC%3a2%23ISV%3a1%23FPC%3aAgEAAAAQALEAwP8zQP9%2fFwD%2b%2f2FC%2fwc%3d%22%2c%22range%22%3a%7b%22min%22%3a%22%22%2c%22max%22%3a%2205C1C9CD673398%22%7d%7d%5d&api-version=2018-08-31" // url that contains continuation token to retrieve next page of the SaaS subscriptions list, if empty or absent, this is the last page. ISV can use this url as is to retrieve the next page or extract the value of continuation token from this url.
}

Se não forem encontradas assinaturas de SaaS adquiridas desse distribuidor, um corpo de resposta vazio será retornado.

Código: 403 Proibido. O token de autorização não está disponível, é inválido ou expirou.

Esse erro geralmente é um sintoma de erros na realização do registro de SaaS.

Código: 500 Erro interno do servidor. Repita a chamada à API. Se o problema persistir, contate o Suporte da Microsoft.

Obter assinatura

Essa API recupera uma assinatura de SaaS adquirida específica de uma oferta de SaaS que o distribuidor publica no marketplace comercial. Use essa chamada para obter todas as informações disponíveis de uma assinatura de SaaS pela ID em vez de chamar a API que é usada para obter uma lista de todas as assinaturas.

Obter `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Parâmetros de consulta:

Parâmetro	Valor
`ApiVersion`	Use 2018-08-31.
`subscriptionId`	O identificador exclusivo da assinatura SaaS adquirida. Essa ID é obtida depois de resolver o token de autorização do marketplace comercial usando a API de resolução.

Cabeçalhos de solicitação:

Parâmetro	Valor
`content-type`	`application/json`
`x-ms-requestid`	Um valor de cadeia de caracteres exclusivo para acompanhamento da solicitação do cliente, preferencialmente um GUID. Se esse valor não for fornecido, um será gerado e fornecido nos cabeçalhos de resposta.
`x-ms-correlationid`	Um valor de cadeia de caracteres exclusiva para a operação no cliente. Esse parâmetro correlaciona todos os eventos da operação do cliente com eventos no lado do servidor. Se esse valor não for fornecido, um será gerado e fornecido nos cabeçalhos de resposta.
`authorization`	Um token de acesso exclusivo que identifica o distribuidor que está fazendo a chamada à API. O formato é `"Bearer <access_token>"` quando o valor do token é recuperado pelo editor, conforme explicado em Obter um token com base no aplicativo Microsoft Entra.

Códigos de resposta:

Código: 200 retorna os detalhes de uma assinatura de SaaS com base no subscriptionId fornecido.

Exemplo de corpo da resposta:

{
  "id": "<guid>", // purchased SaaS subscription ID
  "name": "Contoso Cloud Solution", // SaaS subscription name
  "publisherId": "contoso", // publisher ID
  "offerId": "offer1", // purchased offer ID
  "planId": "silver", // purchased plan ID
  "quantity": 10, // purchased amount of seats is empty if plan is not per seat
  "beneficiary": { // email address, user ID and tenant ID for which SaaS subscription is purchased.
    "emailId": "test@contoso.com",
    "objectId": "<guid>",
    "tenantId": "<guid>",
    "puid": "<ID of the user>"
  },
  "purchaser": { // email address ,user ID and tenant ID that purchased the SaaS subscription. These could be different from beneficiary information for reseller (CSP) scenario
    "emailId": "test@test.com",
    "objectId": "<guid>",
    "tenantId": "<guid>",
    "puid": "<ID of the user>"
  },
  "allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
  "sessionMode": "None", // not relevant
  "isFreeTrial": false, // true - the customer subscription is currently in free trial, false - the customer subscription is not currently in free trial. Optional field – if not returned the value is false.
  "autoRenew": true,
  "isTest": false, // not relevant
  "sandboxType": "None", // not relevant
  "created": "2022-03-01T22:59:45.5468572Z",
     "lastModified": "0001-01-01T00:00:00", //[Deprecated] Do not use.
  "saasSubscriptionStatus": " Subscribed ", // Indicates the status of the operation: PendingFulfillmentStart, Subscribed, Suspended or Unsubscribed.
  "term": { // the period for which the subscription was purchased
    "startDate": "2022-03-04T00:00:00Z", //format: YYYY-MM-DD. This is the date when the subscription was activated by the ISV and the billing started. This field is only available after the saas subscription is active.
    "endDate": "2022-04-03T00:00:00Z", // This is the last day the subscription is valid. Unless stated otherwise, the automatic renew happens the next day. This field is only available after the saas subscription is active.
    "termUnit": "P1M" //where P1M is monthly and P1Y is yearly. Also reflected in the startDate and endDate values.
  }
}

Código: 403 Proibido. O token de autorização é inválido, expirou ou não foi fornecido. A solicitação está tentando acessar uma assinatura SaaS para uma oferta publicada com uma ID de aplicativo do Microsoft Entra diferente daquela usada para criar o token de autorização.

Esse erro geralmente é um sintoma de erros na realização do registro de SaaS.

Código: 404 não encontrado. Não foi localizada uma assinatura de SaaS com subscriptionId especificada.

Código: 500 Erro interno do servidor. Repita a chamada à API. Se o problema persistir, contate o Suporte da Microsoft.

Listar os planos disponíveis

Essa API recupera todos os planos de uma oferta de SaaS identificada pela subscriptionId de uma compra específica da oferta. Use essa chamada para obter uma lista de todos os planos públicos e privados que o beneficiário de uma assinatura de SaaS pode atualizar para a assinatura. Os planos devolvidos estão disponíveis na mesma geografia que o plano já adquirido.

Essa chamada retorna uma lista de planos disponíveis para o cliente, além daquele já adquirido. A lista pode ser apresentada a um usuário final no site do distribuidor. O usuário final pode alterar o plano de assinatura para qualquer um dos planos na lista retornada. Alterar o plano para um plano que não está na lista não funciona.

Essa API também recupera a ID de oferta privada ativa associada (se você chamar a API com o filtro planId). Chamar a API com o filtro planId mostra os GUIDs de ID de oferta privada ativos no corpo da resposta no nó sourceOffers. O planId passado no parâmetro de filtro deve corresponder ao planId que o cliente comprou.

Obter `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>`

Parâmetros de consulta:

Parâmetro	Valor
`ApiVersion`	Use 2018-08-31.
`subscriptionId`	O identificador exclusivo da assinatura SaaS adquirida. Essa ID é obtida depois de resolver o token de autorização do marketplace comercial usando a API de resolução.
`planId (Optional)`	ID do plano de um plano específico que você deseja buscar. Isso é opcional e, se ignorado, retorna todos os planos.

Cabeçalhos de solicitação:

Parâmetro	Valor
`content-type`	`application/json`
`x-ms-requestid`	Um valor de cadeia de caracteres exclusivo para acompanhamento da solicitação do cliente, preferencialmente um GUID. Se esse valor não for fornecido, um será gerado e fornecido nos cabeçalhos de resposta.
`x-ms-correlationid`	Um valor de cadeia de caracteres exclusiva para a operação no cliente. Esse parâmetro correlaciona todos os eventos da operação do cliente com eventos no lado do servidor. Se esse valor não for fornecido, um será gerado e fornecido nos cabeçalhos de resposta.
`authorization`	Um token de acesso exclusivo que identifica o distribuidor que está fazendo a chamada à API. O formato é `"Bearer <access_token>"` quando o valor do token é recuperado pelo editor, conforme explicado em Obter um token com base no aplicativo Microsoft Entra.

Códigos de resposta:

Código: 200 retorna a lista de todos os planos de uma assinatura de SaaS disponíveis, incluindo aquele já adquirido.

Passar planId inválido (opcional) retorna uma lista vazia de planos.

Exemplo de corpo da resposta:

{
  "plans": [
    {
      "planId": "Platinum001",
      "displayName": "plan display name",
      "isPrivate": true, //returns true for private plans and customized plans created within a private offer.
      "description": "plan description",
      "minQuantity": 5,
      "maxQuantity": 100,
      "hasFreeTrials": false,
      "isPricePerSeat": true,
      "isStopSell": false,
      "market": "US",
      "planComponents": {
        "recurrentBillingTerms": [
          {
            "currency": "USD",
            "price": 1,
            "termUnit": "P1M",
            "termDescription": "term description",
            "meteredQuantityIncluded": [
              {
                "dimensionId": "Dimension001",
                "units": "Unit001"
              }
            ]
          }
        ],
        "meteringDimensions": [
          {
            "id": "MeteringDimension001",
            "currency": "USD",
            "pricePerUnit": 1,
            "unitOfMeasure": "unitOfMeasure001",
            "displayName": "unit of measure display name"
          }
        ]
      },
      "sourceOffers": [ //sourceOffers is returned when planId is passed as filter parameter (note that this is the plan that customer has purchased).
        {
          "externalId": "<guid>" //private offer id, returned when purchase is made through private offer.
        }
      ]
    }
  ]
}

Código: 404 Não Encontrado. subscriptionId não foi encontrado.

Código: 403 Proibido. O token de autorização é inválido, expirou ou não foi fornecido. A solicitação pode estar tentando acessar uma assinatura SaaS para uma oferta cuja assinatura foi cancelada ou publicada com uma ID de aplicativo do Microsoft Entra diferente daquela usada para criar o token de autorização.

Esse erro geralmente é um sintoma de erros na realização do registro de SaaS.

Código: 500 Erro interno do servidor. Repita a chamada à API. Se o problema persistir, contate o Suporte da Microsoft.

Alterar o plano na assinatura

Use essa API para atualizar o plano adquirido de uma assinatura de SaaS para um novo plano (público ou privado). O distribuidor deve chamar essa API quando há alteração, no lado dele, de um plano de uma assinatura de SaaS adquirida no marketplace comercial.

É possível chamar a API apenas para assinaturas ativas. Qualquer plano pode ser alterado para qualquer outro plano existente (público ou privado), mas não para ele mesmo. Para planos privados, o locatário do cliente deve ser definido como parte do público-alvo do plano no Partner Center.

Aplicar patch `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Parâmetros de consulta:

Parâmetro	Valor
`ApiVersion`	Use 2018-08-31.
`subscriptionId`	O identificador exclusivo da assinatura SaaS adquirida. Essa ID é obtida depois de resolver o token de autorização do marketplace comercial usando a API de resolução.

Cabeçalhos de solicitação:

Parâmetro	Valor
`content-type`	`application/json`
`x-ms-requestid`	Um valor de cadeia de caracteres exclusivo para acompanhamento da solicitação do cliente, preferencialmente um GUID. Se esse valor não for fornecido, um será gerado e fornecido nos cabeçalhos de resposta.
`x-ms-correlationid`	Um valor de cadeia de caracteres exclusiva para a operação no cliente. Esse parâmetro correlaciona todos os eventos da operação do cliente com eventos no lado do servidor. Se esse valor não for fornecido, um será gerado e fornecido nos cabeçalhos de resposta.
`authorization`	Um token de acesso exclusivo que identifica o distribuidor que está fazendo a chamada à API. O formato é `"Bearer <access_token>"` quando o valor do token é recuperado pelo editor, conforme explicado em Obter um token com base no aplicativo Microsoft Entra.

Solicitar exemplo de conteúdo:

{
  "planId": "gold" // the ID of the new plan to be purchased
}

Códigos de resposta:

Código: 202 a solicitação para alterar o plano foi aceita e manipulada de maneira assíncrona. O parceiro deve sondar a URL da Localização da operação para determinar se a solicitação de alteração do plano teve êxito ou falhou. A sondagem deve ser feita em intervalos de alguns segundos até determinar o status final da operação: falha, êxito ou conflito. O status final da operação deve ser retornado rapidamente, mas pode levar vários minutos em alguns casos.

O parceiro também recebe uma notificação de webhook quando a ação está pronta para ser concluída com êxito no lado do marketplace comercial. Somente então o distribuidor faz a alteração do plano no lado dele.

Cabeçalhos de resposta:

Parâmetro	Valor
`Operation-Location`	URL para obter o status da operação. Por exemplo, `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`

Código: 400 Solicitação incorreta: falhas na validação.

O plano solicitado não pode ser encontrado ou não está disponível para o usuário.
O plano solicitado é o mesmo que o plano subscrito.
O status da assinatura de SaaS não é assinado.
A assinatura de SaaS que está sendo atualizada é adquirida por um CSP (Provedor de Soluções na Nuvem). Você deve trabalhar com o provedor CSP para executar essa ação.

Esse erro geralmente é um sintoma de erros na realização do registro de SaaS.

Código: 404 não encontrado. A assinatura SaaS com o especificado subscriptionId não pode ser encontrada.

Código: 500 Erro interno do servidor. Repita a chamada à API. Se o problema persistir, contate o Suporte da Microsoft.

Observação

É possível alterar o plano ou a quantidade de estações, mas não ambos ao mesmo tempo.

Somente é possível chamar essa API depois de obter aprovação explícita do usuário final para a alteração.

Alterar a quantidade de estações na assinatura de SaaS

Use essa API para atualizar (aumentar ou diminuir) a quantidade de estações compradas em uma assinatura de SaaS. O distribuidor deve chamar essa API quando há alteração, no lado dele, no número de estações de uma assinatura de SaaS criada no marketplace comercial.

A quantidade de licenças não pode ser maior do que a quantidade permitida no plano atual. Nesse caso, o distribuidor deve alterar o plano antes de alterar a quantidade de estações.

Aplicar patch `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Parâmetros de consulta:

Parâmetro	Valor
`ApiVersion`	Use 2018-08-31.
`subscriptionId`	O identificador exclusivo da assinatura de SaaS adquirida. Essa ID é obtida depois de resolver o token de autorização do marketplace comercial usando a API de resolução.

Cabeçalhos de solicitação:

Parâmetro	Valor
`content-type`	`application/json`
`x-ms-requestid`	Um valor de cadeia de caracteres exclusivo para acompanhamento da solicitação do cliente, preferencialmente um GUID. Se esse valor não for fornecido, um será gerado e fornecido nos cabeçalhos de resposta.
`x-ms-correlationid`	Um valor de cadeia de caracteres exclusiva para a operação no cliente. Esse parâmetro correlaciona todos os eventos da operação do cliente com eventos no lado do servidor. Se esse valor não for fornecido, um será gerado e fornecido nos cabeçalhos de resposta.
`authorization`	Um token de acesso exclusivo que identifica o distribuidor que está fazendo a chamada à API. O formato é `"Bearer <access_token>"` quando o valor do token é recuperado pelo editor, conforme explicado em Obter um token com base no aplicativo Microsoft Entra.

Solicitar exemplo de conteúdo:

{
  "quantity": 5 // the new amount of seats to be purchased
}

Códigos de resposta:

Código: 202 a solicitação para alterar a quantidade foi aceita e manipulada de maneira assíncrona. O parceiro deve sondar a URL da Localização da Operação para determinar se a solicitação de alteração da quantidade teve êxito ou falhou. A sondagem deve ser feita em intervalos de alguns segundos até determinar o status final da operação: falha, êxito ou conflito. O status final da operação deve ser retornado rapidamente, mas pode levar vários minutos em alguns casos.

Cabeçalhos de resposta:

Parâmetro	Valor
`Operation-Location`	Vincule a um recurso para obter o status da operação. Por exemplo, `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`.

Código: 400 Solicitação incorreta: falhas na validação.

A nova quantidade não está dentro do intervalo permitido.
A nova quantidade está ausente ou 0.
A nova quantidade é igual à quantidade atual.
O status da assinatura de SaaS não é assinado.
A assinatura de SaaS que está sendo atualizada é adquirida por um CSP (Provedor de Soluções na Nuvem). Você deve trabalhar com o provedor CSP para executar essa ação.

Esse erro geralmente é um sintoma de erros na realização do registro de SaaS.

Código: 404 não encontrado. A assinatura SaaS com o especificado subscriptionId não pode ser encontrada.

Código: 500 Erro interno do servidor. Repita a chamada à API. Se o problema persistir, contate o Suporte da Microsoft.

Observação

É possível alterar o plano ou a quantidade, mas não ambos ao mesmo tempo.

Somente é possível chamar essa API depois de obter aprovação explícita do usuário final para a alteração.

Cancelar uma assinatura

Use essa API para cancelar a assinatura de SaaS especificada. O distribuidor não precisa usar essa API, e recomendamos encaminhar os clientes ao marketplace comercial para cancelar assinaturas de SaaS.

Se o distribuidor decidir implementar o cancelamento de assinaturas de SaaS adquiridas no marketplace comercial no lado dele, deverá chamar essa API. Após a conclusão dessa chamada, o status da assinatura se torna Assinatura cancelada no lado da Microsoft.

O cliente não será cobrado se uma assinatura for cancelada dentro de 72 horas após a compra.

O cliente será cobrado se uma assinatura for cancelada após o período de carência anterior. O cliente perde o acesso à assinatura SaaS no lado da Microsoft imediatamente após o cancelamento.

Excluir `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Parâmetros de consulta:

Parâmetro	Valor
`ApiVersion`	Use 2018-08-31.
`subscriptionId`	O identificador exclusivo da assinatura SaaS adquirida. Essa ID é obtida depois de resolver o token de autorização do marketplace comercial usando a API de resolução.

Cabeçalhos de solicitação:

Parâmetro	Valor
`content-type`	`application/json`
`x-ms-requestid`	Um valor de cadeia de caracteres exclusivo para acompanhamento da solicitação do cliente, preferencialmente um GUID. Se esse valor não for fornecido, um será gerado e fornecido nos cabeçalhos de resposta.
`x-ms-correlationid`	Um valor de cadeia de caracteres exclusiva para a operação no cliente. Esse parâmetro correlaciona todos os eventos da operação do cliente com eventos no lado do servidor. Se esse valor não for fornecido, um será gerado e fornecido nos cabeçalhos de resposta.
`authorization`	Um token de acesso exclusivo que identifica o distribuidor que está fazendo a chamada à API. O formato é `"Bearer <access_token>"` quando o valor do token é recuperado pelo editor, conforme explicado em Obter um token com base no aplicativo Microsoft Entra.

Códigos de resposta:

Código: 202 a solicitação de cancelamento da assinatura foi aceita e manipulada de maneira assíncrona. O parceiro deve sondar a URL da Localização da Operação para determinar se a solicitação teve êxito ou falhou. A sondagem deve ser feita em intervalos de alguns segundos até determinar o status final da operação: falha, êxito ou conflito. O status final da operação deve ser retornado rapidamente, mas pode levar vários minutos em alguns casos.

O parceiro também recebe uma notificação de webhook quando a ação é concluída com êxito no lado do marketplace comercial. Somente então o distribuidor deve cancelar a assinatura no lado dele.

Código: 200 A assinatura já está em um estado Não assinado.

Cabeçalhos de resposta:

Parâmetro	Valor
`Operation-Location`	Vincule a um recurso para obter o status da operação. Por exemplo, `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`.

Código: 400 Solicitação incorreta. A exclusão não está na lista allowedCustomerOperations da assinatura de SaaS.

Código: 403 Proibido. O token de autorização é inválido, expirou ou não está disponível.

Esse erro geralmente é um sintoma de erros na realização do registro de SaaS.

Código: 404 não encontrado. Não foi localizada a assinatura de SaaS com a subscriptionId.

Código: 409

A exclusão não pode ser concluída porque a assinatura está bloqueada devido a operações pendentes.

Código: 500 Erro interno do servidor. Repita a chamada à API. Se o problema persistir, contate o Suporte da Microsoft.

Para obter mais opções de ofertas de SaaS no marketplace comercial, consulte as APIs do serviço de medição do marketplace comercial
Revise e use os clientes para diferentes linguagens de programação e exemplos
Para obter diretrizes de teste, consulte Implementando um webhook no serviço SaaS

Compartilhar via

APIs de assinatura de atendimento de SaaS v2 no marketplace comercial da Microsoft

Resolver uma assinatura comprada

Postar `https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>`

Ativar uma assinatura

Postar `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>`

Obter a lista de todas as assinaturas

Obter `https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>`

Obter assinatura

Obter `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Listar os planos disponíveis

Obter `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>`

Alterar o plano na assinatura

Aplicar patch `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Alterar a quantidade de estações na assinatura de SaaS

Aplicar patch `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Cancelar uma assinatura

Excluir `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Comentários

Recursos adicionais

Compartilhar via

APIs de assinatura de atendimento de SaaS v2 no marketplace comercial da Microsoft

Resolver uma assinatura comprada

Postar https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>

Ativar uma assinatura

Postar https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>

Obter a lista de todas as assinaturas

Obter https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>

Obter assinatura

Obter https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

Listar os planos disponíveis

Obter https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>

Alterar o plano na assinatura

Aplicar patch https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

Alterar a quantidade de estações na assinatura de SaaS

Aplicar patch https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

Cancelar uma assinatura

Excluir https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

Conteúdo relacionado

Comentários

Recursos adicionais

Postar `https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>`

Postar `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>`

Obter `https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>`

Obter `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Obter `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>`

Aplicar patch `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Aplicar patch `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Excluir `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`