مرجع واجهة برمجة تطبيقات SMS-C

← العودة إلى فهرس الوثائق | الملف التعريفي الرئيسي

مرجع كامل لجميع نقاط نهاية واجهة برمجة تطبيقات SMS-C REST مع أمثلة للطلبات/الاستجابات.

جدول المحتويات

نظرة عامة على واجهة برمجة التطبيقات
المصادقة
تنسيقات الاستجابة الشائعة
نقطة نهاية الحالة
واجهة برمجة تطبيقات قائمة الرسائل
واجهة برمجة تطبيقات SMS PDU الخام
واجهة برمجة تطبيقات إدارة الموقع
واجهة برمجة تطبيقات تسجيل الواجهة الأمامية
واجهة برمجة تطبيقات تسجيل الأحداث
واجهة برمجة تطبيقات رسا��ل MMS
واجهة برمجة تطبيقات أحداث SS7
رموز الأخطاء
تحديد معدل الطلبات
أفضل الممارسات

نظرة عامة على واجهة برمجة التطبيقات

تقدم واجهة برمجة تطبيقات SMS-C REST وصولاً برمجياً إلى وظائف تقديم الرسائل وتوجيهها وإدارتها.

عنوان URL الأساسي

https://api.example.com:8443/api

المنفذ الافتراضي: 8443 (قابل للتكوين)
البروتوكول: HTTPS (يتطلب TLS في الإنتاج)

نوع المحتوى

تستخدم جميع الطلبات والاستجابات JSON:

Content-Type: application/json

إصدار واجهة برمجة التطبيقات

الإصدار الحالي من واجهة برمجة التطبيقات هو 1 (ضمني). ستستخدم الإصدارات المستقبلية ترميز الإصدار في عنوان URL:

https://api.example.com:8443/api/v2/...

المصادقة

شهادات عميل TLS (موصى بها)

يجب أن تستخدم عمليات النشر في الإنتاج مصادقة شهادة عميل TLS:

curl --cert client.crt --key client.key \
  https://api.example.com:8443/api/status

مصادقة مفتاح واجهة برمجة التطبيقات

مصادقة مفتاح واجهة برمجة التطبيقات المخصصة عبر رأس X-API-Key:

curl -H "X-API-Key: your_api_key_here" \
  https://api.example.com:8443/api/status

قائمة بيضاء لعناوين IP

تقييد الوصول إلى واجهة برمجة التطبيقات لعناوين IP الموثوقة على مستوى جدار الحماية.

تنسيقات الاستجابة الشائعة

استجابة النجاح

{
  "data": {
    ...
  }
}

استجابة الخطأ

{
  "errors": {
    "detail": "رسالة خطأ تصف ما حدث خطأ"
  }
}

استجابة القائمة

{
  "data": [
    {...},
    {...}
  ]
}

نقطة نهاية الحالة

نقطة فحص الصحة لمراقبة وتحميل الموازنات.

الحصول على حالة واجهة برمجة التطبيقات

الطلب:

GET /api/status

الاستجابة (200 OK):

{
  "status": "ok",
  "application": "OmniMessage",
  "timestamp": "2025-10-30T12:34:56Z"
}

مثال:

curl https://api.example.com:8443/api/status

حالات الاستخدام:

فحوصات صحة موازن التحميل
مراقبة اتصال النظام
التحقق من توفر الخدمة

واجهة برمجة تطبيقات قائمة الرسائل

نقاط نهاية أساسية لتقديم الرسائل وإدارتها.

قائمة الرسائل

استرجاع الرسائل من قائمة الانتظار.

الطلب:

GET /api/messages

رؤوس اختيارية:

smsc: frontend_name - تصفية حسب SMSC الوجهة
include-unrouted: true|false|1|0 - تضمين الرسائل بدون تسجيل الموقع (الافتراضي: false)
- false (افتراضي): إرجاع الرسائل التي تحتوي على توجيه صريح أو تسجيل موقع فقط
- true: تضمين الرسائل بدون تسجيل الموقع (وضع متوافق مع الإصدارات السابقة)

معلمات الاستعلام:

status - تصفية حسب الحالة: pending, delivered, expired, dropped
source_smsc - تصفية حسب SMSC المصدر
dest_smsc - تصفية حسب SMSC الوجهة
limit - تحديد النتائج (الافتراضي: 100، الحد الأقصى: 1000)
offset - إزاحة الصفحات

الاستجابة (200 OK):

{
  "data": [
    {
      "id": 12345,
      "source_msisdn": "+15551234567",
      "destination_msisdn": "+447700900000",
      "message_body": "Hello World",
      "source_smsc": "api_client",
      "dest_smsc": "uk_gateway",
      "status": "pending",
      "send_time": "2025-10-30T12:00:00Z",
      "deliver_time": null,
      "delivery_attempts": 0,
      "inserted_at": "2025-10-30T12:00:00Z"
    }
  ]
}

أمثلة:

الحصول على الرسائل المعلقة لـ SMSC معين (فقط مع توجيه صريح أو موقع):

curl -H "smsc: uk_gateway" \
  https://api.example.com:8443/api/messages

الحصول على الرسائل المعلقة بما في ذلك الرسائل غير الموجهة (متوافق مع الإصدارات السابقة):

curl -H "smsc: uk_gateway" \
  -H "include-unrouted: true" \
  https://api.example.com:8443/api/messages

الحصول على جميع الرسائل التي تم تسليمها:

curl "https://api.example.com:8443/api/messages?status=delivered&limit=50"

الحصول على رسالة واحدة

استرجاع تفاصيل رسالة معينة.

الطلب:

GET /api/messages/:id

الاستجابة (200 OK):

{
  "data": {
    "id": 12345,
    "source_msisdn": "+15551234567",
    "destination_msisdn": "+447700900000",
    "message_body": "Hello World",
    "source_smsc": "api_client",
    "dest_smsc": "uk_gateway",
    "source_imsi": null,
    "dest_imsi": null,
    "message_parts": 1,
    "message_part_number": 1,
    "tp_data_coding_scheme": "00",
    "tp_user_data_header": null,
    "status": "pending",
    "send_time": "2025-10-30T12:00:00Z",
    "deliver_time": null,
    "expires": "2025-10-31T12:00:00Z",
    "deadletter": false,
    "delivery_attempts": 0,
    "charge_failed": false,
    "deliver_after": "2025-10-30T12:00:00Z",
    "raw_data_flag": false,
    "raw_sip_flag": false,
    "raw_pdu": null,
    "inserted_at": "2025-10-30T12:00:00Z",
    "updated_at": "2025-10-30T12:00:00Z"
  }
}

مثال:

curl https://api.example.com:8443/api/messages/12345

تقديم رسالة (متزامنة)

تقديم رسالة واستلام معرف الرسالة على الفور.

الطلب:

POST /api/messages
Content-Type: application/json

الجسم:

{
  "source_msisdn": "+15551234567",
  "destination_msisdn": "+447700900000",
  "message_body": "Hello World",
  "source_smsc": "api_client"
}

الحقول الاختيارية:

dest_smsc - تجاوز قرار التوجيه
send_time - جدولة للتسليم في المستقبل (ISO 8601)
message_parts - إجمالي الأجزاء لرسالة متعددة الأجزاء
message_part_number - رقم الجزء (مؤشر من 1)
tp_data_coding_scheme - SMS DCS (الافتراضي: "00")
source_imsi - IMSI المشترك المصدر
dest_imsi - IMSI المشترك الوجهة

الاستجابة (201 تم الإنشاء):

{
  "data": {
    "id": 12345,
    "source_msisdn": "+15551234567",
    "destination_msisdn": "+447700900000",
    "message_body": "Hello World",
    "source_smsc": "api_client",
    "dest_smsc": "uk_gateway",
    "status": "pending",
    "send_time": "2025-10-30T12:00:00Z",
    "inserted_at": "2025-10-30T12:00:00Z"
  }
}

مثال:

curl -X POST https://api.example.com:8443/api/messages \
  -H "Content-Type: application/json" \
  -d '{
    "source_msisdn": "+15551234567",
    "destination_msisdn": "+447700900000",
    "message_body": "Hello World",
    "source_smsc": "api_client"
  }'

الأداء: ~70 رسالة/ثانية، 14 مللي ثانية متوسط وقت الاستجابة

استخدم عندما:

تحتاج إلى معرف الرسالة على الفور
معالجة الرسائل/ثانية
تتطلب تأكيدًا فوريًا

تقديم رسالة (غير متزامنة)

تقديم رسالة مع معدل عالٍ (معالجة دفعات).

الطلب:

POST /api/messages/create_async
Content-Type: application/json

الجسم: نفس نقطة النهاية المتزامنة

الاستجابة (202 مقبول):

{
  "data": {
    "status": "accepted",
    "message": "تمت إضافة الرسالة إلى قائمة الانتظار للمعالجة"
  }
}

مثال:

curl -X POST https://api.example.com:8443/api/messages/create_async \
  -H "Content-Type: application/json" \
  -d '{
    "source_msisdn": "+15551234567",
    "destination_msisdn": "+447700900000",
    "message_body": "رسالة إشعار جماعي",
    "source_smsc": "bulk_api"
  }'

الأداء: ~4,650 رسالة/ثانية، 0.22 مللي ثانية متوسط وقت الاستجابة

الكمون: تظهر الرسالة في قاعدة البيانات خلال 100 مللي ثانية (قاب�� للتكوين)

استخدم عندما:

الرسائل الجماعية ذات الحجم الكبير (> 100 رسالة/ثانية)
لا تحتاج إلى معرف الرسالة في استجابة واجهة برمجة التطبيقات
معدل الإنتاج أكثر أهمية من التأكيد الفوري

تحديث الرسالة

تحديث جزئي لحقول الرسالة.

الطلب:

PATCH /api/messages/:id
Content-Type: application/json

الجسم:

{
  "dest_smsc": "alternate_gateway",
  "deliver_after": "2025-10-30T14:00:00Z"
}

الحقول القابلة للتحديث:

dest_smsc - تغيير الوجهة
deliver_after - تأخير التسليم
message_body - تحديث نص الرسالة
status - تغيير الحالة

الاستجابة (200 OK):

{
  "data": {
    "id": 12345,
    "dest_smsc": "alternate_gateway",
    "deliver_after": "2025-10-30T14:00:00Z",
    ...
  }
}

مثال:

curl -X PATCH https://api.example.com:8443/api/messages/12345 \
  -H "Content-Type: application/json" \
  -d '{
    "dest_smsc": "backup_gateway"
  }'

وضع علامة على الرسالة كتم تسليمها

وضع علامة على رسالة على أنها تم تسليمها بنجاح.

الطلب:

POST /api/messages/:id/mark_delivered
Content-Type: application/json

الجسم:

{
  "dest_smsc": "uk_gateway"
}

الاستجابة (200 OK):

{
  "data": {
    "id": 12345,
    "status": "delivered",
    "deliver_time": "2025-10-30T12:05:30Z",
    "dest_smsc": "uk_gateway",
    ...
  }
}

مثال:

curl -X POST https://api.example.com:8443/api/messages/12345/mark_delivered \
  -H "Content-Type: application/json" \
  -d '{
    "dest_smsc": "uk_gateway"
  }'

حالة الاستخدام: يتم استدعاؤها بواسطة الأنظمة الأمامية بعد التسليم الناجح

زيادة محاولة التسليم

زيادة عداد إعادة المحاولة وتطبيق التراجع الأسي.

الطلب:

PUT /api/messages/:id

الاستجابة (200 OK):

{
  "data": {
    "id": 12345,
    "delivery_attempts": 2,
    "deliver_after": "2025-10-30T12:08:00Z",
    ...
  }
}

حساب التراجع:

deliver_after = now + 2^(delivery_attempts) minutes

مثال:

curl -X PUT https://api.example.com:8443/api/messages/12345

حالة الاست��دام: يتم استدعاؤها بواسطة الواجهة الأمامية بعد فشل التسليم لجدولة إعادة المحاولة

حذف الرسالة

إزالة الرسالة من قائمة الانتظار.

الطلب:

DELETE /api/messages/:id

الاستجابة (204 لا توجد محتويات)

مثال:

curl -X DELETE https://api.example.com:8443/api/messages/12345

تحذير: يؤدي حذف الرسائل إلى إزالتها بشكل دائم. استخدم بحذر.

واجهة برمجة تطبيقات SMS PDU الخام

تقديم رسائل SMS كـ PDU (وحدة بيانات البروتوكول) خام لتحقيق أقصى توافق مع الأنظمة القديمة.

تقديم SMS خام (متزامن)

الطلب:

POST /api/messages_raw
Content-Type: application/json

الجسم:

{
  "pdu": "0001000B916407007009F0000004D4F29C0E",
  "source_smsc": "legacy_system"
}

تنسيق PDU: SMS TPDU (وحدة بيانات البروتوكول للنقل) مشفرة بتنسيق Hex

الاستجابة (201 تم الإنشاء):

{
  "data": {
    "id": 12346,
    "source_msisdn": "+447700900000",
    "destination_msisdn": "+447700900000",
    "message_body": "اختبار",
    "source_smsc": "legacy_system",
    "raw_pdu": "0001000B916407007009F0000004D4F29C0E",
    ...
  }
}

مثال:

curl -X POST https://api.example.com:8443/api/messages_raw \
  -H "Content-Type: application/json" \
  -d '{
    "pdu": "0001000B916407007009F0000004D4F29C0E",
    "source_smsc": "legacy_system"
  }'

تقديم SMS خام (غير متزامن)

الطلب:

POST /api/messages_raw/async
Content-Type: application/json

الجسم: نفس المتزامن

الاستجابة (202 مقبول):

{
  "data": {
    "status": "accepted",
    "message": "تمت إضافة PDU إلى قائمة الانتظار للمعالجة"
  }
}

مثال:

curl -X POST https://api.example.com:8443/api/messages_raw/async \
  -H "Content-Type: application/json" \
  -d '{
    "pdu": "0001000B916407007009F0000004D4F29C0E",
    "source_smsc": "legacy_gateway"
  }'

معالجة PDU

يقوم النظام تلقائيًا بـ:

فك تشفير PDU باستخدام معايير SMS (3GPP TS 23.040)
استخراج أرقام الهواتف، نص الرسالة، DCS
اكتشاف تقارير التسليم (CP-ACK، RP-ACK، إلخ)
إجراء بحث IMSI إلى MSISDN إذا لزم الأمر
تطبيق قواعد التوجيه
تخزين PDU الأصلي للرجوع إليه

كشف تقرير التسليم:

CP-ACK، CP-ERROR - تأكيدات بروتوكول الاتصال
RP-ACK، RP-ERROR، RP-SMMA - استجابات بروتوكول الترحيل
يتم تسجيل تقارير التسليم ولكن لا يتم تخزينها كرسائل

واجهة برمجة تطبيقات إدارة الموقع

إدارة معلومات موقع المشترك لتسليم الرسائل الموجهة إلى الهاتف المحمول.

قائمة المواقع

الطلب:

GET /api/locations

الاستجابة (200 OK):

{
  "data": [
    {
      "id": 1,
      "msisdn": "+15551234567",
      "imsi": "001001000000001",
      "location": "msc1.region1.example.com",
      "ran_location": "cell_tower_12345",
      "imei": "123456789012345",
      "ims_capable": true,
      "csfb": false,
      "registered": true,
      "expires": "2025-10-30T13:00:00Z",
      "user_agent": "Samsung Galaxy",
      "inserted_at": "2025-10-30T12:00:00Z",
      "updated_at": "2025-10-30T12:00:00Z"
    }
  ]
}

مثال:

curl https://api.example.com:8443/api/locations

الحصول على الموقع

الطلب:

GET /api/locations/:id

الاستجابة (200 OK):

{
  "data": {
    "id": 1,
    "msisdn": "+15551234567",
    "imsi": "001001000000001",
    ...
  }
}

مثال:

curl https://api.example.com:8443/api/locations/1

إنشاء/تحديث الموقع

إنشاء موقع جديد أو تحديث الموقع الموجود بناءً على IMSI (معرف فريد).

الطلب:

POST /api/locations
Content-Type: application/json

الجسم:

{
  "msisdn": "+15551234567",
  "imsi": "001001000000001",
  "location": "msc1.region1.example.com",
  "ran_location": "cell_tower_12345",
  "imei": "123456789012345",
  "ims_capable": true,
  "csfb": false,
  "registered": true,
  "expires": "2025-10-30T13:00:00Z",
  "user_agent": "Samsung Galaxy"
}

الحقول المطلوبة:

imsi - معرف المشترك الفريد
msisdn - رقم الهاتف

الحقول الاختيارية:

location - عنوان MSC/VLR
ran_location - معرف برج/قطاع الخلية
imei - معرف الجهاز
ims_capable - قدرة IMS VoLTE
csfb - علامة التراجع إلى الدائرة
registered - مسجل حاليًا
expires - انتهاء التسجيل
user_agent - طراز/معلومات الجهاز

الاستجابة (201 تم الإنشاء أو 200 OK):

{
  "data": {
    "id": 1,
    "msisdn": "+15551234567",
    ...
  }
}

مثال:

curl -X POST https://api.example.com:8443/api/locations \
  -H "Content-Type: application/json" \
  -d '{
    "msisdn": "+15551234567",
    "imsi": "001001000000001",
    "location": "msc1.region1.example.com",
    "ims_capable": true,
    "registered": true
  }'

حالة الاستخدام: يتم استدعاؤها بواسطة أنظمة إدارة الحركة (HSS، MME، إلخ) عندما يسجل المشترك

تحديث الموقع

الطلب:

PATCH /api/locations/:id
Content-Type: application/json

الجسم: تحديث جزئي مع أي حقول موقع

الاستجابة (200 OK):

{
  "data": {
    "id": 1,
    ...
  }
}

مثال:

curl -X PATCH https://api.example.com:8443/api/locations/1 \
  -H "Content-Type: application/json" \
  -d '{
    "location": "msc2.region2.example.com",
    "ran_location": "cell_tower_67890"
  }'

حذف الموقع

الطلب:

DELETE /api/locations/:id

الاستجابة (204 لا توجد محتويات)

مثال:

curl -X DELETE https://api.example.com:8443/api/locations/1

حالة الاستخدام: يتم استدعاؤها عندما يقوم المشترك بإلغاء التسجيل أو انتهاء الوقت

واجهة برمجة تطبيقات تسجيل الواجهة الأمامية

تتبع وإدارة اتصالات SMSC للواجهة الأمامية.

قائمة جميع الواجهات الأمامية

الطلب:

GET /api/frontends

الاستجابة (200 OK):

{
  "data": [
    {
      "id": 1,
      "frontend_name": "uk_gateway_1",
      "frontend_type": "smpp",
      "ip_address": "10.0.1.50",
      "hostname": "gateway1.uk.example.com",
      "uptime_seconds": 86400,
      "configuration": {
        "max_throughput": 1000,
        "bind_type": "transceiver"
      },
      "status": "active",
      "expires_at": "2025-10-30T12:02:00Z",
      "last_seen_at": "2025-10-30T12:00:30Z",
      "inserted_at": "2025-10-29T12:00:00Z",
      "updated_at": "2025-10-30T12:00:30Z"
    }
  ]
}

مثال:

curl https://api.example.com:8443/api/frontends

قائمة الواجهات الأمامية النشطة فقط

الطلب:

GET /api/frontends/active

الاستجابة (200 OK): نفس التنسيق، فقط الواجهات الأمامية النشطة

مثال:

curl https://api.example.com:8443/api/frontends/active

حالة الاستخدام: الحصول على قائمة الوجهات المتاحة للتوجيه

الحصول على إحصائيات الواجهة الأمامية

الطلب:

GET /api/frontends/stats

الاستجابة (200 OK):

{
  "data": {
    "active_count": 5,
    "expired_count": 2,
    "unique_frontends": 7,
    "total_registrations": 1523
  }
}

مثال:

curl https://api.example.com:8443/api/frontends/stats

الحصول على تاريخ الواجهة الأمامية

الطلب:

GET /api/frontends/history/:name

الاستجابة (200 OK):

{
  "data": [
    {
      "id": 1,
      "frontend_name": "uk_gateway_1",
      "status": "active",
      "inserted_at": "2025-10-30T12:00:00Z",
      ...
    },
    {
      "id": 2,
      "frontend_name": "uk_gateway_1",
      "status": "expired",
      "inserted_at": "2025-10-29T12:00:00Z",
      ...
    }
  ]
}

مثال:

curl https://api.example.com:8443/api/frontends/history/uk_gateway_1

تسجيل الواجهة الأمامية

تسجيل أو تحديث اتصال الواجهة الأمامية.

الطلب:

POST /api/frontends/register
Content-Type: application/json

الجسم:

{
  "frontend_name": "uk_gateway_1",
  "frontend_type": "smpp",
  "ip_address": "10.0.1.50",
  "hostname": "gateway1.uk.example.com",
  "uptime_seconds": 86400,
  "configuration": {
    "max_throughput": 1000,
    "bind_type": "transceiver",
    "system_id": "gateway1"
  }
}

الحقول المطلوبة:

frontend_name - معرف فريد للواجهة الأمامية
frontend_type - النوع: smpp، sip، http، إلخ.

الحقول الاختيارية:

ip_address - عنوان IP للواجهة الأمامية
hostname - اسم المضيف للواجهة الأمامية
uptime_seconds - وقت التشغيل منذ البداية
configuration - كائن تكوين مخصص

الاستجابة (201 تم الإنشاء):

{
  "data": {
    "id": 1,
    "frontend_name": "uk_gateway_1",
    "status": "active",
    "expires_at": "2025-10-30T12:01:30Z",
    ...
  }
}

مثال:

curl -X POST https://api.example.com:8443/api/frontends/register \
  -H "Content-Type: application/json" \
  -d '{
    "frontend_name": "uk_gateway_1",
    "frontend_type": "smpp",
    "ip_address": "10.0.1.50",
    "hostname": "gateway1.uk.example.com"
  }'

مهلة التسجيل: 90 ثانية (يجب على الواجهات الأمامية إعادة التسجيل كل 60-90 ثانية)

حالة الاستخدام: يتم استدعاؤها بشكل دوري بواسطة الأنظمة الأمامية للحفاظ على الحالة النشطة

واجهة برمجة تطبيقات تسجيل الأحداث

تتبع أحداث دورة حياة الرسالة.

الحصول على أحداث الرسالة

الطلب:

GET /api/events/:message_id

الاستجابة (200 OK):

{
  "data": [
    {
      "event_epoch": 1698672000,
      "name": "message_inserted",
      "description": "تم إدخال الرسالة في قائمة الانتظار",
      "event_source": "node1@server.example.com"
    },
    {
      "event_epoch": 1698672001,
      "name": "message_routed",
      "description": "تم توجيهها إلى uk_gateway عبر route_id=42",
      "event_source": "node1@server.example.com"
    },
    {
      "event_epoch": 1698672005,
      "name": "message_delivered",
      "description": "تم التسليم بنجاح",
      "event_source": "node2@server.example.com"
    }
  ]
}

مثال:

curl https://api.example.com:8443/api/events/12345

أنواع الأحداث:

message_inserted - تم إنشاء الرسالة
message_routed - تم اتخاذ قرار التوجيه
message_delivered - التسليم الناجح
message_failed - فشل التسليم
message_dropped - تم إسقاطه بواسطة التوجيه
auto_reply_sent - تم تفعيل الرد التلقائي
number_translated - تم تطبيق تحويل الرقم
routing_failed - لم يتم العثور على مسار
charging_failed - خطأ في نظام الشحن

تسجيل حدث

الطلب:

POST /api/events
Content-Type: application/json

الجسم:

{
  "message_id": 12345,
  "name": "custom_event",
  "description": "وصف الحدث المخصص",
  "event_source": "external_system"
}

الاستجابة (201 تم الإنشاء):

{
  "data": {
    "message_id": 12345,
    "name": "custom_event",
    "description": "وصف الحدث المخصص",
    "event_source": "external_system",
    "event_epoch": 1698672010
  }
}

مثال:

curl -X POST https://api.example.com:8443/api/events \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": 12345,
    "name": "external_delivery_confirmed",
    "description": "تم التأكيد من قبل النظام السفلي"
  }'

احتفاظ الأحداث: 7 أيام (قابل للتكوين)

واجهة برمجة تطبيقات رسائل MMS

إدارة رسائل خدمة الرسائل متعددة الوسائط (MMS).

قائمة رسائل MMS

الطلب:

GET /api/mms_messages

الاستجابة (200 OK): مشابهة لرسائل SMS مع حقول MMS إضافية

إنشاء رسالة MMS

الطلب:

POST /api/mms_messages
Content-Type: application/json

الجسم:

{
  "source_msisdn": "+15551234567",
  "destination_msisdn": "+447700900000",
  "subject": "صورة",
  "content_type": "image/jpeg",
  "content_location": "https://cdn.example.com/media/12345.jpg",
  "message_size": 524288
}

الاستجابة (201 تم الإنشاء): كائن رسالة MMS كامل

واجهة برمجة تطبيقات أحداث SS7

تتبع أحداث إشارة SS7.

قائمة أحداث SS7

الطلب:

GET /api/ss7_events

الاستجابة (200 OK):

{
  "data": [
    {
      "id": 1,
      "event_type": "MAP_UPDATE_LOCATION",
      "imsi": "001001000000001",
      "msisdn": "+15551234567",
      "timestamp": "2025-10-30T12:00:00Z",
      ...
    }
  ]
}

إنشاء حدث SS7

الطلب:

POST /api/ss7_events
Content-Type: application/json

الجسم:

{
  "event_type": "MAP_UPDATE_LOCATION",
  "imsi": "001001000000001",
  "msisdn": "+15551234567"
}

الاستجابة (201 تم الإنشاء): كائن الحدث الكامل

رموز الأخطاء

رموز حالة HTTP

الرمز	المعنى	الوصف
200	حسنًا	الطلب ناجح
201	تم الإنشاء	تم إنشاء المورد بنجاح
202	مقبول	تم قبول الطلب للمعالجة
204	لا توجد محتويات	تم الحذف بنجاح
400	طلب غير صالح	تنسيق الطلب غير صالح
401	غير مصرح	تتطلب المصادقة
403	محظور	أذونات غير كافية
404	غير موج��د	المورد غير موجود
422	كيان غير قابل للمعالجة	أخطاء التحقق
429	عدد كبير جدًا من الطلبات	تم تجاوز حد المعدل
500	خطأ في الخادم الداخلي	خطأ في الخادم
503	الخدمة غير متاحة	غير متاحة مؤقتًا

تنسيق استجابة الخطأ

{
  "errors": {
    "detail": "فشل التحقق: destination_msisdn مطلوب"
  }
}

رسائل الخطأ الشائعة

الخطأ	السبب	الحل
"destination_msisdn مطلوب"	حقل مطلوب مفقود	تضمين destination_msisdn في الطلب
"تنسيق رقم الهاتف غير صالح"	رقم مشوه	استخدم تنسيق E.164: +15551234567
"الرسالة طويلة جدًا"	تتجاوز حد الحجم	قسمها إلى أجزاء متعددة
"لم يتم العثور على مسار"	فشل التوجيه	تحقق من تكوين التوجيه
"فشل الشحن"	خطأ في OCS	تحقق من اتصال نظام الشحن
"لم يتم العثور على الرسالة"	معرف رسالة غير صالح	تحقق من وجود المعرف
"الواجهة الأمام��ة غير مسجلة"	SMSC غير معروف	سجل الواجهة الأمامية أولاً

تحديد معدل الطلبات

الحدود الافتراضية

نقطة النهاية	الحد	النافذة
POST /api/messages	100 req/sec	لكل IP
POST /api/messages/create_async	1000 req/sec	لكل IP
POST /api/messages_raw	100 req/sec	لكل IP
GET /api/*	1000 req/sec	لكل IP

رؤوس حد المعدل

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1698672060

تجاوز حد المعدل

الاستجابة (429 عدد كبير جدًا من الطلبات):

{
  "errors": {
    "detail": "تم تجاوز حد المعدل. حاول مرة أخرى بعد 5 ثوان."
  }
}

أفضل الممارسات

تقديم الرسائل

استخدم غير متزامن للدفعات: استخدم /create_async لأكثر من 100 رسالة/ثانية
تضمين source_smsc: حدد نظامك دائمًا
تحقق من الأرقام: استخدم تنسيق E.164 (+رمز البلد)
تعامل مع الأخطاء: نفذ منطق إعادة المحاولة لأخطاء 5xx
تحقق من التوجيه: اختبر المسارات قبل التقديم بالجملة

تكامل الواجهة الأمامية

سجل بانتظام: أعد التسجيل كل 60 ثانية
استفسر عن الرسائل: استعلم باستخدام رأس smsc لرسائلك
استخدم include-unrouted بحكمة: بشكل افتراضي، يتم إرجاع الرسائل التي تحتوي على توجيه صريح أو تسجيل موقع فقط. قم بتعيين include-unrouted: true فقط إذا كنت بحاجة إلى سلوك متوافق مع الإصدارات السابقة لاستلام جميع الرسائل غير الموجهة
وضع علامة على التسليم: اتصل دائمًا mark_delivered بعد النجاح
زيادة عند الفشل: استخدم نقطة النهاية PUT لمنطق إعادة المحاولة
راقب الأحداث: تحقق من سجل الأحداث لمشاكل التسليم

الأداء

تجميع الاتصالات: إعادة استخدام اتصالات HTTP
طلبات الدفعة: تجميع رسائل متعددة لكل طلب
المعالجة المتوازية: إجراء مكالمات واجهة برمجة التطبيقات المتزامنة
راقب المقاييس: راقب Prometheus ��لاختناقات
تعيين مهلات: استخدم مهلة 30 ثانية لمكالمات واجهة برمجة التطبيقات

الأمان

استخدم TLS: استخدم دائمًا HTTPS في الإنتاج
تحقق من الشهادات: لا تتخطى التحقق من الشهادات
تدوير مفاتيح واجهة برمجة التطبيقات: قم بتغيير المفاتيح بانتظام
قائمة بيضاء لعناوين IP: تقييد المصادر المعروفة
سجل نشاط واجهة برمجة التطبيقات: راقب الأنماط المشبوهة

معالجة الأخطاء

إعادة المحاولة لأخطاء 5xx: تكون أخطاء الخادم عادةً مؤقتة
لا تعيد المحاولة لأخطاء 4xx: تحتاج أخطاء العميل إلى إصلاحات في التعليمات البرمجية
التراجع الأسي: انتظر لفترة أطول بين إعادة المحاولات
قاطع الدائرة: توقف بعد الفشل المتكرر
تنبيه على الأنماط: راقب معدلات الأخطاء

مثال على التكامل (Python)

import requests
import time

class SMSCClient:
    def __init__(self, base_url, api_key=None):
        self.base_url = base_url
        self.session = requests.Session()
        if api_key:
            self.session.headers.update({"X-API-Key": api_key})

    def submit_message(self, from_num, to_num, text, async_mode=False):
        endpoint = "/messages/create_async" if async_mode else "/messages"
        url = f"{self.base_url}{endpoint}"

        payload = {
            "source_msisdn": from_num,
            "destination_msisdn": to_num,
            "message_body": text,
            "source_smsc": "python_client"
        }

        try:
            response = self.session.post(url, json=payload, timeout=30)
            response.raise_for_status()
            return response.json()["data"]
        except requests.exceptions.RequestException as e:
            print(f"خطأ في واجهة برمجة التطبيقات: {e}")
            return None

    def get_pending_messages(self, smsc_name, include_unrouted=False):
        url = f"{self.base_url}/messages"
        headers = {"smsc": smsc_name}

        # تضمين الرسائل غير الموجهة إذا تم الطلب (وضع متوافق مع الإصدارات السابقة)
        if include_unrouted:
            headers["include-unrouted"] = "true"

        try:
            response = self.session.get(url, headers=headers, timeout=30)
            response.raise_for_status()
            return response.json()["data"]
        except requests.exceptions.RequestException as e:
            print(f"خطأ في واجهة برمجة التطبيقات: {e}")
            return []

    def mark_delivered(self, message_id, smsc_name):
        url = f"{self.base_url}/messages/{message_id}/mark_delivered"
        payload = {"dest_smsc": smsc_name}

        try:
            response = self.session.post(url, json=payload, timeout=30)
            response.raise_for_status()
            return True
        except requests.exceptions.RequestException as e:
            print(f"خطأ في واجهة برمجة التطبيقات: {e}")
            return False

# الاستخدام
client = SMSCClient("https://api.example.com:8443/api", api_key="your_key")

# تقديم رسالة واحدة
result = client.submit_message("+15551234567", "+447700900000", "Hello")
print(f"معرف الرسالة: {result['id']}")

# تقديم رسائل جماعية (غير متزامنة)
for i in range(1000):
    client.submit_message("+15551234567", f"+44770090{i:04d}", f"Bulk {i}", async_mode=True)

# حلقة استعلام الواجهة الأمامية
while True:
    # الحصول على الرسائل مع ��وجيه صريح أو تسجيل الموقع
    messages = client.get_pending_messages("my_gateway")

    # أو استخدم include_unrouted=True لسلوك متوافق مع الإصدارات السابقة
    # messages = client.get_pending_messages("my_gateway", include_unrouted=True)

    for msg in messages:
        # تسليم الرسالة عبر بروتوكولك
        success = deliver_via_smpp(msg)

        if success:
            client.mark_delivered(msg["id"], "my_gateway")
        else:
            # زيادة لإعادة المحاولة
            requests.put(f"{client.base_url}/messages/{msg['id']}")

    time.sleep(5)  # استعلام كل 5 ثوان

سجل تغييرات واجهة برمجة التطبيقات

الإصدار 1 (الحالي)

الإصدار الأول
CRUD قائمة الرسائل
تقديم PDU الخام
إدارة الموقع
تسجيل الواجهة الأمامية
تسجيل الأحداث

الميزات المخطط لها

تقديم الرسائل دفعة واحدة (طلب واحد، رسائل متعددة)
قوالب الرسائل
واجهة برمجة التطبيقات للتسليم المجدول
Webhooks في الوقت الحقيقي للأحداث
نقطة نهاية واجهة برم��ة التطبيقات GraphQL
مصادقة OAuth2

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

جدول المحتويات​

نظرة عامة على واجهة برمجة التطبيقات​

عنوان URL الأساسي​

نوع المحتوى​

إصدار واجهة برمجة التطبيقات​

المصادقة​

شهادات عميل TLS (موصى بها)​

مصادقة مفتاح واجهة برمجة التطبيقات​

قائمة بيضاء لعناوين IP​

تنسيقات الاستجابة الشائعة​

استجابة النجاح​

استجابة الخطأ​

استجابة القائمة​

نقطة نهاية الحالة​

الحصول على حالة واجهة برمجة التطبيقات​

واجهة برمجة تطبيقات قائمة الرسائل​

قائمة الرسائل​

الحصول على رسالة واحدة​

تقديم رسالة (متزامنة)​

تقديم رسالة (غير متزامنة)​

تحديث الرسالة​

وضع علامة على الرسالة كتم تسليمها​

زيادة محاولة التسليم​

حذف الرسالة​

واجهة برمجة تطبيقات SMS PDU الخام​

تقديم SMS خام (متزامن)​

تقديم SMS خام (غير متزامن)​

معالجة PDU​

واجهة برمجة تطبيقات إدارة الموقع​

قائمة المواقع​

الحصول على الموقع​

إنشاء/تحديث الموقع​

تحديث الموقع​

حذف الموقع​

واجهة برمجة تطبيقات تسجيل الواجهة الأمامية​

قائمة جميع الواجهات الأمامية​

قائمة الواجهات الأمامية النشطة فقط​

الحصول على إحصائيات الواجهة الأمامية​

الحصول على تاريخ الواجهة الأمامية​

تسجيل الواجهة الأمامية​

واجهة برمجة تطبيقات تسجيل الأحداث​

الحصول على أحداث الرسالة​

تسجيل حدث​

واجهة برمجة تطبيقات رسائل MMS​

قائمة رسائل MMS​

إنشاء رسالة MMS​

واجهة برمجة تطبيقات أحداث SS7​

قائمة أحداث SS7​

إنشاء حدث SS7​

رموز الأخطاء​

رموز حالة HTTP​

تنسيق استجابة الخطأ​

رسائل الخطأ الشائعة​

تحديد معدل الطلبات​

الحدود الافتراضية​

رؤوس حد المعدل​

تجاوز حد المعدل​

أفضل الممارسات​

تقديم الرسائل​

تكامل الواجهة الأمامية​

الأداء​

الأمان​

معالجة الأخطاء​

مثال على التكامل (Python)​

سجل تغييرات واجهة برمجة التطبيقات​

الإصدار 1 (الحالي)​

الميزات المخطط لها​

جدول المحتويات

نظرة عامة على واجهة برمجة التطبيقات

عنوان URL الأساسي

نوع المحتوى

إصدار واجهة برمجة التطبيقات

المصادقة

شهادات عميل TLS (موصى بها)

مصادقة مفتاح واجهة برمجة التطبيقات

قائمة بيضاء لعناوين IP

تنسيقات الاستجابة الشائعة

استجابة النجاح

استجابة الخطأ

استجابة القائمة

نقطة نهاية الحالة

الحصول على حالة واجهة برمجة التطبيقات

واجهة برمجة تطبيقات قائمة الرسائل

قائمة الرسائل

الحصول على رسالة واحدة

تقديم رسالة (متزامنة)

تقديم رسالة (غير متزامنة)

تحديث الرسالة

وضع علامة على الرسالة كتم تسليمها

زيادة محاولة التسليم

حذف الرسالة

واجهة برمجة تطبيقات SMS PDU الخام

تقديم SMS خام (متزامن)

تقديم SMS خام (غير متزامن)

معالجة PDU

واجهة برمجة تطبيقات إدارة الموقع

قائمة المواقع

الحصول على الموقع

إنشاء/تحديث الموقع

تحديث الموقع

حذف الموقع

واجهة برمجة تطبيقات تسجيل الواجهة الأمامية

قائمة جميع الواجهات الأمامية

قائمة الواجهات الأمامية النشطة فقط

الحصول على إحصائيات الواجهة الأمامية

الحصول على تاريخ الواجهة الأمامية

تسجيل الواجهة الأمامية

واجهة برمجة تطبيقات تسجيل الأحداث

الحصول على أحداث الرسالة

تسجيل حدث

واجهة برمجة تطبيقات رسائل MMS

قائمة رسائل MMS

إنشاء رسالة MMS

واجهة برمجة تطبيقات أحداث SS7

قائمة أحداث SS7

إنشاء حدث SS7

رموز الأخطاء

رموز حالة HTTP

تنسيق استجابة الخطأ

رسائل الخطأ الشائعة

تحديد معدل الطلبات

الحدود الافتراضية

رؤوس حد المعدل

تجاوز حد المعدل

أفضل الممارسات

تقديم الرسائل

تكامل الواجهة الأمامية

الأداء

الأمان

معالجة الأخطاء

مثال على التكامل (Python)

سجل تغييرات واجهة برمجة التطبيقات

الإصدار 1 (الحالي)

الميزات المخطط لها