توثيق REST API
واجهات REST API للرسائل SMS وMMS
أرسل رسائل التطبيقات المعتمدة وتعامل مع القبول وأحداث التسليم والتجزئة والرسوم.
اختر واجهة API وبيانات الاعتماد معًا
يمكن للحسابات المعتمدة ضمن فئات «المطوّرون والأتمتة» و«الأعمال» و«مقدّمو خدمات الاتصالات» دمج الخدمات المفعّلة. لا يحتاج المطوّر الفرد إلى التظاهر بأنه شركة. تتطلب رسائل SMS/MMS الخاصة بالتطبيقات موافقة الإرسال والتسجيل المعمول بهما. أما خدمات «الأفراد والعائلات» فلا تتضمن واجهة API متاحة للعملاء لإنشاء الرسائل.
| عائلة API | عنوان URL الأساسي | المصادقة والنتيجة |
|---|---|---|
| الاتصالات v3 | https://api.multitel.net/v3 | بيانات اعتماد Basic المعتمدة؛ ولا تُستخدم الرموز المميزة المؤهلة والمُزوَّدة إلا في العمليات التي تدعمها. يتضمن JSON الحقلين status وresponse. |
| التسجيل لخدمة الاتصال بالطوارئ | https://api.multi.tel/emergency | بيانات اعتماد Basic المعتمدة أو وصول bearer مُزوَّد خصيصًا. يتضمن JSON الحقول code وmessage وdata. |
| تكاملات REST الخاصة بالبوابة | المضيف والعملية كما يظهران في مرجع المطوّر الخاص بحسابك | استخدم بيانات الاعتماد والنطاقات والمخطط الموثقة لتلك العملية. تستخدم طلبات جلسة المتصفح واجهة منفصلة. |
عيّن MULTITEL_API_USERNAME وMULTITEL_API_PASSWORD عبر إعدادات الأسرار في خادمك قبل استخدام الأمثلة. لا تضمّنهما أبدًا في JavaScript العام للمتصفح أو في عناوين URL أو في نظام التحكم بالمصدر. تُدار بيانات الاعتماد المخصصة في إعدادات تكامل API.
تجهيز طلب SMS
استخدم رقم إرسال معتمدًا ومفعّلًا لـ SMS ومملوكًا للحساب، ومستلمًا وافق على تلقي الرسالة، وأكمل التسجيل المطلوب للعلامة التجارية/الحملة (Brand/Campaign) أو التحقق من الرقم المجاني للمتصل. يُرسل المثال أدناه رسالة حقيقية عند تعبئته ببيانات اعتماد وأرقام صالحة؛ وهو ليس بيئة تجريبية.
curl --fail-with-body \
--user "$MULTITEL_API_USERNAME:$MULTITEL_API_PASSWORD" \
--header "Accept: application/json" \
--request POST \
--header "Content-Type: application/json" \
--data '{"from":"YOUR_APPROVED_NUMBER","to":"YOUR_CONSENTED_RECIPIENT","text":"Your requested update is ready."}' \
"https://api.multitel.net/v3/sendsms"استبدل عنصري المرسل والمستلم بأرقام هواتف بالصيغة الدولية، باستخدام الخانات الرقمية فقط مع رمز الدولة. وفي حالة MMS، قدّم عنوان URL للوسائط المدعومة والمتاحة للاسترجاع علنًا في media، وتحقق أولًا من أهلية MMS والتسعير.
القبول لا يعني التسليم
افحص كلًا من حالة التطبيق الخارجية ونتيجة المراسلة المُعادة. سجّل معرّف الرسالة الذي توفره الخدمة، وتابع حالة التسليم وأحداث webhook. لا يثبت نجاح الإرسال أن هاتف المستلم قد استلم الرسالة.
تُحتسب فوترة SMS لكل جزء. وقد يؤدي الترميز وطول الرسالة إلى عدة أجزاء؛ وقد تختلف رسوم الوسائط والرسوم المتعلقة بالناقل عن رسوم SMS. اقرأ سعر البيع الحالي للحساب قبل الإرسال. لا تُعد محاولة إرسال انتهت مهلته بشكل أعمى: افحص نتيجته المسجلة أولًا.
التعامل مع الأخطاء وإعادة المحاولة
- فشل المصادقة أو الصلاحيات
- تحقق من حالة تفعيل بيانات اعتماد API، والخدمة المسموح بها، وقيد عنوان IP المصدر. ملف تعريف الارتباط الخاص بجلسة البوابة ليس بيانات اعتماد للتكامل.
- رصيد غير كافٍ أو موافقة غير مستوفاة
- عالج مسألة رصيد الحساب أو موافقة الإرسال أو متطلب المستندات قبل تكرار العملية.
- لا توجد نتيجة
- تعامل مع المخزون الفارغ أو غياب اسم المتصل على أنه نتيجة عادية. لا تفترض أن رقمًا صحيح الصياغة تتوفر له كل الخدمات.
- انتهاء مهلة الشبكة أو فشل الخدمة
- استخدم إعادة محاولات محدودة مع تأخير تصاعدي لعمليات القراءة. وفي حالة الشراء أو الإرسال أو التسجيل، افحص حالة العملية أولًا؛ فإعادة إرسال طلب مقبول قد تكرر إجراءً يترتب عليه رسوم.
دعم تكرار الطلب بأمان (idempotency) يخص كل عائلة API على حدة. تدعم واجهة Emergency API مفاتيح إعادة المحاولة، لكن ذلك لا يجعل أي طلب عشوائي في v3 آمنًا للتكرار. احتفظ بالطوابع الزمنية والمعرّفات المُعادة والاستجابات بعد حجب بياناتها الحساسة لأغراض الدعم.
تابع مع المرجع الخاص بحسابك
يقوم المرجع الذي يظهر بعد تسجيل الدخول بتصفية العمليات بحسب صلاحياتك والخدمات المفعّلة لديك. استخدم المضيف المحدد ونوع بيانات الاعتماد وحقول الطلب ومخطط الاستجابة الواردة فيه كما هي. يمكن للوحات التحكم تنفيذ عمليات فعلية، بما في ذلك عمليات الشراء والرسائل.