Este tópico visa fomentar o conhecimento na nossa comunidade, principalmente no que tange ao módulo de pedidos, e principalmente a nossa aplicação de assinaturas. Além de complementar o tópico “Dúvidas Frequentes: Como funciona o módulo de assinaturas?” também publicado aqui na comunidade.
Se você tem dúvidas sobre como começar a utilizar APIs como as descritas abaixo, veja o nosso tópico: Dúvidas Frequentes: Como utilizar APIs?. Por outro lado, se você tem dúvidas sobre o que é uma API e quais são suas funcionalidades, veja nosso tópico: Dúvidas Frequentes: O que são APIs, quais seus métodos e como funcionam?.
Existem diversas formas de fazer o gerenciamento de assinaturas na sua loja VTEX, uma delas é por meio das APIs de Subscripitions, que podem ser encontradas na nossa página do Developers no seguinte local:
Dentro das APIs de assinaturas, existem diversas APIs que podem ser utilizadas para auxiliar no gerenciamento desta aplicação na sua loja.
Cycles: São as APIs destinadas a buscar, listar e/ou tentar novamente um ciclo. Um ciclo é um período onde ocorre um pedido de assinatura.
Plans: São APIs cujo objetivo é listar os planos existentes ou obter detalhes de um determinado plano. Cabe pontuar aqui que um plano de assinatura, define os produtos que podem ser assinados e as frequências possíveis (assinatura diária, semanal, mensal…).
Reports: São as APIs capazes de gerar relatórios sobre o módulo de assinaturas.
Subscriptions: Essas são as APIs que, de fato, permitem que seja feito o gerenciamento das assinaturas, alterar itens, editar itens, alterar status de uma assinatura e falaremos mais detalhadamente sobre o uso dessas APIs a seguir.
Settings: Conjunto de APIs destinadas a configurações possíveis do módulo de assinaturas.
Gerenciando assinaturas via API:
Muitas das APIs que fazem o papel de gerenciar as assinaturas de um cliente, como as APIs Get subscription details, Update subscription, Edit items on a subscription, Add item to subscription e Remove items from a subscription precisam do {id} da assinatura em questão para que possam ser executadas.
Como conseguir esse
{id}?
Resp.: Bom existem duas formas, via Admin e via API:
- via Admin:
Através das interações do pedido gerador da assinatura, para mais informações consulte nosso outro tópico: Dúvidas Frequentes: Como funciona o módulo de assinaturas?
- via API:
Existem duas formas de conseguir esse {id} via API:
1. Por meio da API List subscriptions, por meio desta API é possível obter as informações das assinaturas dos seus clientes, filtrando por diversos campos como customerEmail, status, originalOrderId, paymentId e alguns outros.
2. Por meio da API Get order executada em qualquer pedido de assinatura (exceto o pedido que gerou assinatura, no campo SubscriptionGroupId:
Além disso, para algumas dessas APIs, as que tratam da edição (Edit items on a subscription) ou remoção de itens (Remove items from a subscription) além do {id} da assinatura é necessário também o {itemId}:
Como conseguir o
{itemId}referente a um SKU de uma assinatura?
Resp.: Através da API Get subscription details
Na resposta dessa API é possível obter o {itemId} dentro do array 'items':
Limitações do gerenciamento de assinaturas via API:
- Não é possível alterar uma assinatura com
status: CANCELEDsendo assim não é possível reativá-lá ou realizar qualquer outra alteração que possa ser de interesse, como troca do SKU contido nela.
- Não é possível retirar um SKU, caso ele seja o único contido em uma assinatura.
- Caso você queira alterar um item de uma assinatura, isso precisa feito através da API Edit items on a subscription ou adicionando um item por meio da API Add item to subscription para só então remover o item desejado por meio da API Remove items from a subscription. Cabe mais uma vez ressaltar aqui, que essas alterações não podem ser feitas em assinaturas que tenham “
status: CANCELED”.
Caso ainda tenha alguma dúvida sobre o assunto, sinta-se à vontade para perguntar por aqui! 
Karina Mota
Field Software Engineer | VTEX