مرجع الواجهة: الاشتراكات
تحصيل دوري — وهو امتداد يتجاوز عقد Crypto Bot. تنشئ خطة (مبلغ + فترة)، وترسل إلى المستخدمين رابط الموافقة عليها، فتخصم المنصة المبلغ من رصيد محافظهم في كل فترة، وتضيف إلى رصيد تطبيقك المبلغ بعد خصم الرسوم. والقواعد المشتركة تجدها في صفحة مرجع واجهة التجار.
النموذج
الخطة شروط مثبَّتة لا تتغير: فالتفويض الذي يوافق عليه المستخدم هو هذا المبلغ بالضبط عن هذه الفترة بالضبط. ولتغيير السعر أنشئ خطة جديدة وأرشِف القديمة — فيستمر المشتركون الحاليون في التجديد بالشروط التي وافقوا عليها. وتُحصَّل الفترة الأولى عند الموافقة.
ويجري التجديد تلقائيًا في نهاية كل فترة. وإذا فشل التجديد (رصيد غير كافٍ، أو
حساب مقيَّد) يدخل الاشتراك في 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). ولا يمكن
التراجع عن الأرشفة عبر الواجهة. والنتيجة هي كائن الخطة بعد تحديثه ومعه 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 (ملغى أو منتهٍ من قبل).
هل كان هذا المقال مفيدًا؟
شكرًا على ملاحظتك.