API maʼlumotnomasi: obunalar

Muntazam toʻlovlar — Crypto Bot ustidagi kengaytma. Siz tarif yaratasiz (summa + davr), foydalanuvchilarga uni tasdiqlash havolasini yuborasiz, platforma esa har davrda ularning hamyon balansidan pulni yechib, komissiya chegirilgan holda ilova balansingizga oʻtkazadi. Umumiy qoidalar — Merchant API maʼlumotnomasi sahifasida.

Model

Tarif — bu oʻzgarmas snapshot: foydalanuvchi aynan shu davr uchun aynan shu summaga rozi boʻladi. Narxni oʻzgartirish uchun yangi tarif yarating va eskisini arxivlang — mavjud obunachilar oʻzlari tasdiqlagan shartlar boʻyicha uzaytirilaveradi. Birinchi davr tasdiqlash paytida yechiladi.

Uzaytirishlar har davr oxirida avtomatik hisoblanadi. Uzaytirish oʻtmasa (balans yetarli emas, hisob cheklangan), obuna grace holatiga oʻtadi va platforma imtiyoz davri ichida (hozircha 48 soat) har soatda qayta urinadi; baribir yecha olmasa, obuna expired boʻladi. Sotuvchi kirish muddatini current_period_end maydonidan oʻqiydi.

Har bir hayotiy sikl hodisasining ixtiyoriy ravishda yoqiladigan webhooki bor: subscription_activated, subscription_charged, subscription_cancelled, subscription_expired.

createSubscriptionPlan

POST /pay/api/createSubscriptionPlan — subscriptions huquqi.

Parametr	Turi	Majburiy	Maʼnosi
name	string	ha	1–64 belgi, obunachiga koʻrsatiladi
asset	string	ha	aktiv kodi
amount	string	ha	har bir davr uchun yechiladigan summa, musbat oʻnlik satr
period_days	integer	ha	hisob-kitob davri kunlarda, platforma minimumidan (hozircha 7) 365 gacha

Natija — tarif obyekti: plan_id, name, asset, amount, amount_minor, period_days, archived, mini_app_subscribe_url — foydalanuvchilarga tasdiqlash uchun yuboradigan t.me havolasi — va created_at.

Xatolar: 404 unknown_asset, 400 invalid_amount, 409 invalid_period, 503 subs_disabled (funksiya platforma tomonida oʻchirilgan).

getSubscriptionPlans

GET /pay/api/getSubscriptionPlans — read huquqi, parametrsiz. {"items": [plan, …]} qaytaradi, yangilari birinchi; har birida bitta qoʻshimcha maydon boʻladi: active_subscribers — tarifdagi amaldagi (active + grace) obunalar soni.

archiveSubscriptionPlan

POST /pay/api/archiveSubscriptionPlan — subscriptions huquqi. Bitta parametr: plan_id. Yangi tasdiqlashlarni toʻxtatadi; mavjud obunalar oʻz snapshoti boʻyicha uzaytirilaveradi (ularni cancelSubscription bilan bittalab tugatasiz). Arxivlashni API orqali orqaga qaytarib boʻlmaydi. Natija — archived: true bilan yangilangan tarif obyekti. Xato: 404 plan_not_found.

getSubscriptions

GET /pay/api/getSubscriptions — read huquqi. Filtrlar: plan_id, user_id, status (active / grace / cancelled / expired), hamda offset / count (maksimum 500). {"items": [subscription, …]} qaytaradi, yangilari birinchi.

Obuna obyekti: subscription_id, plan_id, user_id (obunachining Telegram ID raqami), snapshot shartlari (asset, amount, amount_minor, period_days), status, auto_renew, period_no (hozirgacha toʻlangan davrlar), current_period_start / current_period_end, created_at, cancelled_at, cancelled_by (user yoki merchant), expired_at.

cancelSubscription

POST /pay/api/cancelSubscription — subscriptions huquqi. Bitta parametr: subscription_id. Uzaytirishlarni toʻxtatadi (cancelled_by: "merchant"); toʻlangan davr current_period_end sanasigacha ishlatilaveradi, holat esa darhol cancelled holatiga oʻtadi va obunachiga xabar beriladi. Bekor qilingan obunachi keyinchalik xuddi shu tarif havolasi orqali qayta tasdiqlashi mumkin. Natija — yangilangan obuna obyekti.

Xatolar: 404 sub_not_found, 409 sub_not_active (allaqachon bekor qilingan yoki muddati tugagan).