توثيق REST API

واجهة REST API للبحث عن توجيه LRN

ابحث عن رقم التوجيه ومعلومات مشغّل الاتصالات المتاحة لرقم هاتف في أمريكا الشمالية بسعر ثابت.

فتح المرجع الخاص بحسابك المطوّرون والأتمتة

اختر واجهة 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.

البحث عن رقم

يقبل GET /v3/lrn/{number} رقم الوجهة في المسار. ويمكن تمرير رقم المتصل اختياريًا باستخدام /v3/lrn/{number}/{ani} للحصول على معلومات تعتمد على المصدر. أدخل أرقام هواتف أمريكا الشمالية باستخدام الخانات الرقمية فقط، مع رمز الدولة عند الاقتضاء؛ وتستخدم الأمثلة أرقامًا خيالية محجوزة.

curl --fail-with-body \
  --user "$MULTITEL_API_USERNAME:$MULTITEL_API_PASSWORD" \
  --header "Accept: application/json" \
  "https://api.multitel.net/v3/lrn/12025550123"

curl --fail-with-body \
  --user "$MULTITEL_API_USERNAME:$MULTITEL_API_PASSWORD" \
  --header "Accept: application/json" \
  "https://api.multitel.net/v3/lrn/12025550123/12025550124"

تنفيذ عملية بحث ببيانات اعتماد صالحة يترتب عليه رسوم. السعر هو ‏0.00025 US$ لكل عملية بحث: ‏0.25 US$ لكل 1,000 أو ‏250 US$ للمليون. لا توجد خصومات على الحجم. هذه عملية بحث عن معلومات التوجيه ولا تُجري مكالمة هاتفية.

قراءة النتيجة

{
  "status": {
    "code": 200,
    "msg": "Success"
  },
  "response": {
    "lrn": "12025550123",
    "ported": 0,
    "ocn": "",
    "lata": "",
    "rc": "",
    "cost": "$0.00025"
  }
}

هذا المثال المُختلَق يوضح شكل الاستجابة فقط؛ وهو ليس نتيجة توجيه مقيسة. تحقق من status.code قبل استخدام response. الحقل cost نص مسبوق برمز العملة وليس رقم JSON.

الحقل	المعنى
`lrn`	رقم توجيه الموقع (Location Routing Number) المستخدم لتحديد وجهة التوجيه.
`ported`	مؤشر نقل الرقم الذي يوفره هذا البحث: عادةً 0 أو 1. لا تستخدمه دليلًا على الملكية أو على أهلية الخدمة.
`ocn`	رقم شركة التشغيل (Operating Company Number)، عند توفره.
`lata`	منطقة الوصول والنقل المحلية (Local Access and Transport Area)، عند توفرها.
`rc`	مركز التعرفة (Rate center)، عند توفره.
`city`, `state`, `lec`, `lectype`, `jurisdiction`, `local`	تفاصيل إضافية تتعلق بالموقع أو الناقل أو المصدر عند توفرها. وقد تكون غائبة أو فارغة.

لا تشترط وجود كل حقول التوجيه. وعلى وجه الخصوص، قد تخلو نتائج الأرقام المجانية للمتصل من تفاصيل مركز التعرفة المحلي ورموز الناقل. ولا يُعد LRN المُعاد ضمانًا فوريًا لإمكانية الوصول ولا اختبارًا لجودة المكالمة.

استخدم عمليات البحث في سير عمل التوجيه لديك

تحقق من الرقم المطلوب وقم بتطبيعه قبل إرساله.
افحص حالة HTTP وحالة التطبيق. احتفظ بسجل بعد حجب البيانات الحساسة يتضمن الرقم والوقت والنتيجة لأغراض استكشاف الأخطاء.
استخدم فقط الحقول المتصلة بقاعدة التوجيه لديك وعالج القيم الغائبة بشكل صريح.
حدّد عدد المحاولات بعد استجابة غير مؤكدة. قد يؤدي تكرار البحث إلى رسوم إضافية؛ ولا يوجد لهذه النقطة مفتاح idempotency موثق.

اطّلع على منتج LRN وتسعيره الثابت. يتضمن مسار OpenAPI العام جزء ANI؛ كما يقبل تنفيذ LRN المنشور الطلب الأقصر دون ANI. lrninfo عملية منفصلة ولا ينبغي استخدامها بديلًا عن هذه النقطة.

التعامل مع الأخطاء وإعادة المحاولة

فشل المصادقة أو الصلاحيات: تحقق من حالة تفعيل بيانات اعتماد API، والخدمة المسموح بها، وقيد عنوان IP المصدر. ملف تعريف الارتباط الخاص بجلسة البوابة ليس بيانات اعتماد للتكامل.
رصيد غير كافٍ أو موافقة غير مستوفاة: عالج مسألة رصيد الحساب أو موافقة الإرسال أو متطلب المستندات قبل تكرار العملية.
لا توجد نتيجة: تعامل مع المخزون الفارغ أو غياب اسم المتصل على أنه نتيجة عادية. لا تفترض أن رقمًا صحيح الصياغة تتوفر له كل الخدمات.
انتهاء مهلة الشبكة أو فشل الخدمة: استخدم إعادة محاولات محدودة مع تأخير تصاعدي لعمليات القراءة. وفي حالة الشراء أو الإرسال أو التسجيل، افحص حالة العملية أولًا؛ فإعادة إرسال طلب مقبول قد تكرر إجراءً يترتب عليه رسوم.

دعم تكرار الطلب بأمان (idempotency) يخص كل عائلة API على حدة. تدعم واجهة Emergency API مفاتيح إعادة المحاولة، لكن ذلك لا يجعل أي طلب عشوائي في v3 آمنًا للتكرار. احتفظ بالطوابع الزمنية والمعرّفات المُعادة والاستجابات بعد حجب بياناتها الحساسة لأغراض الدعم.

تابع مع المرجع الخاص بحسابك

يقوم المرجع الذي يظهر بعد تسجيل الدخول بتصفية العمليات بحسب صلاحياتك والخدمات المفعّلة لديك. استخدم المضيف المحدد ونوع بيانات الاعتماد وحقول الطلب ومخطط الاستجابة الواردة فيه كما هي. يمكن للوحات التحكم تنفيذ عمليات فعلية، بما في ذلك عمليات الشراء والرسائل.

فهرس نقاط النهاية الخاص بالحساب وحدة تحكم REST للاتصالات مستند OpenAPI العام للاتصالات دليل تكامل OAuth