Partilhar via

APIs de operações de atendimento SaaS v2 no mercado comercial da Microsoft

  • Artigo

Nota

Para poder chamar APIs de operações 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

Este artigo descreve a versão 2 das APIs de operações de atendimento SaaS.

As operações são úteis para responder a quaisquer solicitações que venham por meio do webhook como parte das ações ChangePlan, ChangeQuantity e Reinstate. Isso oferece uma oportunidade de aceitar ou rejeitar uma solicitação por patch que webhook operação com sucesso ou falha usando as APIs abaixo.

Isso só se aplica a eventos de webhook como ChangePlan, ChangeQuantity e Reinstate que precisam de um ACK. Nenhuma ação é necessária do ISV (fornecedor independente de software) em eventos Renovar, Suspender e Cancelar Inscrição porque eles são eventos somente de notificação.

Listar operações pendentes

Obtenha uma lista das operações pendentes para a assinatura SaaS especificada. O editor deve reconhecer as operações retornadas chamando a API de Patch de Operação.

Obter https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations?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 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 operações pendentes na assinatura SaaS especificada.

Exemplo de carga útil de resposta:

{
  "operations": [
    {
      "id": "<guid>", //Operation ID, should be provided in the operations patch API call
      "activityId": "<guid>", //not relevant
      "subscriptionId": "<guid>", // subscriptionId of the SaaS subscription that is being reinstated
      "offerId": "offer1", // purchased offer ID
      "publisherId": "contoso",
      "planId": "silver", // purchased plan ID
      "quantity": 20, // purchased amount of seats, will be empty is not relevant
      "action": "Reinstate",
      "timeStamp": "2018-12-01T00:00:00", // UTC
      "status": "InProgress" // the only status that can be returned in this case
    }
  ]
}

Retorna json vazio se nenhuma operação estiver pendente.

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

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.

Obter o status da operação

Essa API permite que o editor acompanhe o status da operação assíncrona especificada: Cancelar inscrição, ChangePlan ou ChangeQuantity.

A operationId chamada para esta API pode ser recuperada do valor retornado por Operation-Location, da chamada da API de operações pendentes ou do valor do <id> parâmetro recebido em uma chamada webhook.

Obter https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?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.
operationId O identificador exclusivo da operação que está sendo recuperada.

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: 200 Obtém detalhes para a operação SaaS especificada.

Exemplo de carga útil de resposta:

Response body:
{
  "id  ": "<guid>", //Operation ID, should be provided in the patch operation API call
  "activityId": "<guid>", //not relevant
  "subscriptionId": "<guid>", // subscriptionId of the SaaS subscription for which this operation is relevant
  "offerId": "offer1", // purchased offer ID
  "publisherId": "contoso",
  "planId": "silver", // purchased plan ID
  "quantity": 20, // purchased amount of seats
  "action": "ChangePlan", // Can be ChangePlan, ChangeQuantity or Reinstate
  "timeStamp": "2018-12-01T00:00:00", // UTC
  "status": "InProgress", // Possible values: NotStarted, InProgress, Failed, Succeeded, Conflict (new quantity / plan is the same as existing)
  "errorStatusCode": "",
  "errorMessage": ""
}

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 subscrição com subscriptionId não foi encontrada.
  • A operação com operationId 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.

Atualizar o status de uma operação

Use essa API para atualizar o status de uma operação pendente para indicar o sucesso ou falha da operação no lado do editor.

A operationId chamada para esta API pode ser recuperada do valor retornado por Operation-Location, da chamada da API de operações pendentes ou do valor do <id> parâmetro recebido em uma chamada webhook.

Adesivo https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?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.
operationId O identificador exclusivo da operação que está sendo concluída.

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:

{
  "status": "Success" // Allowed Values: Success/Failure. Indicates the status of the operation on ISV side.
}

Códigos de resposta:

Código: 200 Chamada para informar sobre a conclusão de uma operação do lado do parceiro. Por exemplo, esta resposta poderia sinalizar a conclusão da mudança de assentos ou planos do lado da editora.

Código: 403

  • Proibido. O token de autorização não está disponível, é inválido ou expirou. A solicitação pode estar tentando acessar uma assinatura que não pertence ao editor atual.
  • 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 subscrição com subscriptionId não foi encontrada.
  • A operação com operationId não foi encontrada.

Código: 409 Conflito. Por exemplo, uma atualização mais recente já foi realizada.

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

Conteúdos relacionados