Obter assinaturas para um usuário

  • Artigo

Use este 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

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

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

Pré-requisitos

Para usar esse método, você precisará:

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

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

Solicitação

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

parâmetro Tipo Descrição
Autorização string Obrigatórios. O token de acesso Azure AD notoken> de portador< do formulário.
Host string Deve ser definido como 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 Type Descrição Obrigatório
b2bKey string A chave de ID da Microsoft Store que representa a identidade do usuário cujas inscrições você deseja obter. Sim
continuationToken string Se o usuário tiver direitos sobre múltiplas assinaturas, o corpo da resposta retornará um token de continuação quando o limite da página for atingido. Forneça esse token de continuação em chamadas subsequentes para recuperar produtos restantes. Não
pageSize string O número máximo de assinaturas para retornar 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 tenha direitos a serem usados. Substitua o valor b2bKey pela chave 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

Este 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 a serem usados. O exemplo a seguir demonstra o corpo de resposta para um usuário que possui um direito para 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 de resposta contém os seguintes dados.

Valor Type Descrição
itens matriz Uma série de objetos que contêm dados sobre cada complemento de inscrição 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 itens contém os seguintes valores.

Valor Type Descrição
Renovar automaticamente Boolean Indica se a assinatura está configurada para renovar automaticamente no final do período de inscrição atual.
beneficiary string A ID do beneficiário do direito associado a esta subscrição.
expirationTime string A data e a hora em que a assinatura expirará, no formato ISO 8601. Este campo só está disponível quando a assinatura está em certos estados. O tempo de expiração geralmente indica quando o estado atual expira. Por exemplo, para uma assinatura ativa, a data de validade 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 delas você deseja modificar ao chamar o método alterar o estado de cobrança de uma assinatura para um usuário.
isTrial Boolean Indica se a assinatura é uma versão de avaliação.
lastModified string A data e 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 alpha-2 de duas letras) no qual o usuário adquiriu a assinatura.
productId string A ID da Store para o 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 Store para o SKU que representa o complemento de assinatura no catálogo da Microsoft Store. Um exemplo de ID da loja para SKU é 0010.
startTime string A data e a hora de início da assinatura, no formato ISO 8601.
recurrenceState string Um dos seguintes valores:
  • Nenhum: isso indica uma assinatura perpétua.
  • Ativo: a assinatura está ativa e o usuário tem o direito de usar os serviços.
  • Inativo: a assinatura já passou da data de validade e o usuário desativou a opção de renovação automática para a assinatura.
  • Cancelado: a assinatura foi finalizada propositalmente antes da data de validade, com ou sem reembolso.
  • InDunning: a assinatura está em andamento (ou seja, a assinatura está prestes a expirar e a Microsoft está tentando adquirir fundos para renovar automaticamente a assinatura).
  • Falha: o período de insucesso acabou e a assinatura não foi renovada após várias tentativas.

Observação:

  • Inativo/Cancelado/Falha são estados de terminal. Quando uma inscrição entra em um desses estados, o usuário deve recomprar a assinatura para ativá-la novamente. O usuário não tem direito a usar os serviços nesses estados.
  • Quando uma assinatura for Cancelada, o expirationTime será atualizado com a data e hora de cancelamento.
  • A ID da assinatura permanecerá a mesmo durante toda a sua vida. Ela não irá mudar se a opção de renovação automática for ativada ou desativada. Se um usuário recomprar uma inscrição depois de chegar a um estado terminal, será criada uma nova ID de inscrição.
  • O ID de uma assinatura deve ser usado para executar qualquer operação em uma assinatura individual.
  • Quando um usuário recompra uma assinatura depois de cancelar ou descontinuar, se você consultar os resultados para o usuário, você receberá duas entradas: uma com a ID da assinatura antiga em um estado terminal e uma com a nova ID da inscrição em um estado ativo.
  • É sempre uma boa prática verificar os tempos de recorrência e expiração, uma vez que as atualizações do estado de recorrência podem ser atrasadas em poucos minutos (ou ocasionalmente horas).
cancellationDate string A data e hora que é assinatura do usuário foi cancelada, sem formato ISO 8601.