البحث عن اسم المتصل
استرجع نتيجة اسم المتصل المتاحة لرقم هاتف. يُنفَّذ هذا البحث في بيئة الإنتاج وقد تترتب عليه رسوم على حسابك، حتى عندما تأتي النتيجة من ذاكرة التخزين المؤقت للخدمة. وهو لا يغيّر الاسم الظاهر عند إجراء مكالمات صادرة من رقم تملكه.
لا يُعدّ الاسم المُعاد إثباتًا لهوية موثَّقة أو لملكية الرقم أو لإذن بإجراء اتصال. وقد تكون الأسماء غير متاحة أو قديمة أو مختصرة، أو تكون تسميات جغرافية، أو يُستخدم رقم هاتف بدلًا منها.
الطلب
استخدم حساب API المفعّل لديك من عنوان بروتوكول الإنترنت المصدر المسموح به لهذا الحساب. احتفظ ببيانات الاعتماد في مخزن للأسرار على جانب الخادم. يستخدم المثال متغيرات البيئة ورقمًا وهميًا من أمريكا الشمالية؛ لا تضع بيانات الاعتماد في عناوين المواقع أو في شيفرة المتصفح المتاحة للعامة.
curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
https://api.multitel.net/v3/cnam/12025550123قدّم الرقم كاملًا على هيئة أرقام متضمنًا رمز الدولة، مثل أحد عشر رقمًا تبدأ بالرقم 1 لأمريكا الشمالية. لا تعتمد على معالج الطلب لتوحيد تنسيق علامات الترقيم أو علامة الجمع. لا يلزم تقديم متن للطلب أو محدِّد للمنطقة. تأكّد من التغطية المدعومة لدى MultiTEL للاستخدام الذي تنويه.
الاستجابة
القيم للتوضيح فقط؛ ولا تُعدّ التكلفة عرض سعر.
{
"status": {
"code": 200,
"msg": ""
},
"response": {
"number": "12025550123",
"name": "EXAMPLE NAME",
"cost": 0.0037,
"balance": 9.9963
}
}| الحقل | المعنى |
|---|---|
| number | الرقم المطلوب. |
| name | الاسم المتاح أو النص البديل. ولا يُعدّ ذلك تحققًا من الهوية. |
| cost | سعر البحث المضبوط للحساب أو الخدمة، كما يُبلّغ عنه مسار المعالجة هذا. استخدم التعرفة الحالية للحساب، وليس القيمة التوضيحية. |
| balance | الرصيد المحسوب للاستجابة. ولا يمثّل استعلامًا جديدًا عن رصيد الحساب يُنفَّذ ضمن معاملة. |
الرسوم والمطابقة المالية
تُحتسب رسوم النتائج التي تتضمن اسمًا وفق سعر CNAM المضبوط للحساب. وقد يترتب على تكرار البحث أو استرجاعه من ذاكرة التخزين المؤقت رسم إضافي؛ ولا يُتاح مفتاح يضمن عدم تكرار أثر الطلب. تحقّق من التعرفة الحالية للحساب قبل تفعيل عمليات البحث الآلية.
هناك قصور معروف في الاستجابة عندما يكون الاسم المخزّن مؤقتًا فارغًا: فقد يُعيد المعالج الرمز 200 من API مع اسم فارغ وتكلفة غير صفرية ورصيد محسوب أقل، رغم أن فرع المعالجة هذا لا يخصم من الحساب. لا تعتبر هذه الاستجابة وحدها دليلًا على احتساب رسوم. طابق النتائج مع سجلات فوترة الحساب ومع نتيجة جديدة لعملية الاستعلام عن الرصيد، وتواصل مع الدعم إذا كانت النتائج ملتبسة.
يشترط فحص الرصيد المدفوع مسبقًا حاليًا وجود رصيد لا يقل عن 0.004 قبل البحث، بصرف النظر عن السعر المضبوط لكل استعلام. ويُرفض أيضًا الحساب الذي عُطّلت فيه عمليات الشراء. ولا تجعل هذه الفحوص نقطة النهاية هذه واجهة API لتقديم عروض الأسعار أو فرض حدود الإنفاق.
الأخطاء وإعادة المحاولة
تحقّق من حالة HTTP ومن status.code/status.msg في JSON معًا. قد يعني الرمز 403 من API عدم كفاية الرصيد المدفوع مسبقًا، أو حظر عمليات الشراء، أو مشكلة في تفويض الحساب، أو عدم العثور على اسم للمتصل. وقد يُعيد مسار عدم العثور على اسم الرمز على هيئة سلسلة نصية. افحص الرسالة بدلًا من اعتبار كل رمز 403 دليلًا على بيانات اعتماد غير صحيحة. وقد تؤدي تعارضات الإعدادات إلى إرجاع الرمز 500 من API.
قد تنتهي مهلة الانتظار بعد تنفيذ بحث قابل للفوترة. استخدم عددًا محدودًا من محاولات الإعادة مع زيادة الفاصل الزمني بينها فقط عندما يكون ذلك مناسبًا لتطبيقك، وطابق أولًا سجلات المحاولات التي لم تتضح نتيجتها. لا تكرّر المحاولة مرارًا لرقم مرفوض أو عند حدوث فشل متعلق بصلاحيات الحساب أو رصيده. ويمكن لذاكرة تخزين مؤقت للاستجابات في تطبيقك أن تقلّل الطلبات المتكررة، مع مراعاة اتفاقيتك ومتطلبات الدقة لديك.
عمليات أخرى على الأرقام
عملية القراءة هذه منفصلة عن تحديث الاسم الظاهر في المكالمات الصادرة أو LIDB، أو الإدراج في دليل الهاتف، أو تسجيل المتصل. ولكل من تلك العمليات حقولها المطلوبة وتفويضها ورسومها الخاصة. استخدم تغطية تخصيص الأرقام لفحص جدول البادئات، أو البحث عن الأرقام للاطلاع على الأرقام المتاحة للطلب. ولا يثبت أي من ذلك أن المتصل هو الشخص الذي يدّعي أنه هو.