Referência da API: assinaturas

Cobrança recorrente — uma extensão sobre o Crypto Bot. Você cria um plano (valor + período), manda aos usuários o link de aprovação dele, e a plataforma cobra dessas pessoas, com o saldo da carteira delas, a cada período, creditando o saldo do seu app já líquido de taxa. As convenções estão na página da referência da API para comerciantes.

O modelo

Um plano é um conjunto de condições fixas: o mandato que o usuário aprova é exatamente este valor por este período. Para mudar o preço, crie um plano novo e arquive o antigo — quem já assina continua renovando nos termos que aprovou. O primeiro período é cobrado na aprovação.

As renovações são cobradas automaticamente no fim de cada período. Quando uma renovação falha (saldo insuficiente, conta restrita), a assinatura entra em grace e a plataforma tenta de novo a cada hora dentro do período de carência (a duração é definida pela plataforma); se ainda assim não conseguir cobrar, a assinatura vira expired. Os comerciantes leem o current_period_end como o prazo do acesso. Se a renovação é cobrada durante grace, o próximo período começa no current_period_end anterior, e não no momento do pagamento.

Os eventos do ciclo de vida têm webhooks opcionais: subscription_activated, subscription_charged, subscription_cancelled, subscription_expired. A entrada em grace não tem webhook (o assinante recebe uma mensagem no Telegram); se precisar, consulte getSubscriptions com status=grace. Se o seu app for excluído, as assinaturas dele são canceladas na renovação seguinte com cancelled_by: "merchant".

createSubscriptionPlan

POST /pay/api/createSubscriptionPlan — escopo subscriptions.

Parâmetro	Tipo	Obrigatório	O que significa
name	string	sim	de 1 a 64 caracteres, mostrado a quem assina
asset	string	sim	código do ativo
amount	string	sim	a cobrança por período, string decimal positiva
period_days	integer	sim	período de cobrança em dias, do mínimo da plataforma (informado em invalid_period quando o período é curto demais) até 365

O resultado é o objeto de plano: plan_id, name, asset, amount, amount_minor, period_days, archived, mini_app_subscribe_url — o link t.me que você manda para os usuários aprovarem — e created_at.

Erros: 400 unknown_asset, 400 invalid_amount, 409 invalid_period (período menor que o mínimo da plataforma), 400 invalid_request (period_days ausente, não positivo ou acima de 365; também se faltar name, asset ou amount), 503 subs_disabled (recurso indisponível) e 409 too_many_plans (no máximo 50 planos não arquivados — arquive um plano sem uso antes de criar outro).

getSubscriptionPlans

GET /pay/api/getSubscriptionPlans — escopo read, sem parâmetros. Devolve {"items": [plan, …]}, dos mais novos para os mais antigos, cada um com um campo a mais: active_subscribers — a contagem de assinaturas vigentes (active + grace) naquele plano.

archiveSubscriptionPlan

POST /pay/api/archiveSubscriptionPlan — escopo subscriptions. Um parâmetro: plan_id. Interrompe as novas aprovações; as assinaturas existentes continuam renovando pelas condições aprovadas (encerre uma a uma com cancelSubscription). Arquivar não pode ser desfeito pela API. O resultado é o objeto de plano atualizado, com archived: true. Erro: 404 plan_not_found.

getSubscriptions

GET /pay/api/getSubscriptions — escopo read. Filtros: plan_id, user_id, status (active / grace / cancelled / expired), além de offset / count (padrão 100, máx. 500). Devolve {"items": [subscription, …]}, das mais novas para as mais antigas.

O objeto de assinatura: subscription_id, plan_id, user_id (o id do Telegram de quem assina), as condições aprovadas (asset, amount, amount_minor, period_days), status, auto_renew, period_no (períodos pagos até agora), current_period_start / current_period_end, created_at, cancelled_at, cancelled_by (user ou merchant), expired_at.

cancelSubscription

POST /pay/api/cancelSubscription — escopo subscriptions. Um parâmetro: subscription_id. Interrompe as renovações (cancelled_by: "merchant"); o período pago continua utilizável até o current_period_end, o status muda para cancelled na hora, e quem assina é avisado. Quem teve a assinatura cancelada pode aprovar novamente pelo mesmo link enquanto o plano e o app estiverem disponíveis. A nova aprovação cobra imediatamente e inicia outro período. O resultado é o objeto de assinatura atualizado.

Erros: 404 sub_not_found, 409 sub_not_active (já cancelada ou expirada).