Assinaturas e compras programadas

Como oferecer, criar e cancelar assinaturas e compras programadas de um produto.

Produtos de consumo recorrente (café, ração, refil, higiene) vendem mais quando o cliente não precisa lembrar de comprar. A plataforma oferece duas formas: a assinatura, que cobra o cliente a cada ciclo, e a compra programada, uma recompra com desconto numa frequência escolhida. Esta seção cobre o lado do cliente: descobrir o que o produto aceita, criar e cancelar.

Como funciona

Assinatura x compra programada:

	Assinatura	Compra programada
Ideia	Pago e entregue a cada ciclo até cancelar	Recompra com desconto numa frequência
Termos	O cliente aceita os termos do produto	Sem termos
Rota de criação	`POST /recurring/subscriptions`	`POST /recurring/scheduled`
`mode` na oferta	`subscription`	`custom`, `allows` ou `mandatory`

O fluxo típico:

Perguntar o que o produto aceita
Oferta de recorrência. Se enabled for false, não mostre o botão.
Mostrar o preço com desconto e os termos
Aplique discounts[frequência] ao preço de tabela. Para assinatura, mostre os termos.
Criar
Assinar ou programar a compra, com o cliente logado.
Gerenciar
Liste e cancele quando o cliente pedir.

Tabela de frequências (cycle_days e nome do desconto):

`cycle_days`	Frequência
7	`semanal`
14 (ou 15)	`quinzenal`
30	`mensal`
60	`bimestral`
90	`trimestral`
120	`quadrimestral`
180	`semestral`
365	`anual`

Conceitos-chave

A regra em cascata

A oferta de um produto vem da primeira camada que a define: o produto, depois a categoria, depois o seller. Qualquer camada pode estar disabled, e então o produto não oferece recorrência. O campo source diz de qual camada veio.

Preço do ciclo

preço do ciclo = preço base x (100 - desconto) / 100, com o desconto da frequência. O preço base é o preço atual do produto.

Assinatura e cartão

A cobrança de cada ciclo usa um cartão salvo (carteira) ligado à assinatura. A rota de criação desta seção não envia cartão: card_last_four só aparece quando há um cartão vinculado.

Endpoints

Método e caminho	Para quê	Autenticação	Página
`GET /api/v1/storefront/recurring/config`	Diz se o produto aceita recorrência e com que descontos	Pública	Oferta de recorrência
`GET /api/v1/storefront/recurring/terms/{productId}`	Termos de assinatura vigentes de um produto	Pública	Oferta de recorrência
`GET /api/v1/storefront/recurring/subscriptions`	Lista as assinaturas do cliente	Token do cliente	Assinaturas
`POST /api/v1/storefront/recurring/subscriptions`	Cria uma assinatura	Token do cliente	Assinaturas
`POST /api/v1/storefront/recurring/subscriptions/{id}/cancel`	Cancela uma assinatura	Token do cliente	Assinaturas
`GET /api/v1/storefront/recurring/scheduled`	Lista as compras programadas do cliente	Token do cliente	Compras programadas
`POST /api/v1/storefront/recurring/scheduled`	Cria uma compra programada	Token do cliente	Compras programadas
`POST /api/v1/storefront/recurring/scheduled/{id}/cancel`	Cancela uma compra programada	Token do cliente	Compras programadas

Erros comuns

Próximos passos

Oferta de recorrência

O que o produto aceita e os termos.

Assinaturas

Assinar, listar e cancelar.

Compras programadas

Recompra com desconto.