دليل المطور لربط خدمة الرسائل النصية SMS

واجهة برمجة التطبيقات API من بيفاتيل | النسخة العربية

دليل الاستخدام التقني: التهيئة، الرسائل، رمز التحقق، التقارير وإدارة عمليات الإرسال

مقدمة

تتيح واجهة برمجة التطبيقات (API) من بيفاتيل للمطورين ربط أنظمتهم وتطبيقاتهم بخدمة الرسائل النصية SMS، وإدارة الرسائل الفردية والجماعية، ورسائل التحقق (OTP)، بالإضافة إلى استعراض الرسائل وتقارير الإرسال. تعتمد الواجهة على مبادئ RESTful، ويوضح هذا الدليل نقاط الاتصال وطلبات الاستخدام والاستجابات المحتملة.

1. إعداد الاتصال بواجهة API

الرابط الأساسي (Base URL):

https://bevatel-system-api.bevatel.com/

يجب تضمين الترويسات التالية في طلبات API:

{
  "Authorization": "Bearer YOUR_API_TOKEN",
  "Content-Type": "application/json"
}

احصل على رمز المصادقة (API Token) من قسم API داخل منصة بيفاتيل، واستبدل YOUR_API_TOKEN بالرمز الخاص بك.

2. الحصول على معرف المرسل (Sender ID)

قبل إرسال الرسائل، احصل على معرف المرسل المرتبط بحسابك، واستخدمه في قيمة senderId.

GET https://bevatel-system-api.bevatel.com/sms/developer/v1/clients/all

3. إرسال رسالة نصية سريعة (Send Quick Message)

إرسال رسالة نصية إلى رقم واحد أو عدة أرقام.

POST https://bevatel-system-api.bevatel.com/sms/developer/v1/quick-message

{
  "senderId": "UUID of the sender",
  "jobName": "Job name or description",
  "isScheduled": false,
  "scheduledTime": "",
  "content": ["Message content"],
  "phoneNumbers": ["966558883879"],
  "templateMessageId": ""
}

ملاحظة: عند توفير templateMessageId يمكن ترك content فارغًا، والعكس صحيح. توضح الوثيقة المصدر الحقول senderId وjobName وisScheduled وscheduledTime وphoneNumbers باعتبارها إلزامية. تنسيق رقم الهاتف في المصدر مثال سعودي. يفصل T بين التاريخ والوقت، ويشير Z إلى توقيت UTC.

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

{
  "success": true,
  "message": "Success",
  "data": {"message": "Message sent to queue, the status will be provided after a while"}
}

لا تعني إضافة الرسالة إلى قائمة الانتظار تأكيد تسليمها. الأخطاء المحتملة: 400 Bad Request عند بيانات غير صحيحة، و404 Not Found عند غياب الاشتراك (Not Subscribed).

4. إنشاء وإرسال رمز التحقق (Create OTP)

إنشاء رسالة رمز تحقق لمرة واحدة وإرسالها إلى المستلم.

POST https://bevatel-system-api.bevatel.com/sms/developer/v1/otp

{
  "senderId": "UUID of the sender",
  "jobName": "Job name or description",
  "isScheduled": false,
  "scheduledTime": "",
  "content": ["OTP message content"],
  "phoneNumbers": ["966558883879"],
  "templateMessageId": ""
}

الاستجابة:

{ "success": true, "message": "Success",
  "data": {"message": "Message sent to queue, the status will be provided after a while"} }

الأخطاء المحتملة: 400 Bad Request للحقول غير الصحيحة، و404 Not Found عندما لا يتوفر الاشتراك.

5. إعادة إرسال رمز التحقق (Resend OTP)

إعادة إرسال رسالة رمز التحقق إلى رقم المستخدم.

POST https://bevatel-system-api.bevatel.com/sms/developer/v1/resend-otp

{
  "senderId": "UUID of the sender",
  "jobName": "Job name or description",
  "isScheduled": false,
  "scheduledTime": "",
  "content": ["OTP message content"],
  "phoneNumbers": ["966558883879"],
  "templateMessageId": ""
}

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

{ "success": true, "message": "Success", "data": {"message": "OTP ReSent successfully"} }

الأخطاء المحتملة: 400 Bad Request للبيانات غير الصحيحة، و422 Unprocessable Entity عند معرف مرسل غير موجود (Client with the given ID does not exist).

6. التحقق من رمز OTP (Verify OTP)

التحقق من الرمز المرسل إلى هاتف المستخدم.

POST https://bevatel-system-api.bevatel.com/sms/developer/v1/verify

{ "phoneNumber": "966558883879", "otp": "123456" }

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

{ "success": true, "message": "OTP verified successfully" }

الأخطاء المحتملة: 400 Bad Request عند تنسيق هاتف غير صحيح، و404 Not Found عند عدم العثور على رسالة التحقق (Message not found).

7. إرسال الرسائل النصية الجماعية (Create Bulk SMS)

إرسال رسائل جماعية برفع ملف CSV يتضمن بيانات المستلمين.

POST https://bevatel-system-api.bevatel.com/sms/developer/v1/bulk

مثال توضيحي للحقول الواردة بالمصدر:

{
  "senderId": "UUID of the sender",
  "jobName": "Job name or description",
  "isScheduled": false,
  "scheduledTime": "",
  "content": [""],
  "attachment": "Sample File.csv"
}

ملاحظة: هذا مثال توضيحي لبنية الحقول وليس طريقة مؤكدة لرفع الملف. يجب إرسال CSV بالتنسيق الفعلي الذي تتطلبه نقطة الاتصال، ولا يكفي اسم الملف داخل JSON.

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

{ "success": true, "message": "Success" }

أخطاء محتملة: 422 عند عدم إرفاق ملف (You must upload one file)، أو عند معرف مرسل غير صحيح (Client with the given ID does not exist).

8. استعراض جميع الرسائل (Get All Messages)

استرجاع قائمة الرسائل مع إمكانية تقسيم النتائج إلى صفحات.

GET https://bevatel-system-api.bevatel.com/sms/developer/v1?page={{page}}&limit={{limit}}

مثال مختصر على الاستجابة:

{
"success": true, "message": "Success",
"data": [{
  "id": "89c4b2f8-b503-4592-8213-00127552b501",
  "senderIdName": "Bevatel5",
  "phoneNumber": "966558883879",
  "content": "TEST", "status": 0, "sentAt": null,
  "createdAt": "2024-09-25T11:20:42.822Z"
}],
"meta": {"current_page": 1, "from": 1, "last_page": 1, "per_page": 10, "to": 1, "total": 1}
}

تشير data إلى بيانات الرسائل، ويحتوي meta على معلومات تقسيم النتائج. حالة status هي القيمة المسجلة في النظام، وsentAt وقت الإرسال المسجل إن توفر.

9. استعراض رسالة باستخدام المعرف (Get Message by ID)

استرجاع تفاصيل رسالة واحدة باستخدام المعرف الخاص بها.

GET https://bevatel-system-api.bevatel.com/sms/developer/v1/{{message-ID}}

{
  "success": true, "message": "Success",
  "data": {
    "id": "89c4b2f8-b503-4592-8213-00127552b501",
    "phoneNumber": "966558883879",
    "content": "TEST", "status": 0, "sentAt": null,
    "client": null, "template": null
  }
}

إذا لم يتم العثور على الرسالة، يظهر الخطأ 404 Not Found مع الرسالة Message not found.

10. استعراض تقارير عمليات الإرسال (Reports)

استرجاع عمليات الإرسال وتصفية النتائج حسب نوع العملية مع دعم تقسيم الصفحات.

GET https://bevatel-system-api.bevatel.com/messages/jobs?type[eq]={{type}}&page={{page}}&limit={{limit}}

{
"success": true, "message": "Success",
"data": [{
  "name": "SMS Campaign", "senderName": "Bevatel5",
  "id": "66814898-1036-4710-8e74-19515fc0a037",
  "type": "quick", "failedCount": 0,
  "pendingCount": 1, "sentCount": 0,
  "total": 1, "status": "finished",
  "startedAt": "2024-09-25T11:20:42.799Z"
}]
}

توضح failedCount عدد الرسائل الفاشلة وpendingCount عدد الرسائل المنتظرة وsentCount عدد الرسائل المرسلة وفق النظام وtotal الإجمالي. لا تكفي حالة finished وحدها لإثبات تسليم جميع الرسائل.

11. حذف عملية إرسال (Delete Job)

حذف عملية إرسال باستخدام Job ID عندما تسمح حالة العملية بذلك.

DELETE https://bevatel-system-api.bevatel.com/messages/jobs/{{job_ID}}

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

{ "success": true, "message": "Success" }

الأخطاء: 404 Not Found عند عدم العثور على العملية (MessageJob not found)، و400 Bad Request عند محاولة حذف عملية بدأت بالفعل (Cannot delete a job that has already started).

12. إرشادات مهمة

• استخدم رمز Bearer الصحيح في جميع الطلبات.

• تحقق من senderId وتنسيق أرقام المستلمين.

• استخدم تنسيق التاريخ والوقت المطلوب عند الجدولة.

• حدد content أو templateMessageId وفق طريقة الإرسال.

• راجع استجابات API ورسائل الأخطاء.

• تابع النتائج النهائية للرسائل من خلال نقاط الاتصال الخاصة بالرسائل والتقارير.

13. الوصول إلى وثائق المطورين

الرابط الأساسي للواجهة: https://bevatel-system-api.bevatel.com/

يمكن إدارة مفاتيح API من قسم المطورين داخل منصة بيفاتيل.

تنبيه قبل النشر: أُعد هذا الدليل استنادًا إلى المستند المقدم، مع الحفاظ على أسماء الحقول ونقاط الاتصال بالإنجليزية. يجب اختبار الأمثلة قبل اعتمادها كمرجع تنفيذي نهائي، خصوصًا رفع CSV وجدولة الرسائل وتنسيقات OTP.