Compartilhar via

APIs de operações de cumprimento de SaaS v2 no marketplace comercial da Microsoft

  • Artigo

Nota

Para poder chamar APIs de Operações de Cumprimento de 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 cumprimento de SaaS.

As operações são úteis para responder a todas as solicitações que vêm por meio do webhook como parte das ações ChangePlan, ChangeQuantity e Restore. Isso oferece uma oportunidade de aceitar ou rejeitar uma solicitação por patch da operação de webhook com êxito ou falha usando as APIs abaixo.

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

Listar operações pendentes

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

Obter 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. 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 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 operações pendentes na assinatura SaaS especificada.

exemplo de conteúdo 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 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: 404 Não encontrado. A assinatura saaS com subscriptionId não foi encontrada.

Código: 500 Erro interno do servidor. Tente novamente a chamada à API. Se o erro persistir, entre em contato 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, changeplan ou ChangeQuantity.

O operationId para essa chamada de API pode ser recuperado do valor retornado por operation-location, a chamada à API de Operações pendente ou o valor do parâmetro <id> recebido em uma chamada de webhook.

Obter 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. Essa ID é obtida depois de resolver o token de autorização do marketplace 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 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 Obtém detalhes da operação SaaS especificada.

exemplo de conteúdo 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 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: 404 Não encontrado.

  • A assinatura 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 à API. Se o erro persistir, entre em contato 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 êxito ou falha da operação no lado do editor.

O operationId para essa chamada de API pode ser recuperado do valor retornado por operation-location, a chamada à API de Operações pendente ou o 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. Essa ID é obtida depois de resolver o token de autorização do marketplace 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 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 :

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

códigos de resposta :

Código: 200 Uma chamada para informar sobre a conclusão de uma operação no lado do parceiro. Por exemplo, essa resposta pode sinalizar a conclusão da alteração de assentos ou planos no lado do editor.

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: 404 Não encontrado.

  • A assinatura 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á está atendida.

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

Conteúdo relacionado