كيفية استلام تقارير التسليم عبر واجهة برمجة تطبيقات SMPP

إعداد اتصال عميل SMPP API

يتطلب استلام تقارير تسليم SMPP اتصالًا مستقرًا لعميل SMPP API مع SMSC. يبسط Ozeki SMS Gateway هذه العملية، لكن فهم العمليات على مستوى البروتوكول ضروري للمستخدمين المتقدمين واستكشاف الأخطاء وإصلاحها.

1. تكوين عميل SMPP في Ozeki SMS Gateway

لإعداد اتصال عميل SMPP API في Ozeki SMS Gateway لاستلام تقارير التسليم، اتبع هذه الخطوات:

1. الوصول إلى وحدة التحكم الإدارية: سجل الدخول إلى واجهة الويب لـ Ozeki SMS Gateway باستخدام حساب المسؤول (اسم المستخدم الافتراضي: "admin").
2. إنشاء اتصال جديد: في لوحة "الاتصالات"، انقر على "إضافة اتصال جديد" وحدد "عميل SMPP" من قسم "اتصالات SMS عبر IP".
3. إدخال إعدادات SMPP: قدم التفاصيل التالية، والتي يوفرها عادةً مزود خدمة الرسائل القصيرة الخاص بك:
   • اسم المضيف: عنوان IP أو اسم المضيف لـ SMSC (مثال: "192.168.1.1").
   • رقم المنفذ: منفذ TCP/IP لاتصال SMPP (الافتراضي هو 9500، تحقق من مزود الخدمة).
   • اسم المستخدم (معرف النظام): معرف حساب SMSC الخاص بك (مثال: "smppuser").
   • كلمة المرور: كلمة المرور لمعرف النظام (مثال: "password123").
   • إصدار SMPP: حدد v3.4 لدعم جهاز الإرسال والاستقبال، وهو الأمثل للإرسال والاستقبال.
   • نوع النظام: اختياري، غالبًا ما يكون "SMPP"، كما يحدده المزود.
   • عنوان المرسل: رقم الهاتف الافتراضي لرسائل SMS الصادرة (مثال: "+1234567890").
   • نطاق العناوين: اختياري، يستخدم لاستلام الرسائل أو التقارير لأرقام محددة.
4. وضع الربط: حدد "جهاز الإرسال والاستقبال" لتمكين إرسال رسائل SMS واستلام تقارير التسليم عبر اتصال واحد.
5. تمكين تقارير التسليم: في علامة التبويب "متقدم"، حدد "طلب تقرير التسليم" لضمان إرسال SMSC لتقارير التسليم للرسائل المرسلة.
6. إعدادات Keepalive: قم بتمكين "إرسال حزم keepalive" للحفاظ على الاتصال لاستقبال التقارير المستمرة.
7. تمكين التسجيل: في علامة التبويب "متقدم"، قم بتمكين "تسجيل أحداث الاتصال" لتسجيل PDUs الخاصة بـ SMPP لتصحيح الأخطاء.
8. حفظ والتوصيل: انقر على "موافق" للحفظ، ثم انقر على "توصيل" لبدء اتصال SMPP API.

تعد هذه الإعدادات Ozeki SMS Gateway لإقامة اتصال SMPP API باستخدام PDU bind_transceiver، مما يتيح استلام تقارير التسليم.

2. PDU bind_transceiver

يقوم PDU bind_transceiver بمصادقة عميل SMPP مع SMSC ويقيم اتصالًا لكل من إرسال رسائل SMS واستلام تقارير التسليم. إنها الخطوة الأولى في تمكين وظائف SMPP API.

هيكل PDU bind_transceiver

طول الأمر: 4 بايت (الطول الكلي لـ PDU)
معرف الأمر: 0x00000009 (bind_transceiver)
حالة الأمر: 0x00000000 (يتم تعيينه على 0 للطلبات)
رقم التسلسل: معرف فريد لـ PDU
معرف النظام: اسم المستخدم للمصادقة (مثال: "smppuser")
كلمة المرور: كلمة المرور للمصادقة (مثال: "password123")
نوع النظام: اختياري، غالبًا ما يكون "SMPP"
إصدار الواجهة: إصدار SMPP (مثال: 0x34 لـ v3.4)
نطاق العناوين: اختياري، لاستلام الرسائل أو التقارير

مثال PDU bind_transceiver (بالنظام الست عشري):

0000002F 00000009 00000000 00000001 736D70707573657200 70617373776F726431323300 534D505000 34 00

شرح:

• طول الأمر (0000002F): الطول الكلي لـ PDU (47 بايت).
• معرف الأمر (00000009): يحدد PDU كـ bind_transceiver.
• حالة الأمر (00000000): يتم تعيينه على 0 للطلب.
• رقم التسلسل (00000001): معرف فريد لتتبع PDU.
• معرف النظام (736D70707573657200): ASCII لـ "smppuser" مع نهاية فارغة.
• كلمة المرور (70617373776F726431323300): ASCII لـ "password123" مع نهاية فارغة.
• نوع النظام (534D505000): ASCII لـ "SMPP" مع نهاية فارغة.
• إصدار الواجهة (34): يشير إلى SMPP v3.4.
• نطاق العناوين (00): فارغ، لأنه اختياري.

يستجيب SMSC بـ PDU bind_transceiver_resp. تشير حالة الأمر 0x00000000 إلى اتصال ناجح. يقوم Ozeki SMS Gateway بتسجيل هذا التفاعل في سجل "أحداث الاتصال"، وهو مفيد للتحقق من الاتصال.

الحفاظ على اتصال SMPP API

يعد الاتصال المستقر ضروريًا لاستلام تقارير تسليم SMPP، حيث يمكن أن تؤدي الانقطاعات إلى فقدان تحديثات الحالة. يتم استخدام PDU enquire_link للحفاظ على الاتصال نشطًا.

PDU enquire_link

يتم إرسال PDU enquire_link بشكل دوري بواسطة عميل SMPP لتأكيد حالة الاتصال، مما يمنع قطع الاتصال بسبب عدم النشاط.

هيكل PDU enquire_link

طول الأمر: 0x00000010 (16 بايت)
معرف الأمر: 0x00000015 (enquire_link)
حالة الأمر: 0x00000000 (يتم تعيينه على 0 للطلبات)
رقم التسلسل: معرف فريد لـ PDU

مثال PDU enquire_link (بالنظام الست عشري):

00000010 00000015 00000000 00000002

شرح:

• طول الأمر (00000010): الطول الكلي (16 بايت).
• معرف الأمر (00000015): يحدد PDU كـ enquire_link.
• حالة الأمر (00000000): يتم تعيينه على 0 للطلب.
• رقم التسلسل (00000002): معرف فريد لتتبع PDU.

يستجيب SMSC بـ PDU enquire_link_resp لتأكيد حالة الاتصال. في Ozeki SMS Gateway، يتيح تمكين "إرسال حزم keepalive" في علامة التبويب "الاتصال" إرسال PDUs enquire_link تلقائيًا (مثال: كل 30 ثانية). هذا أمر بالغ الأهمية للحفاظ على اتصال SMPP API موثوق لاستقبال تقارير التسليم.

استلام تقارير تسليم SMPP

يتم استلام تقارير تسليم SMPP عبر وحدة deliver_sm PDU، والتي يرسلها SMSC إلى العميل للإبلاغ عن حالة الرسالة النصية المرسلة سابقًا. تحتوي وحدة PDU على تفاصيل مثل معرف الرسالة، حالة التسليم، والطابع الزمني.

وحدة deliver_sm PDU لتقارير التسليم

تُستخدم وحدة deliver_sm PDU لكل من الرسائل النصية الواردة وتقارير التسليم. بالنسبة لتقارير التسليم، يتم تعيين حقل ESM Class في وحدة PDU للإشارة إلى إيصال التسليم (عادةً 0x04)، ويتضمن محتوى الرسالة تقريرًا منظمًا بمعلومات الحالة.

هيكل وحدة deliver_sm PDU (تقرير التسليم)

طول الأمر: متغير (يعتمد على طول التقرير)
معرف الأمر: 0x00000005 (deliver_sm)
حالة الأمر: 0x00000000 (يتم تعيينه إلى 0 للطلبات)
رقم التسلسل: معرف فريد لوحدة PDU
نوع الخدمة: اختياري، غالبًا ما يكون فارغًا
نوع رقم المصدر: نوع رقم المرسل (SMSC أو المستلم)
مؤشر خطة ترقيم المصدر: مؤشر خطة الترقيم للمرسل
عنوان المصدر: رقم هاتف المرسل أو معرف SMSC
نوع رقم الوجهة: نوع رقم المستلم (ESME)
مؤشر خطة ترقيم الوجهة: مؤشر خطة الترقيم للمستلم
عنوان الوجهة: رقم هاتف المستلم (مثل الرقم الافتراضي لـ ESME)
فئة ESM: 0x04 (تشير إلى إيصال التسليم)
ترميز البيانات: ترميز الأحرف (مثل 0x00 لـ GSM 7-bit)
الرسالة القصيرة: نص تقرير التسليم (مثل "id:12345 sub:001 dlvrd:001 submit date:2505270415 done date:2505270416 stat:DELIVRD err:000")
المعاملات الاختيارية: حقول TLV مثل receipted_message_id و message_state

مثال لوحدة deliver_sm PDU (بالهيكساديسيمال):

0000007A 00000005 00000000 00000003 00 01 01 2B3938373635343332313000 01 01 2B3132333435363738393000 04 00 00 00 00 69643A3132333435207375623A30303120646C7672643A303031207375626D697420646174653A3235303532373034313520646F6E6520646174653A3235303532373034313620737461743A44454C49565244206572723A303030

شرح:

• طول الأمر (0000007A): الطول الإجمالي (122 بايت).
• معرف الأمر (00000005): يُحدد وحدة PDU كـ deliver_sm.
• حالة الأمر (00000000): يتم تعيينه إلى 0 للطلب.
• رقم التسلسل (00000003): معرف فريد لتتبع وحدة PDU.
• نوع الخدمة (00): فارغ، لأنه اختياري.
• نوع رقم المصدر (01): رقم دولي.
• مؤشر خطة ترقيم المصدر (01): خطة ترقيم ISDN/الهاتف.
• عنوان المصدر (2B3938373635343332313000): ASCII لـ "+9876543210" (رقم المستلم).
• نوع رقم الوجهة (01): رقم دولي.
• مؤشر خطة ترقيم الوجهة (01): خطة ترقيم ISDN/الهاتف.
• عنوان الوجهة (2B3132333435363738393000): ASCII لـ "+1234567890" (رقم ESME).
• فئة ESM (04): تشير إلى إيصال التسليم.
• ترميز البيانات (00): ترميز GSM 7-bit.
• الرسالة القصيرة: ASCII لـ "id:12345 sub:001 dlvrd:001 submit date:2505270415 done date:2505270416 stat:DELIVRD err:000".

حقول تقرير التسليم:

• id: معرف الرسالة المخصص من قبل SMSC (مثل "12345").
• sub: عدد المستلمين (مثل "001").
• dlvrd: عدد الرسائل المسلمة (مثل "001").
• submit date: الطابع الزمني للإرسال (مثل "2505270415" لـ 27 مايو 2025، 04:15).
• done date: الطابع الزمني للتسليم (مثل "2505270416").
• stat: حالة التسليم (مثل "DELIVRD" للتسليم، "UNDELIV" لغير القابل للتسليم).
• err: رمز الخطأ (مثل "000" لعدم وجود خطأ).

يجب على العميل الرد بوحدة deliver_sm_resp PDU لتأكيد الاستلام. يتعامل Ozeki SMS Gateway مع هذا تلقائيًا ويوجه تقرير التسليم إلى التطبيق أو قاعدة البيانات المكونة، ويسجله في لوحة "الرسائل".

تكوين Ozeki SMS Gateway لاستقبال تقارير التسليم

لضمان معالجة Ozeki SMS Gateway لتقارير تسليم SMPP بشكل صحيح:

1. تمكين تقارير التسليم: في تكوين عميل SMPP، حدد "طلب تقرير التسليم" في علامة التبويب "متقدم" لإرشاد SMSC لإرسال تقارير التسليم.
2. إعداد الرقم الافتراضي: تأكد من تكوين SMSC لإرسال تقارير التسليم إلى الرقم الافتراضي أو نطاق العناوين المحدد في إعدادات عميل SMPP.
3. تكامل قاعدة البيانات: قم بتكوين Ozeki لتخزين تقارير التسليم في قاعدة بيانات عن طريق تعديل عبارة SQL SELECT في تكوين "مستخدم قاعدة البيانات" (مثل "SELECT id, sender, receiver, msg, msgtype, status FROM ozekimessagein WHERE msgtype='DLR'").
4. التسجيل: تمكين تسجيل وحدة PDU لمراقبة وحدات deliver_sm الواردة لتصحيح الأخطاء.

مع هذه الإعدادات، سيقوم Ozeki SMS Gateway بمعالجة وتخزين تقارير التسليم، مما يجعلها متاحة للتطبيقات أو لمزيد من التحليل.

عندما لا تكون جلسة SMPP API مطلوبة بعد الآن، يرسل العميل وحدة unbind PDU لإنهاء الاتصال بشكل سلس.

وحدة unbind PDU

تشير وحدة unbind PDU إلى SMSC لإغلاق جلسة SMPP.

هيكل وحدة unbind PDU

طول الأمر: 0x00000010 (16 بايت)
معرف الأمر: 0x00000006 (unbind)
حالة الأمر: 0x00000000 (يتم تعيينه إلى 0 للطلبات)
رقم التسلسل: معرف فريد لوحدة PDU

مثال لوحدة unbind PDU (بالهيكساديسيمال):

00000010 00000006 00000000 00000004

شرح:

• طول الأمر (00000010): الطول الإجمالي (16 بايت).
• معرف الأمر (00000006): يُحدد وحدة PDU كـ unbind.
• حالة الأمر (00000000): يتم تعيينه إلى 0 للطلب.
• رقم التسلسل (00000004): معرف فريد لتتبع وحدة PDU.

يستجيب SMSC بوحدة unbind_resp PDU، مؤكدًا إنهاء الجلسة. في Ozeki SMS Gateway، يمكن بدء ذلك بالنقر على "قطع الاتصال" في لوحة "الاتصالات".

أفضل الممارسات لمعالجة تقارير التسليم في واجهة برمجة تطبيقات SMPP

لتحسين تنفيذ واجهة برمجة تطبيقات SMPP لاستقبال تقارير التسليم مع بوابة Ozeki للرسائل القصيرة:

• طلب تقارير التسليم: قم دائمًا بتمكين خيار "طلب تقرير التسليم" عند إرسال الرسائل القصيرة لضمان إنشاء التقارير من قبل مركز خدمة الرسائل القصيرة (SMSC).
• مراقبة السجلات: استخدم سجلات وحدات بيانات البروتوكول (PDU) الخاصة بـ SMPP لاستكشاف المشكلات المتعلقة بوحدات deliver_sm، خاصةً فيما يتعلق بتقارير التسليم.
• استخدام وضع الترانسيڤر: يُفضل استخدام وضع الترانسيڤر للكفاءة، حيث يدعم إرسال الرسائل القصيرة واستقبال تقارير التسليم.
• اتصالات آمنة: استخدم SMPPS (SMPP عبر SSL/TLS) إذا كان مزود الخدمة يدعمه لضمان نقل آمن لتقارير التسليم.
• تحليل تقارير التسليم: قم بتكوين التطبيقات لتحليل حقل الرسالة القصيرة في وحدة deliver_sm لاستخراج معلومات الحالة (مثل "DELIVRD" أو "UNDELIV") للحصول على رؤى قابلة للتنفيذ.

يتضمن استقبال تقارير تسليم SMPP باستخدام واجهة برمجة تطبيقات SMPP مع بوابة Ozeki للرسائل القصيرة إنشاء اتصال بوحدة bind_transceiver، والحفاظ عليه بوحدات enquire_link، ومعالجة تقارير التسليم عبر وحدة deliver_sm. من خلال تكوين بوابة Ozeki للرسائل القصيرة بشكل صحيح وفهم بروتوكول SMPP الأساسي، يمكن للمطورين بناء أنظمة موثوقة لتتبع حالة تسليم الرسائل القصيرة. توفر متانة واجهة برمجة تطبيقات SMPP والتكوين المرن لـ Ozeki خيارًا ممتازًا لإدارة تقارير التسليم في تطبيقات الرسائل القصيرة عالية الحجم. لمزيد من التفاصيل، يُرجى الرجوع إلى وثائق بوابة Ozeki للرسائل القصيرة أو الاتصال بمزود خدمة الرسائل القصيرة للحصول على متطلبات التكوين المحددة.