توثيق REST API
واجهات REST API لأرقام الهاتف
اكتشف الدول والأرقام المتاحة، وافحص العرض كاملاً، وأدِر الأرقام التي تملكها.
اختر واجهة 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.
قراءة كتالوج الدول المتاحة
curl --fail-with-body \
--user "$MULTITEL_API_USERNAME:$MULTITEL_API_PASSWORD" \
--header "Accept: application/json" \
"https://api.multitel.net/v3/getcountries"تحتوي استجابة v3 على status ومصفوفة response. تتضمن عناصر الدول isocode وname وcountrycode ومعلومات القدرات وnext_function. يعتمد التوفر على الحساب والمخزون؛ ولا يعني ظهور دولة ما أن كل بادئة أو نوع رقم متوفر في المخزون.
{
"status": {
"code": 200,
"msg": "Results: 1"
},
"response": [
{
"countrycode": "1",
"name": "United States",
"description": "United States",
"isocode": "US",
"is_mobile": 0,
"sms_coverage": 1,
"latitude": "37.0902",
"longitude": "-95.7129",
"next_function": "v3/getareas/US"
}
]
}من الاستكشاف إلى التفعيل
- اختر الدولة، والتقسيم الفرعي عند الحاجة، والمنطقة ونوع الرقم باستخدام عمليات الجغرافيا المناسبة.
- اقرأ أسعار الإعداد والاشتراك الشهري والاستخدام للرقم المختار، والقنوات، والحصة المضمّنة، ومتطلبات التسجيل.
- أرسل مستندات المستخدم النهائي المطلوبة وراجع حالتها. قد يبقى الرقم قيد الانتظار إلى حين الموافقة.
- قدّم الطلب مرة واحدة بالاختيار الدقيق للمخزون والسعر. وإذا كانت الاستجابة غير مؤكدة، فافحص مخزونك قبل تقديم طلب آخر.
- اضبط توجيه الصوت وتسليم الرسائل بشكل مستقل، ثم اختبر المسار المقصود كاملًا.
التعامل مع الأخطاء وإعادة المحاولة
- فشل المصادقة أو الصلاحيات
- تحقق من حالة تفعيل بيانات اعتماد API، والخدمة المسموح بها، وقيد عنوان IP المصدر. ملف تعريف الارتباط الخاص بجلسة البوابة ليس بيانات اعتماد للتكامل.
- رصيد غير كافٍ أو موافقة غير مستوفاة
- عالج مسألة رصيد الحساب أو موافقة الإرسال أو متطلب المستندات قبل تكرار العملية.
- لا توجد نتيجة
- تعامل مع المخزون الفارغ أو غياب اسم المتصل على أنه نتيجة عادية. لا تفترض أن رقمًا صحيح الصياغة تتوفر له كل الخدمات.
- انتهاء مهلة الشبكة أو فشل الخدمة
- استخدم إعادة محاولات محدودة مع تأخير تصاعدي لعمليات القراءة. وفي حالة الشراء أو الإرسال أو التسجيل، افحص حالة العملية أولًا؛ فإعادة إرسال طلب مقبول قد تكرر إجراءً يترتب عليه رسوم.
دعم تكرار الطلب بأمان (idempotency) يخص كل عائلة API على حدة. تدعم واجهة Emergency API مفاتيح إعادة المحاولة، لكن ذلك لا يجعل أي طلب عشوائي في v3 آمنًا للتكرار. احتفظ بالطوابع الزمنية والمعرّفات المُعادة والاستجابات بعد حجب بياناتها الحساسة لأغراض الدعم.
تابع مع المرجع الخاص بحسابك
يقوم المرجع الذي يظهر بعد تسجيل الدخول بتصفية العمليات بحسب صلاحياتك والخدمات المفعّلة لديك. استخدم المضيف المحدد ونوع بيانات الاعتماد وحقول الطلب ومخطط الاستجابة الواردة فيه كما هي. يمكن للوحات التحكم تنفيذ عمليات فعلية، بما في ذلك عمليات الشراء والرسائل.