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

  • Artigo

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

Resolver uma subscrição comprada

O ponto de extremidade de resolução permite que o editor troque o token de identificação de compra do mercado comercial (referido como token em Comprado, mas ainda não ativado) por um ID de assinatura SaaS comprado persistente e seus detalhes.

Quando um cliente é redirecionado para o URL da página de destino do parceiro, o token de identificação do cliente é passado como o parâmetro de token nessa chamada de URL. Espera-se que o parceiro use esse token e faça uma solicitação para resolvê-lo. A resposta da API Resolve contém o ID da assinatura 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 forneça as seguintes orientações ao utilizador final:

"Não conseguimos identificar essa 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 os detalhes e o status da assinatura SaaS em todos os status suportados.

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

Parâmetros de consulta:

Parâmetro Value
ApiVersion Use 2018-08-31.

Cabeçalhos de solicitação:

Parâmetro Value
content-type application/json
x-ms-requestid Um valor de cadeia de caracteres exclusivo para acompanhar a solicitação do cliente, de preferência 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 exclusivo para operação no cliente. Este 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 editor que faz essa chamada de 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 do token de identificação de compra a ser resolvido. O token é passado na chamada de URL da página de destino quando o cliente é redirecionado para o site do parceiro 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 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, onde token é ab%2Bcd%2Fef. O mesmo token decodificado é: Ab+cd/ef

Códigos de resposta:

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

Exemplo de corpo de 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 Mau pedido. x-ms-marketplace-token está ausente, malformado, inválido ou expirado.

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 um ID de aplicativo Microsoft Entra diferente daquele usado para criar o token de autorização.

Esse erro geralmente é um sintoma de não executar o registro SaaS corretamente.

Código: 500 Erro interno do servidor. Tente novamente a chamada de API. Se o erro persistir, contacte o suporte da Microsoft.

Ativar uma subscrição

Depois que a conta SaaS for configurada para um usuário final, o editor deverá chamar a API Ativar Assinatura no lado da Microsoft. O cliente não será cobrado, a menos que esta chamada de API seja bem-sucedida.

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

Parâmetros de consulta:

Parâmetro Value
ApiVersion Use 2018-08-31.
subscriptionId O identificador exclusivo da assinatura SaaS comprada. Esse ID é obtido depois de resolver o token de autorização do mercado comercial usando a API de resolução.

Cabeçalhos de solicitação:

Parâmetro Value
content-type application/json
x-ms-requestid Um valor de cadeia de caracteres exclusivo para acompanhar a solicitação do cliente, de preferência 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 exclusivo para 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 editor que faz essa chamada de 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 Pedido para atualizar a subscrição e marcar como "Subscrito" é recebido. Os ISVs (Fornecedores Independentes de Software) podem verificar o status da assinatura após alguns minutos (leia a operação Obter para verificar o status da assinatura). Isso lhe dá a resposta definitiva se a assinatura foi atualizada com sucesso. A falha na assinatura envia automaticamente um webhook "Cancelar inscrição".

Não há um 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 um ID de aplicativo Microsoft Entra diferente daquele usado para criar o token de autorização.

Esse erro geralmente é um sintoma de não executar o registro SaaS corretamente.

Código: 404 Não encontrado. A assinatura SaaS está em um estado Unsubscribed .

Código: 500 Erro interno do servidor. Tente novamente a chamada de API. Se o erro persistir, contacte o suporte da Microsoft.

Obter lista de todas as subscrições

Essa API recupera uma lista de todas as assinaturas SaaS compradas para todas as ofertas que o editor publica no mercado 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 Value
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 @nextLink parâmetro para recuperar a próxima página.

Cabeçalhos de solicitação:

Parâmetro Value
content-type application/json
x-ms-requestid Um valor de cadeia de caracteres exclusivo para acompanhar a solicitação do cliente, de preferência 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 exclusivo para operação no cliente. Este 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 editor que está fazendo essa chamada de 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 Devolve a lista de todas as subscrições existentes para todas as ofertas feitas por este editor, com base no token de autorização do editor.

Exemplo de corpo de 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 nenhuma assinatura SaaS comprada for encontrada para este editor, o 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 não executar o registro SaaS corretamente.

Código: 500 Erro interno do servidor. Tente novamente a chamada de API. Se o erro persistir, contacte o suporte da Microsoft.

Obter subscrição

Essa API recupera uma assinatura SaaS comprada especificada para uma oferta SaaS que o editor publica no mercado comercial. Use esta chamada para obter todas as informações disponíveis para uma assinatura SaaS específica por sua ID em vez de chamar a API 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 Value
ApiVersion Use 2018-08-31.
subscriptionId O identificador exclusivo da assinatura SaaS comprada. Esse ID é obtido depois de resolver o token de autorização do mercado comercial usando a API Resolve.

Cabeçalhos de solicitação:

Parâmetro Value
content-type application/json
x-ms-requestid Um valor de cadeia de caracteres exclusivo para acompanhar a solicitação do cliente, de preferência 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 exclusivo para operação no cliente. Este 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 editor que está fazendo essa chamada de 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 Devolve detalhes de uma subscrição SaaS com base no subscriptionId fornecido.

Exemplo de corpo de 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 um ID de aplicativo Microsoft Entra diferente daquele usado para criar o token de autorização.

Esse erro geralmente é um sintoma de não executar o registro SaaS corretamente.

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. Tente novamente a chamada de API. Se o erro persistir, contacte o suporte da Microsoft.

Listar planos disponíveis

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

Esta chamada devolve uma lista de planos disponíveis para esse cliente, para além do já adquirido. A lista pode ser apresentada a um utilizador final no site do editor. Um 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 o ID de oferta privada ativo associado (se você chamar a API com filtro planId). Chamar a API com o filtro planId mostra os GUIDs de ID de oferta privada ativa 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 Value
ApiVersion Use 2018-08-31.
subscriptionId O identificador exclusivo da assinatura SaaS comprada. Esse ID é obtido depois de resolver o token de autorização do mercado comercial usando a API Resolve.
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 Value
content-type application/json
x-ms-requestid Um valor de cadeia de caracteres exclusivo para acompanhar a solicitação do cliente, de preferência 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 exclusivo para operação no cliente. Este 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 editor que está fazendo essa chamada de 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 Devolve uma lista de todos os planos disponíveis para uma subscrição SaaS existente, incluindo a já adquirida.

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

Exemplo de corpo de 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 Microsoft Entra diferente daquela usada para criar o token de autorização.

Esse erro geralmente é um sintoma de não executar o registro SaaS corretamente.

Código: 500 Erro interno do servidor. Tente novamente a chamada de API. Se o erro persistir, contacte o suporte da Microsoft.

Alterar o plano na subscrição

Use esta API para atualizar o plano existente adquirido para uma assinatura SaaS para um novo plano (público ou privado). O editor deve chamar essa API quando um plano é alterado no lado do editor para uma assinatura SaaS comprada no mercado comercial.

Essa API pode ser chamada apenas para assinaturas ativas . Qualquer plano pode ser alterado para qualquer outro plano existente (público ou privado), mas não para si mesmo. Para planos privados, o locatário do cliente deve ser definido como parte do público do plano no Partner Center.

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

Parâmetros de consulta:

Parâmetro Value
ApiVersion Use 2018-08-31.
subscriptionId O identificador exclusivo da assinatura SaaS comprada. Esse ID é obtido depois de resolver o token de autorização do mercado comercial usando a API Resolve.

Cabeçalhos de solicitação:

Parâmetro Value
content-type application/json
x-ms-requestid Um valor de cadeia de caracteres exclusivo para acompanhar a solicitação do cliente, de preferência 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 exclusivo para operação no cliente. Este 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 editor que está fazendo essa chamada de 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.

Exemplo de solicitação de carga útil:

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

Códigos de resposta:

Código: 202 O pedido de alteração de plano foi aceite e tratado de forma assíncrona. Espera-se que o parceiro pesquise a URL de Localização da Operação para determinar um sucesso ou falha da solicitação do plano de alteração. A sondagem deve ser feita a cada vários segundos até que o status final de Falha, Êxito ou Conflito seja recebido para a operação. O status final da operação deve ser devolvido 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 sucesso no lado do mercado comercial. Só então a editora deve fazer a mudança de plano do lado da editora.

Cabeçalhos de resposta:

Parâmetro Value
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 de validação.

  • O novo plano não existe ou não está disponível para esta subscrição SaaS específica.
  • O novo plano é o mesmo que o atual.
  • O status da assinatura SaaS não é Assinado.
  • A operação de atualização para uma assinatura SaaS não está incluída no 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 um ID de aplicativo Microsoft Entra diferente daquele usado para criar o token de autorização.

Esse erro geralmente é um sintoma de não executar o registro SaaS corretamente.

Código: 404 Não encontrado. A assinatura SaaS com subscriptionId não foi encontrada.

Código: 500 Erro interno do servidor. Tente novamente a chamada de API. Se o erro persistir, contacte o suporte da Microsoft.

Nota

O plano ou a quantidade de assentos podem ser alterados de uma só vez, não ambos.

Essa API só pode ser chamada depois de obter aprovação explícita para a alteração do usuário final.

Alterar a quantidade de licenças na assinatura SaaS

Use esta API para atualizar (aumentar ou diminuir) a quantidade de licenças compradas para uma assinatura SaaS. O editor deve chamar essa API quando o número de estações for alterado do lado do editor para uma assinatura SaaS criada no mercado comercial.

A quantidade de assentos não pode ser superior à quantidade permitida no plano atual. Neste caso, a editora deve alterar o plano antes de alterar a quantidade de lugares.

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

Parâmetros de consulta:

Parâmetro Value
ApiVersion Use 2018-08-31.
subscriptionId Um identificador exclusivo da assinatura SaaS comprada. Esse ID é obtido depois de resolver o token de autorização do mercado comercial usando a API Resolve.

Cabeçalhos de solicitação:

Parâmetro Value
content-type application/json
x-ms-requestid Um valor de cadeia de caracteres exclusivo para acompanhar a solicitação do cliente, de preferência 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 exclusivo para operação no cliente. Este 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 editor que está fazendo essa chamada de 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.

Exemplo de solicitação de carga útil:

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

Códigos de resposta:

Código: 202 O pedido de alteração de quantidade foi aceite e tratado de forma assíncrona. Espera-se que o parceiro pesquise a URL de Localização da Operação para determinar um sucesso ou falha da solicitação de quantidade de alteração. A sondagem deve ser feita a cada vários segundos até que o status final de Falha, Êxito ou Conflito seja recebido para a operação. O status final da operação deve ser devolvido 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 sucesso no lado do mercado comercial. Só então o editor deve fazer a alteração de quantidade no lado do editor.

Cabeçalhos de resposta:

Parâmetro Value
Operation-Location Link para 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 de validação.

  • A nova quantidade é maior ou menor do que o limite atual do plano.
  • Falta a nova quantidade.
  • A nova quantidade é a mesma que a quantidade atual.
  • O estado da Subscrição SaaS não é Subscrito.
  • A operação de atualização para uma assinatura SaaS não está incluída no 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 editor atual.

Esse erro geralmente é um sintoma de não executar o registro SaaS corretamente.

Código: 404 Não encontrado. A assinatura SaaS com subscriptionId não foi encontrada.

Código: 500 Erro interno do servidor. Tente novamente a chamada de API. Se o erro persistir, contacte o suporte da Microsoft.

Nota

Apenas um plano ou quantidade pode ser alterado de uma só vez, não ambos.

Essa API pode ser chamada somente depois de obter aprovação explícita do usuário final para a alteração.

Cancelar uma subscrição

Use esta API para cancelar a assinatura de uma assinatura SaaS especificada. O editor não precisa usar essa API e recomendamos que os clientes sejam direcionados ao mercado comercial para cancelar assinaturas de SaaS.

Se o editor decidir implementar o cancelamento de uma assinatura SaaS comprada no mercado comercial do lado do editor, ele deve chamar essa API. Após a conclusão desta chamada, o status da assinatura torna-se 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 do lado da Microsoft imediatamente após o cancelamento.

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

Parâmetros de consulta:

Parâmetro Value
ApiVersion Use 2018-08-31.
subscriptionId O identificador exclusivo da assinatura SaaS comprada. Esse ID é obtido depois de resolver o token de autorização do mercado comercial usando a API Resolve.

Cabeçalhos de solicitação:

Parâmetro Value
content-type application/json
x-ms-requestid Um valor de cadeia de caracteres exclusivo para acompanhar a solicitação do cliente, de preferência 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 exclusivo para operação no cliente. Este 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 editor que faz essa chamada de 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 O pedido de cancelamento de subscrição foi aceite e tratado de forma assíncrona. Espera-se que o parceiro pesquise a URL de localização da operação para determinar o sucesso ou a falha dessa solicitação. A sondagem deve ser feita a cada vários segundos até que o status final de Falha, Êxito ou Conflito seja recebido para a operação. O status final da operação deve ser devolvido 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 sucesso no lado do mercado comercial. Só então o editor deve cancelar a assinatura do lado do editor.

Código: 200 A subscrição já se encontra num estado de Não Subscrito.

Cabeçalhos de resposta:

Parâmetro Value
Operation-Location Link para 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 Mau pedido. Excluir não está na allowedCustomerOperations lista para esta assinatura 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 não executar o registro SaaS corretamente.

Código: 404 Não encontrado. A assinatura SaaS com subscriptionId não foi encontrada.

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. Tente novamente a chamada de API. Se o erro persistir, contacte o suporte da Microsoft.

Próximos passos