Gerenciar produtos de assinatura a partir do seu serviço

Para produtos de assinatura, use um serviço de back-end para validar o status e gerenciar operações de ciclo de vida. O uso das APIs de Recurrence oferece às suas equipes de suporte e de operações ao vivo uma maneira confiável de inspecionar, estender ou cancelar assinaturas. Este artigo explica como usar os pontos de extremidade de Recurrence para esses cenários.

​

Utilizar a biblioteca .NET Microsoft.StoreServices e o exemplo

Para ajudar a demonstrar os princípios e fluxos descritos neste artigo, examine o Microsoft.StoreServices Sample. O exemplo usa a biblioteca Microsoft.StoreServices para gerenciar a autenticação e fazer as chamadas para os Microsoft Store Services. O próprio serviço de exemplo tem lógica de exemplo para gerenciar produtos de assinatura e fornece um guia de configuração para colocá-lo em funcionamento.

• Microsoft.StoreServices (GitHub)
• Microsoft.StoreServices Sample (GitHub)

​

Tipos de produto de assinatura

Os tipos de produto de assinatura gerenciada pela Store e de assinatura de complemento funcionam com o serviço Recurrence para exibir e gerenciar a assinatura do usuário. Para obter mais informações sobre cada um desses tipos de produto, consulte Escolher o tipo de produto certo

​

Consultar a assinatura de um usuário

Use purchase.mp.microsoft.com/v8.0/b2b/recurrences/query como o ponto de extremidade principal para o status da assinatura. Ele retorna períodos de assinatura ativos e históricos, além do subscriptionId necessário para operações de alteração. Ele também inclui os campos necessários para distinguir os períodos de Carência e de Cobrança (Dunning). As APIs de Collections (b2bLicensePreview (v8) e publisherQuery (v9)) podem mostrar o direito de assinatura ativo, mas não o mesmo detalhe de recorrência.

​

Atraso entre a satisfação de verificações de direito no cliente e de servidor para servidor

Quando você publica uma atualização que adiciona novos itens (direitos satisfatórios) a um pacote, existe um atraso na visibilidade dos novos itens entre o cliente e as consultas de API de servidor para servidor. Esse atraso ocorre porque diferentes sistemas da loja atualizam seus caches de catálogo em intervalos diferentes. Quando a alteração é publicada no catálogo, os serviços de licenciamento locais geralmente obtêm as informações atualizadas primeiro, e os caches usados pelo publisherQuery de duas a três horas depois. Portanto, conte com algumas horas entre as APIs do lado do cliente concederem acesso e suas chamadas de servidor para servidor ainda não refletirem a propriedade dos novos itens. O próprio serviço Recurrence não é afetado, apenas os pontos de extremidade publisherQuery ou b2bLicensePreview que consultam direitos satisfatórios nos itens recém-adicionados.

​

Entender as datas de início, renovação e expiração da assinatura

A data StartTime de uma assinatura é a data em que a assinatura ativa começou. Se a assinatura estiver configurada para renovação automática, a data de início permanece a mesma, mas as datas de expiração mudam à medida que a assinatura é renovada nos meses seguintes. Se uma assinatura for cancelada, expirar ou for revogada, um novo objeto de assinatura será criado quando o usuário comprar a assinatura novamente. O novo período de assinatura ativo tem o StartTime do dia em que o usuário ativou ou comprou a nova assinatura. Os períodos de assinatura na Microsoft Store normalmente são configurados como uma quantidade de meses. Por exemplo, 1 mês, 3 meses ou 12 meses. Quando um usuário compra uma assinatura de um mês, o StartTime é a meia-noite UTC (00:00:00) do dia em que ele iniciou a assinatura. ExpirationTime é o número de meses (não dias) adicionado ao StartTime menos um segundo (23:59:59 UTC).
Esse valor existe para que a assinatura expire pouco antes da meia-noite UTC. No entanto, alguns meses têm um número diferente de dias, criando um conflito com assinaturas iniciadas no dia 29, 30 ou 31 de um mês.
Se o StartTime do usuário cair em qualquer um desses dias, o ExpirationTime é modificado para 23:59:59 UTC do último dia do mês de expiração. Dessa forma, a data de renovação passa a ser sempre a meia-noite UTC (00:00:00) do primeiro dia do mês, e o ExpirationTime é sempre 23:59:59 UTC do último dia do mês.

​

Exemplo de comportamento das datas de início, renovação e expiração de uma assinatura de um mês

​

Entender os estados de Carência e de Cobrança (Dunning)

Se um pagamento de renovação automática falhar no ExpirationTime, a assinatura entra em Carência e, depois, em Cobrança (Dunning), se o problema ainda não tiver sido resolvido. Ambos os períodos informam o status InDunning, portanto, determine o período atual comparando a hora UTC atual com ExpirationTimeWithGrace. Enquanto a assinatura de um usuário estiver em Carência ou Cobrança, você deve notificar os usuários para verificarem o status de cobrança em Serviços e assinaturas da conta Microsoft. Para colocar corretamente uma conta em cada um desses estados para teste, consulte Testar produtos de assinatura.

​

Período de carência

Durante a Carência, mantenha os benefícios da assinatura habilitados enquanto a Store tenta novamente o pagamento da renovação. Se a renovação for bem-sucedida, os dias de Carência usados serão descontados do próximo período. Se o pagamento não for resolvido antes de ExpirationTimeWithGrace, a assinatura passará para Cobrança.

​

Período de cobrança (Dunning)

A Cobrança começa depois que a Carência termina. Desabilite os benefícios da assinatura durante esse período. Os usuários não podem comprar novamente nem resgatar a mesma assinatura durante a Cobrança. Se o pagamento continuar sem resolução durante toda a Cobrança, a assinatura se tornará inativa.

​

Durações de Carência e de Cobrança

​

Alterar a assinatura de um usuário

Seus serviços também podem modificar assinaturas com purchase.mp.microsoft.com/v8.0/b2b/recurrences//change. As operações compatíveis incluem adicionar dias, desabilitar a renovação automática e cancelar a assinatura. Seu serviço precisa do recurrenceId (o mesmo valor de id da API RecurrenceQuery e dos valores de recurrenceData da API de consulta de Collections) para operar na assinatura do usuário. Aqui estão alguns exemplos de como o ponto de extremidade Recurrence Change pode ser útil com seus serviços:

• Adicionar tempo às assinaturas de usuários que enfrentaram uma interrupção do serviço.
• Integração com suas equipes de Suporte ao Cliente para ajudar os usuários com informações sobre o status da assinatura, cancelamentos etc.
• Interface do usuário no jogo que permite aos usuários alterar configurações, como a renovação automática, ou encerrar suas assinaturas.

​

Testar produtos de assinatura

A API Recurrence Change também pode ser usada para testes. Extend aceita valores de dias negativos, permitindo que você avance uma assinatura de teste até os estados desejados.

​

Testar os estados Ativo, Inativo e Cancelado

Ao testar os estados Ativo, Inativo e Cancelado de uma assinatura, você pode usar um preço base de $0.00 na assinatura. Adicione a assinatura à conta de teste para verificar o estado Ativo e use o ponto de extremidade Recurrence Change para desabilitar a renovação automática. Em seguida, use o ponto de extremidade Recurrence Change para cancelar a assinatura ou subtrair dias suficientes para que o ExpirationTime fique antes da data e hora UTC atual.

​

Testar os estados de Carência e de Cobrança

Para testar os estados de Carência e de Cobrança, a assinatura deve ter um preço diferente de zero.
Além disso, a conta de teste deve estar configurada de modo que os pagamentos subsequentes não sejam bem-sucedidos quando o ExpirationTime passar. Atualmente, a Microsoft Store não tem instrumentos de pagamento de teste, portanto, a maneira mais fácil de configurar uma conta é usando códigos de moeda pré-paga da seguinte forma:

1. Configure a assinatura com um preço baixo, como $0.99, no seu ambiente de teste.
2. Compre um cartão-presente pré-pago do XBOX de $1.00 ou$2.00 para cobrir a primeira compra da assinatura (mais impostos), mas não a renovação.
3. Resgate o cartão-presente na sua conta de teste.
4. Compre a assinatura na conta de teste.
5. Verifique se a renovação automática está habilitada para a assinatura, mas não há fundos suficientes para renová-la.
6. Use Recurrence Change para mover o ExpirationTime da assinatura para dentro das próximas 24 horas (consulte a observação a seguir).
7. Aguarde o ExpirationTime passar naturalmente e o status mostrar InDunning (pode levar até 24 horas após o ExpirationTime).

Para obter um comportamento preciso de Carência -> Cobrança -> Inativo, deixe a conta progredir naturalmente depois de configurar o teste.

​

Confira também

Visão geral de comércio APIs de serviço da Microsoft Store purchase.mp.microsoft.com/v8.0/b2b/recurrences/query purchase.mp.microsoft.com/v8.0/b2b/recurrences//change Biblioteca Microsoft.StoreServices (GitHub) Microsoft.StoreServices Sample (GitHub)