Riferimento API: abbonamenti

Fatturazione ricorrente: un’estensione rispetto a Crypto Bot. Crei un piano (importo + periodo), mandi agli utenti il suo link di approvazione, e la piattaforma addebita la quota sul loro saldo a ogni periodo, accreditando l’importo sul saldo della tua app al netto della commissione. Le convenzioni comuni sono descritte nella pagina Riferimento della Merchant API.

Come è fatto

Un piano è immutabile: il mandato che l’utente approva è esattamente questo importo per questo periodo. Per cambiare il prezzo crei un piano nuovo e archivi il vecchio; chi è già abbonato continua a rinnovare alle condizioni che aveva approvato. Il primo periodo si addebita all’approvazione.

I rinnovi vengono addebitati automaticamente alla fine di ogni periodo. Quando un rinnovo non riesce (saldo insufficiente, account limitato), l’abbonamento entra in grace e la piattaforma riprova ogni ora entro il periodo di tolleranza (la durata è stabilita dalla piattaforma); se ancora non riesce a incassare, l’abbonamento diventa expired. Per l’esercente il termine dell’accesso è current_period_end.

Ogni evento del ciclo di vita ha un webhook facoltativo: subscription_activated, subscription_charged, subscription_cancelled, subscription_expired.

createSubscriptionPlan

POST /pay/api/createSubscriptionPlan — ambito subscriptions.

Parametro	Tipo	Obbligatorio	Descrizione
name	stringa	sì	da 1 a 64 caratteri, mostrato a chi si abbona
asset	stringa	sì	il codice dell’asset
amount	stringa	sì	l’addebito per periodo, stringa decimale positiva
period_days	intero	sì	il periodo di fatturazione in giorni, dal minimo della piattaforma (indicato da invalid_period se il periodo è troppo breve) a 365

Il risultato è l’oggetto piano: plan_id, name, asset, amount, amount_minor, period_days, archived, mini_app_subscribe_url — il link t.me che mandi agli utenti per l’approvazione — e created_at.

Errori: 400 unknown_asset, 400 invalid_amount, 409 invalid_period, 503 subs_disabled (la funzione non è disponibile) e 409 too_many_plans (archivia un piano inutilizzato prima di crearne un altro).

getSubscriptionPlans

GET /pay/api/getSubscriptionPlans — ambito read, nessun parametro. Restituisce {"items": [piano, …]}, dal più recente, ciascuno con un campo in più: active_subscribers, cioè il numero di abbonamenti in corso (active + grace) su quel piano.

archiveSubscriptionPlan

POST /pay/api/archiveSubscriptionPlan — ambito subscriptions. Un parametro solo: plan_id. Ferma le nuove approvazioni; gli abbonamenti esistenti continuano a rinnovarsi alle condizioni che avevano approvato (li chiudi uno a uno con cancelSubscription). L’archiviazione non si annulla dall’API. Il risultato è l’oggetto piano aggiornato, con archived: true. Errore: 404 plan_not_found.

getSubscriptions

GET /pay/api/getSubscriptions — ambito read. Filtri: plan_id, user_id, status (active / grace / cancelled / expired), più offset / count (al massimo 500). Restituisce {"items": [abbonamento, …]}, dal più recente.

L’oggetto abbonamento: subscription_id, plan_id, user_id (l’ID Telegram di chi si è abbonato), le condizioni approvate (asset, amount, amount_minor, period_days), status, auto_renew, period_no (i periodi pagati finora), current_period_start / current_period_end, created_at, cancelled_at, cancelled_by (user oppure merchant), expired_at.

cancelSubscription

POST /pay/api/cancelSubscription — ambito subscriptions. Un parametro solo: subscription_id. Ferma i rinnovi (cancelled_by: "merchant"); il periodo pagato resta utilizzabile fino a current_period_end, lo stato passa subito a cancelled e chi era abbonato viene avvisato. Chi ha disdetto può approvare di nuovo l’abbonamento dallo stesso link, finché il piano e l’app sono disponibili. La nuova approvazione comporta un addebito immediato e avvia un nuovo periodo. Il risultato è l’oggetto abbonamento aggiornato.

Errori: 404 sub_not_found, 409 sub_not_active (già disdetto o già scaduto).