SMS API أم SMPP: أي طريقة ربط تناسب نشاطك؟

هذا الدليل موجّه للمهندسين والقادة التقنيين الذين يقررون طريقة الربط مع مزوّد رسائل SMS: عبر HTTP/REST SMS API، أو عبر SMPP، أو بالاثنين معًا. ويشرح الفروق الحقيقية بينهما على مستوى البروتوكول وعلى مستوى التشغيل، لتختار الواجهة المناسبة لكل نوع من الحركة، وتخطط للانتقال إذا تجاوزت احتياجاتك خيارك الأول.

وللاطلاع على أنماط الربط بصورة أشمل، بما فيها الـ webhooks ومنع التكرار (idempotency)، راجع دليل ربط واجهات المراسلة البرمجية.

ما الفرق بين SMS API وSMPP؟

يرسل REST SMS API كل رسالة في طلب HTTPS منفصل ويعيد معرّف الرسالة. أما SMPP (Short Message Peer-to-Peer) فيُبقي جلسة واحدة طويلة الأمد وموثّقة مفتوحة، ويتبادل عبرها في الاتجاهين رسائل ثنائية تُسمّى PDU. صُمّم REST للبساطة، وصُمّم SMPP للحجم المستمر من رسائل SMS.

كيف يعمل REST SMS API؟

ترسل طلب HTTPS من نوع POST يحمل token ومحتوى JSON، فيرد المزوّد بمعرّف. كل طلب مستقل، لذا يمكنك الإرسال من أي خادم أو دالة أو حاوية دون إدارة اتصال.

يبدو الإرسال المعتاد عبر واجهتنا هكذا:

curl -X POST https://api.broadnet.me/sms/sendSms \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "senderId": "OmniDemo",
    "destinationNumber": "971500000000",
    "message": "Your OmniDemo code is 482913",
    "messageType": "TEXT"
  }'

تكون الاستجابة 200 OK مع معرّف الرسالة كنص عادي. ثم تصل الحالة النهائية لاحقًا إلى الـ webhook لديك بإحدى القيم SUBMITTED أو SENT أو DELIVERED أو FAILED أو REJECTED. وتجد أسماء الحقول والخيارات في مرجع SMS API.

مزايا REST:

• أدوات مألوفة: أي لغة برمجة، وأي عميل HTTP، ورموز حالة قياسية كما يعرّفها RFC 9110.
• تأمين سهل: TLS في كل مكان وtoken في ترويسة Authorization.
• إرسال جماعي دون اتصالات: ارفع ملف المستلمين في طلب واحد بدل فتح جلسة.
• واجهة واحدة لقنوات كثيرة: النمط نفسه يرسل قوالب WhatsApp أو بطاقات RCS.

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

كيف يعمل SMPP؟

SMPP بروتوكول ثنائي تعرّفه مواصفة SMPP v3.4 التي نشرها منتدى مطوري SMPP (الذي أصبح لاحقًا SMS Forum)، ولا يزال الإصدار الأوسع انتشارًا. يتصل نظامك، المسمّى ESME (External Short Message Entity)، بمركز SMSC (Short Message Service Centre) لدى المزوّد ويفتح جلسة تُسمّى bind.

أنواع الـ bind

• Transmitter (TX) باستخدام bind_transmitter: لإرسال الرسائل فقط.
• Receiver (RX) باستخدام bind_receiver: لاستقبال تقارير التسليم والرسائل الواردة فقط.
• Transceiver (TRX) باستخدام bind_transceiver: الاثنان معًا في جلسة واحدة، وهو الخيار المعتاد.

دورة حياة الجلسة

1. افتح اتصال TLS بالمضيف والمنفذ اللذين يزوّدك بهما المزوّد.
2. أرسل bind_transceiver مع system_id وكلمة المرور، وانتظر استجابة قيمة command_status فيها 0.
3. أرسل الرسائل عبر submit_sm، وكل submit_sm_resp يعيد message_id.
4. استقبل تقارير التسليم على شكل deliver_sm ورد على كل منها بـ deliver_sm_resp.
5. أرسل enquire_link دوريًا في فترات الخمول ليعرف الطرفان أن الجلسة ما زالت حية.
6. أغلق الجلسة بـ unbind وانتظر unbind_resp.

تحمل كل PDU رقمًا تسلسليًا، وتحمل الاستجابات الرقم نفسه، وبهذه الطريقة تطابق كل submit_sm_resp مع الرسالة التي أرسلتها. وتغطي وثائق SMPP لدينا كل خطوة مع إعداداتنا.

ما آلية النوافذ في SMPP ولماذا تهم؟

تعني النوافذ (windowing) إرسال عدة PDU من نوع submit_sm قبل عودة استجاباتها. وعدد وحدات PDU غير المؤكَّدة المسموح بها قيد الإرسال هو حجم النافذة. وهذا هو السبب الرئيسي في أن SMPP يحافظ على إنتاجية أعلى من HTTP الذي يرسل طلبًا واحدًا في كل مرة.

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

قواعد عملية:

• استخدم حجم النافذة الذي يتفق عليه المزوّد معك ولا تتجاوزه أبدًا، فقد تُرفض وحدات PDU الزائدة.
• التزم بالمعدل المتفق عليه لكل bind. وإذا تلقيت ESME_RTHROTTLED فخفّض الوتيرة وأعد المحاولة مع تأخير متزايد.
• تتبّع الأرقام التسلسلية المعلّقة حتى لا يضيع عند انقطاع الاتصال أثر الرسائل التي قُبلت.
• توسّع بزيادة عدد جلسات الـ bind ضمن العدد المتفق عليه لحسابك، لا بتكبير النافذة بلا حدود.

الحدود الافتراضية لواجهة REST لدينا ولجلسات SMPP مدرجة في الأخطاء والحدود، وتُؤكَّد حدود حسابك عند تفعيل الوصول.

كيف تختلف تقارير التسليم؟

في REST، يرسل المزوّد حدث JSON إلى الـ webhook لديك. وفي SMPP، يصل التقرير على شكل PDU من نوع deliver_sm عبر الجلسة، مع تفعيل بت التقرير في esm_class. وكلاهما غير متزامن؛ فلا 200 OK ولا submit_sm_resp يعني أن الهاتف استلم الرسالة.

تقدّم مواصفة SMPP v3.4 صيغة نص التقرير كمثال وتترك الصيغة الدقيقة لمورّد SMSC، لكن معظم المزوّدين يتبعونها:

id:2603121407537573731 sub:001 dlvrd:001 submit date:2610100914 done date:2610100915 stat:DELIVRD err:000 text:Your OmniDemo code

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

وهناك فرقان عمليان أهم من الصيغة:

• التأكيد. يجب أن يرد عميل SMPP على كل deliver_sm. فالتقارير غير المؤكَّدة يُعاد إرسالها وقد تبطئ الـ bind. وللسبب نفسه يجب أن يرد معالج الـ webhook بسرعة برمز 2xx.
• الاستعادة. إذا انقطع اتصال عميل SMPP، تنتظر التقارير حتى الـ bind التالي أو قد تنتهي صلاحيتها في طابور المزوّد. أما في REST فقد يتيح المزوّد إعادة إرسال التقارير لفترة زمنية محددة. اسأل عن آلية كل منهما.

اقرأ المزيد عن معنى كل حالة في شرح حالات تسليم الرسائل.

كيف يُعالَج الترميز؟

على الواجهتين الاختيار بين GSM-7 وUnicode، وكلتاهما تقسّم الرسائل الطويلة إلى أجزاء. والفرق في الجهة التي تتولى العمل.

• REST: تضبط حقلًا مثل messageType على TEXT أو UNICODE، وتتولى المنصة تقسيم الرسائل الطويلة. كما توفّر واجهتنا POST /sms/identify لحساب الأحرف والأجزاء مسبقًا.
• SMPP: تضبط data_coding (0 لأبجدية GSM-7 الافتراضية و8 لـ UCS-2) وترمّز البايتات بنفسك. وفي الرسائل الطويلة إما أن تضيف User Data Header إلى كل جزء وتضبط esm_class على 0x40، أو ترسل النص كاملًا في حقل message_payload إذا فعّله مزوّدك.

بحسب 3GPP TS 23.040، تحمل رسالة SMS الواحدة 140 ثُمانيًا: 160 حرفًا بترميز GSM-7 أو 70 حرفًا بترميز UCS-2، وتنخفض إلى 153 أو 67 لكل جزء عند إضافة الترويسة. ويكفي حرف عربي واحد أو رمز تعبيري واحد لتحويل الرسالة كلها إلى Unicode. وأخطاء الترميز هي أكثر أعطال ربط SMPP شيوعًا، لذا اختبر بنصوص عربية ورموز تعبيرية ونصوص طويلة. راجع دليل حدود الأحرف.

كيف تُقارن نماذج الأمان؟

يعتمد REST على TLS وbearer token مع كل طلب. أما SMPP v3.4 فلا يملك تشفيرًا خاصًا به ويرسل بيانات الاعتماد داخل الـ bind، لذا يعتمد على طبقة النقل وضوابط الشبكة المحيطة به.

في SMPP:

• استخدم TLS (يعرّف RFC 8446 الإصدار TLS 1.3) أو ربطًا خاصًا، ولا تستخدم SMPP غير المشفّر عبر الإنترنت العام أبدًا.
• سجّل عناوين IP المصدر بحيث لا تتمكن من فتح bind إلا خوادمك.
• احفظ system_id وكلمة المرور كأسرار، منفصلة لكل بيئة، وغيّرها إن تعرّضت للكشف.
• راقب إخفاقات الـ bind، فقد تدل على خطأ في الإعداد أو إساءة استخدام لبيانات الاعتماد.

في REST:

• أبقِ الـ token على الخوادم فقط، ولا تضعه أبدًا في تطبيقات الجوال أو شيفرة المتصفح.
• تجنّب واجهات HTTP القديمة التي تمرّر اسم المستخدم وكلمة المرور في الرابط، فينتهي بها الأمر في السجلات.
• احمِ الـ webhook باستخدام HTTPS ومسار يصعب تخمينه وتحقق صارم من محتوى الطلب.

ما التكلفة التشغيلية لكل خيار؟

لا يضيف REST عبئًا تشغيليًا يُذكر: إما أن تنجح الطلبات أو تعيد خطأ يمكنك إعادة المحاولة بعده. أما SMPP فيضيف مكوّنًا يعمل باستمرار يجب مراقبته وصيانته.

يحتاج عميل SMPP إلى:

1. إدارة الاتصال، مع إعادة الاتصال بتأخير متزايد وعشوائية (jitter) بدل حلقة متلاحقة؛
2. رسائل إبقاء الاتصال، واكتشاف الاتصالات الصامتة نصف المفتوحة؛
3. التحكم في النافذة والمعدل لكل bind؛
4. تتبّع الأرقام التسلسلية والمطابقة بعد الانقطاعات؛
5. تأكيد استلام التقارير وتخزينها؛
6. منطق الترميز ودمج الأجزاء؛
7. مراقبة حالة الـ bind والإنتاجية وأخطاء التقييد وتأخر التقارير.

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

متى تستخدم كل خيار؟

استخدم REST ما لم يكن لديك سبب واضح لإضافة SMPP.

اختر REST SMS API عندما

• ترسل رموز OTP أو تنبيهات أو إشعارات أو حملات من تطبيقاتك؛
• تحتاج إلى WhatsApp أو RCS أو قنوات أخرى إلى جانب SMS؛
• تعمل منصتك على دوال serverless أو حاويات قصيرة العمر؛
• لا يملك فريقك خبرة في SMPP ولا حاجة إلى بنائها.

اختر SMPP عندما

• ترسل حجمًا كبيرًا ومستمرًا من رسائل SMS وبلغت حدود REST؛
• تشغّل أصلًا بوابة SMPP أو منصة مراسلة؛
• تعمل كمجمّع أو مشغّل أو موزّع يربط حركة SMS الخاصة بعملائه؛
• تحتاج إلى البروتوكول نفسه مع عدة مزوّدين في المنبع.

كيف يبدو الإعداد الهجين؟

تستخدم شركات كثيرة الاثنين على حساب واحد: REST للحركة متعددة القنوات وحركة التطبيقات، وSMPP لرسائل SMS الجماعية. والفخ هنا أن ينتهي بك الأمر بنموذجين للتسليم.

• وجّه الحركة بحسب حالة الاستخدام لا عشوائيًا: مثلًا رموز OTP وWhatsApp عبر REST، وكشوف الحساب الجماعية عبر SMPP.
• وحّد الحالات الواردة من الـ webhooks ومن deliver_sm في جدول واحد مفتاحه معرّف الرسالة.
• اعتمد سياسة واحدة لأسماء المرسل في الواجهتين، لأن التسجيلات تسري أيًّا كانت الواجهة المستخدمة.
• اجمع التقارير معًا حتى تظهر الحملة الموزعة على الواجهتين بنتيجة واحدة.

كيف تنتقل من SMS API إلى SMPP؟

انتقل تدريجيًا مع تشغيل الواجهتين معًا، وقِس النتائج قبل نقل الحجم.

1. تأكد من الحاجة: وثّق الحجم أو الإنتاجية التي لا يلبيها REST.
2. اطلب التجهيز: شارك الدول المستهدفة، وأسماء المرسل، وذروة الإنتاجية المتوقعة، وعناوين IP المصدر.
3. اختر مكتبة عميل ناضجة في بيئتك التقنية وغلّفها بواجهة إرسال خاصة بك.
4. ابنِ معالجة التقارير أولًا، مربوطة بنموذج الحالات نفسه المستخدم في الـ webhooks.
5. اختبر الترميز: GSM-7، والعربية، والرموز التعبيرية، والرسائل متعددة الأجزاء على هواتف حقيقية.
6. اختبر الأعطال: اقطع الاتصال أثناء الإرسال، وتسبّب في التقييد، وتحقق من المطابقة.
7. شغّل بالتوازي: انقل نسبة صغيرة من نوع واحد من الحركة إلى SMPP وقارن التسليم والتقارير.
8. انقل الحجم على مراحل، مع إبقاء REST مسارًا احتياطيًا.

فيما يلي مثال توضيحي لإعدادات الـ bind. المضيف والمنفذ والحدود قيم مؤقتة، والقيم الحقيقية تصلك مع بيانات الاعتماد عند التجهيز.

host:                 <provided with your bind>
port:                 <TLS port provided with your bind>
bind type:            transceiver
system_id:            <your system_id>
password:             <your password>
system_type:          (empty unless told otherwise)
interface_version:    0x34
source_addr_ton/npi:  5 / 0   (اسم مرسل أبجدي رقمي)
dest_addr_ton/npi:    1 / 1   (رقم دولي)
registered_delivery:  1       (طلب تقارير التسليم)
data_coding:          0 (GSM-7) or 8 (UCS-2)
enquire_link:         every 30 seconds while idle
window:               as agreed for your account

مثال تطبيقي: متجر إقليمي يضيف SMPP لكشوف الحساب

«سوق رفيق» (مثال افتراضي)، متجر إلكتروني يعمل في الإمارات ومصر والأردن، يرسل رموز OTP وتحديثات الطلبات عبر REST API، وقوالب WhatsApp عبر الواجهة نفسها. وقد نمت كشوف الحساب الشهرية التي يرسلها بالـ SMS إلى كامل قاعدة عملائه حتى صارت مهمة REST تستغرق وقتًا أطول مما تريده الإدارة.

• القرار: إبقاء OTP وتحديثات الطلبات وWhatsApp على REST، ونقل رسائل كشوف الحساب الشهرية إلى bind من نوع transceiver عبر SMPP.
• التجهيز: يسجّل الفريق عنواني IP مصدر، ويؤكد أسماء المرسل لكل دولة، ويتفق على الإنتاجية وعدد جلسات الـ bind.
• البناء: خدمة SMPP صغيرة تستخدم مكتبة مفتوحة المصدر، وتكتب التقارير في جدول الحالات نفسه الذي يستخدمه الـ webhook، وتوفّر واجهة الإرسال الداخلية نفسها المستخدمة في مسار REST.
• الاختبار: يُتحقق من أن كشوف الحساب العربية تُرسل بترميز UCS-2 مع دمج صحيح للأجزاء على عدة هواتف.
• الإطلاق: تنتقل دولة واحدة أولًا. وبعد مقارنة التسليم وتوقيت التقارير بخط الأساس في REST، تلحق بها الدولتان الأخريان، مع إبقاء REST مسارًا احتياطيًا.

أخطاء شائعة

• اختيار SMPP للوجاهة. إذا كان REST يلبي حجمك، فإن SMPP لا يضيف سوى العمل.
• التشغيل بنافذة حجمها 1 ثم لوم المزوّد على ضعف الإنتاجية.
• عدم تأكيد deliver_sm، ما يؤدي إلى إعادة إرسال التقارير والتقييد.
• إعادة الاتصال في حلقة متلاحقة بعد الانقطاع، وهو ما قد يبدو كهجوم.
• الخلط بين short_message وmessage_payload في PDU واحدة، ما يسبب أخطاء في الطول.
• SMPP غير مشفّر عبر الإنترنت، ما يكشف بيانات الاعتماد والمحتوى.
• نموذجان للحالات في الإعداد الهجين، فتتعارض التقارير.
• الحدود: يصف هذا الدليل الممارسات الشائعة. أحجام النوافذ والمعدلات ومنافذ TLS وتفاصيل التقارير تختلف بحسب المزوّد والحساب، فتأكد منها أثناء التجهيز.

كيف تساعدك OmniChannels.ai

توفّر OmniChannels.ai الخيارين معًا. تستخدم واجهة REST على https://api.broadnet.me مصادقة Bearer token، وتغطي SMS إلى جانب WhatsApp وRCS وMessenger وInstagram وTelegram وEmail وPush، مع إرسال حالات التسليم إلى الـ webhook لديك بصيغة واحدة. ولرسائل SMS عالية الحجم، تُجهَّز جلسات SMPP 3.4 عبر TLS لكل حساب، مع قائمة سماح لعناوين IP المصدر، وتستخدم مسارات SMS نفسها عبر الربط المباشر بين BroadNet والمشغّلين. ويمكن للموزّعين وشركاء الجملة الحصول على جلسات bind مخصصة. ابدأ بـ وثائق SMPP أو دليل البدء السريع، أو اطّلع على نظرة عامة للمطورين.