Partilhar via

Obter assinaturas para um usuário

  • Artigo

Use esse método na API de compra da Microsoft Store para obter os complementos de assinatura que um determinado usuário tem direitos de usar.

Observação

Esse método só pode ser usado por contas de desenvolvedor que foram provisionadas pela Microsoft para poder criar complementos de assinatura para aplicativos UWP (Plataforma Universal do Windows). No momento, os complementos de assinatura não estão disponíveis para a maioria das contas de desenvolvedor.

A biblioteca Microsoft.StoreServices fornece a funcionalidade desse método por meio da API StoreServicesClient.RecurrenceQueryAsync.

Pré-requisitos

Para usar este método, você precisará de:

  • Um token de acesso do Azure AD que tem o valor https://onestore.microsoft.comdo URI da audiência.
  • Uma chave de ID da Microsoft Store que representa a identidade do usuário cujas assinaturas você deseja obter.

Para obter mais informações, consulte Gerenciar direitos de produto de um serviço.

Solicitar

Sintaxe da solicitação

Método URI da solicitação
POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/query

Cabeçalho da solicitação

Cabeçalho Tipo Descrição
Autorização string Obrigatório. O token de acesso do Azure AD no Token<de portador> do formulário.
Host string Deve ser definido com o valor purchase.mp.microsoft.com.
Content-Length número O tamanho do corpo da solicitação.
Tipo de conteúdo string Especifica o tipo de solicitação e resposta. Atualmente, o único valor com suporte é application/json.

Corpo da solicitação

Parâmetro Tipo Descrição Obrigatório
b2bChave string A chave de ID da Microsoft Store que representa a identidade do usuário cujas assinaturas você deseja obter. Sim
continuationToken string Se o usuário tiver direitos a várias assinaturas, o corpo da resposta retornará um token de continuação quando o limite de páginas for atingido. Forneça esse token de continuação aqui em chamadas subsequentes para recuperar os produtos restantes. Não
pageSize string O número máximo de assinaturas a serem retornadas em uma resposta. O padrão é 25. Não

Exemplo de solicitação

O exemplo a seguir demonstra como usar esse método para obter os complementos de assinatura que um determinado usuário tem direitos de usar. Substitua o valor b2bKey pela chave de ID da Microsoft Store que representa a identidade do usuário cujas assinaturas você deseja obter.

POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/query HTTP/1.1
Authorization: Bearer <your access token>
Content-Type: application/json
Host: purchase.mp.microsoft.com

{
  "b2bKey":  "eyJ0eXAiOiJ..."
}

Resposta

Esse método retorna um corpo de resposta JSON que contém uma coleção de objetos de dados que descrevem os complementos de assinatura que o usuário tem direitos de usar. O exemplo a seguir demonstra o corpo da resposta para um usuário que tem direito a uma assinatura.

{
  "items": [
    {
      "autoRenew":true,
      "beneficiary":"pub:gFVuEBiZHPXonkYvtdOi+tLE2h4g2Ss0ZId0RQOwzDg=",
      "expirationTime":"2017-06-11T03:07:49.2552941+00:00",
      "id":"mdr:0:bc0cb6960acd4515a0e1d638192d77b7:77d5ebee-0310-4d23-b204-83e8613baaac",
      "lastModified":"2017-01-08T21:07:51.1459644+00:00",
      "market":"US",
      "productId":"9NBLGGH52Q8X",
      "skuId":"0024",
      "startTime":"2017-01-10T21:07:49.2552941+00:00",
      "recurrenceState":"Active"
    }
  ]
}

Corpo da resposta

O corpo da resposta contém os dados a seguir.

Valor Type Descrição
itens matriz Uma matriz de objetos que contém dados sobre cada complemento de assinatura que o usuário especificado tem o direito de usar. Para obter mais informações sobre os dados em cada objeto, consulte a tabela a seguir.

Cada objeto na matriz items contém os valores a seguir.

Valor Type Descrição
renovação automática Booliano Indica se a assinatura está configurada para ser renovada automaticamente no final do período de assinatura atual.
beneficiário string A ID do beneficiário do direito associado a essa assinatura.
expirationTime string A data e a hora em que a assinatura expirará, no formato ISO 8601. Esse campo só está disponível quando a assinatura está em determinados estados. O tempo de expiração geralmente indica quando o estado atual expira. Por exemplo, para uma assinatura ativa, a data de expiração indica quando ocorrerá a próxima renovação automática.
expirationTimeWithGrace string A data e a hora em que a assinatura expirará, incluindo o período de carência, no formato ISO 8601. Esse valor indica quando o usuário perderá o acesso à assinatura depois que a assinatura não for renovada automaticamente.
ID string A ID da assinatura. Use esse valor para indicar qual assinatura você deseja modificar ao chamar o método alterar o estado de cobrança de uma assinatura para um usuário .
é julgamento Booliano Indica se a assinatura é uma avaliação.
lastModified string A data e a hora em que a assinatura foi modificada pela última vez, no formato ISO 8601.
market string O código do país (no formato ISO 3166-1 alfa-2 de duas letras) no qual o usuário adquiriu a assinatura.
productId string A ID da Loja do produto que representa o complemento de assinatura no catálogo da Microsoft Store. Um exemplo de ID da loja para um produto é 9NBLGGH42CFD.
skuId string A ID da Loja para o SKU que representa o complemento de assinatura no catálogo da Microsoft Store. Um exemplo de ID da loja para um SKU é 0010.
startTime string A data e hora de início da assinatura, no formato ISO 8601.
estado de recorrência string Um dos seguintes valores:
  • Nenhum: indica uma assinatura perpétua.
  • Ativo: A assinatura está ativa e o usuário tem direito a usar os serviços.
  • Inativo: a assinatura já passou da data de expiração e o usuário desativou a opção de renovação automática da assinatura.
  • Cancelada: a assinatura foi encerrada propositalmente antes da data de expiração, com ou sem reembolso.
  • InDunning: a assinatura está em cobrança (ou seja, a assinatura está se aproximando da expiração e a Microsoft está tentando adquirir fundos para renovar automaticamente a assinatura).
  • Falha: o período de cobrança terminou e a assinatura não foi renovada após várias tentativas.

Observação:

  • Inativo/Cancelado/Falha são estados terminais. Quando uma assinatura entra em um desses estados, o usuário deve comprar novamente a assinatura para ativá-la novamente. O usuário não tem o direito de usar os serviços nesses estados.
  • Quando uma assinatura é Cancelada, o expirationTime será atualizado com a data e a hora do cancelamento.
  • O ID da assinatura permanecerá o mesmo durante todo o seu tempo de vida. Ele não mudará se a opção de renovação automática estiver ativada ou desativada. Se um usuário recomprar uma assinatura depois de atingir um estado terminal, uma nova ID de assinatura será criada.
  • A ID de uma assinatura deve ser usada para executar qualquer operação em uma assinatura individual.
  • Quando um usuário recompra uma assinatura depois de cancelá-la ou descontinuá-la, se você consultar os resultados para o usuário, obterá duas entradas: uma com a ID de assinatura antiga em um estado terminal e outra com a nova ID de assinatura em um estado ativo.
  • É sempre uma boa prática verificar recurrenceState e expirationTime, pois as atualizações para recurrenceState podem ser atrasadas por alguns minutos (ou ocasionalmente horas).
data de cancelamento string A data e a hora em que a assinatura do usuário foi cancelada, no formato ISO 8601.