> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Gerenciar produtos de assinatura a partir do seu serviço
> Descreve como usar o serviço Recurrence para consultar e gerenciar seus produtos de assinatura e lidar com os diferentes estados de assinatura de um usuário.
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)](https://github.com/microsoft/Microsoft-Store-Services)
* [Microsoft.StoreServices Sample (GitHub)](https://github.com/microsoft/Microsoft-Store-Services-Sample)
## 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](/pt-BR/publishing/xstore-commerce/xstore-choosing-product-type#subscriptions)
## Consultar a assinatura de um usuário
Use [purchase.mp.microsoft.com/v8.0/b2b/recurrences/query](/pt-BR/reference/microsoft-store-apis/xstore-v8-recurrence-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)](/pt-BR/reference/microsoft-store-apis/xstore-v8-query-for-products) e [publisherQuery (v9)](/pt-BR/reference/microsoft-store-apis/xstore-v9-query-for-products)) 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
| Data da compra | StartTime | ExpireTime | Data de renovação automática | Dias ativos |
| - | - | - | - | - |
| 2023-02-27T12:00:00Z | 2023-02-27T00:00:00Z | 2023-03-26T23:59:59Z | 2023-03-27T00:00:00Z | 28 |
| 2023-03-27T12:00:00Z | 2023-03-27T00:00:00Z | 2023-04-26T23:59:59Z | 2023-05-27T00:00:00Z | 31 |
| 2023-03-29T12:00:00Z | 2023-03-29T00:00:00Z | 2023-04-30T23:59:59Z | 2023-05-01T00:00:00Z | 32 |
| 2023-04-29T12:00:00Z | 2023-04-29T00:00:00Z | 2023-05-31T23:59:59Z | 2023-06-01T00:00:00Z | 33 |
| 2023-04-30T12:00:00Z | 2023-04-30T00:00:00Z | 2023-05-31T23:59:59Z | 2023-06-01T00:00:00Z | 32 |
| 2024-02-27T12:00:00Z | 2024-02-27T00:00:00Z | 2024-03-26T23:59:59Z | 2024-03-27T00:00:00Z | 29 (ano bissexto) |
### 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](https://account.microsoft.com/services).
Para colocar corretamente uma conta em cada um desses estados para teste, consulte [Testar produtos de assinatura](#testing-subscription-products).
#### 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
| Tipo de assinatura | Duração da assinatura | Carência | Cobrança (após a Carência) |
| - | - | - | - |
| Assinatura de complemento | Qualquer | 3 dias | 39 dias |
| Assinatura gerenciada pela Store | Qualquer | 7 dias | 36 dias |
## Alterar a assinatura de um usuário
Seus serviços também podem modificar assinaturas com [purchase.mp.microsoft.com/v8.0/b2b/recurrences/](/pt-BR/reference/microsoft-store-apis/xstore-v8-recurrence-change){recurrenceId}[/change](/pt-BR/reference/microsoft-store-apis/xstore-v8-recurrence-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](/pt-BR/reference/microsoft-store-apis/xstore-v8-recurrence-query) e dos valores de `recurrenceData` da [API de consulta de Collections](/pt-BR/reference/microsoft-store-apis/xstore-v9-query-for-products)) 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](/pt-BR/reference/microsoft-store-apis/xstore-v8-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](https://www.microsoft.com/en-us/p/xbox-gift-card-digital-code/cfq7ttc0k63h/0002?activetab=pivot:overviewtab) 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.
Para colocar corretamente uma conta no estado 'InDunning' para os períodos de Carência e de Cobrança, a conta deve passar pelas datas `ExpirationTime` e `ExpirationTimeWithGrace` naturalmente. Ao subtrair dias, defina como meta um `ExpirationTime` dentro das próximas 24 horas e, em seguida, deixe o tempo passar naturalmente. Se você mover o `ExpirationTime` para um ponto que já está no passado, `InDunning` pode não aparecer e o estado de teste pode se tornar inválido. A única maneira de resolver esse problema é cancelar a assinatura e criar uma nova assinatura de teste.
## Confira também
[Visão geral de comércio](/pt-BR/publishing/xstore-commerce/xstore-commerce-overview)
[APIs de serviço da Microsoft Store](/pt-BR/reference/microsoft-store-apis/index)
[purchase.mp.microsoft.com/v8.0/b2b/recurrences/query](/pt-BR/reference/microsoft-store-apis/xstore-v8-recurrence-query)
[purchase.mp.microsoft.com/v8.0/b2b/recurrences/](/pt-BR/reference/microsoft-store-apis/xstore-v8-recurrence-change){recurrenceId}[/change](/pt-BR/reference/microsoft-store-apis/xstore-v8-recurrence-change)
[Biblioteca Microsoft.StoreServices (GitHub)](https://github.com/microsoft/Microsoft-Store-Services)
[Microsoft.StoreServices Sample (GitHub)](https://github.com/microsoft/Microsoft-Store-Services-Sample)
## Related topics
- [Gerenciando produtos consumíveis a partir do seu serviço](/pt-BR/publishing/xstore-commerce/xstore-managing-consumables.md)
- [Detectar o acesso à assinatura do XBOX Game Pass a partir do seu serviço](/pt-BR/publishing/xstore-commerce/xstore-detecting-game-pass.md)
- [Autenticar seu serviço com as APIs da Microsoft Store](/pt-BR/publishing/xstore-commerce/xstore-authenticating-service.md)
- [API de alteração de recorrência de assinatura do Microsoft Store v8](/pt-BR/reference/microsoft-store-apis/xstore-v8-recurrence-change.md)
- [Concedendo aos jogadores acesso a conteúdo complementar](/pt-BR/publishing/xstore-commerce/xstore-granting-access.md)