مدفوعات العملات المشفرة لـ 3x-ui
خدمة صغيرة تستضيفها بنفسك تتيح للوحة 3x-ui قبول المدفوعات بالعملات المشفرة عبر SnapEX Pay. يطلب منها بوت Telegram أو موقعك رابط دفع، فيدفع العميل بـ USDT على صفحة SnapEX Pay، وعند دفع الفاتورة تُضيف الخدمة client إلى الـ inbound لديك، أو تُمدّد الحالي، وتُعيد رابط الاشتراك. لا تتضمن 3x-ui نفسها نظام فوترة، لذا فهذه هي طبقة الدفع بين متجرك واللوحة.
مجانًا. الإصدار 1.1.0.
ماذا تفعل الوحدة
- لكل طلب فاتورة SnapEX Pay خاصة به و
pay_urlخاص به. يدفع العملاء بـ USDT على TRC20 أو ERC20 أو BEP20؛ وقد تظهر عملات أخرى على صفحة الدفع حين يتمكن SnapEX Pay من إتاحتها. - اسم المستخدم الجديد يصبح client جديدًا على
XUI_INBOUND_ID. أما الحالي فيُجدَّد: يُؤجَّل تاريخ الانتهاء (أو يُحتسب من الآن إذا كان قد انتهى؛ ويبقى الـ client الذي لا تاريخ انتهاء له بلا حدود)، ويُعاد تفعيل الـ client، ويُصفَّر الترافيك في الباقات ذات الحصة. يبقى UUID وsubIdكما هما، فيستمر إعداد العميل في العمل. - تعمل مع 3x-ui 2.x و3.x: تستخدم API الجديد
/panel/api/clientsحيث تدعمه اللوحة، وإلا فـ API الأقدمinbounds/addClient. - إشعارات Webhook آمنة: توقيعات HMAC-SHA256 مع نافذة مدتها 5 دقائق، وتُقرأ حالة الفاتورة دائمًا من جديد من API SnapEX Pay، وتُنفَّذ كل فاتورة مرة واحدة فقط.
- الباقات (الأيام، والسعر بالدولار، وحصة الترافيك) في متغير بيئة واحد. حاوية واحدة: FastAPI وSQLite.
التثبيت
- في لوحة تحكم التاجر في SnapEX Pay أنشئ مفتاح API بالصلاحيتين
invoices.readوinvoices.write. - نزّل الأرشيف وفُكّ ضغطه، ثم نفّذ في مجلده
cp .env.example .envواملأSNAPEX_API_KEYوAPI_TOKENوXUI_URL(مع المسار الأساسي للويب web base path) وXUI_USERNAMEوXUI_PASSWORDوXUI_INBOUND_IDوXUI_SUB_URL. - شغّل الخدمة:
docker compose up -d، ثم تحقّق عبرcurl http://localhost:8080/health. - ضع الخدمة خلف HTTPS (nginx أو Caddy أو Traefik). في لوحة التحكم ← للمطورين اضبط عنوان Webhook على
https://<your service>/webhook، وضع سر التوقيعwhsec_…(يظهر مرة واحدة فقط، عند حفظ العنوان أول مرة) فيSNAPEX_WEBHOOK_SECRET، ثم نفّذdocker compose up -dمرة أخرى. - من البوت أو الخادم الخلفي استدعِ
POST /v1/checkoutمعAuthorization: Bearer <API_TOKEN>، وأرسلpay_urlإلى العميل، وتحقّق منGET /v1/orders/{invoice_id}للحصول على رابط الاشتراك.
الإعدادات
| SNAPEX_API_KEY, SNAPEX_WEBHOOK_SECRET | مفتاح API التاجر (invoices.read، invoices.write) وسر توقيع Webhook (whsec_…). |
|---|---|
| SNAPEX_ENVIRONMENT, SNAPEX_FEE_ON | فواتير live أو test؛ ومن يدفع عمولة الخدمة — merchant أو customer. |
| API_TOKEN | رمز Bearer لـ /v1/checkout و/v1/orders. |
| XUI_URL | عنوان اللوحة مع المسار الأساسي للويب، مثل https://xui.example.com:2053/secretpath. |
| XUI_API_TOKEN | لـ 3x-ui 3.x فقط: رمز API للوحة يُستخدم بدلًا من اسم المستخدم وكلمة المرور (للوحات التي تتطلب تسجيل الدخول بخطوتين). |
| XUI_INBOUND_ID, XUI_SUB_URL | الـ inbound للعملاء الجدد (VLESS أو VMess أو Trojan أو Shadowsocks أو Hysteria) وبادئة رابط الاشتراك. |
| PLANS | قيم id:days:usd:traffic_bytes مفصولة بفواصل، و0 بايت = بلا حدود. |
| SNAPEX_PARTNER_ID | اختياري: Partner ID للمُدمِج الذي أعدّ الوحدة (برنامج الإحالة في SnapEX Pay). اتركه فارغًا إذا أعددتها بنفسك. |
أسئلة
ما إصدارات 3x-ui المدعومة؟
3x-ui 2.x و3.x: كلٌّ من API الجديد /panel/api/clients وAPI الأقدم inbounds/addClient.
ماذا يحدث عندما يجدّد العميل اشتراكه؟
أرسل اسم المستخدم نفسه مرة أخرى. يحتفظ الـ client بـ UUID وsubId نفسيهما، ويُؤجَّل تاريخ الانتهاء، ويُعاد تفعيل الـ client، ويُصفَّر الترافيك في الباقات ذات الحصة.
لوحتي تتطلب تسجيل الدخول بخطوتين. هل ستعمل؟
على 3x-ui 3.x نعم: اضبط XUI_API_TOKEN (رمز API للوحة) بدلًا من اسم المستخدم وكلمة المرور.
هل يمكن تنفيذ دفعة واحدة مرتين؟
لا. تُنفَّذ كل فاتورة مرة واحدة فقط، حتى لو وصل إشعار Webhook مرتين أو وصلت نسختان منه في اللحظة نفسها.
هل يوجد بوت Telegram جاهز؟
نعم، بوت Telegram مستقل من SnapEX Pay لـ Marzban و3x-ui وRemnawave. أما هذه الخدمة فتناسبك إذا كان لديك بوت أو موقع خاص بك بالفعل.
هل أنت مستعد لقبول العملات المشفرة؟
أنشئ حساب تاجر، واحصل على مفتاح API، ثم اربط الوحدة. عمولة 1% على كل دفعة، دون رسوم شهرية.