بيع اشتراكات VPN عبر بوت Telegram مقابل USDT: الإعداد خطوة بخطوة

تبيع خدمات VPN كثيرة عبر Telegram: العميل موجود في المحادثة أصلًا، فالأولى أن يتم الشراء هناك أيضًا. يشرح هذا الدليل كيف تشغّل بوتًا جاهزًا على خادمك: يختار العميل باقة، ويدفع بـ USDT على شبكة TRC20 أو ERC20 أو BEP20 أو بعملة أخرى، فيُنشئ البوت المستخدم أو يمدّد اشتراكه في لوحة Marzban أو 3x-ui أو Remnawave الخاصة بك، ويرسل رابط الاشتراك إلى المحادثة نفسها. لا تحتاج إلى إدارة محفظة أو عقدة بلوكتشين: تصل الأموال إلى رصيد التاجر الخاص بك في SnapEX Pay.

كيف تتم عملية البيع

customer → /start → taps a plan
bot → SnapEX Pay: invoice → "Pay" button
customer → pays on the SnapEX Pay page
SnapEX Pay → signed webhook → bot
bot → GET invoice from the API → paid?
bot → panel: create or extend user
bot → customer: subscription link

1. يعرض الأمر /start باقاتك على شكل أزرار. كل ضغطة تُنشئ فاتورة في SnapEX Pay، ويردّ البوت بزر Pay («ادفع»).
2. يختار العميل عملة في صفحة الدفع ويدفع. وعندما تُدفع الفاتورة، يرسل SnapEX Pay إلى البوت إشعار Webhook موقّعًا.
3. يتحقق البوت من التوقيع، ويستعلم عن الفاتورة عبر API في SnapEX Pay، ولا يُجهِّز المستخدم إلا إذا كانت حالتها هناك paid وكانت الفاتورة تخص طلبًا أنشأه البوت نفسه.

اسم المستخدم في اللوحة هو tg<telegram_id>، لذلك يقابل كل حساب Telegram مستخدم VPN واحدًا بالضبط.

ما تحتاج إليه

• رمز البوت من @BotFather.
• صلاحيات مشرف في لوحة Marzban أو 3x-ui ‏(MHSanaei) أو Remnawave ‏(⁦2.x⁩ أو ⁦3.x⁩). بدون لوحة يقتصر عمل البوت على قبول المدفوعات (PANEL_TYPE=none)، وتتولى أنت تسليم بيانات الوصول.
• خادم عليه Docker Compose (أو ⁦Python 3.12⁩).
• عنوان عام عبر HTTPS لإشعارات Webhook: لا يرسل SnapEX Pay إشعارات Webhook إلا إلى عناوين https://.
• حساب تاجر في SnapEX Pay: أنشئ حسابك على pay.snapex.pro.

يعمل البوت بأسلوب long polling، لذلك لا يحتاج Telegram إلى أي منفذ مفتوح على خادمك؛ يكفي أن يكون منفذ Webhook خلف HTTPS متاحًا من الخارج.

الخطوة 1. نزّل البوت

نزّل الأرشيف snapexpay-telegram-vpn-bot-1.1.0.zip (رخصة MIT، مجاني) وأنشئ ملف الإعدادات:

curl -fsSLO https://pay.snapex.pro/downloads/telegram-vpn-bot/snapexpay-telegram-vpn-bot-1.1.0.zip
unzip snapexpay-telegram-vpn-bot-1.1.0.zip
cd snapexpay-telegram-vpn-bot-1.1.0
cp .env.example .env

كل الإعدادات موجودة في .env. ضع رمز البوت في TELEGRAM_BOT_TOKEN واسم متجرك في SHOP_NAME، فهو يظهر في رسالة /start وفي وصف الفاتورة.

الخطوة 2. احصل على مفتاح API

افتح في لوحة تحكم التاجر في SnapEX Pay صفحة للمطورين وأنشئ مفتاح API. يظهر المفتاح مرة واحدة فقط، فانسخه فورًا إلى SNAPEX_API_KEY. المفتاح الذي تُنشئه في لوحة التحكم يحصل على كل صلاحيات API التاجر، ومنها invoices.read وinvoices.write اللتان يحتاج إليهما البوت. إصدار مفتاح جديد يُلغي القديم فورًا، لذا حدّث .env في اللحظة نفسها.

إعدادان آخران للدفع:

• ‏SNAPEX_FEE_ON: القيمة merchant (الافتراضية) تعني أن العميل يدفع سعر الباقة بالضبط وتُخصم الرسوم مما تستلمه؛ والقيمة customer تعني أن الرسوم تُضاف إلى السعر. للمزيد: من يدفع الرسوم في فاتورة العملات المشفرة.
• ‏SNAPEX_EXPIRES_MINUTES: المدة التي تبقى فيها الفاتورة قابلة للدفع، وهي 60 دقيقة افتراضيًا (من 1 إلى 1440).

الخطوة 3. صِف باقاتك

تُكتب الباقات في سطر واحد في PLANS بالصيغة id:days:price_usd:traffic_bytes، ويُفصل بينها بفواصل. القيمة 0 بايت تعني حركة بيانات غير محدودة.

PLANS=week:7:2.00:0,month:30:5.00:0,quarter:90:12.00:107374182400

هنا الباقة quarter مدتها 90 يومًا مع ⁦100 GiB⁩ من حركة البيانات. يظهر id على الزر («⁦month — $5.00 / 30d⁩»)، لذلك اجعله قصيرًا: حروف لاتينية وأرقام و_ و-. الأسعار بالدولار الأمريكي (USD)، والحد الأدنى للفاتورة ⁦0.50 USD⁩.

يحتفظ كل طلب بنسخة من باقته، لذا يمكنك تغيير الأسعار لاحقًا دون أن تتأثر الطلبات المدفوعة من قبل.

الخطوة 4. اربط اللوحة

حدّد PANEL_TYPE وبيانات الوصول إلى لوحتك.

‏Marzban — PANEL_TYPE=marzban:

• ‏MARZBAN_URL، MARZBAN_USERNAME، MARZBAN_PASSWORD: عنوان اللوحة وبيانات دخول مشرف (أو رمز مشرف جاهز في MARZBAN_TOKEN).
• ‏MARZBAN_SUB_URL: فقط إذا كان Marzban يعيد روابط نسبية /sub/<token> (أي أن XRAY_SUBSCRIPTION_URL_PREFIX فارغ): العنوان الأساسي العام للرابط.

‏3x-ui — PANEL_TYPE=3xui:

• ‏XUI_URL: عنوان اللوحة متضمنًا المسار الأساسي للويب (web base path) إن كنت قد حدّدته (https://xui.example.com:2053/secretpath).
• ‏XUI_USERNAME، XUI_PASSWORD: يجب أن تكون المصادقة الثنائية معطّلة لهذا الحساب.
• ‏XUI_INBOUND_ID: الـ inbound الذي يُضاف إليه العملاء الجدد (vless أو vmess أو trojan أو shadowsocks).
• ‏XUI_SUB_URL: العنوان الأساسي للاشتراك، مثل https://xui.example.com:2096/sub. بدونه يرسل البوت subId فقط.

‏Remnawave — PANEL_TYPE=remnawave:

• ‏REMNAWAVE_URL وREMNAWAVE_TOKEN: عنوان اللوحة ورمز API من قسم API Tokens.
• ‏REMNAWAVE_SQUAD_UUIDS: الـ squads الداخلية للمستخدمين الجدد، مفصولة بفواصل. بدون squad لا تتوفر للمستخدم الجديد أي خوادم.

الخطوة 5. شغّل البوت خلف HTTPS

docker compose up -d --build
docker compose logs -f bot

يستمع البوت على المنفذ 8080: المسار /webhook لـ SnapEX Pay والمسار /health لفحص الحالة. ضعه خلف وكيل عكسي (reverse proxy) مع TLS، مثل Caddy:

pay-bot.example.com {
    reverse_proxy 127.0.0.1:8080
}

يجب أن يمرّر الوكيل جسم الطلب دون أي تغيير، لأن التوقيع يُحسب على الجسم الخام.

الخطوة 6. اضبط Webhook

في لوحة التحكم، في صفحة للمطورين، أدخل عنوان Webhook ‏https://pay-bot.example.com/webhook واحفظ. يظهر سر التوقيع whsec_… مرة واحدة فقط، مباشرة بعد الحفظ الأول؛ انسخه إلى SNAPEX_WEBHOOK_SECRET وأعد تشغيل البوت: docker compose up -d.

لكل حساب في لوحة التحكم عنوان Webhook واحد، وتُرسل إليه جميع الأحداث. لا يتعامل البوت إلا مع أحداث الفواتير، ويؤكد استلام البقية.

كيف يتحقق البوت من الإشعار:

• الترويسة Webhook-Signature: توقيع HMAC-SHA256 على {Webhook-Timestamp}.{raw request body} بسرّك؛ الطلبات غير الموقّعة أو المعدّلة تتلقى 401؛
• ‏Webhook-Timestamp لا يبتعد أكثر من 5 دقائق عن ساعة الخادم، لذا أبقِ NTP قيد التشغيل؛
• الفاتورة نفسها، إذ يعيد البوت قراءتها من API في SnapEX Pay بمفتاحك: لا يُجهَّز المستخدم إلا إذا كانت حالتها هناك paid.

إذا كانت اللوحة أو API في SnapEX Pay غير متاحة في تلك اللحظة، يردّ البوت بـ 502، ويعيد SnapEX Pay محاولة التسليم (حتى 5 محاولات). عمليات التسليم المكررة والمتزامنة لا تُنفِّذ الفاتورة إلا مرة واحدة. للمزيد عن التوقيعات وإعادة المحاولة: إشعارات Webhook لمدفوعات العملات المشفرة.

الخطوة 7. عملية شراء تجريبية بدون أموال حقيقية

1. اضبط SNAPEX_ENVIRONMENT=test وأعد التشغيل: docker compose up -d.
2. أرسل /start إلى بوتك من حسابك الشخصي في Telegram واضغط على باقة.
3. اضغط Pay. تعرض صفحة SnapEX Pay شارة تجريبي. اختر أي عملة وأي شبكة: تعرض الصفحة عنوانًا تجريبيًا، وبعد نحو 10 ثوانٍ تُؤكَّد الدفعة تلقائيًا. لا حاجة إلى إرسال أي شيء.
4. يجب أن يرسل البوت «Payment received» («تم استلام الدفعة») ورابط الاشتراك، وأن يظهر المستخدم tg<your telegram id> في اللوحة. إن لم يحدث ذلك، فراجع docker compose logs -f bot وسجل التسليم في صفحة للمطورين.
5. اضبط SNAPEX_ENVIRONMENT=live وأعد التشغيل.

ما دام البوت في وضع test، فإن كل باقة تُشترى عبره تُفعَّل بدون أموال، لذا اجعل الاختبار قصيرًا. للمزيد: كيف تختبر مدفوعات العملات المشفرة بدون أموال حقيقية.

ما يراه العميل

• ‏/start: اسم متجرك، وسطر عن الدفع بـ USDT ‏(⁦TRC20 / ERC20 / BEP20⁩) أو بعملات أخرى، وأزرار الباقات.
• بعد الضغط على باقة: الباقة وعدد أيامها وسعرها ورقم الفاتورة، إضافة إلى زر «⁦Pay $5.00 with crypto⁩» («ادفع ⁦$5.00⁩ بالعملات المشفرة»).
• صفحة SnapEX Pay مع اختيار العملة: USDT على شبكات TRC20 وERC20 وBEP20 وعملات أخرى (أكثر من 70 عملة إجمالًا) عندما يتيحها SnapEX Pay لمبلغ الفاتورة.
• بعد الدفع: «Payment received» ورابط الاشتراك في المحادثة نفسها. ومع PANEL_TYPE=none تقول الرسالة إن المشرف سيرسل بيانات الوصول قريبًا.

رسائل البوت نفسها باللغة الإنجليزية، ولا يأتي منك فيها سوى اسم المتجر وأسماء الباقات.

العميل العائد يدفع من حساب Telegram نفسه، فيُمدَّد اشتراكه بدءًا من تاريخ انتهائه الحالي (أو من الآن إذا كان قد انتهى بالفعل)؛ أما الباقة المحدودة بحركة بيانات فتبدأ بحصة جديدة. التفاصيل: تجديد اشتراكات VPN المدفوعة بالعملات المشفرة.

إذا أرسل العميل أقل من المبلغ الكامل، فلن يُجهَّز المستخدم: لا يمنح البوت الوصول إلا لفاتورة حالتها paid. يُضاف المبلغ المستلم إلى رصيدك في SnapEX Pay، وتسوّي أنت الباقي مع العميل. كيف يُعالَج الدفع الناقص: أرسل العميل أقل من مبلغ الفاتورة.

إذا لم يعمل شيء ما

• «Payment is unavailable right now» بعد الضغط على باقة. لم يتمكن البوت من إنشاء فاتورة: تحقّق من SNAPEX_API_KEY (مفتاح خاطئ أو ملغى) ومن السجلات.
• يتلقى Webhook الرمز 401 «bad webhook signature». قيمة SNAPEX_WEBHOOK_SECRET غير مطابقة، أو أن الوكيل يغيّر جسم الطلب. وتحقّق أيضًا من مزامنة ساعة الخادم.
• دفع العميل ولم يحصل على شيء. ابحث عن provision failed في السجلات. يواصل SnapEX Pay إعادة محاولة التسليم؛ وعندما تعود اللوحة إلى العمل، يُجهِّز التسليم التالي المستخدم، أو يمكنك إعادة إرسال التسليم من السجل في لوحة التحكم.
• يرسل Marzban رابطًا بدون اسم المضيف. اضبط XRAY_SUBSCRIPTION_URL_PREFIX في Marzban أو MARZBAN_SUB_URL في البوت.
• ‏3x-ui: «login failed». تحقّق من XUI_URL (مع المسار الأساسي للويب) ومن بيانات الدخول، وعطّل المصادقة الثنائية لهذا الحساب.
• ‏Remnawave: يُنشأ المستخدم لكن الاشتراك فارغ. اضبط في REMNAWAVE_SQUAD_UUIDS الـ squads التي تضم عقدك.
• عدة نسخ من البوت. شغّل نسخة واحدة لكل DATA_DIR: الحماية من التكرار تعمل داخل عملية واحدة وملف SQLite الخاص بها.

التكلفة

عمولة ⁦1%⁩ على كل دفعة، بلا رسوم إعداد ولا رسوم شهرية. البوت مجاني.

صفحة البوت: بوت Telegram لخدمات VPN. تفضّل البيع عبر المتجر المدمج في اللوحة نفسها؟ راجع مدفوعات العملات المشفرة في Xboard وV2Board. نظرة عامة لخدمات VPN: مدفوعات العملات المشفرة لخدمات VPN. إنشاء حساب: pay.snapex.pro.