تخطي إلى المحتوى
Guide

بوت تيليغرام يستقبل دفعات سيريتل كاش

بقلم فايز الشامينُشر: قراءة لمدة 12 دقائق
الخلاصة

بوت تيليغرام ينشئ الطلب، يستقبل رقم عملية سيريتل كاش، ويسأل البوابة قبل أن يعلّم الطلب مدفوعًا.

محل إلكترونيات بحمص كان يبيع من قناة تيليغرام. الزبون يختار الجهاز، يحوّل على رقم سيريتل كاش، ثم يرسل لقطة الشاشة في الخاص. صاحب المحل يفتح التطبيق، يدور على العملية، ويرد: تم، جهّزنا الطلب. الساعة الثانية ليلًا وصله تحويل وهو نائم. الزبون أعاد إرسال الصورة في الصباح، وصارت اللخبطة: هل هذه عملية جديدة أم نفس اللقطة؟ هذا المشهد يتكرر في صفحات تبيع ملابس أو شحن ألعاب أو منتجات رقمية داخل تيليغرام. الحل الذي أركّبه لهؤلاء هو بوت تيليغرام سيريتل كاش: المحادثة تنشئ الطلب، والزبون يدخل رقم العملية بعد التحويل، والبوت يسأل بوابة الدفع ويغيّر الحالة.

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

ماذا يجري داخل المحادثة

البوت ليس بديلًا عن رقم المحفظة. الرقم يبقى رقمك. البوت يرتّب ما يحدث قبل التحويل وبعده: ينشئ طلبًا بمبلغ واضح، يعرض تعليمات الدفع، يستقبل رقم العملية، ويطلب من البوابة التحقق.

كتبت التدفق العام (طلب، دفع، مطابقة، تأكيد) في مقال التأكيد التلقائي، وخطوات الربط للمتاجر في كيف تربط سيريتل كاش بمتجرك الإلكتروني. هنا أنقل المنطق نفسه إلى تيليغرام، حيث الزبون لا يفتح صفحة ويب أصلًا.

باقة بوت الدفع عندي تبدأ من 120 دولارًا مرة واحدة، وتتصل بسيريتل كاش أو شام كاش حسب السوق. API سيريتل كاش نفسه دولاران للرقم في الشهر. إذا كنت تطوّر البوت بنفسك، الباقي من هذا المقال يشرح القرار داخل الكود وكيف تتحدث مع البوابة المستضافة. الإعداد يتم في اليوم نفسه، والتسليم خدمة جاهزة من دون كود مصدري للبوابة.

ما تحتاجه قبل أول أمر

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

وتحتاج بوتًا من BotFather: اسمًا ظاهرًا، واسم مستخدم، ورمز وصول (token). احفظ الرمز في متغيرات البيئة، لا في مستودع الكود.

ونظام طلبات بسيط يكفي في البداية: رقم طلب، مبلغ بالليرة، حالة (بانتظار الدفع، مدفوع، يحتاج مراجعة، منتهٍ)، معرّف محادثة تيليغرام، حقل لرقم العملية، وحقل لرقم المرسل. قاعدة SQLite تفي للتجربة. في الإنتاج أفضّل Postgres مع قيد فريد على رقم العملية.

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

أبقِ لنفسك أمرًا سريًا أو لوحة صغيرة تؤكد أو ترفض طلبًا يدويًا. الحالات الغريبة ستظهر: الزبون يرسل صورة بدل الرقم، أو يحوّل ولا يعود إلى المحادثة، أو يلصق رقمًا من تحويل قديم.

إذا كنت تطوّر من خارج سوريا، البوابة تعمل من دون وسيط سوري ومن دون VPN. يمكن طلب وصول تجريبي قبل ربط الرقم الحي.

طلب واحد يدفع بسيريتل كاش من /start حتى التأكيد

الزبون يضغط Start أو يختار منتجًا من أزرار. البوت ينشئ الطلب: مثلًا شحن لعبة بمبلغ 45,000 ل.س، ويعطيه رقمًا داخليًا، ويعرض رقم التحويل والمبلغ كما هو، مع تعليمات قصيرة: حوّل المبلغ كاملًا، ثم أرسل رقم العملية هنا. لا تطلب ملاحظة في التحويل.

بعد نجاح التحويل يلصق الزبون الرقم في المحادثة. البوت يرسله إلى البوابة على عنوان يصلك عند الإعداد (ضع مكانه YOUR_GATEWAY_URL إلى ذلك الحين). إن وُجدت العملية، يعود الرد بالمبلغ ووقت الوصول ورقم المرسل. رقم المرسل يعود دائمًا مع كل تحويل. أحفظه على الطلب لأنه يفيد عند الدعم. لا أستخدمه كشرط للمطابقة؛ كثير من الزبائن يدفعون من محفظة أخ أو زميل.

بعدها القرار. إذا كان رقم العملية مستخدمًا من قبل على طلب آخر، ارفضه واترك هذا الطلب غير مدفوع. إذا لم تظهر العملية بعد، لا تغلق الطلب ولا تستهلك الرقم؛ قد تكون الكتابة غلطًا، أو التحويل لم يظهر بعد. اطلب انتظار دقيقة وإعادة المحاولة. إذا وُجدت العملية والمبلغ مختلف، علّق الطلب للمراجعة، واربط الرقم به حتى لا يُستخدم على طلب ثانٍ، وأبلغك أنت. إذا وُجدت العملية والمبلغ ينطبق والرقم جديد، علّم الطلب مدفوعًا، واحفظ رقم العملية ورقم المرسل، وأرسل للزبون تأكيدًا، وأَخطر التاجر.

المهلة قرارك. بعض البوتات تعطي ساعة، وبعضها يبقي الطلب مفتوحًا حتى نهاية اليوم. اكتب القاعدة في النظام، وذكّر الزبون بها في رسالة التعليمات.

طلبان بنفس المبلغ لا يفسدان المطابقة، لأن المفتاح هو رقم العملية لا المبلغ وحده. المبلغ شرط تحقق بعد إيجاد العملية.

بناء البوت بـ python-telegram-bot

المثال التالي على النسخة غير المتزامنة من المكتبة (الإصدار 21 وما بعده). هو نمط لحديث البوت مع البوابة الجاهزة، لا مسارًا رسميًا لمحفظة سيريتل كاش. استبدل YOUR_GATEWAY_URL وYOUR_API_KEY وأسماء الحقول بما يصلك عند الإعداد. في الإنتاج استبدل مخزن الذاكرة بقيد فريد في قاعدة البيانات، وشغّل البحث ثم الكتابة داخل معاملة حتى لا يُطبَّق الرقم مرتين إذا أرسل الزبون الرسالة مرتين بسرعة.

```python import os import sqlite3 from enum import IntEnum

import httpx from telegram import ReplyKeyboardRemove, Update from telegram.ext import ( Application, CommandHandler, ContextTypes, ConversationHandler, MessageHandler, filters, )

# حقول تقريبية في رد البوابة: found, amount, receivedAt, senderNumber GATEWAY_URL = os.environ["GATEWAY_URL"] # ضع YOUR_GATEWAY_URL حتى يصلك العنوان الحقيقي GATEWAY_KEY = os.environ["GATEWAY_API_KEY"] BOT_TOKEN = os.environ["TELEGRAM_BOT_TOKEN"] WALLET_NUMBER = os.environ["SYRIATEL_CASH_NUMBER"]

DB_PATH = "orders.db" PRODUCT_NAME = "شحن لعبة" PRODUCT_AMOUNT = 45000

class Step(IntEnum): WAITING_TX = 1

def connect(): conn = sqlite3.connect(DB_PATH) conn.execute("PRAGMA foreign_keys = ON") conn.execute( """ CREATE TABLE IF NOT EXISTS orders ( id INTEGER PRIMARY KEY AUTOINCREMENT, chat_id INTEGER NOT NULL, amount INTEGER NOT NULL, status TEXT NOT NULL, transaction_id TEXT UNIQUE, sender_number TEXT, created_at TEXT DEFAULT CURRENT_TIMESTAMP ) """ ) conn.commit() return conn

def to_int_amount(value): return int(round(float(value)))

async def lookup_transfer(transaction_id: str) -> dict: async with httpx.AsyncClient(timeout=20) as client: response = await client.post( GATEWAY_URL, headers={ "Authorization": f"Bearer {GATEWAY_KEY}", "Content-Type": "application/json", }, json={"transactionId": transaction_id}, ) response.raise_for_status() return response.json()

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE): await update.message.reply_text( "أهلاً. اكتب /buy لتطلب، وبعد التحويل أرسل رقم العملية فقط." )

async def buy(update: Update, context: ContextTypes.DEFAULT_TYPE): chat_id = update.effective_chat.id with connect() as conn: cursor = conn.execute( "INSERT INTO orders (chat_id, amount, status) VALUES (?, ?, ?)", (chat_id, PRODUCT_AMOUNT, "awaiting_payment"), ) order_id = cursor.lastrowid conn.commit()

context.user_data["order_id"] = order_id await update.message.reply_text( f"طلب رقم {order_id}: {PRODUCT_NAME}.\n" f"حوّل {PRODUCT_AMOUNT} ل.س إلى رقم سيريتل كاش {WALLET_NUMBER}.\n" "التحويل لا يحتاج ملاحظة. بعد نجاحه أرسل رقم العملية هنا كما يظهر عندك." ) return Step.WAITING_TX

async def receive_tx(update: Update, context: ContextTypes.DEFAULT_TYPE): transaction_id = (update.message.text or "").strip() order_id = context.user_data.get("order_id") if not transaction_id or order_id is None: await update.message.reply_text("أرسل رقم العملية، أو ابدأ من /buy.") return Step.WAITING_TX

result = await confirm_order(order_id, transaction_id)

if result["status"] == "paid": await update.message.reply_text( f"وصل المبلغ. طلبك رقم {order_id} دخل التجهيز." ) return ConversationHandler.END

if result["status"] == "not_found": await update.message.reply_text( "ما ظهرت العملية بعد. راجع الرقم، انتظر دقيقة إذا كان التحويل للتو، ثم أعد الإرسال." ) return Step.WAITING_TX

if result["status"] == "wrong_amount": await update.message.reply_text( "وصل تحويل مرتبط بهذا الطلب، والمبلغ مختلف عن المطلوب. رح نراجعه ونرجع لك." ) return ConversationHandler.END

if result["status"] == "already_used": await update.message.reply_text( "هذا الرقم مستخدم من قبل على طلب آخر. أرسل رقم عملية التحويل الجديد." ) return Step.WAITING_TX

await update.message.reply_text("ما قدرنا نؤكد الآن. أعد المحاولة بعد قليل أو راسل الدعم.") return Step.WAITING_TX

async def confirm_order(order_id: int, transaction_id: str) -> dict: with connect() as conn: order = conn.execute( "SELECT id, amount, status FROM orders WHERE id = ?", (order_id,) ).fetchone() if not order or order[2] != "awaiting_payment": return {"status": "closed"}

taken = conn.execute( "SELECT id FROM orders WHERE transaction_id = ?", (transaction_id,) ).fetchone() if taken: return {"status": "already_used"}

try: payload = await lookup_transfer(transaction_id) except httpx.HTTPError: return {"status": "gateway_error"}

if not payload or not payload.get("found"): return {"status": "not_found"}

paid = to_int_amount(payload["amount"]) expected = to_int_amount(order[1]) sender = payload.get("senderNumber")

if paid != expected: conn.execute( """ UPDATE orders SET status = ?, transaction_id = ?, sender_number = ? WHERE id = ? AND transaction_id IS NULL """, ("needs_review", transaction_id, sender, order_id), ) conn.commit() return {"status": "wrong_amount", "paid": paid, "senderNumber": sender}

try: conn.execute( """ UPDATE orders SET status = ?, transaction_id = ?, sender_number = ? WHERE id = ? AND transaction_id IS NULL """, ("paid", transaction_id, sender, order_id), ) conn.commit() except sqlite3.IntegrityError: return {"status": "already_used"}

return {"status": "paid", "senderNumber": sender, "paidAt": payload.get("receivedAt")}

async def cancel(update: Update, context: ContextTypes.DEFAULT_TYPE): context.user_data.clear() await update.message.reply_text("ألغينا الطلب الحالي.", reply_markup=ReplyKeyboardRemove()) return ConversationHandler.END

def main(): connect().close() app = Application.builder().token(BOT_TOKEN).build() app.add_handler(CommandHandler("start", start)) app.add_handler( ConversationHandler( entry_points=[CommandHandler("buy", buy)], states={ Step.WAITING_TX: [MessageHandler(filters.TEXT & ~filters.COMMAND, receive_tx)], }, fallbacks=[CommandHandler("cancel", cancel)], ) ) app.run_polling()

if __name__ == "__main__": main() ```

قبل الإنتاج أراجع ثلاثة قيود. رقم العملية يُحفظ بقيد فريد حتى لو كرّر الزبون لصق الرقم أو وصل التحديث مرتين من تيليغرام. المبلغ يُقارن كعدد، لا كنص، حتى لا تفشل مقارنة 45000 مع 45000.00. ورقم المرسل يُحفظ ولا يُشترط تطابقه مع رقم حساب تيليغرام.

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

للتطوير يكفي run_polling. في الإنتاج أضع البوت خلف webhook على عنوان HTTPS، حتى لا تعتمد العملية على جلسة طرفية مفتوحة.

إذا كنت تفضّل aiogram

المنطق لا يتغيّر. تتغيّر طريقة حفظ الخطوة: في aiogram 3 تستخدم FSMContext بدل ConversationHandler. هذا مختصر لنقطة استقبال رقم العملية فقط، ويستدعي confirm_order نفسها من المثال السابق.

```python from aiogram import F, Router from aiogram.filters import Command from aiogram.fsm.context import FSMContext from aiogram.fsm.state import State, StatesGroup from aiogram.types import Message

router = Router()

class Pay(StatesGroup): waiting_tx = State()

@router.message(Command("buy")) async def buy_aiogram(message: Message, state: FSMContext): # أنشئ الطلب في قاعدة البيانات كما في المثال السابق order_id = 0 # استبدله بمعرّف الطلب المُدرج await state.update_data(order_id=order_id) await state.set_state(Pay.waiting_tx) await message.answer("حوّل المبلغ ثم أرسل رقم العملية هنا. التحويل لا يحتاج ملاحظة.")

@router.message(Pay.waiting_tx, F.text) async def receive_tx_aiogram(message: Message, state: FSMContext): data = await state.get_data() result = await confirm_order(data["order_id"], message.text.strip()) if result["status"] == "paid": await state.clear() await message.answer("وصل المبلغ. طلبك دخل التجهيز.") return if result["status"] == "not_found": await message.answer("ما ظهرت العملية بعد. راجع الرقم وأعد الإرسال.") return await state.clear() await message.answer("طلبك انتقل للمراجعة أو يحتاج رقم عملية جديد.") ```

إذا كان الفريق معتادًا على aiogram فلا داعي للتحويل إلى المكتبة الأخرى. قرار المطابقة يجب أن يبقى في طبقة واحدة يستدعيها أي إطار، حتى لا يتفرع منطق «مدفوع / غير موجود / مبلغ مختلف» في ملفين.

حالات تكسر التأكيد في تيليغرام

أكثر خطأ أراه: الزبون يرسل صورة الإشعار بدل رقم العملية. إذا استقبل البوت صورة في خطوة الانتظار، لا تحاول قراءة الرقم من الصورة تلقائيًا في النسخة الأولى. رد برسالة واضحة: افتح تفاصيل التحويل، انسخ رقم العملية، والصقه كنص. يمكنك أنت أن تدخل الرقم من اللوحة وتشغّل نفس التحقق.

إعادة استخدام الرقم أخطر من غلطة الكتابة. بلا قيد فريد، رقم واحد قد يغلق طلبين إذا نسخه زبون آخر أو إذا وصلت الرسالة مرتين. ارفض الرقم المستخدم، واحتفظ بالأثر: لأي طلب ارتبط أول مرة، ومتى.

الدفع الناقص أو الزائد يحتاج قاعدة مكتوبة. لا تفترض السبب. قد يكون الزبون أخطأ في الرقم، أو حوّل على دفعتين، أو زاد مبلغًا عن قصد. علّق الطلب، واربط رقم العملية به، وأبلغ الطرفين. التسليم لا يتم حتى ينطبق المبلغ أو يؤكد شخص من اللوحة.

الدفع المتأخر شائع في المحادثة أكثر من الموقع. الزبون يبدأ التحويل، ينشغل، ثم يعود بعد أن انتهت المهلة. قرّر مسبقًا: مراجعة يدوية، أو رفض مع طلب تواصل لإعادة المبلغ أو إنشاء طلب جديد. أنا أميل إلى المراجعة اليدوية مع إشعار فوري.

يبقى أن الزبون يحوّل ولا يرسل الرقم. البوابة ترى ما وصل إلى رقمك؛ هي لا تعلّم الطلبات من تلقاء نفسها بالتخمين. إذا كتب «دفعت» من دون رقم، اطلب الرقم. إذا لم يعد، استخدم التدقيق اليدوي.

إذا كان جزء من البيع يتم على واتساب أيضًا، المنطق نفسه ينطبق هناك مع شام كاش أو سيريتل كاش. كتبت ذلك في بوت واتساب للطلبات والدفع بشام كاش. نسخة إنكليزية للمطورين الذين يبنون البوت من خارج سوريا: How to build a Telegram bot that accepts Syriatel Cash.

مقارنة السعر بين المحفظتين (دولاران للرقم شهريًا لسيريتل كاش، وخمسة دولارات للحساب لشام كاش، وكل اشتراك يُدار وحده) موجودة في مقال المقارنة بين الواجهتين.

قائمة تحقق قبل فتح البوت للزبائن

  • رقم سيريتل كاش الحي متصل بالبوابة، لا رقم تجريبي نُسي في الإنتاج.
  • كل طلب يُنشأ بمبلغ وحالة قبل أن يظهر رقم التحويل في المحادثة.
  • رسالة التعليمات توضح المبلغ ورقم المحفظة، وتقول إن التحويل لا يحتاج ملاحظة.
  • رقم العملية يُحفظ بقيد فريد، ويُرفض إذا أُعيد استخدامه.
  • رقم لم يظهر بعد لا يُستهلك، والزبون يستطيع إعادة الإرسال.
  • المبلغ يُقارن كعدد، والدفع المختلف يدخل المراجعة مع ربط الرقم بهذا الطلب.
  • رقم المرسل يُحفظ ولا يُشترط تطابقه مع حساب تيليغرام.
  • أمر أو لوحة للتأكيد والرفض اليدوي، مع أثر مكتوب.
  • إشعار التاجر يعمل بعد حفظ حالة «مدفوع»، مع إعادة محاولة إذا فشل الإرسال.
  • جرّبت مسار النجاح ومسار اللبس: رقم صحيح، رقم مكرّر، مبلغ مختلف، ورقم غير موجود بعد، وصورة بدل النص.

إذا نقص بند، أُبقي ردًا يدويًا موازيًا لأيام قليلة. بوت نصف جاهز في قناة عليها طلبات حقيقية يربك الزبائن أكثر من موظف يرد على عشر صور في اليوم.

أسئلة تتكرر

هل أحتاج رقم سيريتل كاش خاصًا بي؟

نعم. تربط رقمك الحالي، والبوابة تمنح البوت وصولًا برمجيًا إليه. فتح الرقم عند الشركة ليس جزءًا من الخدمة.

هل يكتب الزبون ملاحظة في التحويل؟

لا. تحويل سيريتل كاش ما فيه حقل ملاحظة. المطابقة تتم برقم العملية الذي يلصقه في البوت بعد الدفع.

python-telegram-bot أم aiogram؟

الاثنان يصلحان. اختر ما يعرفه فريقك، وانقل قرار المطابقة إلى دالة واحدة مشتركة. أنا أبدأ عادةً بـ python-telegram-bot إذا كان المشروع صغيرًا ويحتاج محادثة واضحة الخطوات.

ماذا لو دفع الزبون من محفظة شخص آخر؟

هذا شائع. رقم المرسل يعود دائمًا وأحفظه. لا أرفض الطلب لأن الرقم لا يطابق هاتف الزبون في تيليغرام.

كم سعر البوت والواجهة، وهل أجرب قبل الإنتاج؟

بوت الدفع يبدأ من 120 دولارًا مرة واحدة. API سيريتل كاش دولاران للرقم في الشهر. الإعداد يتم في اليوم نفسه، ويمكن طلب وصول تجريبي قبل الرقم الحي.

هل يعمل البوت إذا كان السيرفر خارج سوريا؟

نعم. البوابة تعمل من خارج سوريا من دون وسيط سوري ومن دون VPN. هذا هو الوضع المعتاد إذا كان الاستضافة خارج البلد.

بعد تجربة المسارات الأربعة

افتح البوت على منتج واحد أولًا، ومسار مراجعة يدوية للحالات الشاذة. بعد أسبوع من طلبات حقيقية تظهر ثغرات المحادثة أوضح من أي تجربة: ناس يرسلون «تم» بدل الرقم، أو يدفعون بعد المهلة، أو يلصقون الرقم مع جملة طويلة. عندها تضيف شام كاش إذا احتجتها، أو تفتح الكتالوج كاملًا.

إذا بدك بوت تيليغرام يستقبل دفعات سيريتل كاش، أو بوابة جاهزة يتصل بها بوتك الحالي، راسلني من صفحة الموقع أو على fayezalshami.dev@gmail.com. اذكر المحفظة، وعدد الأرقام، وهل البيع يتم في تيليغرام أو في موقع أو في الاثنين.

بقلم فايز الشامي | Fayez Alshami، مطور باك إند وبوابات دفع سيريتل كاش وشام كاش.

أدلّة ومقارنات

تحتاج إلى بناء هذا أو ربطه لعملك؟

استعرض الخدمات