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

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

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

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

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

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

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

عنوان 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 الموثوقة على مستوى جدار الحماية.

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

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

{
  "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 Created):

{
  "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 Accepted):

{
  "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 No Content)

مثال:

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

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

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

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

إرسال SMS خام (متزامن)

الطلب:

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

الجسم:

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

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

الاستجابة (201 Created):

{
  "data": {
    "id": 12346,
    "source_msisdn": "+447700900000",
    "destination_msisdn": "+447700900000",
    "message_body": "Test",
    "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 Accepted):

{
  "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 Created أو 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 No Content)

مثال:

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 Created):

{
  "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 Created):

{
  "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": "Photo",
  "content_type": "image/jpeg",
  "content_location": "https://cdn.example.com/media/12345.jpg",
  "message_size": 524288
}

الاستجابة (201 Created): كائن رسالة 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 Created): كائن الحدث الكامل

أكواد الأخطاء

أكواد حالة HTTP

الرمز	المعنى	الوصف
200	OK	الطلب ناجح
201	Created	تم إنشاء المورد بنجاح
202	Accepted	تم قبول الطلب للمعالجة
204	No Content	الحذف ناجح
400	Bad Request	تنسيق الطلب غير صالح
401	Unauthorized	المصادقة مطلوبة
403	Forbidden	أذونات غير كافية
404	Not Found	المورد غير موجود
422	Unprocessable Entity	أخطاء التحقق
429	Too Many Requests	تجاوز حد المعدل
500	Internal Server Error	خطأ في الخادم
503	Service Unavailable	غير متوفر مؤقتًا

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

{
  "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 Too Many Requests):

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

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

إرسال الرسائل

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

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

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

الأداء

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

الأمان

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

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

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

مثال على التكامل (بايثون)

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"خطأ API: {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"خطأ API: {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"خطأ API: {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 (موصى بها)​

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

قائمة العناوين الموثوقة​

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

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

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

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

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

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

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

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

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

إرسال رسالة (متزامن)​

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

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

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

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

حذف الرسالة​

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

إرسال SMS خام (متزامن)​

إرسال SMS خام (غير متزامن)​

معالجة PDU​

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

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

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

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

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

حذف الموقع​

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

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

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

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

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

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

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

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

تسجيل حدث​

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

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

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

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

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

إنشاء حدث SS7​

أكواد الأخطاء​

أكواد حالة HTTP​

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

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

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

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

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

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

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

إرسال الرسائل​

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

الأداء​

الأمان​

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

مثال على التكامل (بايثون)​

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

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

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

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

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

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

نوع المحتوى

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

المصادقة

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

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

قائمة العناوين الموثوقة

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

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

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

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

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

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

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

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

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

إرسال رسالة (متزامن)

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

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

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

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

حذف الرسالة

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

إرسال SMS خام (متزامن)

إرسال SMS خام (غير متزامن)

معالجة PDU

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

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

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

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

تحديث الموقع

حذف الموقع

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

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

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

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

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

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

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

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

تسجيل حدث

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

قائمة رسائل MMS

إنشاء رسالة MMS

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

قائمة أحداث SS7

إنشاء حدث SS7

أكواد الأخطاء

أكواد حالة HTTP

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

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

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

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

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

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

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

إرسال الرسائل

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

الأداء

الأمان

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

مثال على التكامل (بايثون)

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

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

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