الاشتراكات والدفع التلقائي

يمكن للمتجر أن يطلب من مستخدم Heth.me الموافقة على الدفعات المتكررة. يقوم الدافع بمراجعة الشروط وتوقيعها باستخدام HethWallet العادية غير المؤمنة. ليست هناك حاجة إلى حساب بريد إلكتروني منفصل أو تسجيل الدخول إلى بوابة العملاء. يتم خصم الدفعات من رصيد حساب Heth بالعملة والشبكة المتفق عليهما.

للدافع

1. افتح الإعدادات → الاشتراكات والدفع التلقائي. تظهر الطلبات الجديدة بشكل منفصل عن الاشتراكات الموجودة.
2. افتح طلبًا وتحقق من المتجر ومبلغ الدفعة والعملة/الشبكة وفترة الفاتورة. يفتح رابط التأكيد نفس الشاشة. تطلب المحفظة المقفلة PIN المعتاد وتعود إلى الطلب.
3. اختر تفعيل الاشتراك أو رفض. لا يؤدي فتح رابط أو تلقي إشعار إلى الموافقة على الاشتراك مطلقًا.
4. بعد الموافقة يتم تحديد موعد الدفعة الأولى. تظهر القائمة المبلغ والمدة وتاريخ الدفع التالي. أثناء إعادة محاولة الدفع الفاشلة، فإنه يظهر وقت إعادة المحاولة التالي.
5. قم بإلغاء الاشتراك لإيقاف الرسوم المستقبلية. لا يؤدي الإلغاء إلى استرداد الدفعات المكتملة.

الموافقة تسجل الموافقة وتحدد موعد الدفع؛ وهذا لا يعني أن الدفع قد نجح. التحقق من حالة المعاملة. يجب أن يكون الرصيد كافيا عند تنفيذ الدفع.

كيفية الإعلان عن الطلبات الجديدة

بالنسبة للدافع المعترف به، يرسل الخادم دفعة لطلب الاشتراك إلى الأجهزة المسجلة، مع رابط إلى /subscriptions/confirm/<request_id>?env=<env>. يتم أيضًا حفظ الإدخال في جرس الإشعارات، حتى في حالة عدم تمكن أي جهاز من تلقي الدفع. تظل الطلبات المعلقة متاحة في الإعدادات → الاشتراكات والدفع التلقائي.

تستخدم تطبيقات PWA المثبتة دفع الويب. يستخدم Heth.me لنظامي التشغيل iOS وAndroid، بدءًا من الإصدار 1.0.0 (الإصدار 5)، إشعارات النظام. تمكين الإشعارات في المحفظة والسماح بها في إعدادات جهازك. يؤدي النقر على طلب الاشتراك إلى فتح شاشة التأكيد الخاصة به؛ تطلب المحفظة المقفلة أولاً PIN المعتاد أو مفتاح المرور المتاح. استلام أو فتح إشعار لا يعني الموافقة على الاشتراك. إذا لم يصل الإشعار، افتح قائمة الطلبات المعلقة أو رابط التأكيد من المتجر.

للمحل

في HethWallet، افتح الأعمال ← الاشتراكات والدفع التلقائي. أدخل عنوان محفظة الدافع أو رقم بطاقة @username أو Heth واسم الاشتراك والمبلغ لكل دفعة والعملة/الشبكة والفترة. أرسل الطلب، ثم انسخ رابط التأكيد الخاص به. يمكنك إدراج طلباتك وإلغاء الطلب وهو لا يزال معلقًا.

يجب على المشغل تمكين اشتراكات Heth للمؤسسة وتكوين مسار دفع فعال. إنشاء طلب لا يسمح بالخصم.

قم بإنشاء طلب عبر API

استخدم مفتاح API الخاص بالمتجر أو جلسة Bearer الشريكة العادية. في app.heth.me، يتم حل المؤسسة من المضيف. لا يمكن لمفتاح القراءة فقط إنشاء الطلبات أو إلغائها.

curl -X POST 'https://app.heth.me/api/v1/heth/subscription-requests' \
  -H "x-api-key: $HETH_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "request_id": "b56b2c66-4ae5-4cb9-92ea-7a3297b72b55",
    "payer": "@alice",
    "description": "Monthly membership",
    "amount": "1000000",
    "currency": "USDT",
    "network": "ETH",
    "interval": "monthly",
    "period": 1,
    "env": "prod"
  }'

المجال	الوصف	اكتب	مثال
request_id	فريدة من نوعها عاجزة UUID. أعد استخدامه بعبارات متطابقة عند إعادة محاولة نفس الطلب.	String	b56b2c66-4ae5-4cb9-92ea-7a3297b72b55
payer	عنوان المحفظة أو اسم المستخدم أو رقم بطاقة هيث.	String	@alice
description	اسم الاشتراك، أحرف 1–250 بدون فواصل الأسطر.	String	Monthly membership
amount	عدد صحيح موجب في الوحدات الثانوية الرمزية. بالنسبة إلى 6-decimal USDT، 1000000 تعني 1 USDT.	String	1000000
currency, network	تمكين زوج الرمز المميز/الشبكة للحساب. الشبكات: ETH، TRX، BASE.	String	USDT, ETH
interval	daily أو weekly أو monthly أو yearly.	String	monthly
period	عدد الفواصل الزمنية، 1–365؛ الافتراضي 1.	Number	1
env	prod (افتراضي). الحفاظ على هذه القيمة عند فتح الطلب وتأكيده.	String	prod

HTTP 201 تقوم بإرجاع الطلب مباشرة، بما في ذلك id وstatus وamount_decimals وconfirm_url وexpires_at وsubscription_id وnext_charge_at. تنتهي صلاحية الطلبات بعد سبعة أيام. لا يكشف الإنشاء الناجح ما إذا كان الدافع المقدم موجودًا أم لا؛ يمكن للمستلم الفعلي فقط قراءة الطلب والموافقة عليه.

عمليات API

جميع المسارات أدناه تبدأ بـ /api/v1. تتطلب عمليات المتجر مفتاح API الخاص بالمتجر أو جلسة حامل الشريك.

الطريقة والمسار	الغرض
POST /heth/subscription-requests	إنشاء طلب.
GET /heth/subscription-requests?env=prod&limit=50	قم بإدراج طلبات المتجر في data وtotal.
POST /heth/subscription-requests/:id/cancel	إلغاء الطلب المعلق؛ الجسم {"env":"prod"}.

للصفحة الأولى حذف page. استخدم page=1 للصفحة التالية، ثم قم بزيادتها؛ يتحكم limit في حجم الصفحة.

تتطلب عمليات المحفظة جلسة حامل المحفظة العادية للدافع. لا يمكن لمفتاح API الخاص بالمتجر الموافقة على الدافع.

الطريقة والمسار	الغرض
GET /heth/subscriptions?env=prod&limit=50	الاشتراكات الخاصة في data/total، الطلبات المعلقة في requests/requests_total.
GET /heth/subscription-requests/:id?env=prod	اقرأ الطلب الموجه والتوقيع الأساسي message.
POST /heth/subscription-requests/:id/confirm	الموافقة على {"signature":"<wallet signature>","env":"prod"} بعد مراجعة الشروط الدقيقة.
POST /heth/subscription-requests/:id/reject	يرفض؛ الجسم {"env":"prod"}.
POST /heth/subscriptions/:id/revoke-mandate	وقف الرسوم المستقبلية. الجسم {"env":"prod"}.

التوقيع يربط المحل، الدافع، المنظمة، الوصف، المبلغ وحجمه، العملة/الشبكة، الفاصل الزمني والفترة، قاعدة الدفعة الأولى، عدم النفاذ وانتهاء الصلاحية. يتطلب تغيير الشروط طلبًا جديدًا وموافقة جديدة. لا يمكن لإعادة محاولة الموافقة أو الدفع المجدول خصم الفترة نفسها مرتين. الطوابع الزمنية API بدون لاحقة المنطقة الزمنية هي UTC؛ يعرض التطبيق التوقيت المحلي للجهاز.

الحالات والأخطاء

حالات الطلب هي pending وsigned وrejected وexpired. الطلب المعتمد له subscription_id. تتبع إتمام الدفع الفعلي من خلال المعاملة API وخطافات الويب التي تم تكوينها.

401 تعني مصادقة مفقودة/غير صالحة؛ يعني 403 أن الاشتراكات معطلة أو أن مفتاح API للقراءة فقط. يقوم الطلب الذي يتعذر الوصول إليه بإرجاع 404. يشير 422 إلى مصطلحات غير صالحة، أو UUID مُعاد استخدامه بشروط مختلفة، أو توقيع غير صالح، أو طلب منتهي الصلاحية/مغلق. لا يمكن للمتجر تغيير الشروط الموقعة للاشتراك النشط دون موافقة الدافع الجديد.