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

إشعارات فورية لصاحب المتجر عبر بوت تيليغرام

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

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

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

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

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

ماذا يُرسل، ومتى يُرسل

أرسل بعد نجاح الكتابة في قاعدة البيانات، لا قبلها. الرسالة التي تصل التاجر يجب أن تعني أن الحالة صارت محفوظة، لا أن الطلب «ربما» دُفع. الحالات التي أرسل عليها عادة:

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

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

نص الرسالة قصير وقابل للنسخ. أضع رقم الطلب، والمبلغ، ورقم العملية، والمحفظة، والحالة، ورابطًا يفتح الطلب في اللوحة إن وُجدت. لا أضع توكنًا ولا بيانات بطاقة ولا لقطة شاشة كبيرة تملأ المجموعة.

الإشعار قناة منفصلة عن حالة الطلب

إذا نجح حفظ «مدفوع» وفشل إرسال تيليغرام لأن الشبكة قطعت، الطلب يبقى مدفوعًا وتعاد المحاولة. العكس أخطر: لا تؤجّل حفظ الدفع حتى يرد تيليغرام 200، وإلا قد يؤكد الزبون ويرى التاجر فراغًا بعد إعادة تشغيل العملية.

هذا الفصل نفسه يظهر عندما تمرّر الحدث إلى أداة أتمتة. المسار الأوسع في أتمتة شغل متجرك بـ n8n. الإشعار يمكن أن يخرج من الخادم مباشرة أو من n8n، بشرط أن تكون إعادة المحاولة على الإرسال لا على تعليم الطلب مرة ثانية.

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

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

مثال للكود: طابور إعادة محاولة بعد الحفظ

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

```javascript import express from "express"; import Database from "better-sqlite3";

const app = express(); app.use(express.json());

const db = new Database("shop.db"); db.exec( CREATE TABLE IF NOT EXISTS orders ( id TEXT PRIMARY KEY, amount INTEGER NOT NULL, status TEXT NOT NULL, transaction_id TEXT UNIQUE, sender_number TEXT ); CREATE TABLE IF NOT EXISTS notify_jobs ( id INTEGER PRIMARY KEY AUTOINCREMENT, order_id TEXT NOT NULL, payload TEXT NOT NULL, attempts INTEGER NOT NULL DEFAULT 0, next_attempt_at INTEGER NOT NULL, sent_at INTEGER ); );

const TOKEN = process.env.TELEGRAM_BOT_TOKEN; const ADMIN_CHAT_ID = process.env.ADMIN_CHAT_ID;

function enqueueNotify(orderId, text) { db.prepare( INSERT INTO notify_jobs (order_id, payload, next_attempt_at) VALUES (?, ?, ?) ).run(orderId, text, Date.now()); }

async function sendTelegram(text) { const url = https://api.telegram.org/bot${TOKEN}/sendMessage; const res = await fetch(url, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ chat_id: ADMIN_CHAT_ID, text, disable_web_page_preview: true, }), }); if (!res.ok) { const body = await res.text(); throw new Error(telegram ${res.status}: ${body}); } }

async function pumpOnce() { const job = db.prepare( SELECT * FROM notify_jobs WHERE sent_at IS NULL AND next_attempt_at <= ? ORDER BY id LIMIT 1 ).get(Date.now()); if (!job) return;

try { await sendTelegram(job.payload); db.prepare("UPDATE notify_jobs SET sent_at = ? WHERE id = ?").run(Date.now(), job.id); } catch (err) { const attempts = job.attempts + 1; const delayMs = Math.min(10 * 60 * 1000, 2000 * 2 ** Math.min(attempts, 6)); db.prepare( UPDATE notify_jobs SET attempts = ?, next_attempt_at = ? WHERE id = ? ).run(attempts, Date.now() + delayMs, job.id); console.error("notify failed", job.id, err.message); } }

function markPaid({ orderId, amount, transactionId, senderNumber }) { const order = db.prepare("SELECT * FROM orders WHERE id = ?").get(orderId); if (!order) return { ok: false, reason: "unknown_order" }; if (order.status === "paid") return { ok: true, already: true };

if (Number(order.amount) !== Number(amount)) { db.prepare( UPDATE orders SET status = 'review', transaction_id = ?, sender_number = ? WHERE id = ? ).run(transactionId, senderNumber || null, orderId); enqueueNotify( orderId, مراجعة مبلغ\nطلب ${orderId}\nالمتوقع ${order.amount}\nالواصل ${amount}\nرقم العملية ${transactionId} ); return { ok: false, reason: "amount_mismatch" }; }

try { db.prepare( UPDATE orders SET status = 'paid', transaction_id = ?, sender_number = ? WHERE id = ? AND status != 'paid' ).run(transactionId, senderNumber || null, orderId); } catch (err) { if (String(err.message).includes("UNIQUE")) { enqueueNotify( orderId, رقم عملية مكرر رُفض\nطلب ${orderId}\nرقم العملية ${transactionId} ); return { ok: false, reason: "already_used" }; } throw err; }

enqueueNotify( orderId, دفعة مؤكدة\nطلب ${orderId}\nالمبلغ ${amount}\nرقم العملية ${transactionId} ); return { ok: true }; }

app.post("/internal/payments/confirm", (req, res) => { const result = markPaid(req.body); res.json(result); });

setInterval(() => { pumpOnce().catch((err) => console.error(err)); }, 2000);

app.listen(Number(process.env.PORT || 3000), "0.0.0.0"); ```

القيد الفريد على transaction_id هو الذي يمنع استخدام رقم العملية مرتين. الإشعار عن التكرار يخرج بعد رفض الكتابة، لا قبلها. المبلغ يُقارن كعدد، حتى يتفق 85000 و "85000.00".

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

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

أخطاء شائعة في إشعار التاجر

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

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

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

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

إرسال الإشعار من هاتف التاجر عبر عميل غير رسمي. الحساب يُحظر في أسوأ وقت. استخدم Bot API بتوكن من BotFather على سيرفرك.

قائمة تحقق قبل التشغيل الحي

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

أسئلة تتكرر

هل أحتاج بوتًا ثانيًا للإشعارات؟

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

ماذا لو كان التاجر خارج الشبكة ساعات؟

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

هل يغني الإشعار عن لوحة الطلبات؟

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

هل أرسل إشعارًا لكل دفع عند الاستلام أيضًا؟

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

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

بقلم فايز الشامي | Fayez Alshami

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

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

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