Partilhar via

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

  • Artigo

Observação

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 fornece uma oportunidade de aceitar ou rejeitar uma solicitação por patch que webhook operação com sucesso ou falha usando as seguintes APIs.

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 Operation Patch.

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

Parâmetros de consulta:

Parâmetro Valor
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 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 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 com base 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: 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 um ID de aplicativo Microsoft Entra diferente daquele usado para criar o token de autenticação.

Código: 403 Proibido. O token de autorização é inválido, não foi fornecido ou foi fornecido com permissões insuficientes. Certifique-se de fornecer um token de autorização válido.

Esse erro geralmente é um sintoma de não executar o de 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 de 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 assinatura, ChangePlanou ChangeQuantity.

O operationId para essa chamada de API pode ser recuperado do valor retornado por de Local de Operação, da chamada da API de operações pendentes ou do valor do parâmetro <id> recebido em uma chamada de webhook.

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

Parâmetros de consulta:

Parâmetro Valor
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 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 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 com base 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: 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 um ID de aplicativo Microsoft Entra diferente daquele usado para criar o token de autenticação.

Código: 403 Proibido. O token de autorização é inválido, não foi fornecido ou foi fornecido com permissões insuficientes. Certifique-se de fornecer um token de autorização válido.

Esse erro geralmente é um sintoma de não executar o de 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 de 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.

O operationId para essa chamada de API pode ser recuperado do valor retornado por de Local de Operação, da chamada da API de operações pendentes ou do valor do parâmetro <id> recebido em uma chamada de webhook.

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

Parâmetros de consulta:

Parâmetro Valor
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 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 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 com base no aplicativo Microsoft Entra.

Exemplo de carga útil de solicitação:

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

Código: 403 Proibido. O token de autorização é inválido, não foi fornecido ou foi fornecido com permissões insuficientes. Certifique-se de fornecer um token de autorização válido.

Esse erro geralmente é um sintoma de não executar o de 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 de suporte da Microsoft .

Conteúdo relacionado