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

Artigo
01/31/2025

Este artigo descreve a versão 2 das APIs de assinatura de atendimento saaS.

Nota

Para poder chamar APIs de assinatura de atendimento 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 resolve permite que o editor troque o token de identificação de compra do marketplace comercial (conhecido como de token em Comprado, mas ainda não ativado) para uma ID de assinatura SaaS comprada 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 token parâmetro nesta chamada de URL. Espera-se que o parceiro use esse token e faça uma solicitação para resolvê-lo. A resposta da API resolver contém a ID da assinatura SaaS e outros detalhes para identificar exclusivamente a compra. O token fornecido com a chamada de URL da página de aterrissagem é válido por 24 horas. Se o token que você recebe expirar, recomendamos que você forneça as seguintes diretrizes ao usuário final:

"Não foi possível 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 resolver retorna detalhes e status da assinatura para assinaturas SaaS em todos os status com suporte.

Post `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 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 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 editor que está fazendo essa chamada à API. O formato é `"Bearer <access_token>"` quando o valor do token é recuperado pelo publicador, conforme explicado em Obter um token com base no aplicativo Microsoft Entra.
`x-ms-marketplace-token`	A identificação de compra token parâmetro a ser resolvido. O token é passado na chamada de URL da página de aterrissagem quando o cliente é redirecionado para o site do parceiro SaaS (por exemplo: `https://contoso.com/signup?token=<token><authorization_token>`). O token valor que está sendo codificado faz parte da URL da página de aterrissagem, portanto, ele precisa ser decodificado antes de ser usado como um parâmetro nesta chamada à 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 SaaS exclusivos com base no x-ms-marketplace-token fornecido.

Exemplo do 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 expirado.

Código: 401 Não autorizado. O token de autorização é inválido ou expirou. 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 autenticação.

Código: 403 Proibido. O token de autorização é inválido, não foi fornecido ou recebeu permissões insuficientes. Forneça um token de autorização válido.

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

Código: 500 Erro interno do servidor. Tente novamente a chamada à API. Se o erro persistir, entre em contato suporte da Microsoft.

Ativar uma assinatura

Depois que a conta saaS for configurada para um usuário final, o publicador deverá chamar a API ativar assinatura no lado da Microsoft. O cliente não é cobrado a menos que essa chamada à API seja bem-sucedida.

Post `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 comprada. Essa ID é obtida depois de resolver o token de autorização do marketplace comercial usando o de API de Resolução de.

cabeçalhos de solicitação :

Parâmetro	Valor
`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 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 editor que está fazendo essa chamada à API. O formato é `"Bearer <access_token>"` quando o valor do token é recuperado pelo publicador, 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" é recebido. Os ISVs (Fornecedores Independentes de Software) podem verificar o status da assinatura após alguns minutos (leia mais sobre 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á nenhum corpo de resposta para esta chamada.

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

A assinatura saaS está em estado de suspenso.

Código: 403 Proibido. O token de autorização é inválido, não foi fornecido ou recebeu permissões insuficientes. Forneça um token de autorização válido.

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

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

Código: 500 Erro interno do servidor. Tente novamente a chamada à API. Se o erro persistir, entre em contato suporte da Microsoft.

Obter lista de todas as assinaturas

Essa API recupera uma lista de todas as assinaturas SaaS compradas para todas as ofertas que o editor publica no marketplace comercial. As assinaturas saaS em todos os status possíveis são retornadas. Assinaturas 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, você deve passar o continuationToken para obter os resultados subsequentes.

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 vazia. Use o valor retornado em `@nextLink` parâmetro para recuperar a próxima página.

cabeçalhos de solicitação :

Parâmetro	Valor
`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 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 editor que está fazendo essa chamada à API. O formato é `"Bearer <access_token>"` quando o valor do token é recuperado pelo publicador, 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 existentes para todas as ofertas feitas por esse editor, com base no token de autorização do editor.

exemplo do 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 nenhuma assinatura SaaS comprada for encontrada para este editor, o corpo da resposta vazia será retornado.

Código: 403 Proibido. O token de autorização é inválido, não foi fornecido ou recebeu permissões insuficientes. Forneça um token de autorização válido.

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

Código: 500 Erro interno do servidor. Tente novamente a chamada à API. Se o erro persistir, entre em contato suporte da Microsoft.

Obter assinatura

Essa API recupera uma assinatura SaaS comprada especificada para uma oferta de SaaS que o editor publica no marketplace comercial. Use essa 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	Valor
`ApiVersion`	Use 2018-08-31.
`subscriptionId`	O identificador exclusivo da assinatura saaS comprada. Essa ID é obtida depois de resolver o token de autorização do marketplace comercial usando a API Resolve.

cabeçalhos de solicitação :

Parâmetro	Valor
`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 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 editor que está fazendo essa chamada à API. O formato é `"Bearer <access_token>"` quando o valor do token é recuperado pelo publicador, conforme explicado em Obter um token com base no aplicativo Microsoft Entra.

códigos de resposta :

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

exemplo do 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, não foi fornecido ou recebeu permissões insuficientes. Forneça um token de autorização válido.

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

Código: 404 Não encontrado. A assinatura saaS com a subscriptionId especificada não pode ser encontrada.

Código: 500 Erro interno do servidor. Tente novamente a chamada à API. Se o erro persistir, entre em contato suporte da Microsoft.

Listar planos disponíveis

Essa API recupera todos os planos para uma oferta de SaaS identificada pelo subscriptionId de uma compra específica desta oferta. Use essa 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 retornados estão disponíveis na mesma geografia que o plano já comprado.

Essa chamada retorna uma lista de planos disponíveis para esse cliente, além daquele já comprado. A lista pode ser apresentada a um usuário final no site do editor. Um usuário final pode alterar o plano de assinatura para qualquer um dos planos na lista retornada. A alteração do 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 filtro planId). Chamar a API com o filtro planId mostra os GUIDs de ID da oferta privada ativa no corpo da resposta no nó sourceOffers. O planId passado no parâmetro de filtro deve corresponder à 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 comprada. Essa ID é obtida depois de resolver o token de autorização do marketplace comercial usando a API Resolve.
`planId (Optional)`	Planeje a ID 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 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 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 editor que está fazendo essa chamada à API. O formato é `"Bearer <access_token>"` quando o valor do token é recuperado pelo publicador, conforme explicado em Obter um token com base no aplicativo Microsoft Entra.

códigos de resposta :

Código: 200 Retorna uma lista de todos os planos disponíveis para uma assinatura SaaS existente, incluindo a já adquirida.

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

Exemplo do 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, não foi fornecido ou recebeu permissões insuficientes. Forneça um token de autorização válido.

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

Código: 500 Erro interno do servidor. Tente novamente a chamada à API. Se o erro persistir, entre em contato suporte da Microsoft.

Alterar o plano na assinatura

Use essa API para atualizar o plano existente comprado 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 marketplace comercial.

Essa API só pode ser chamada para assinaturas do Active. 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-alvo do plano no Partner Center.

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 comprada. Essa ID é obtida depois de resolver o token de autorização do marketplace comercial usando a API Resolve.

cabeçalhos de solicitação :

Parâmetro	Valor
`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 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 editor que está fazendo essa chamada à API. O formato é `"Bearer <access_token>"` quando o valor do token é recuperado pelo publicador, conforme explicado em Obter um token com base no aplicativo Microsoft Entra.

exemplo de conteúdo da solicitação :

{
  "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 tratada de forma assíncrona. Espera-se que o parceiro pesquise a URL Operation-Location para determinar um êxito 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 Com Falha, Êxitoou de Conflito seja recebido para a operação. O status da operação final 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 editor deve fazer a alteração do plano no lado do editor.

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 de validação.

O plano solicitado não pode ser encontrado ou o plano não está disponível para o usuário.
O plano solicitado é o mesmo que o plano assinado.
O status da assinatura saaS não é assinatura.
A assinatura 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.

Código: 403 Proibido. O token de autorização é inválido, não foi fornecido ou recebeu permissões insuficientes. Forneça um token de autorização válido.

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

Código: 404 Não encontrado. A assinatura saaS com a subscriptionId especificada não pode ser encontrada.

Código: 500 Erro interno do servidor. Tente novamente a chamada à API. Se o erro persistir, entre em contato suporte da Microsoft.

Nota

O plano ou a quantidade de assentos podem ser alterados ao mesmo tempo, 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 assentos na assinatura saaS

Use essa API para atualizar (aumentar ou diminuir) a quantidade de assentos comprados para uma assinatura saaS. O editor deve chamar essa API quando o número de assentos for alterado do lado do editor para uma assinatura 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 editor deve alterar o plano antes de alterar a quantidade de assentos.

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`	Um identificador exclusivo da assinatura saaS comprada. Essa ID é obtida depois de resolver o token de autorização do marketplace comercial usando a API Resolve.

cabeçalhos de solicitação :

Parâmetro	Valor
`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 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 editor que está fazendo essa chamada à API. O formato é `"Bearer <access_token>"` quando o valor do token é recuperado pelo publicador, conforme explicado em Obter um token com base no aplicativo Microsoft Entra.

exemplo de conteúdo da solicitação :

{
  "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 tratada de forma assíncrona. Espera-se que o parceiro pesquise a URL Operation-Location para determinar um êxito 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 Com Falha, Êxitoou de Conflito seja recebido para a operação. O status da operação final deve ser retornado rapidamente, mas pode levar vários minutos em alguns casos.

Cabeçalhos de resposta :

Parâmetro	Valor
`Operation-Location`	Vincular 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 de validação.

A nova quantidade não está dentro do intervalo permitido.
A nova quantidade está ausente ou 0.
A nova quantidade é a mesma da quantidade atual.
O status da Assinatura SaaS não está inscrito.
A assinatura 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.

Código: 403 Proibido. O token de autorização é inválido, não foi fornecido ou recebeu permissões insuficientes. Forneça um token de autorização válido.

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

Código: 404 Não encontrado. A assinatura saaS com a subscriptionId especificada não pode ser encontrada.

Código: 500 Erro interno do servidor. Tente novamente a chamada à API. Se o erro persistir, entre em contato suporte da Microsoft.

Nota

Somente um plano ou quantidade pode ser alterado ao mesmo tempo, não ambos.

Essa API só pode ser chamada 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 uma assinatura SaaS especificada. O publicador não precisa usar essa API e recomendamos que os clientes sejam direcionados para o marketplace comercial para cancelar assinaturas SaaS.

Se o editor decidir implementar o cancelamento de uma assinatura SaaS comprada no marketplace comercial do lado do editor, ele deverá chamar essa API. Após a conclusão dessa chamada, o status da assinatura se torna não assinados 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 comprada. Essa ID é obtida depois de resolver o token de autorização do marketplace comercial usando a API Resolve.

cabeçalhos de solicitação :

Parâmetro	Valor
`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 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 editor que está fazendo essa chamada à API. O formato é `"Bearer <access_token>"` quando o valor do token é recuperado pelo publicador, conforme explicado em Obter um token com base no aplicativo Microsoft Entra.

códigos de resposta :

Código: 202 A solicitação para cancelar a assinatura foi aceita e tratada de forma assíncrona. Espera-se que o parceiro pesquise a URL Operation-Location para determinar um êxito ou falha dessa solicitação. A sondagem deve ser feita a cada vários segundos até que o status final de Com Falha, Êxitoou de Conflito seja recebido para a operação. O status da operação final 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 editor deve cancelar a assinatura no lado do editor.

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

Cabeçalhos de resposta :

Parâmetro	Valor
`Operation-Location`	Vincular 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 para esta assinatura saaS.

Código: 403 Proibido. O token de autorização é inválido, não foi fornecido ou recebeu permissões insuficientes. Forneça um token de autorização válido.

Esse erro geralmente é um sintoma de não executar o registro de 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 à API. Se o erro persistir, entre em contato suporte da Microsoft.

Para obter mais opções para ofertas de SaaS no marketplace comercial, consulte as APIs de serviço de medição do marketplace comercial
Examine 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 saaS v2 no marketplace comercial da Microsoft

Resolver uma assinatura comprada

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

Ativar uma assinatura

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

Obter 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 planos disponíveis

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

Alterar o plano na assinatura

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

Alterar a quantidade de assentos na assinatura saaS

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 saaS v2 no marketplace comercial da Microsoft

Resolver uma assinatura comprada

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

Ativar uma assinatura

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

Obter 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 planos disponíveis

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

Alterar o plano na assinatura

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

Alterar a quantidade de assentos na assinatura saaS

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

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

Post `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>`

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

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

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