مرجع API: اشتراک‌ها

صورت‌حساب دوره‌ای — افزوده‌ای بر Crypto Bot. یک طرح می‌سازید (مبلغ + دوره)، لینک تأیید آن را برای کاربران می‌فرستید و پلتفرم هر دوره مبلغ را از موجودی کیف پولشان کسر می‌کند و پس از کسر کارمزد به موجودی برنامه‌ی شما می‌افزاید. قراردادهای مشترک در صفحه‌ی مرجع API پذیرنده آمده است.

مدل کار

هر طرح شرایطی ثبت‌شده و تغییرناپذیر است: اجازه‌ای که کاربر می‌دهد دقیقاً همین مبلغ برای همین دوره است. برای تغییر قیمت، طرح جدیدی بسازید و قبلی را بایگانی کنید — مشترکان فعلی با همان شرایطی که تأیید کرده‌اند تمدید می‌شوند. مبلغ دوره‌ی اول در لحظه‌ی تأیید کسر می‌شود.

در پایان هر دوره، مبلغ تمدید به‌طور خودکار کسر می‌شود. اگر تمدید ناموفق باشد (موجودی کافی نیست، حساب محدود شده است)، اشتراک به وضعیت grace می‌رود و پلتفرم در همان مهلت (با مدت تعیین‌شده توسط پلتفرم) هر ساعت دوباره تلاش می‌کند؛ اگر باز هم موفق به کسر نشود، اشتراک expired می‌شود. پذیرنده‌ها current_period_end را به‌عنوان مهلت دسترسی در نظر می‌گیرند. اگر مبلغ تمدید در طول grace کسر شود، دوره‌ی بعد از همان current_period_end قبلی شروع می‌شود، نه از زمان پرداخت.

رویدادهای چرخه‌ی عمر وب‌هوکهای اختیاری دارند: subscription_activated، subscription_charged، subscription_cancelled، subscription_expired. ورود به grace وب‌هوک ندارد (مشترک در تلگرام پیام می‌گیرد)؛ اگر لازم دارید، getSubscriptions را با status=grace به‌طور منظم بررسی کنید. اگر برنامه‌ی شما حذف شود، اشتراک‌های آن در تمدید بعدی با cancelled_by: "merchant" لغو می‌شوند.

createSubscriptionPlan

POST /pay/api/createSubscriptionPlan — دامنه‌ی subscriptions.

پارامتر	نوع	اجباری	معنی
name	رشته	بله	1 تا 64 نویسه، که به مشترک نشان داده می‌شود
asset	رشته	بله	کد دارایی
amount	رشته	بله	مبلغ هر دوره، رشته‌ی اعشاری مثبت
period_days	عدد صحیح	بله	دوره‌ی صورت‌حساب برحسب روز، از حداقل پلتفرم (اگر دوره کوتاه‌تر باشد با invalid_period اعلام می‌شود) تا 365

نتیجه، شیء طرح است: plan_id، name، asset، amount، amount_minor، period_days، archived، mini_app_subscribe_url — همان لینک t.me که برای تأیید به کاربران می‌فرستید — و created_at.

خطاها: 400 unknown_asset، 400 invalid_amount، 409 invalid_period (دوره کوتاه‌تر از حداقل پلتفرم)، 400 invalid_request (نبودن period_days، مثبت نبودن آن یا بیشتر بودن از 365؛ همچنین نبودن name، asset یا amount)، 503 subs_disabled (قابلیت در دسترس نیست) و 409 too_many_plans (حداکثر 50 طرح بایگانی‌نشده — پیش از ساخت طرح جدید، یک طرح بدون استفاده را بایگانی کنید).

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 (پیش‌فرض 100، حداکثر 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 (پیش‌تر لغو یا منقضی شده).