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