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

  • Artigo

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

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 orientações ao usuário final:

"Não foi possível identificar a compra. Reabra esta assinatura 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 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 baseado 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 da URL da página de destino, portanto, ele precisa ser decodificado antes de ser usado como um parâmetro nessa 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 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 de 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 baseado no aplicativo Microsoft Entra.

Códigos de resposta:

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

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 .

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 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. 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 SaaS em todos os status possíveis são retornadas. As assinaturas SaaS não assinadas também são retornadas porque essas informações não são excluídas do 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 baseado 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 baseado 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 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 do 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 esteja na lista não funciona.

Essa API também recupera o ID de oferta privada ativo associado (se você chamar a API com filtro planId). Chamar API com 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 baseado 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 que 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 baseado 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 notificação de webhook quando a ação está pronta para ser concluída com sucesso no lado do mercado 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 novo plano não existe ou não está disponível para esta assinatura de SaaS específica.
  • O novo plano é o mesmo que o plano atual.
  • O status da assinatura de SaaS não é assinado.
  • A operação de atualização de uma assinatura de SaaS não foi incluída em allowedCustomerOperations.

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 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 a assinatura de SaaS com a subscriptionId.

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 assentos 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 baseado 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.

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

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 é maior ou menor que o limite do plano atual.
  • A nova quantidade está ausente.
  • A nova quantidade é igual à quantidade atual.
  • O status da assinatura de SaaS não é assinado.
  • A operação de atualização de uma assinatura de SaaS não foi incluída em allowedCustomerOperations.

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 que não pertence ao distribuidor atual.

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: 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 desta chamada, o status da assinatura se torna Cancelar inscrição 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 baseado 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 notificação de webhook quando a ação é concluída com sucesso no lado do mercado comercial. Somente então o distribuidor deve cancelar a assinatura no lado dele.

Código: 200 A assinatura já está em um estado Unsubscribed.

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.

Próximas etapas