مرجع API: اشتراکها
صورتحساب دورهای — افزودهای بر Crypto Bot. یک طرح میسازید (مبلغ + دوره)، لینک تأیید آن را برای کاربران میفرستید و پلتفرم هر دوره مبلغ را از موجودی کیف پولشان کسر میکند و پس از کسر کارمزد به موجودی برنامهی شما میافزاید. قراردادهای مشترک در صفحهی مرجع API پذیرنده آمده است.
مدل کار
هر طرح شرایطی ثبتشده و تغییرناپذیر است: اجازهای که کاربر میدهد دقیقاً همین مبلغ برای همین دوره است. برای تغییر قیمت، طرح جدیدی بسازید و قبلی را بایگانی کنید — مشترکان فعلی با همان شرایطی که تأیید کردهاند تمدید میشوند. مبلغ دورهی اول در لحظهی تأیید کسر میشود.
در پایان هر دوره، مبلغ تمدید بهطور خودکار کسر میشود. اگر تمدید ناموفق باشد
(موجودی کافی نیست، حساب محدود شده است)، اشتراک به وضعیت grace میرود و پلتفرم
در همان مهلت (فعلاً 48 ساعت) هر ساعت دوباره تلاش میکند؛ اگر باز هم موفق به کسر
نشود، اشتراک expired میشود. پذیرندهها current_period_end را بهعنوان مهلت
دسترسی در نظر میگیرند.
هر رویداد چرخهی عمر یک وبهوک اختیاری دارد:
subscription_activated، subscription_charged، subscription_cancelled،
subscription_expired.
createSubscriptionPlan
POST /pay/api/createSubscriptionPlan — دامنهی subscriptions.
| پارامتر | نوع | اجباری | معنی |
|---|---|---|---|
name | رشته | بله | 1 تا 64 نویسه، که به مشترک نشان داده میشود |
asset | رشته | بله | کد دارایی |
amount | رشته | بله | مبلغ هر دوره، رشتهی اعشاری مثبت |
period_days | عدد صحیح | بله | دورهی صورتحساب برحسب روز، از حداقل پلتفرم (فعلاً 7) تا 365 |
نتیجه، شیء طرح است: plan_id، name، asset، amount، amount_minor،
period_days، archived، mini_app_subscribe_url — همان لینک t.me که برای
تأیید به کاربران میفرستید — و created_at.
خطاها: 404 unknown_asset، 400 invalid_amount، 409 invalid_period،
503 subs_disabled (این قابلیت سمت پلتفرم غیرفعال است).
getSubscriptionPlans
GET /pay/api/getSubscriptionPlans — دامنهی read، بدون پارامتر.
{"items": [plan, …]} را به ترتیب از جدیدترین برمیگرداند، هرکدام با یک فیلد اضافه:
active_subscribers — تعداد اشتراکهای جاری (active + grace) روی آن طرح.
archiveSubscriptionPlan
POST /pay/api/archiveSubscriptionPlan — دامنهی subscriptions. یک پارامتر:
plan_id. جلوی تأییدهای جدید را میگیرد؛ اشتراکهای موجود با همان شرایط
ثبتشدهشان تمدید میشوند (اگر میخواهید به آنها پایان دهید، یکییکی با
cancelSubscription آنها را لغو کنید). بایگانی از طریق API برگشتپذیر نیست. نتیجه،
شیء بهروزشدهی طرح است با archived: true. خطا: 404 plan_not_found.
getSubscriptions
GET /pay/api/getSubscriptions — دامنهی read. فیلترها: plan_id، user_id،
status (active / grace / cancelled / expired)، بهعلاوهی offset /
count (حداکثر 500). خروجی {"items": [subscription, …]} است، به ترتیب از جدیدترین.
شیء اشتراک: subscription_id، plan_id، user_id (شناسهی تلگرامِ مشترک)،
شرایط ثبتشده (asset، amount، amount_minor، period_days)، status،
auto_renew، period_no (تعداد دورههای پرداختشده تاکنون)،
current_period_start / current_period_end، created_at، cancelled_at،
cancelled_by (user یا merchant)، expired_at.
cancelSubscription
POST /pay/api/cancelSubscription — دامنهی subscriptions. یک پارامتر:
subscription_id. تمدید را متوقف میکند (cancelled_by: "merchant")؛ دورهی
پرداختشده تا current_period_end قابل استفاده میماند، وضعیت بیدرنگ به
cancelled میرود و به مشترک اطلاع داده میشود. مشترکی که لغو کرده میتواند
بعدها از همان لینک طرح دوباره تأیید کند. نتیجه، شیء بهروزشدهی اشتراک است.
خطاها: 404 sub_not_found، 409 sub_not_active (پیشتر لغو یا منقضی شده).
آیا این مطلب برای شما مفید بود؟
از بازخوردتان ممنونیم.