توثيق واجهة رسالة البرمجية: إرسال الرسائل النصية ورموز التحقق

عن هذه الواجهة

أرسل رموز التحقق والرسائل من تطبيقك، واستعلم عن حالة كل رسالة.

الرابط الأساسي

https://dev.resala.ly/api/v1

ترويسة التوثيق

Authorization: Bearer <API_KEY>

تحتاج مفتاح ربط لتجربة الأمثلة. اضغط «احصل على مفتاح ربط» وسيصلك رمز تحقق على هاتفك.

احصل على مفتاح ربط

إرسال رمز تحقق (pins)

يولّد رمز تحقق ويرسله برسالة نصية ويعيده لك.

POST https://dev.resala.ly/api/v1/pins

معاملات الرابط

`service_name`	اسم تطبيقك، يُلحق بنص الرسالة.
`test`	بيئة تجريبية: لا إرسال ولا خصم.
`len`	عدد أرقام الرمز: 4 أو 5 أو 6 (الافتراضي 6).
`autofill`	رمز التطبيق (App Signature) للتعبئة التلقائية في أندرويد.
`sender`	اسم المرسل المسجّل لحسابك (اختياري). انظر قسم «اسم المرسل».

محتوى الطلب

phone إلزامي رقم المستلم بالصيغة الدولية. الليبي: 091 أو 092 أو 093 أو 094 ثم 7 أرقام. الأرقام غير الليبية تُقبل هنا فقط.

{
  "phone": "218910001234"
}

مثال على الطلب

curl -X POST "https://dev.resala.ly/api/v1/pins?service_name=MyApp" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phone":"218910001234"}'

الرد الناجح (201)

{
  "id": "9b1f5b7e-3f1a-4c2e-8a5e-6f3d2c1b0a9e",
  "pin": "482913",
  "code": "218",
  "region": "LY",
  "number": "910001234",
  "content": "رمز التحقق: 482913 - MyApp",
  "hit_count": 0,
  "created_at": "2026-09-16T12:00:00Z",
  "updated_at": "2026-09-16T12:00:00Z",
  "sender_name": "MyBrand"
}

التحقق من الرمز مسؤوليتك: احفظ pin في خادمك وقارنه بما يدخله المستخدم.

إرسال رسالة عبر قالب (send-template)

يرسل قالباً معتمداً إلى مستلم أو أكثر مع تعويض المتغيّرات.

POST https://dev.resala.ly/api/v1/messages/send-template

معاملات الرابط

`sms_template_id` إلزامي	معرّف القالب، من صفحة «قوالب الرسائل».
`test`	بيئة تجريبية: تُحسب التكلفة دون إرسال أو خصم.
`sender`	اسم المرسل المسجّل لحسابك (اختياري). انظر قسم «اسم المرسل».
`scheduled_at`	وقت الإرسال المجدول (اختياري): سنة-شهر-يوم ساعة:دقيقة بتوقيت ليبيا أو RFC 3339، في المستقبل وضمن 30 يوماً. يُتجاهل مع test.

محتوى الطلب

`records` إلزامي	الصفوف المراد إرسالها.
`phone` إلزامي	رقم ليبي: 091 أو 092 أو 093 أو 094 ثم 7 أرقام. غيره لا يُرسل ولا يُخصم، ويعود في invalid_numbers.
`variables`	‎$1، ‎$2 … بنفس أسمائها في القالب.

{
  "records": [
    { "phone": "218910001234", "$1": "رسالة", "$2": "أحمد علي" },
    { "phone": "218910001234", "$1": "رسالة", "$2": "سارة", "scheduled_at": "2026-10-20 09:00" }
  ]
}

مثال على الطلب

curl -X POST "https://dev.resala.ly/api/v1/messages/send-template?sms_template_id=TEMPLATE_ID" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"records":[{"phone":"218910001234","$1":"رسالة","$2":"أحمد علي"}]}'

الرد الناجح (201)

{
  "is_prod": true,
  "total_messages": 1,
  "total_free_messages": 0,
  "total_sent_free_messages": 0,
  "total_cost": 0.05,
  "succeeded": 1,
  "failed": 0,
  "failed_numbers": [],
  "invalid_numbers": [],
  "sender_names": { "libyana": "MyBrand", "almadar": "MyBrand" },
  "sms_template_version": {
    "id": "6d2f9c41-7b8e-4a10-9c33-1e5a7d0b4f22",
    "version_number": 3,
    "body": "أهلاً بك في $1، نحن سعداء بانضمامك يا $2",
    "status": "APPROVED"
  }
}

جدولة الإرسال: مرّر scheduled_at بصيغة سنة-شهر-يوم ساعة:دقيقة بتوقيت ليبيا (أو RFC 3339). في رابط الطلب رمّز القيمة: المسافة %20 وعلامة + تصبح %2B (أو استخدم صيغة Z مثل 2026-10-20T07:00:00Z). يمكن أيضاً وضع scheduled_at داخل أي سجل في records ليأخذ وقته الخاص (أو عموداً في ملف CSV)، ووقت السجل يغلب المعامل، والسجلات بلا وقت تُرسل فوراً إن لم يُمرَّر المعامل. الوقت يجب أن يكون مستقبلياً وضمن 30 يوماً. الإرسال المجدول يُقبل في الخلفية مهما كان عدد الأرقام: الرد يحمل batch_id و queued: true و scheduled_at، والتكلفة تُخصم عند الجدولة ولا يمكن الإلغاء. تابعه عبر GET /message-batches/{id} (الحالة: scheduled ثم running ثم completed).

سجل الرسائل (sent-view)

كل ما أرسلته، رموزاً ورسائل، مع حالة كل واحدة.

GET https://dev.resala.ly/api/v1/sent-view

معاملات الرابط

`filters`	‏source:message أو source:pin.
`q`	بحث في النص ورقم المستلم.
`sorts`	عمود الترتيب، ويسبقه ‎- للتنازلي.
`page`	رقم الصفحة، من 1.
`paginate`	عدد الصفوف في الصفحة.

مثال على الطلب

curl "https://dev.resala.ly/api/v1/sent-view?filters=source:message|pin&paginate=20" \
  -H "Authorization: Bearer TOKEN"

الرد الناجح (200)

{
  "data": [
    {
      "id": "1f0c8a54-2b77-4d6e-9f31-0a8b7c6d5e4f",
      "code": "218",
      "region": "LY",
      "number": "910001234",
      "content": "نص الرسالة",
      "source": "message",
      "status": "delivered",
      "pages": 1,
      "env": "production",
      "created_at": "2026-09-16T12:00:00Z",
      "updated_at": "2026-09-16T12:05:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "per_page": 20,
    "current_page": 1,
    "last_page": 1
  }
}

status تتحدّث بعد الإرسال، فاستعلم هنا بدل انتظارها في رد الإرسال.
أُسقطت من المثال حقول meta الاستكشافية (columns وغيرها).

اسم المرسل (sender)

أرسل باسم علامتك التجارية بدل الاسم الافتراضي بإضافة المعامل sender إلى رابط طلب الإرسال.

يُقبل في كل طلبات الإرسال: رموز التحقق (/pins)، والرسالة الواحدة، والإرسال عبر قالب، والإرسال الجماعي، كمعامل في الرابط: ?sender=MyBrand.
يُكتب الاسم كما سُجّل حرفياً، والأحرف الكبيرة والصغيرة مختلفة: MyBrand ليس mybrand.
يجب أن يكون الاسم مفعّلاً لحسابك وغير منتهي الصلاحية على شبكة المستلم (ليبيانا أو المدار)؛ الاسم المفعّل على شبكة واحدة لا يُستخدم مع أرقام الشبكة الأخرى.
إن لم تُرسل sender أو لم يتحقق ما سبق، تخرج الرسالة باسمك الافتراضي على شبكة المستلم، وإن لم يكن لك اسم مفعّل عليها فباسم Resala. لا يُرجع الطلب خطأً في هذه الحالة.
الاسم الذي خرجت به الرسالة يعود في رد الطلب: sender_name لرمز التحقق والرسالة الواحدة، وsender_names (اسم لكل شبكة: libyana أو almadar) للإرسال عبر قالب والإرسال الجماعي. ويظهر أيضاً في سجل الرسائل (/sent-view).

مثال: إرسال قالب باسم MyBrand

curl -X POST "https://dev.resala.ly/api/v1/messages/send-template?sms_template_id=TEMPLATE_ID&sender=MyBrand" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"records":[{"phone":"218910001234","$1":"رسالة"}]}'

حالات الرسالة (status)

`accepted`	مقبولة: سُلّمت إلى شبكة الاتصال وبانتظار تقريرها.
`sent`	تم الإرسال: حالتها لدى شبكة الاتصال مرسلة.
`delivered`	تم التسليم: وصلت إلى جهاز المستلم.
`undelivered`	لم يتم التسليم: أبلغت الشبكة بعدم تسليمها.
`pending`	قيد الانتظار: في طابور شبكة الاتصال وقرارها لم يصل بعد.
`failed`	فشلت: لم تقبلها أي شبكة ولن تُعاد.

دليل الأخطاء

فرّع برمجياً على type لا على message، فالأخير مترجم ومتغيّر. أرفق request_id عند مراسلة الدعم.

{
  "status": 400,
  "type": "AccountExpired",
  "message": "لقد انتهت صلاحية حسابك في رسالة، رجاء قم بتجديد الصلاحية لاستخدام الخدمة",
  "request_id": "01JQ8Z4K7M"
}

status	type	المعنى
400	`AccountExpired`	انتهى اشتراك حسابك.
400	`InsufficientCredit`	الرصيد غير كافٍ للإرسال.
400	`BadRequest`	تعذّرت معالجة الطلب.
401	`Unauthorized`	التوكن مفقود أو غير صالح.
401	`TokenExpired`	انتهت صلاحية التوكن، الرجاء تسجيل الدخول مجددًا.
403	`Forbidden`	لا تملك صلاحية القيام بهذا الإجراء.
404	`NotFound`	المورد المطلوب غير موجود.
422	`InputValidation`	فشل التحقق من صحة حقل واحد أو أكثر.

مستند التوثيق (Postman)

نزّل واجهات هذه الصفحة كمجموعة Postman جاهزة للاستيراد.

تنزيل مجموعة Postman

في Postman: Import ← الملف المنزَّل ← Variables ← الصق مفتاح الربط في token. الملف لا يحتوي المفتاح، فمشاركته آمنة.