Compartilhar via

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

  • Artigo

Observação

Para poder chamar APIs de operações de atendimento 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 chegam por meio do webhook como parte das ações ChangePlan, ChangeQuantity e Reintegrar. Isso oferece uma oportunidade de aceitar ou rejeitar uma solicitação com patch dessa operação de webhook com êxito ou falha usando as APIs abaixo.

Isso só se aplica a eventos de webhook, como ChangePlan, ChangeQuantity e Replace, que precisam de um ACK. Nenhuma ação é necessária do ISV (fornecedor independente de software) em eventos de renovação, suspensão e cancelamento de assinatura porque eles são eventos somente de notificação.

Listar operações pendentes

Obter a lista das operações pendentes da assinatura de SaaS especificada. O distribuidor 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 Valor
ApiVersion Use 2018-08-31.
subscriptionId O identificador exclusivo da assinatura SaaS adquirida. Essa ID é obtida depois de resolver o token de autorização do marketplace comercial usando a API de resolução.

Cabeçalhos de solicitação:

Parâmetro Valor
content-type application/json
x-ms-requestid Um valor de cadeia de caracteres exclusivo para acompanhamento da solicitação do cliente, preferencialmente 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 exclusiva 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 editor, conforme explicado em Obter um token com base no aplicativo Microsoft Entra.

Códigos de resposta:

Código: 200 retorna as operações pendentes da assinatura de 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 um JSON vazio se nenhuma operação estiver pendente.

Código: 400 Solicitação incorreta: falhas na 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 uma ID de aplicativo do Microsoft Entra diferente daquela usada para criar o token de autorização.

Esse erro geralmente é um sintoma de erros na realização do registro de SaaS.

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

Código: 500 Erro interno do servidor. Repita a chamada à API. Se o problema persistir, contate o Suporte da Microsoft.

Obter status da operação

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

É possível obter a operationId dessa chamada à API usando o valor retornado pela Localização da Operação, a chamada à API obter operações pendentes ou o valor de 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 adquirida. Essa ID é obtida depois de resolver o token de autorização do marketplace comercial usando a API de resolução.
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 acompanhamento da solicitação do cliente, preferencialmente 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 exclusiva 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 distribuidor que está fazendo a chamada à 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 os 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: 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 uma ID de aplicativo do Microsoft Entra diferente daquela usada para criar o token de autorização.

Esse erro geralmente é um sintoma de erros na realização do registro de SaaS.

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. Repita a chamada à API. Se o problema persistir, contate o Suporte da Microsoft.

Atualizar o status de uma operação

Use essa API para atualizar o status de uma operação pendente, a fim de indicar o êxito ou a falha dela no lado do distribuidor.

É possível obter a operationId dessa chamada à API usando o valor retornado pela Localização da Operação, a chamada à API obter operações pendentes ou o valor de parâmetro <id> recebido em uma chamada de webhook.

Aplicar 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 adquirida. Essa ID é obtida depois de resolver o token de autorização do marketplace comercial usando a API de resolução.
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 acompanhamento da solicitação do cliente, preferencialmente 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 exclusiva 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 distribuidor que está fazendo a chamada à 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.

Solicitar exemplo de conteúdo:

{
  "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 a conclusão de uma operação no lado do parceiro. Por exemplo, essa resposta pode sinalizar a conclusão da alteração de estações ou de planos no lado do distribuidor.

Código: 403

  • Negado. 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.
  • Negado. 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 uma ID de aplicativo do Microsoft Entra diferente daquela usada para criar o token de autorização.

Esse erro geralmente é um sintoma de erros na realização do registro de SaaS.

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á foi atendida.

Código: 500 Erro interno do servidor. Repita a chamada à API. Se o problema persistir, contate o Suporte da Microsoft.

Conteúdo relacionado