Partilhar via

Alterar o estado de cobrança de uma assinatura para um usuário

  • Artigo

Use esse método na API de compra da Microsoft Store para alterar o estado de cobrança de um complemento de assinatura para um determinado usuário. Você pode cancelar, estender, reembolsar ou desativar a renovação automática de uma assinatura.

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.RecurrenceChangeAysnc.

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 que tem direito à assinatura que você deseja alterar.

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/{recurrenceId}/change

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.

Parâmetros da solicitação

Nome Tipo Descrição Obrigatório
recorrência string A ID da assinatura que você deseja alterar. Para obter essa ID, chame o método get subscriptions para um usuário, identifique a entrada do corpo da resposta que representa o complemento de assinatura que você deseja alterar e use o valor do campo id para a entrada. Sim

Corpo da solicitação

Campo Type Descrição Obrigatório
b2bChave string A chave de ID da Microsoft Store que representa a identidade do usuário cuja assinatura você deseja alterar. Sim
changeType string Uma das seguintes cadeias de caracteres que identifica o tipo de alteração que você deseja fazer:
  • Cancelar: cancela a assinatura.
  • Estender: Estende a assinatura. Se você especificar esse valor, também deverá incluir o parâmetro extensionTimeInDays .
  • Reembolso: Reembolsa a assinatura ao cliente.
  • ToggleAutoRenew: desabilita a renovação automática da assinatura. Se a renovação automática estiver desabilitada no momento para a assinatura, esse valor não fará nada.
 Sim
extensionTimeInDays string Se o parâmetro changeType tiver o valor Extend, esse parâmetro especificará o número de dias para estender a assinatura. Sim, se changeType tiver o valor Extend; caso contrário, não.

Exemplo de solicitação

O exemplo a seguir demonstra como usar esse método para estender o período de assinatura em 5 dias. Substitua o valor b2bKey pela chave de ID da Microsoft Store que representa a identidade do usuário cuja assinatura você deseja alterar.

POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/mdr:0:bc0cb6960acd4515a0e1d638192d77b7:77d5ebee-0310-4d23-b204-83e8613baaac/change HTTP/1.1
Authorization: Bearer <your access token>
Content-Type: application/json
Host: https://purchase.mp.microsoft.com

{
  "b2bKey":  "eyJ0eXAiOiJ...",
  "changeType": "Extend",
  "extensionTimeInDays": "5"
}

Resposta

Esse método retorna um corpo de resposta JSON que contém informações sobre o complemento de assinatura que foi modificado, incluindo todos os campos que foram modificados. O exemplo a seguir demonstra um corpo de resposta para esse método.

{
  "items": [
    {
      "autoRenew":true,
      "beneficiary":"pub:gFVuEBiZHPXonkYvtdOi+tLE2h4g2Ss0ZId0RQOwzDg=",
      "expirationTime":"2017-06-16T03:07:49.2552941+00:00",
      "id":"mdr:0:bc0cb6960acd4515a0e1d638192d77b7:77d5ebee-0310-4d23-b204-83e8613baaac",
      "lastModified":"2017-01-10T21:08:13.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
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.