Assinaturas e compras programadas

Algumas compras se repetem: o café que chega todo mês, a ração a cada 30 dias, o insumo toda semana. A plataforma tem dois modelos para isso, e estas rotas do administrador da loja cuidam dos dois:

• Assinatura (subscription): o cliente autoriza uma cobrança recorrente de um produto, a cada N dias, no cartão que deixou guardado. Cada ciclo é uma cobrança.
• Compra programada (scheduled purchase): o cliente agenda a reposição de um produto numa frequência (semanal, mensal...) e ganha um desconto por frequência. Cada data gera um pedido de verdade.

Uma rotina em segundo plano (o worker de ciclo) cobra o que venceu, cria os pedidos e tenta de novo quando a cobrança falha. Aqui você enxerga tudo, age sobre cada item e define as regras.

Como funciona

O ciclo de uma assinatura ou compra programada

Um item active com retry_count maior que zero teve uma cobrança que falhou e está em nova tentativa (inadimplente): ele continua active até as tentativas acabarem.

Novas tentativas de cobrança

Quando uma cobrança falha (cartão recusado, por exemplo), o item não é cancelado: o worker tenta de novo uma vez por dia, até o limite de tentativas da loja (3 por padrão, configurável de 1 a 10 no módulo). Esgotado o limite, o item vira suspended. Um administrador pode então pedir uma nova tentativa à mão, que dá exatamente mais uma chance (veja Assinaturas). Enquanto há falha, retry_count mostra quantas tentativas já falharam e last_charge_error traz o motivo.

Frequências e descontos

A compra programada tem um desconto por frequência. As frequências são fixas:

O desconto de cada chave é uma porcentagem inteira de 0 a 99. Quem decide o desconto é uma cascata: o que estiver configurado no produto vale primeiro, depois a categoria, depois o seller (veja Regras de desconto).

Termos de aceite

Para assinar, o cliente aceita um termo (texto legal). A plataforma guarda quem aceitou, qual versão, quando, de que IP e um resumo (hash) do texto aceito. Editar um termo cria uma nova versão; as aceitações antigas continuam apontando para a versão que o cliente de fato viu.

Endpoints

Erros comuns

1. Usar o UUID puro no caminho. As rotas de assinatura e compra programada recebem a referência com prefixo (sub:..., sch:..., app:...). Um UUID sem prefixo devolve 404 not found.
2. Misturar os tipos. Uma referência sub: numa rota de compra programada (e o contrário) devolve 404.
3. Agir no estado errado. Pausar uma pausada, retomar uma ativa ou mexer numa cancelada devolve 409 action not allowed in the current status.
4. Pedir nova tentativa num item saudável. A nova tentativa só vale para item active ou suspended que já teve uma falha de cobrança (retry_count maior que zero); senão volta 409.
5. Pular entrega de assinatura. Só compras programadas têm skip; numa assinatura a ação não existe.
6. Esperar que cancelar estorne. Cancelar só impede cobranças futuras; não devolve nada já cobrado.
7. Configurar produto como assinatura e compra programada ao mesmo tempo. A regra de desconto custom do produto é recusada com 422 mutually_exclusive se o produto já é assinatura.

Próximos passos