بنية تقرير التسليم في SMPP
عندما ترسل رسالة نصية مع ضبط registered_delivery على 1، يعيد مركز SMSC لاحقًا وحدة deliver_sm عبر ربط استقبال أو ربط إرسال واستقبال. يشير البت 0x04 في esm_class إلى أنها تقرير تسليم لا رسالة واردة، ويحمل حقل short_message التقرير نصيًا. يورد الملحق B من مواصفة SMPP v3.4 هذه الصيغة مثالًا، وتلتزم بها جميع مراكز SMSC تقريبًا: id:IIIIIIIIII sub:SSS dlvrd:DDD submit date:YYMMDDhhmm done date:YYMMDDhhmm stat:DDDDDDD err:E text:….
ولأن الملحق B مثال لا قاعدة صارمة، تختلف التقارير الفعلية: مفاتيح بأحرف صغيرة، أو مسافات زائدة، أو submit_date بشرطة سفلية، أو تواريخ من 12 رقمًا تتضمن الثواني، أو غياب حقل text. تقبل هذه الأداة كل هذه الصيغ وتخبرك بالحقول الناقصة.
- id: معرّف الرسالة الذي أعاده مركز SMSC في submit_sm_resp، وبه تربط التقرير برسالتك. يُظهر مثال المواصفة 10 أحرف، لكن كثيرًا من المراكز تستخدم معرّفات أطول، وأحيانًا بالنظام الست عشري.
- sub وdlvrd: عدد الرسائل المُرسلة والمُسلّمة في 3 أرقام. تهمّ أساسًا في قوائم التوزيع، أما في الرسالة الفردية فتكون غالبًا 001 و001 (أو 000).
- submit date وdone date: وقت إرسال الرسالة ووقت بلوغها حالتها النهائية، بحسب ساعة مركز SMSC.
- stat: الحالة النهائية أو المرحلية في رمز من 7 أحرف مثل DELIVRD.
- err: رمز خطأ من 3 خانات خاص بالشبكة أو بمركز SMSC، و000 تعني عدم وجود خطأ.
- text: أول 20 حرفًا من الرسالة الأصلية، وكثيرًا ما تكون مقتطعة أو فارغة.
- قد تكرر حقول TLV اختيارية هذه البيانات بشكل أوضح: receipted_message_id (0x001E) وmessage_state (0x0427) وnetwork_error_code (0x0423).
رموز stat في تقارير التسليم ومعانيها
يعرّف SMPP v3.4 ثماني حالات للرسالة: ENROUTE وACCEPTD مرحليتان، والبقية نهائية. توحّد واجهتنا البرمجية جميع القنوات في ست حالات webhook هي SUBMITTED وSENT وDELIVERED وREAD وFAILED وREJECTED، وتعرض الأداة أقرب مطابقة لكل قيمة stat. اعتبر هذه المطابقة تقريبية، إذ تُؤكَّد القاعدة الدقيقة لحسابك أثناء الإعداد.
- DELIVRD (message_state 2): سُلّمت إلى الهاتف. أقرب حالة webhook: DELIVERED.
- ACCEPTD (6): تعني رسميًا «قرأها فريق خدمة العملاء يدويًا نيابةً عن المشترك»، لكن معظم مراكز SMSC ترسلها تقريرًا مرحليًا بمعنى «قبلتها الشبكة». الأقرب: SENT.
- ENROUTE (1): ما زالت في الطريق، كأن تكون في قائمة انتظار لمحاولة جديدة. الأقرب: SENT.
- UNDELIV (5): تعذّر تسليمها، كأن يكون الرقم غير صالح أو غير نشط. الأقرب: FAILED.
- EXPIRED (3): انتهت مدة الصلاحية قبل الوصول إلى الهاتف، وغالبًا لأنه مغلق أو خارج التغطية. الأقرب: FAILED.
- DELETED (4): حُذفت قبل التسليم، مثلًا عبر cancel_sm. الأقرب: FAILED.
- REJECTD (8): رفضتها الشبكة أو جدار حماية الرسائل، مثلًا بسبب اسم مرسل غير مسجّل أو محتوى محظور. الأقرب: REJECTED.
- UNKNOWN (7): لا يملك مركز SMSC حالة نهائية. تعامل معها على أنها غير مؤكدة، لا على أنها فشل مثبت.
رموز err: لماذا لا توجد قائمة موحّدة
يتكوّن الحقل err من ثلاث خانات، ولا تحدد مواصفة SMPP قيمه. تعني 000 دائمًا عدم وجود خطأ، أما القيم الأخرى فمصدرها مورّد مركز SMSC أو المشغّل أو مجمّع وسيط. بعض المراكز تمرّر أسباب أخطاء GSM MAP (فمثلًا خطأ MAP رقم 1 يعني مشتركًا غير معروف، و27 يعني مشتركًا غير متاح)، بينما يستخدم غيرها جداول خاصة.
إذا تضمّن التقرير الحقل network_error_code (0x0423) فهو أدق: يحدد أول بايت نوع الشبكة (3 تعني GSM)، ويحمل البايتان التاليان رمز الخطأ. وتقرير DELIVRD بقيمة err غير صفرية متناقض ويستحق المراجعة مع مزوّدك، وتنبّهك الأداة إليه.
أخطاء command_status مقابل تقارير التسليم
يبلّغ SMPP عن المشكلات في لحظتين. يصل command_status في submit_sm_resp خلال أجزاء من الثانية ويبيّن هل قبل مركز SMSC طلبك، و0x00000000 (ESME_ROK) تعني القبول لا التسليم. أما تقرير التسليم فيصل بعد ثوانٍ أو حتى أيام، ويحمل النتيجة النهائية.
تُعرَّف قيم command_status في القسم 5.1.3 من SMPP v3.4. وأكثرها شيوعًا في التشغيل الفعلي: 0x00000058 ESME_RTHROTTLED (تجاوزت عدد الرسائل في الثانية المتفق عليه، فخفّف السرعة وأعد المحاولة مع تباعد أُسّي)، و0x00000014 ESME_RMSGQFUL (قائمة الانتظار ممتلئة، فتمهّل)، و0x0000000A و0x0000000B (عنوان مصدر أو وجهة غير صالح)، و0x0000000D أو 0x0000000E (فشل الربط أو كلمة مرور خاطئة). والقيم من 0x00000400 إلى 0x000004FF محجوزة لأخطاء خاصة بمورّد مركز SMSC، فاسأل مزوّدك عنها.
التواريخ والمناطق الزمنية وزمن التسليم
تُكتب تواريخ التقارير بصيغة YYMMDDhhmm، وتضيف مراكز كثيرة الثواني (YYMMDDhhmmss). ولا يتضمن التقرير منطقة زمنية، فالوقت بحسب ساعة مركز SMSC، وغالبًا UTC. تعرض الأداة التواريخ كما وردت، وتحسب زمن التسليم بطرح submit date من done date، وهو حساب لا يتأثر بالمنطقة الزمنية ما دام التاريخان من الساعة نفسها.
زمن التسليم مؤشر جيد على الجودة. فرسائل OTP إلى هاتف متاح تكتمل عادةً خلال ثوانٍ. أما الأزمنة الطويلة التي تنتهي بحالة EXPIRED فتدل على هواتف مغلقة أو في تجوال، وdone date الأسبق من submit date يعني أن الساعتين غير متطابقتين. والتواريخ المقرّبة إلى الدقيقة لا تقيس أزمنة أقل من دقيقة، لذا يُفضَّل المزوّد الذي يرسل الثواني.
معالجة التقارير بموثوقية في بيئة الإنتاج
ردّ على كل deliver_sm بوحدة deliver_sm_resp حتى لو فشلت معالجتك، وإلا أعاد مركز SMSC إرسالها وقد يحدّ من سرعة الربط. احفظ التقرير الخام، ثم عالجه بشكل غير متزامن وبطريقة لا تتأثر بالتكرار اعتمادًا على معرّف الرسالة، لأن التقارير قد تصل مكررة أو بغير ترتيبها: فلا ينبغي لتقرير ENROUTE متأخر أن يستبدل DELIVRD أبدًا.
وإن كنت تفضّل عدم تحليل التقارير بنفسك، فواجهة REST للرسائل النصية لدينا تقدّم المعلومات نفسها في صورة حالات webhook موحّدة، ويمكن إعادة دفع التقارير الفائتة عبر POST /sms/resendDlr. كما تتوفر روابط SMPP عبر TLS للأحجام الكبيرة والموزّعين.