Assinaturas e compras programadas

Vender de novo para o mesmo cliente, automaticamente, é o que a recorrência faz. A plataforma tem dois formatos: a assinatura (cobrança automática no cartão) e a compra programada (pedido repetido com desconto). Esta seção é o lado do seller (lojista): configurar, acompanhar e cancelar. Cria-se a assinatura ou a compra pela loja, não por aqui.

Como funciona

1. O seller define a regra

   Em Configuração escolhe se oferece compra programada e com que descontos. Os termos de assinatura ficam em Termos.

2. O cliente adere

   Pela loja (lado do cliente), ele assina um produto ou programa uma compra. O aceite do termo é gravado.

3. A plataforma cobra a cada ciclo

   Assinaturas cobram o cartão salvo. Compras programadas geram um pedido novo. Se uma cobrança falha, a assinatura vira past_due, é tentada de novo e, esgotadas as tentativas, suspended.

4. O seller acompanha

   Pelo painel, pelas listas e pelo CSV. O seller pode cancelar.

Conceitos-chave

Assinatura versus compra programada

Assinatura: o cliente salva um cartão e a plataforma cobra o valor a cada ciclo até ele cancelar. Compra programada: o cliente agenda a repetição de um pedido, com desconto por frequência; a cada data nasce um pedido comum. Um produto não pode ser os dois ao mesmo tempo.

Camadas de regra

Para compra programada, o desconto vem do produto, senão da categoria, senão do seller. disabled em qualquer nível desliga; custom define descontos próprios; inherit passa para o nível de cima. As frequências são semanal, quinzenal, mensal, bimestral, trimestral, quadrimestral, semestral e anual.

O que o seller pode fazer

Só ver o que é dos produtos dele e cancelar. Pausar, retomar, pular entrega e repetir cobrança são ações da loja e não existem na API do seller. O texto de erro do gateway também é ocultado.

Referências

Os registros de assinatura e compra programada têm id com prefixo: sub:<uuid>, sch:<uuid>, app:<número>. Passe-o inteiro nas rotas de detalhe e cancelamento.

Dinheiro e datas

Valores em centavos inteiros (e uma cópia formatada R$ 49,90). Datas de agenda em YYYY-MM-DD; instantes em RFC 3339 UTC.

Endpoints

Erros comuns

• Esperar dados com o módulo recurring-payments desligado: toda rota recurring/* responde 403 module_disabled.
• Usar só o UUID de um registro no caminho. É preciso o id com prefixo (sub:...).
• Chamar a rota de assinaturas com um sch: (ou o contrário): volta 404 not found.
• Tentar pausar ou repetir cobrança como seller. Só cancel é permitido.
• Ler GET /recurring/config e achar que a regra está em vigor sem nunca ter feito PUT.
• Somar compras programadas no painel: ele conta apenas assinaturas.
• Confundir /vendor/recurring/subscriptions com /vendor/subscriptions. São dois sistemas e dois conjuntos de dados.

Próximos passos