البدء

تعمل البنية التحتية لشبكة الهاتف المحمول العالمية على نظام يُعرف بشبكة إشارات SS7. تسهل هذه الشبكة تبادل بيانات المشتركين وتوجيه المكالمات وإرسال الرسائل النصية وتحديثات حالة الاتصال المحمول الفوري بين شركات الاتصالات. تحتفظ كل شبكة محمول بسجل الموقع الرئيسي (HLR) - وهو قاعدة بيانات أساسية تخزن التفاصيل الجوهرية حول مشتركيها.

تتيح تقنية استعلام HLR للشركات الاستعلام عن هذه السجلات واسترجاع تفاصيل الاتصال والشبكة المباشرة لأي رقم هاتف محمول. يشمل ذلك ما إذا كان الهاتف قيد التشغيل، والشبكة المخصص لها حالياً، وما إذا كان قد تم نقله، وما إذا كان الرقم صالحاً أم معطلاً، وما إذا كان في وضع التجوال.

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

استخدام واجهة برمجة تطبيقات HLR Lookups

تنفيذ استعلامات HLR Lookup سريع وآمن ومباشر. بمجرد التسجيل والحصول على مفتاح API الخاص بك، يمكنك المصادقة وبدء الاستعلامات الفورية من خلال طلبات HTTP POST البسيطة، عبر POST /hlr-lookup. بدلاً من ذلك، يمكنك معالجة مجموعات البيانات الكبيرة من خلال اختيار طلبات API غير المتزامنة السريعة مع إرسال النتائج مرة أخرى إلى خادمك عبر webhook، كما هو موضح في قسم المفاهيم.

مثال على الطلب

curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookup' \
          -H "X-Digest-Key: YOUR_API_KEY" \
          -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
          -H "X-Digest-Timestamp: UNIX_TIMESTAMP" \
          -d "@payload.json"

يتم توفير المصادقة عبر رؤوس HTTP، ويجب أن يحتوي payload.json (كحد أدنى) على كائن JSON التالي:

مثال على البيانات المرسلة

{
   "msisdn": "+14156226819"
}

عند التنفيذ الناجح، ستتلقى استجابة تحتوي على تفاصيل الاتصال الفورية لرقم الهاتف المحمول المحدد.

استجابة ناجحة application/json

{
   "id":"f94ef092cb53",
   "msisdn":"+14156226819",
   "connectivity_status":"CONNECTED",
   "mccmnc":"310260",
   "mcc":"310",
   "mnc":"260",
   "imsi":"***************",
   "msin":"**********",
   "msc":"************",
   "original_network_name":"Verizon Wireless",
   "original_country_name":"United States",
   "original_country_code":"US",
   "original_country_prefix":"+1",
   "is_ported":true,
   "ported_network_name":"T-Mobile US",
   "ported_country_name":"United States",
   "ported_country_code":"US",
   "ported_country_prefix":"+1",
   "is_roaming":false,
   "roaming_network_name":null,
   "roaming_country_name":null,
   "roaming_country_code":null,
   "roaming_country_prefix":null,
   "cost":"0.0100",
   "timestamp":"2020-08-07 19:16:17.676+0300",
   "storage":"SYNC-API-2020-08",
   "route":"IP1",
   "processing_status":"COMPLETED",
   "error_code":null,
   "error_description":null,
   "data_source":"LIVE_HLR",
   "routing_instruction":"STATIC:IP1"
}

للحصول على تفصيل كامل لسمات الطلب والاستجابة وحالات الاتصال، راجع POST /hlr-lookup.

خدمات الاستعلام الإضافية

استعلامات قابلية نقل الأرقام المحمولة (MNP)

استخدم استعلامات MNP لتحديد ملكية الشبكة وتفاصيل قابلية النقل دون الاستعلام عن الاتصال الفوري. إذا كنت تحتاج فقط إلى MCCMNC لرقم ما، راجع POST /mnp-lookup.

استعلامات الكشف عن نوع الرقم (NT)

حدد ما إذا كان رقم الهاتف ينتمي إلى خط أرضي أو محمول أو بسعر مميز أو VoIP أو جهاز نداء أو نطاقات خطة ترقيم أخرى باستخدام POST /nt-lookup.

مجموعات تطوير البرمجيات (SDKs)

تعمل واجهة برمجة تطبيقات HLR Lookups مع أي عميل REST بأي لغة برمجة، وقد نشرنا مجموعات تطوير برمجيات لـ PHP وRuby وNodeJS على GitHub الخاص بنا لمساعدتك على البدء بسرعة.

الأدوات

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

لست مطوراً؟

يمكن إجراء استعلامات HLR وقابلية نقل الأرقام دون أي برمجة. تعرف على المزيد حول عميل الويب للمؤسسات وميزات التقارير المستندة إلى المتصفح.

المصادقة

لضمان الأمان والتحكم السليم في الوصول، تتطلب معظم الطلبات إلى واجهة برمجة تطبيقات HLR Lookups المصادقة. يتم تصنيف نقاط النهاية إما كعامة أو محمية. عند الوصول إلى نقطة نهاية محمية، يجب مصادقة طلبك باستخدام مفتاح API والسر الخاص بك عبر طريقة Digest-Auth أو Basic-Auth. Digest-Auth هو الخيار الأكثر أماناً ويُوصى به بشدة. استخدم نقطة النهاية GET /auth-test للتحقق من إعداد المصادقة الخاص بك.

مفتاح API والسر

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

المصادقة الأساسية مصادقة Digest القائمة البيضاء لعناوين IP

المصادقة الأساسية القياسية سهلة التنفيذ ومدعومة على نطاق واسع. يمكنك المصادقة عن طريق تمرير مفتاح API والسر الخاص بك كزوج user:pass في طلب HTTP.

مصادقة HTTP الأساسية

curl 'https://YOUR_API_KEY:YOUR_API_SECRET@www.hlr-lookups.com/api/v2/auth-test'

يرسل هذا رأس Authorization:

Authorization: Basic BASE64(YOUR_API_KEY:YOUR_API_SECRET)

موصى به: رأس X-Basic مع SHA256

لتحسين الأمان، يمكنك إرسال تجزئة SHA256 لبيانات الاعتماد الخاصة بك بدلاً من نقلها مباشرة بصيغة base64. لاستخدام هذه الطريقة، احسب التجزئة لزوج YOUR_API_KEY:YOUR_API_SECRET الخاص بك وأرسلها عبر رأس X-Basic:

طلب المصادقة الأساسية

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Basic: BASIC_AUTH_HASH"

رؤوس المصادقة الأساسية

المفتاح	النوع	الوصف
`X-Basic`	string	تجزئة SHA256 لـ `YOUR_API_KEY:YOUR_API_SECRET`. قم بتضمين رمز النقطتين (:) في التجزئة.	إلزامي

مثال على الكود

$key = 'YOUR_API_KEY';
$secret = 'YOUR_API_SECRET';

$basicAuthHash = hash('sha256', $key . ':' . $secret);

Digest-Auth هي الطريقة الموصى بها لتأمين الوصول إلى نقاط نهاية واجهة برمجة تطبيقات HLR Lookup المحمية. يجب أن يتضمن كل طلب الرؤوس التالية: X-Digest-Key و X-Digest-Signature و X-Digest-Timestamp، والتي يتم شرحها أدناه.

مثال على الطلب

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Digest-Key: YOUR_API_KEY" \
  -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
  -H "X-Digest-Timestamp: UNIX_TIMESTAMP"

رؤوس الطلب

المفتاح	النوع	الوصف
`X-Digest-Key`	string	مفتاح واجهة برمجة تطبيقات HLR Lookups الفريد الخاص بك.	إلزامي
`X-Digest-Signature`	string	توقيع مصادقة فريد (انظر أدناه).	إلزامي
`X-Digest-Timestamp`	integer	الطابع الزمني Unix الحالي (انظر أيضاً `GET /time`).	إلزامي

إنشاء التوقيع

يتم إنشاء X-Digest-Signature باستخدام تجزئة SHA256 HMAC، مع سر API الخاص بك كمفتاح مشترك.

يتم تنظيم السلسلة المراد تجزئتها على النحو التالي:

ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY

يمثل رمز . دمج السلاسل النصية.

مكونات توقيع Digest

المكون	النوع	الوصف
`ENDPOINT_PATH`	string	نقطة نهاية API المطلوبة، على سبيل المثال `/auth-test` بأحرف صغيرة.
`UNIX_TIMESTAMP`	integer	الطابع الزمني Unix الحالي (يجب أن يكون ضمن 30 ثانية). انظر `GET /time`.
`REQUEST_METHOD`	string	طريقة HTTP المستخدمة، على سبيل المثال `POST` أو `GET`.
`REQUEST_BODY`	string	بيانات نص الطلب. اضبطها على `null` لطلبات `GET`.

أمثلة على الأكواد

PHP

NodeJS

Ruby

$path = '/auth-test'
    $timestamp = time();
    $method = 'GET';
    $body = $method == 'GET' ? null : json_encode($params);
    $secret = 'YOUR_API_SECRET';

    $signature = hash_hmac('sha256', $path . $timestamp . $method . $body, $secret);

require('crypto');

    let path = '/auth-test'
    let timestamp = Date.now() / 1000 | 0;
    let method = 'GET'
    let body = method === 'GET' ? '' : JSON.stringify(params)
    let secret = 'YOUR_API_SECRET'

    let signature = crypto.createHmac('sha256', secret)
                    .update(path + timestamp + method + body)
                    .digest('hex');

require 'openssl'

path = '/auth-test'
timestamp = Time.now.to_i
method = 'GET'
body = method == 'GET' ? NIL : params.to_json
secret = 'YOUR_API_SECRET'

signature = OpenSSL::HMAC.hexdigest('sha256', secret, path + timestamp.to_s + method + body.to_s)

التمرير لأعلى

المفاهيم

يعد تطبيق استعلامات HLR في أي لغة برمجة أو نظام عبر واجهة برمجة التطبيقات HTTP REST الخاصة بنا أمراً بسيطاً وفعالاً. من خلال عملية تكامل بسيطة، يمكنك البدء في الاستعلام عن شبكات الهاتف المحمول في الوقت الفعلي للحصول على رؤى فورية حول صحة رقم الهاتف وحالة الاتصال وتفاصيل التوجيه.

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

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

واجهة برمجة تطبيقات استعلام HLR المتزامنة

تقوم نقطة النهاية POST /hlr-lookup بمعالجة رقم هاتف محمول واحد (MSISDN) لكل طلب وتعيد النتائج فوراً في نص استجابة HTTP. يتم تنسيق النتائج بصيغة JSON وهي مثالية للتطبيقات الفورية، بما في ذلك التحقق من صحة رقم الهاتف المحمول وتوجيه المكالمات وتسليم رسائل SMS.

يتكون استدعاء واجهة برمجة التطبيقات المتزامنة من طلب واستجابة HTTP مباشرة. يقدم نظامك رقم MSISDN واحد (رقم الهاتف المحمول) لكل طلب ويتلقى استجابة فورية تحتوي على نتائج استعلام HLR في الوقت الفعلي بتنسيق JSON. تم تحسين واجهة برمجة التطبيقات هذه لحالات الاستخدام التي تتطلب التحقق الفوري وفحوصات الاتصال، مثل كشف الاحتيال وتوجيه مكالمات VoIP وتحسين بوابة SMS.

واجهة برمجة تطبيقات HLR غير المتزامنة

تم تصميم نقطة النهاية POST /hlr-lookups للمعالجة الجماعية وكبيرة الحجم، مما يتيح لك إرسال ما يصل إلى 1,000 رقم MSISDN لكل طلب. بدلاً من إرجاع النتائج فوراً، تستخدم واجهة برمجة التطبيقات هذه خطافات الويب التلقائية لإرسال النتائج تدريجياً إلى خادمك. يتم إرجاع نتائج الاستعلام ككائنات JSON عبر استدعاءات HTTP POST.

تم تحسين واجهة برمجة التطبيقات غير المتزامنة من حيث السرعة والكفاءة وقابلية التوسع. إنها تزيل مشكلات زمن الاستجابة الشبكي المرتبطة بالاستدعاءات المتزامنة، مما يجعلها مثالية للشركات التي تحتاج إلى استعلامات عالية الإنتاجية. يقدم نظامك ما يصل إلى 1,000 رقم MSISDN لكل طلب، وتقوم منصتنا بمعالجتها بشكل متوازٍ، وتسليم النتائج إلى خادمك عبر خطافات ويب HTTP على دفعات تصل إلى 1,000 نتيجة لكل استدعاء.

مجموعات تطوير البرمجيات (SDKs)

تعمل مجموعات تطوير البرمجيات (SDKs) الخاصة بنا لـ PHP وNodeJS وRuby على تبسيط عملية التكامل، مما يتيح لك الاتصال بواجهة برمجة تطبيقات HLR Lookups بكفاءة وبأقل جهد ممكن.

توفر مجموعات تطوير البرمجيات هذه وظائف جاهزة ومعالجة للمصادقة وقوالب منظمة لطلبات API، مما يقلل من وقت التطوير ويضمن اتباع أفضل الممارسات.

استكشف القائمة الكاملة لمجموعات تطوير البرمجيات المتاحة على GitHub وابدأ التكامل اليوم.

PHP

NodeJS

Ruby

1   include('HLRLookupClient.class.php');
2
3   $client = new HLRLookupClient(
4       'YOUR-API-KEY',
5       'YOUR-API-SECRET',
6       '/var/log/hlr-lookups.log'
7   );
8
9   $params = array('msisdn' => '+14156226819');
10  $response = $client->post('/hlr-lookup', $params);

عرض على GitHub README.md

1   require('node-hlr-client');
2
3   let response = await client.post('/hlr-lookup', {msisdn: '+491788735000'});
4
5   if (response.status === 200) {
6      // lookup was successful
7      let data = response.data;
8   }

عرض على GitHub README.md

1   require 'ruby_hlr_client/client'
2
3   client = HlrLookupsSDK::Client.new(
4       'YOUR-API-KEY',
5       'YOUR-API-SECRET',
6       '/var/log/hlr-lookups.log'
7   )
8
9   params = { :msisdn => '+14156226819' }
10  response = client.get('/hlr-lookup', params)

عرض على GitHub README.md

التمرير لأعلى

POST/hlr-lookupمحمي

يقوم بإجراء استعلام HLR متزامن، ويوفر بيانات الاتصال والنقل لأرقام الهواتف المحمولة في الوقت الفعلي مباشرة من مشغلي الشبكات. هذه النقطة الطرفية مثالية لسيناريوهات حركة المرور المباشرة حيث تتطلب التطبيقات الحساسة للوقت التحقق الفوري مما إذا كان رقم الهاتف متاحاً حالياً (متصل) أو غير متاح (مغلق). بالإضافة إلى ذلك، يساعد في التمييز بين الأرقام النشطة والأرقام غير الصالحة أو غير المعروفة أو الوهمية.

للمعالجة الجماعية لمجموعات البيانات الكبيرة التي لا تتطلب نتائج فورية، يُرجى استخدام POST /hlr-lookups غير المتزامن، والمُحسَّن للمعالجة الدفعية عالية السرعة.

إذا كان تركيزك الأساسي هو استرجاع بيانات نقل أرقام الهواتف المحمولة (MCCMNC) ولا تحتاج إلى حالة الاتصال المباشر، فإن POST /mnp-lookup يوفر بديلاً فعالاً من حيث التكلفة لاستعلامات نقل أرقام الهواتف المحمولة.

الطلب استجابة ناجحة استجابة خطأ مرجع الحالات

curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookup' \
          -d "@payload.json"

البيانات المرسلة

{
   "msisdn":"+14156226819",
   "route":null,
   "storage":null
}

معاملات الطلب

المفتاح	النوع	الوصف	افتراضي	إلزامي
`msisdn`	string	رقم الهاتف المحمول (MSISDN) المراد الاستعلام عنه، مُقدَّم بالصيغة الدولية (مثل +14156226819 أو 0014156226819). يجب تضمين رموز الدول.	null	إلزامي
`route`	string(3)	معرّف اختياري مكون من ثلاثة أحرف يحدد المسار لهذا الاستعلام. اضبطه على `null` أو احذف هذا المعامل لتطبيق خريطة التوجيه المخصصة الخاصة بك أو دع نظامنا يحدد تلقائياً أفضل مسار لهذا الاستعلام.	null	اختياري
`storage`	string	معرّف تخزين اختياري يحدد التقرير الذي سيتم فيه تخزين النتائج للمراجعة اليدوية والتحليلات وإعداد التقارير. يضيف النظام تلقائياً طابعاً زمنياً بالشهر الحالي. إذا تم حذفه أو ضبطه على `null`، سيقوم النظام تلقائياً بتجميع النتائج حسب الشهر لأغراض إعداد التقارير.	null	اختياري

{
   "id":"f94ef092cb53",
   "msisdn":"+14156226819",
   "connectivity_status":"CONNECTED",
   "mccmnc":"310260",
   "mcc":"310",
   "mnc":"260",
   "imsi":"***************",
   "msin":"**********",
   "msc":"************",
   "original_network_name":"Verizon Wireless",
   "original_country_name":"United States",
   "original_country_code":"US",
   "original_country_prefix":"+1",
   "is_ported":true,
   "ported_network_name":"T-Mobile US",
   "ported_country_name":"United States",
   "ported_country_code":"US",
   "ported_country_prefix":"+1",
   "is_roaming":false,
   "roaming_network_name":null,
   "roaming_country_name":null,
   "roaming_country_code":null,
   "roaming_country_prefix":null,
   "cost":"0.0100",
   "timestamp":"2020-08-07 19:16:17.676+0300",
   "storage":"SYNC-API-2020-08",
   "route":"IP1",
   "processing_status":"COMPLETED",
   "error_code":null,
   "error_description":null,
   "data_source":"LIVE_HLR",
   "routing_instruction":"STATIC:IP1"
}

خصائص الاستجابة الناجحة

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`id`	string(12)	معرّف فريد مخصص لطلب الاستعلام هذا.	false
`msisdn`	string	رقم الهاتف المحمول المستعلم عنه، منسق بالصيغة الدولية (مثل +14156226819 أو 0014156226819).	false
`connectivity_status`	string	يشير إلى ما إذا تم استرجاع حالة الاتصال للرقم بنجاح. القيم المحتملة: `CONNECTED` ، `ABSENT` ، `INVALID_MSISDN` ، أو `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	رمز الدولة المحمول (MCC) ورمز الشبكة المحمولة (MNC) المكون من خمسة أو ستة أرقام والذي يحدد الشبكة المرتبطة حالياً برقم الهاتف.	true
`mcc`	string(3)	رمز الدولة المحمول (MCC) المكون من ثلاثة أرقام والذي يحدد الدولة التي تم تسجيل رقم الهاتف فيها.	true
`mnc`	string(2\|3)	رمز الشبكة المحمولة (MNC) المكون من رقمين أو ثلاثة أرقام والذي يحدد الشبكة المحددة التي ينتمي إليها رقم الهاتف.	true
`imsi`	string	هوية المشترك الدولية المتنقلة (IMSI)، وهي معرّف فريد لبطاقة SIM المرتبطة بهذا الرقم. تعتمد الإتاحة على إعدادات الشبكة.	true
`msin`	string(10)	رقم تعريف الاشتراك المحمول (MSIN) ضمن قاعدة بيانات مشغل الشبكة المحمولة. تعتمد الإتاحة على إعدادات الشبكة.	true
`msc`	string(12)	مركز تبديل الهاتف المحمول (MSC) الذي يتولى حالياً معالجة اتصالات هذا المشترك. تعتمد الإتاحة على إعدادات الشبكة.	true
`original_network_name`	string	اسم مشغل الشبكة الأصلي (الأساسي) المرتبط بهذا الرقم.	true
`original_country_name`	string	الاسم الكامل للدولة التي تم تسجيل رقم الهاتف المحمول فيها أصلاً، مقدم باللغة الإنجليزية.	true
`original_country_code`	string(2)	رمز الدولة ISO المكون من حرفين والذي يمثل الدولة التي تم تخصيص رقم الهاتف فيها لأول مرة.	true
`original_country_prefix`	string	رمز الاتصال الدولي (رمز الاتصال بالدولة) المقابل للدولة الأصلية لرقم الهاتف المحمول.	true
`is_ported`	boolean	يشير إلى ما إذا تم نقل الرقم المحمول من شبكته الأصلية إلى مشغل مختلف.	true
`ported_network_name`	string	اسم مشغل الشبكة الذي تم نقل الرقم المحمول إليه، إن وجد.	true
`ported_country_name`	string	اسم الدولة التي تم نقل الرقم المحمول إليها، إن وجد.	true
`ported_country_code`	string(2)	رمز الدولة ISO المكون من حرفين والذي يمثل الدولة التي تم نقل الرقم المحمول إليها، إن وجد.	true
`ported_country_prefix`	string	رمز الاتصال الدولي (رمز الاتصال بالدولة) للدولة التي تم نقل الرقم المحمول إليها، إن وجد.	true
`is_roaming`	boolean	يشير إلى ما إذا كان الرقم المحمول يعمل حالياً في وضع التجوال على شبكة أجنبية. تعتمد إتاحة حالة التجوال على مشغل الشبكة المحمولة.	true
`roaming_network_name`	string	اسم الشبكة التي يعمل عليها الرقم المحمول حالياً في وضع التجوال، إن وجد.	true
`roaming_country_name`	string	اسم الدولة التي يعمل فيها الرقم المحمول حالياً في وضع التجوال، إن وجد.	true
`roaming_country_code`	string(2)	رمز الدولة ISO المكون من حرفين للدولة التي يعمل فيها الرقم المحمول حالياً في وضع التجوال، إن وجد.	true
`roaming_country_prefix`	string	رمز الاتصال الدولي (رمز الاتصال بالدولة) للدولة التي يعمل فيها الرقم المحمول حالياً في وضع التجوال، إن وجد.	true
`cost`	string	قيمة عشرية ممثلة كنص، تشير إلى تكلفة الاستعلام باليورو.	true
`timestamp`	string	طابع زمني بصيغة W3C يتضمن المنطقة الزمنية، يحدد موعد إتمام الاستعلام.	true
`storage`	string	اسم مساحة التخزين التي تم حفظ نتائج الاستعلام فيها. يتوافق هذا مع أسماء التقارير وتنزيلات CSV المتاحة عبر واجهة الويب.	true
`route`	string(3)	معرّف مكون من ثلاثة أحرف يشير إلى طريقة التوجيه المستخدمة لطلب الاستعلام هذا.	true
`processing_status`	string	نتيجة معالجة الاستعلام. القيم المحتملة: `COMPLETED` (ناجح)، `REJECTED` (الشبكة غير متاحة، لم يتم تطبيق رسوم)، أو `FAILED` (حدث خطأ أثناء المعالجة).	false
`error_code`	integer	رمز خطأ داخلي اختياري يوفر معلومات تشخيصية إضافية لدعم العملاء.	true
`error_description`	string	شرح موجز لرمز الخطأ المحدد (إن وجد) بنص إنجليزي بسيط.	true
`data_source`	string	مصدر البيانات المستخدم لهذا الطلب. القيم المحتملة: `LIVE_HLR` (استعلام HLR في الوقت الفعلي) أو `MNP_DB` (قاعدة بيانات ثابتة لنقل الأرقام المحمولة). راجع خيارات التوجيه للحصول على التفاصيل.	false
`routing_instruction`	string	نص مفصول بنقطتين يصف تعليمات التوجيه المستخدمة في الطلب. المكون الأول هو `STATIC` عندما تحدد مساراً أو `AUTO` للتوجيه التلقائي؛ المكون الثاني هو معرّف المسار، وبالنسبة لطلبات التوجيه التلقائي يظهر مكون ثالث يوضح الأصل الذي تم بناءً عليه اتخاذ قرار التوجيه (أي `SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`).	false

{
    "errors":[
        "Service unavailable."
    ]
}

معاملات استجابة الخطأ

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`errors[]`	string[]	قائمة من النصوص توضح الخطأ.	false

الحالة	الوصف
CONNECTED	الرقم صالح، والجهاز المستهدف متصل حالياً بشبكة الهاتف المحمول. يجب أن تصل المكالمات والرسائل النصية والخدمات الأخرى إلى المستلم بنجاح.
ABSENT	الرقم صالح، لكن الجهاز المستهدف إما مغلق أو خارج نطاق تغطية الشبكة مؤقتاً. قد لا يتم تسليم الرسائل أو المكالمات حتى يعاود الجهاز الاتصال بالشبكة.
INVALID_MSISDN	الرقم غير صالح أو غير مخصص حالياً لأي مشترك على شبكة الهاتف المحمول. ستفشل المكالمات والرسائل إلى هذا الرقم.
UNDETERMINED	تعذر تحديد حالة الاتصال للرقم. قد يكون ذلك بسبب رقم غير صالح، أو استجابة خطأ SS7، أو عدم وجود اتصال مع مشغل الشبكة المستهدف. راجع رمز الخطأ وحقل الوصف الخاص به للحصول على تشخيصات إضافية.

التمرير لأعلى

POST/hlr-lookupsمحمي

يبدأ دفعة من عمليات بحث HLR غير المتزامنة، ويسترجع بيانات الاتصال والنقل المباشرة للهواتف المحمولة من مشغلي الشبكات. يتم تسليم النتائج عبر webhooks إلى الخادم الخاص بك. هذه الطريقة محسّنة لمعالجة أحجام كبيرة من الأرقام التي لا تتطلب استجابات فورية، مثل تنظيف قواعد البيانات والتحقق منها. للتطبيقات الفورية مثل توجيه المكالمات أو تسليم الرسائل القصيرة، يُرجى استخدام نقطة نهاية POST /hlr-lookup بدلاً من ذلك.

نقطة النهاية هذه مثالية للمعالجة الجماعية عندما يكون الهدف هو تحديد أرقام الهواتف التي يمكن الوصول إليها حالياً (متصلة) أو غير متاحة (الهاتف مغلق) مع تصفية الأرقام غير الصالحة أو غير المخصصة أو المزيفة. بالإضافة إلى ذلك، توفر حالة النقل المباشرة (MCCMNC) إلى جانب تفاصيل الاتصال.

قبل استخدام نقطة النهاية هذه، تأكد من تكوين عنوان URL لـ webhook لاستقبال نتائج البحث بشكل غير متزامن. يمكنك إعداد ذلك في إعدادات API الخاصة بك.

الطلب استجابة ناجحة استجابة خطأ Webhooks مرجع الحالات

curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookups' \
          -d "@payload.json"

البيانات المرسلة

{
   "msisdns":["+14156226819","+491788735000","+905536939460"],
   "route":null,
   "storage":null
}

معاملات الطلب

المفتاح	النوع	الوصف	افتراضي	إلزامي
`msisdns`	array	مصفوفة من أرقام الهواتف المحمولة (MSISDNs) بالتنسيق الدولي (مثل +14156226819 أو 0014156226819). يمكنك تضمين ما يصل إلى 1000 رقم لكل طلب.	null	إلزامي
`route`	string(3)	معرّف اختياري مكون من ثلاثة أحرف يحدد المسار لهذا الاستعلام. اضبطه على `null` أو احذف هذا المعامل لتطبيق خريطة التوجيه المخصصة الخاصة بك أو دع نظامنا يحدد تلقائياً أفضل مسار لهذا الاستعلام.	null	اختياري
`storage`	string	معرّف تخزين اختياري يحدد التقرير الذي سيتم فيه تخزين النتائج للمراجعة اليدوية والتحليلات وإعداد التقارير. يضيف النظام تلقائياً طابعاً زمنياً بالشهر الحالي. إذا تم حذفه أو ضبطه على `null`، سيقوم النظام تلقائياً بتجميع النتائج حسب الشهر لأغراض إعداد التقارير.	null	اختياري

{
   "accepted":[
      {
         "id":"0424928f332e",
         "msisdn":"+491788735000"
      }
   ],
   "accepted_count":1,
   "rejected":[
      {
         "id":null,
         "msisdn":"+31"
      }
   ],
   "rejected_count":1,
   "total_count":2,
   "cost":"0.01",
   "storage":"ASYNC-API-2020-08",
   "route":"IP1",
   "webhook_urls":[
      "https://your-server.com/endpoint"
   ]
}

خصائص الاستجابة الناجحة

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`accepted`	array	قائمة بالكائنات التي تحتوي على معرفات فريدة وأرقام MSISDNs التي تم قبولها للمعالجة.	false
`accepted_count`	integer	العدد الإجمالي لأرقام MSISDNs التي تم قبولها بنجاح للمعالجة.	false
`rejected`	array	قائمة بالكائنات التي تحتوي على معرفات فريدة وأرقام MSISDNs التي تم رفضها للمعالجة، عادةً بسبب أرقام غير صالحة. لا يتم تطبيق أي رسوم على الإدخالات المرفوضة.	false
`rejected_count`	integer	العدد الإجمالي لأرقام MSISDNs المرفوضة بسبب أخطاء التحقق.	false
`total_count`	integer	العدد الإجمالي لأرقام MSISDNs المقبولة والمرفوضة التي تم إرسالها للمعالجة.	false
`cost`	string	قيمة عشرية ممثلة كنص، تشير إلى التكلفة الإجمالية باليورو لعمليات البحث المقبولة.	false
`storage`	string	اسم المخزن الذي يتم إلحاق نتائج البحث به، ويُستخدم لإعداد التقارير وتنزيلات CSV عبر واجهة الويب.	false
`route`	string(3\|4)	معرّف من ثلاثة أو أربعة أحرف يحدد المسار المستخدم لطلب البحث هذا. يحتوي على AUTO إذا تم طلب التوجيه التلقائي على أساس الرقم.	false
`webhook_urls`	array	عناوين URL لـ webhook المكونة في إعدادات API الخاصة بك. يتم نشر النتائج مرة أخرى هنا.	false

{
    "errors":[
        "Service unavailable."
    ]
}

معاملات استجابة الخطأ

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`errors[]`	string[]	قائمة من النصوص توضح الخطأ.	false

معالجة الويب هوك

بمجرد الإرسال، تبدأ منصتنا في معالجة أرقام الهواتف المقدمة وترسل النتائج إلى عنوان URL للويب هوك المحدد مسبقاً على الخادم الخاص بك. يتم إرسال النتائج كطلب HTTP POST مع كائن JSON في نص الطلب.

المصادقة

قم بمصادقة الويب هوك من خلال فحص رأس HTTP الخاص بـ X-Signatures.

يحتوي رأس X-Signatures على قائمة توقيعات مفصولة بفاصلة منقوطة. يتم إنشاء كل توقيع في القائمة باستخدام أحد أسرار API المكونة في حسابك. للتحقق من الويب هوك، قم بإنشاء تجزئة SHA-256 باستخدام مفتاح API والسر ونص HTTP الخام، ثم قارنها بالتوقيعات الموجودة في القائمة.

التطابق يؤكد أن الطلب أصلي وموقّع بسر تتحكم فيه.

مثال على الكود

$signaturesHeader = (getallheaders() ?? [])['X-Signatures'] ?? ''; // list of signatures
$key = getenv('AUTH_KEY'); // Your API Key
$secret = getenv('AUTH_SECRET'); // Your API Secret
$payload = file_get_contents('php://input'); // The HTTP body of the incoming POST request

// Generate the expected signature
$expectedSignature = hash('sha256', $key . $secret . $payload);

// Split the header into individual signatures
$providedSignatures = explode(';', $signaturesHeader);

// Check if any signature matches
$valid = false;
foreach ($providedSignatures as $sig) {
    if (hash_equals($expectedSignature, $sig)) {
        $valid = true;
        break;
    }
}

يكون الطلب صالحاً إذا كان أي من التوقيعات المعطاة في الرأس يساوي تجزئة SHA256 المحسوبة من السلسلة المدمجة لمفتاح API والسر ونص HTTP.

تأكيد الاستلام

من المتوقع أن يستجيب الخادم الخاص بك برمز حالة HTTP 200 OK لتأكيد الاستلام الناجح. إذا تم إرجاع أي رمز استجابة آخر، أو حدث انقطاع في الاتصال (10 ثوانٍ)، أو نشأت أي مشكلة أخرى في التسليم، سيقوم النظام تلقائياً بإعادة محاولة الويب هوك بعد دقيقة واحدة. إذا استمر فشل الطلب، ستتبع إعادات المحاولة استراتيجية التراجع الأسي، مع محاولات لاحقة بعد 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 دقيقة.

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

حمولة الويب هوك

{
   "type":"HLR",
   "results":[
      {
         "id":"3b4ac4b6ed1b",
         "msisdn":"+905536939460",
         "connectivity_status":"CONNECTED",
         "mccmnc":"28603",
         "mcc":"286",
         "mnc":"03",
         "imsi":"28603XXXXXXXXXX",
         "msin":"XXXXXXXXXX",
         "msc":"XXXXXXXXXX",
         "original_network_name":"Turk Telekom (AVEA)",
         "original_country_name":"Turkey",
         "original_country_code":"TR",
         "original_country_prefix":"+90",
         "is_ported":false,
         "ported_network_name":null,
         "ported_country_name":null,
         "ported_country_code":null,
         "ported_country_prefix":null,
         "is_roaming":false,
         "roaming_network_name":null,
         "roaming_country_name":null,
         "roaming_country_code":null,
         "roaming_country_prefix":null,
         "cost":"0.0100",
         "timestamp":"2020-08-13 00:04:38.261+0300",
         "storage":"ASYNC-API-2020-08",
         "route":"IP1",
         "processing_status":"COMPLETED",
         "error_code":null,
         "error_description":null,
         "data_source":"LIVE_HLR",
         "routing_instruction":"STATIC:IP1"
      }
   ]
}

سمات حمولة Webhook

يحتوي كائن JSON على سمة type => HLR إلى جانب سمة results التي تتضمن قائمة بكائنات البحث، كما هو موثق أدناه.

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`id`	string(12)	معرّف فريد مخصص لطلب الاستعلام هذا.	false
`msisdn`	string	رقم الهاتف المحمول المستعلم عنه، منسق بالصيغة الدولية (مثل +14156226819 أو 0014156226819).	false
`connectivity_status`	string	يشير إلى ما إذا تم استرجاع حالة الاتصال للرقم بنجاح. القيم المحتملة: `CONNECTED` ، `ABSENT` ، `INVALID_MSISDN` ، أو `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	رمز الدولة المحمول (MCC) ورمز الشبكة المحمولة (MNC) المكون من خمسة أو ستة أرقام والذي يحدد الشبكة المرتبطة حالياً برقم الهاتف.	true
`mcc`	string(3)	رمز الدولة المحمول (MCC) المكون من ثلاثة أرقام والذي يحدد الدولة التي تم تسجيل رقم الهاتف فيها.	true
`mnc`	string(2\|3)	رمز الشبكة المحمولة (MNC) المكون من رقمين أو ثلاثة أرقام والذي يحدد الشبكة المحددة التي ينتمي إليها رقم الهاتف.	true
`imsi`	string	هوية المشترك الدولية المتنقلة (IMSI)، وهي معرّف فريد لبطاقة SIM المرتبطة بهذا الرقم. تعتمد الإتاحة على إعدادات الشبكة.	true
`msin`	string(10)	رقم تعريف الاشتراك المحمول (MSIN) ضمن قاعدة بيانات مشغل الشبكة المحمولة. تعتمد الإتاحة على إعدادات الشبكة.	true
`msc`	string(12)	مركز تبديل الهاتف المحمول (MSC) الذي يتولى حالياً معالجة اتصالات هذا المشترك. تعتمد الإتاحة على إعدادات الشبكة.	true
`original_network_name`	string	اسم مشغل الشبكة الأصلي (الأساسي) المرتبط بهذا الرقم.	true
`original_country_name`	string	الاسم الكامل للدولة التي تم تسجيل رقم الهاتف المحمول فيها أصلاً، مقدم باللغة الإنجليزية.	true
`original_country_code`	string(2)	رمز الدولة ISO المكون من حرفين والذي يمثل الدولة التي تم تخصيص رقم الهاتف فيها لأول مرة.	true
`original_country_prefix`	string	رمز الاتصال الدولي (رمز الاتصال بالدولة) المقابل للدولة الأصلية لرقم الهاتف المحمول.	true
`is_ported`	boolean	يشير إلى ما إذا تم نقل الرقم المحمول من شبكته الأصلية إلى مشغل مختلف.	true
`ported_network_name`	string	اسم مشغل الشبكة الذي تم نقل الرقم المحمول إليه، إن وجد.	true
`ported_country_name`	string	اسم الدولة التي تم نقل الرقم المحمول إليها، إن وجد.	true
`ported_country_code`	string(2)	رمز الدولة ISO المكون من حرفين والذي يمثل الدولة التي تم نقل الرقم المحمول إليها، إن وجد.	true
`ported_country_prefix`	string	رمز الاتصال الدولي (رمز الاتصال بالدولة) للدولة التي تم نقل الرقم المحمول إليها، إن وجد.	true
`is_roaming`	boolean	يشير إلى ما إذا كان الرقم المحمول يعمل حالياً في وضع التجوال على شبكة أجنبية. تعتمد إتاحة حالة التجوال على مشغل الشبكة المحمولة.	true
`roaming_network_name`	string	اسم الشبكة التي يعمل عليها الرقم المحمول حالياً في وضع التجوال، إن وجد.	true
`roaming_country_name`	string	اسم الدولة التي يعمل فيها الرقم المحمول حالياً في وضع التجوال، إن وجد.	true
`roaming_country_code`	string(2)	رمز الدولة ISO المكون من حرفين للدولة التي يعمل فيها الرقم المحمول حالياً في وضع التجوال، إن وجد.	true
`roaming_country_prefix`	string	رمز الاتصال الدولي (رمز الاتصال بالدولة) للدولة التي يعمل فيها الرقم المحمول حالياً في وضع التجوال، إن وجد.	true
`cost`	string	قيمة عشرية ممثلة كنص، تشير إلى تكلفة الاستعلام باليورو.	true
`timestamp`	string	طابع زمني بصيغة W3C يتضمن المنطقة الزمنية، يحدد موعد إتمام الاستعلام.	true
`storage`	string	اسم مساحة التخزين التي تم حفظ نتائج الاستعلام فيها. يتوافق هذا مع أسماء التقارير وتنزيلات CSV المتاحة عبر واجهة الويب.	true
`route`	string(3)	معرّف مكون من ثلاثة أحرف يشير إلى طريقة التوجيه المستخدمة لطلب الاستعلام هذا.	true
`processing_status`	string	نتيجة معالجة الاستعلام. القيم المحتملة: `COMPLETED` (ناجح)، `REJECTED` (الشبكة غير متاحة، لم يتم تطبيق رسوم)، أو `FAILED` (حدث خطأ أثناء المعالجة).	false
`error_code`	integer	رمز خطأ داخلي اختياري يوفر معلومات تشخيصية إضافية لدعم العملاء.	true
`error_description`	string	شرح موجز لرمز الخطأ المحدد (إن وجد) بنص إنجليزي بسيط.	true
`data_source`	string	مصدر البيانات المستخدم لهذا الطلب. القيم المحتملة: `LIVE_HLR` (استعلام HLR في الوقت الفعلي) أو `MNP_DB` (قاعدة بيانات ثابتة لنقل الأرقام المحمولة). راجع خيارات التوجيه للحصول على التفاصيل.	false
`routing_instruction`	string	نص مفصول بنقطتين يصف تعليمات التوجيه المستخدمة في الطلب. المكون الأول هو `STATIC` عندما تحدد مساراً أو `AUTO` للتوجيه التلقائي؛ المكون الثاني هو معرّف المسار، وبالنسبة لطلبات التوجيه التلقائي يظهر مكون ثالث يوضح الأصل الذي تم بناءً عليه اتخاذ قرار التوجيه (أي `SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`).	false

الحالة	الوصف
CONNECTED	الرقم صالح، والجهاز المستهدف متصل حالياً بشبكة الهاتف المحمول. يجب أن تصل المكالمات والرسائل النصية والخدمات الأخرى إلى المستلم بنجاح.
ABSENT	الرقم صالح، لكن الجهاز المستهدف إما مغلق أو خارج نطاق تغطية الشبكة مؤقتاً. قد لا يتم تسليم الرسائل أو المكالمات حتى يعاود الجهاز الاتصال بالشبكة.
INVALID_MSISDN	الرقم غير صالح أو غير مخصص حالياً لأي مشترك على شبكة الهاتف المحمول. ستفشل المكالمات والرسائل إلى هذا الرقم.
UNDETERMINED	تعذر تحديد حالة الاتصال للرقم. قد يكون ذلك بسبب رقم غير صالح، أو استجابة خطأ SS7، أو عدم وجود اتصال مع مشغل الشبكة المستهدف. راجع رمز الخطأ وحقل الوصف الخاص به للحصول على تشخيصات إضافية.

التمرير لأعلى

POST/mnp-lookupمحمي

يقوم بإجراء استعلام متزامن لنقل الأرقام ويوفر معلومات حول قابلية نقل الأرقام المحمولة والشبكة. هذه النقطة النهائية مناسبة إذا كان هدفك الأساسي هو استخراج رمز MCCMNC الحالي لرقم هاتف محمول معين وتحديد الشبكات الأصلية والحالية في الوقت الفعلي.

للمعالجة الجماعية لمجموعات البيانات الكبيرة التي لا تتطلب نتائج فورية، يُرجى استخدام POST /mnp-lookups غير المتزامن، والمُحسَّن للمعالجة الدفعية عالية السرعة.

تحدد استعلامات نقل الأرقام بشكل موثوق معلومات القابلية للنقل والشبكة ولكنها لا تشير إلى ما إذا كان الهاتف المحمول المستهدف متصلاً حالياً بالشبكة وقابلاً للوصول. لاستخراج معلومات الاتصال المباشر، يرجى استخدام نقطة POST /hlr-lookup بدلاً من ذلك.

الطلب استجابة ناجحة استجابة خطأ

curl -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookup' \
          -d "@payload.json"

البيانات المرسلة

{
   "msisdn":"+14156226819",
   "route":null,
   "storage":null
}

معاملات الطلب

المفتاح	النوع	الوصف	افتراضي	إلزامي
`msisdn`	string	رقم الهاتف المحمول (MSISDN) المراد الاستعلام عنه، مُقدَّم بالصيغة الدولية (مثل +14156226819 أو 0014156226819). يجب تضمين رموز الدول.	null	إلزامي
`route`	string(3)	معرّف اختياري مكون من ثلاثة أحرف يحدد المسار لهذا الاستعلام. اضبطه على `null` أو احذف هذا المعامل لتطبيق خريطة التوجيه المخصصة الخاصة بك أو دع نظامنا يحدد تلقائياً أفضل مسار لهذا الاستعلام.	null	اختياري
`storage`	string	معرّف تخزين اختياري يحدد التقرير الذي سيتم فيه تخزين النتائج للمراجعة اليدوية والتحليلات وإعداد التقارير. يضيف النظام تلقائياً طابعاً زمنياً بالشهر الحالي. إذا تم حذفه أو ضبطه على `null`، سيقوم النظام تلقائياً بتجميع النتائج حسب الشهر لأغراض إعداد التقارير.	null	اختياري

{
   "id":"e428acb1c0ae",
   "msisdn":"+14156226819",
   "query_status":"OK",
   "mccmnc":"310260",
   "mcc":"310",
   "mnc":"260",
   "is_ported":true,
   "original_network_name":"Verizon Wireless:6006 - SVR/2",
   "original_country_name":"United States",
   "original_country_code":"US",
   "original_country_prefix":"+1415",
   "ported_network_name":"T-Mobile US:6529 - SVR/2",
   "ported_country_name":"United States",
   "ported_country_code":"US",
   "ported_country_prefix":"+1",
   "extra":"LRN:4154250000",
   "cost":"0.0050",
   "timestamp":"2020-08-05 21:21:33.490+0300",
   "storage":"WEB-CLIENT-SOLO-MNP-2020-08",
   "route":"PTX",
   "error_code":null
}

خصائص الاستجابة الناجحة

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`id`	string(12)	معرّف فريد مكون من 12 حرفاً لهذا الاستعلام.	false
`msisdn`	string	رقم الهاتف المحمول الذي تم تقييمه في طلب الاستعلام هذا.	false
`query_status`	string	يشير إلى ما إذا كان استرجاع معلومات قابلية النقل والشبكة ناجحاً. القيم المحتملة هي `OK` أو `FAILED`.	false
`mccmnc`	string(5\|6)	رمز MCCMNC مكون من خمسة أو ستة أحرف (رمز الدولة المحمول ورمز الشبكة المحمولة) يحدد الشبكة التي ينتمي إليها رقم الهاتف المحمول حالياً.	true
`mcc`	string(3)	رمز MCC مكون من ثلاثة أحرف (رمز الدولة المحمول) يمثل الدولة المرتبطة بالشبكة الحالية لرقم الهاتف المحمول.	true
`mnc`	string(2\|3)	رمز MNC مكون من حرفين أو ثلاثة أحرف (رمز الشبكة المحمولة) يحدد مشغل الشبكة الحالي لرقم الهاتف المحمول.	true
`is_ported`	boolean	يشير إلى ما إذا كان رقم الهاتف قد تم نقله من شبكته الأصلية إلى مشغل جديد.	true
`original_network_name`	string	نص اختياري (بالإنجليزية) يحدد اسم مشغل الشبكة الأصلي لرقم الهاتف المحمول المفحوص.	true
`original_country_name`	string	نص اختياري (بالإنجليزية) يشير إلى الدولة الأصلية لرقم الهاتف المحمول المفحوص.	true
`original_country_code`	string(2)	رمز دولة ISO مكون من حرفين يمثل الدولة الأصلية لرقم الهاتف المحمول المفحوص.	true
`original_country_prefix`	string	رمز الاتصال الدولي للدولة الأصلية المرتبطة برقم الهاتف المحمول المفحوص.	true
`ported_network_name`	string	يحدد مشغل الشبكة الذي تم نقل رقم الهاتف المحمول المفحوص إليه، إن وجد.	true
`ported_country_name`	string	يحدد الدولة التي تم نقل رقم الهاتف المحمول المفحوص إليها، إن وجدت.	true
`ported_country_code`	string(2)	رمز دولة ISO مكون من حرفين يمثل الدولة التي تم نقل رقم الهاتف المحمول المفحوص إليها، إن وجدت.	true
`ported_country_prefix`	string	رمز الاتصال الدولي للدولة التي تم نقل رقم الهاتف المحمول المفحوص إليها، إن وجدت.	true
`extra`	string	نص اختياري يوفر تفاصيل إضافية حول رقم الهاتف.	true
`cost`	string	قيمة عشرية، ممثلة كنص، تشير إلى التكلفة باليورو لهذا الاستعلام.	true
`timestamp`	string	طابع زمني بتنسيق W3C، يتضمن معلومات المنطقة الزمنية، يشير إلى وقت اكتمال الاستعلام.	true
`storage`	string	اسم التخزين (أو اسم التقرير) الذي تمت إضافة نتائج الاستعلام إليه. يُستخدم هذا لتنزيلات CSV وإعداد التقارير عبر واجهة الويب.	true
`route`	string(3)	معرّف مكون من ثلاثة أحرف يحدد المسار المستخدم لطلب الاستعلام هذا.	true
`error_code`	integer	رمز خطأ داخلي اختياري يوفر سياقاً إضافياً لتشخيصات دعم العملاء.	true

{
    "errors":[
        "Service unavailable."
    ]
}

معاملات استجابة الخطأ

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`errors[]`	string[]	قائمة من النصوص توضح الخطأ.	false

التمرير لأعلى

POST/mnp-lookupsمحمي

يبدأ دفعة من عمليات البحث غير المتزامنة لنقل الأرقام (MNP)، لاسترجاع MCCMNC الحالي وتحديد الشبكات الأصلية والحالية في الوقت الفعلي. يتم تسليم النتائج عبر webhooks إلى الخادم الخاص بك. هذه الطريقة محسّنة لمعالجة أحجام كبيرة من الأرقام التي لا تتطلب استجابات فورية، مثل تنظيف قواعد البيانات والتحقق منها. للتطبيقات الفورية مثل توجيه المكالمات أو تسليم الرسائل القصيرة، يُرجى استخدام نقطة نهاية POST /mnp-lookup بدلاً من ذلك.

تحدد استعلامات نقل الأرقام بشكل موثوق معلومات القابلية للنقل والشبكة ولكنها لا تشير إلى ما إذا كان الهاتف المحمول المستهدف متصلاً حالياً بالشبكة وقابلاً للوصول. لاستخراج معلومات الاتصال المباشر، يرجى استخدام نقطة POST /hlr-lookups بدلاً من ذلك.

قبل استخدام نقطة النهاية هذه، تأكد من تكوين عنوان URL لـ webhook لاستقبال نتائج البحث بشكل غير متزامن. يمكنك إعداد ذلك في إعدادات API الخاصة بك.

الطلب استجابة ناجحة استجابة خطأ Webhooks

curl -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookups' \
          -d "@payload.json"

البيانات المرسلة

{
   "msisdns":["+14156226819","+491788735000","+905536939460"],
   "route":null,
   "storage":null
}

معاملات الطلب

المفتاح	النوع	الوصف	افتراضي	إلزامي
`msisdns`	array	مصفوفة من أرقام الهواتف المحمولة (MSISDNs) بالتنسيق الدولي (مثل +14156226819 أو 0014156226819). يمكنك تضمين ما يصل إلى 1000 رقم لكل طلب.	null	إلزامي
`route`	string(3)	معرّف اختياري مكون من ثلاثة أحرف يحدد المسار لهذا البحث. اضبطه على `null` أو احذف هذا المعامل لتطبيق خريطة التوجيه المخصصة أو السماح لنظامنا بتحديد المسارات الأفضل تلقائياً لهذا الطلب.	null	اختياري
`storage`	string	معرّف تخزين اختياري يحدد التقرير الذي سيتم فيه تخزين النتائج للمراجعة اليدوية والتحليلات وإعداد التقارير. يضيف النظام تلقائياً طابعاً زمنياً بالشهر الحالي. إذا تم حذفه أو ضبطه على `null`، سيقوم النظام تلقائياً بتجميع النتائج حسب الشهر لأغراض إعداد التقارير.	null	اختياري

{
   "accepted":[
      {
         "id":"0424928f332e",
         "msisdn":"+491788735000"
      }
   ],
   "accepted_count":1,
   "rejected":[
      {
         "id":null,
         "msisdn":"+31"
      }
   ],
   "rejected_count":1,
   "total_count":2,
   "cost":"0.01",
   "storage":"ASYNC-API-2020-08",
   "route":"IP1",
   "webhook_urls":[
      "https://your-server.com/endpoint"
   ]
}

خصائص الاستجابة الناجحة

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`accepted`	array	قائمة بالكائنات التي تحتوي على معرفات فريدة وأرقام MSISDNs التي تم قبولها للمعالجة.	false
`accepted_count`	integer	العدد الإجمالي لأرقام MSISDNs التي تم قبولها بنجاح للمعالجة.	false
`rejected`	array	قائمة بالكائنات التي تحتوي على معرفات فريدة وأرقام MSISDNs التي تم رفضها للمعالجة، عادةً بسبب أرقام غير صالحة. لا يتم تطبيق أي رسوم على الإدخالات المرفوضة.	false
`rejected_count`	integer	العدد الإجمالي لأرقام MSISDNs المرفوضة بسبب أخطاء التحقق.	false
`total_count`	integer	العدد الإجمالي لأرقام MSISDNs المقبولة والمرفوضة التي تم إرسالها للمعالجة.	false
`cost`	string	قيمة عشرية ممثلة كنص، تشير إلى التكلفة الإجمالية باليورو لعمليات البحث المقبولة.	false
`storage`	string	اسم المخزن الذي يتم إلحاق نتائج البحث به، ويُستخدم لإعداد التقارير وتنزيلات CSV عبر واجهة الويب.	false
`route`	string(3)	معرّف مكون من ثلاثة أحرف يحدد المسار المستخدم لطلب الاستعلام هذا.	false
`webhook_urls`	array	عناوين URL لـ webhook المكونة في إعدادات API الخاصة بك. يتم نشر النتائج مرة أخرى هنا.	false

{
    "errors":[
        "Service unavailable."
    ]
}

معاملات استجابة الخطأ

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`errors[]`	string[]	قائمة من النصوص توضح الخطأ.	false

معالجة الويب هوك

بمجرد الإرسال، تبدأ منصتنا في معالجة أرقام الهواتف المقدمة وترسل النتائج إلى عنوان URL للويب هوك المحدد مسبقاً على الخادم الخاص بك. يتم إرسال النتائج كطلب HTTP POST مع كائن JSON في نص الطلب.

المصادقة

قم بمصادقة الويب هوك من خلال فحص رأس HTTP الخاص بـ X-Signatures.

يحتوي رأس X-Signatures على قائمة توقيعات مفصولة بفاصلة منقوطة. يتم إنشاء كل توقيع في القائمة باستخدام أحد أسرار API المكونة في حسابك. للتحقق من الويب هوك، قم بإنشاء تجزئة SHA-256 باستخدام مفتاح API والسر ونص HTTP الخام، ثم قارنها بالتوقيعات الموجودة في القائمة.

التطابق يؤكد أن الطلب أصلي وموقّع بسر تتحكم فيه.

مثال على الكود

$signaturesHeader = (getallheaders() ?? [])['X-Signatures'] ?? ''; // list of signatures
$key = getenv('AUTH_KEY'); // Your API Key
$secret = getenv('AUTH_SECRET'); // Your API Secret
$payload = file_get_contents('php://input'); // The HTTP body of the incoming POST request

// Generate the expected signature
$expectedSignature = hash('sha256', $key . $secret . $payload);

// Split the header into individual signatures
$providedSignatures = explode(';', $signaturesHeader);

// Check if any signature matches
$valid = false;
foreach ($providedSignatures as $sig) {
    if (hash_equals($expectedSignature, $sig)) {
        $valid = true;
        break;
    }
}

يكون الطلب صالحاً إذا كان أي من التوقيعات المعطاة في الرأس يساوي تجزئة SHA256 المحسوبة من السلسلة المدمجة لمفتاح API والسر ونص HTTP.

تأكيد الاستلام

من المتوقع أن يستجيب الخادم الخاص بك برمز حالة HTTP 200 OK لتأكيد الاستلام الناجح. إذا تم إرجاع أي رمز استجابة آخر، أو حدث انقطاع في الاتصال (10 ثوانٍ)، أو نشأت أي مشكلة أخرى في التسليم، سيقوم النظام تلقائياً بإعادة محاولة الويب هوك بعد دقيقة واحدة. إذا استمر فشل الطلب، ستتبع إعادات المحاولة استراتيجية التراجع الأسي، مع محاولات لاحقة بعد 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 دقيقة.

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

حمولة الويب هوك

{
    "type":"MNP",
    "results":[
        {
           "id":"e428acb1c0ae",
           "msisdn":"+14156226819",
           "query_status":"OK",
           "mccmnc":"310260",
           "mcc":"310",
           "mnc":"260",
           "is_ported":true,
           "original_network_name":"Verizon Wireless:6006 - SVR/2",
           "original_country_name":"United States",
           "original_country_code":"US",
           "original_country_prefix":"+1415",
           "ported_network_name":"T-Mobile US:6529 - SVR/2",
           "ported_country_name":"United States",
           "ported_country_code":"US",
           "ported_country_prefix":"+1",
           "extra":"LRN:4154250000",
           "cost":"0.0050",
           "timestamp":"2020-08-05 21:21:33.490+0300",
           "storage":"WEB-CLIENT-SOLO-MNP-2020-08",
           "route":"PTX",
           "error_code":null
        }
    ]
}

سمات حمولة Webhook

يحتوي كائن JSON على سمة type => MNP إلى جانب سمة results التي تتضمن قائمة بكائنات البحث، كما هو موثق أدناه.

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`id`	string(12)	معرّف فريد مكون من 12 حرفاً لهذا الاستعلام.	false
`msisdn`	string	رقم الهاتف المحمول الذي تم تقييمه في طلب الاستعلام هذا.	false
`query_status`	string	يشير إلى ما إذا كان استرجاع معلومات قابلية النقل والشبكة ناجحاً. القيم المحتملة هي `OK` أو `FAILED`.	false
`mccmnc`	string(5\|6)	رمز MCCMNC مكون من خمسة أو ستة أحرف (رمز الدولة المحمول ورمز الشبكة المحمولة) يحدد الشبكة التي ينتمي إليها رقم الهاتف المحمول حالياً.	true
`mcc`	string(3)	رمز MCC مكون من ثلاثة أحرف (رمز الدولة المحمول) يمثل الدولة المرتبطة بالشبكة الحالية لرقم الهاتف المحمول.	true
`mnc`	string(2\|3)	رمز MNC مكون من حرفين أو ثلاثة أحرف (رمز الشبكة المحمولة) يحدد مشغل الشبكة الحالي لرقم الهاتف المحمول.	true
`is_ported`	boolean	يشير إلى ما إذا كان رقم الهاتف قد تم نقله من شبكته الأصلية إلى مشغل جديد.	true
`original_network_name`	string	نص اختياري (بالإنجليزية) يحدد اسم مشغل الشبكة الأصلي لرقم الهاتف المحمول المفحوص.	true
`original_country_name`	string	نص اختياري (بالإنجليزية) يشير إلى الدولة الأصلية لرقم الهاتف المحمول المفحوص.	true
`original_country_code`	string(2)	رمز دولة ISO مكون من حرفين يمثل الدولة الأصلية لرقم الهاتف المحمول المفحوص.	true
`original_country_prefix`	string	رمز الاتصال الدولي للدولة الأصلية المرتبطة برقم الهاتف المحمول المفحوص.	true
`ported_network_name`	string	يحدد مشغل الشبكة الذي تم نقل رقم الهاتف المحمول المفحوص إليه، إن وجد.	true
`ported_country_name`	string	يحدد الدولة التي تم نقل رقم الهاتف المحمول المفحوص إليها، إن وجدت.	true
`ported_country_code`	string(2)	رمز دولة ISO مكون من حرفين يمثل الدولة التي تم نقل رقم الهاتف المحمول المفحوص إليها، إن وجدت.	true
`ported_country_prefix`	string	رمز الاتصال الدولي للدولة التي تم نقل رقم الهاتف المحمول المفحوص إليها، إن وجدت.	true
`extra`	string	نص اختياري يوفر تفاصيل إضافية حول رقم الهاتف.	true
`cost`	string	قيمة عشرية، ممثلة كنص، تشير إلى التكلفة باليورو لهذا الاستعلام.	true
`timestamp`	string	طابع زمني بتنسيق W3C، يتضمن معلومات المنطقة الزمنية، يشير إلى وقت اكتمال الاستعلام.	true
`storage`	string	اسم التخزين (أو اسم التقرير) الذي تمت إضافة نتائج الاستعلام إليه. يُستخدم هذا لتنزيلات CSV وإعداد التقارير عبر واجهة الويب.	true
`route`	string(3)	معرّف مكون من ثلاثة أحرف يحدد المسار المستخدم لطلب الاستعلام هذا.	true
`error_code`	integer	رمز خطأ داخلي اختياري يوفر سياقاً إضافياً لتشخيصات دعم العملاء.	true

التمرير لأعلى

POST/nt-lookupمحمي

يستدعي استعلام متزامن عن نوع الرقم (NT). هذه النقطة النهائية مثالية إذا كان هدفك الأساسي هو تحديد ما إذا كانت أرقام الهواتف المقدمة تنتمي إلى نطاقات الخطوط الأرضية أو المحمولة أو الأسعار المميزة أو VoIP أو أجهزة النداء أو نطاقات الترقيم الأخرى في الوقت الفعلي.

تكتشف استعلامات NT نوع رقم الهاتف بشكل موثوق، ولكنها لا تشير إلى ما إذا كان الرقم المستهدف متصلاً حالياً بشبكة ويمكن الوصول إليه. لاستخراج معلومات الاتصال المباشر، يرجى استخدام النقطة النهائية POST /hlr-lookup.

إذا كانت حالة استخدامك تتطلب معلومات دقيقة عن الشبكة وقابلية النقل (MCCMNC) ولكن ليس حالة الاتصال المباشر، يرجى استخدام النقطة النهائية POST /mnp-lookup لاستعلامات نقل أرقام الهواتف المحمولة.

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

curl -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookup' \
          -d "@payload.json"

البيانات المرسلة

{
   "number":"+14156226819",
   "route":null,
   "storage":null
}

معاملات الطلب

المفتاح	النوع	الوصف	افتراضي	إلزامي
`number`	string	رقم هاتف بالصيغة الدولية (مثل +4989702626 أو 004989702626).	null	mandatory
`route`	string(3)	معرّف اختياري مكون من ثلاثة أحرف يحدد المسار لهذا الاستعلام. اضبطه على `null` أو احذف هذه المعلمة لتطبيق خريطة التوجيه المخصصة الخاصة بك أو دع نظامنا يحدد تلقائياً أفضل المسارات لهذا الطلب.	null	اختياري
`storage`	string	معرّف تخزين اختياري يحدد التقرير الذي سيتم فيه تخزين النتائج للمراجعة اليدوية والتحليلات وإعداد التقارير. يضيف النظام تلقائياً طابعاً زمنياً بالشهر الحالي. إذا تم حذفه أو ضبطه على `null`، سيقوم النظام تلقائياً بتجميع النتائج حسب الشهر لأغراض إعداد التقارير.	null	اختياري

{
     "id":"2ed0788379c6",
     "number":"+4989702626",
     "number_type":"LANDLINE",
     "query_status":"OK",
     "is_valid":true,
     "invalid_reason":null,
     "is_possibly_ported":false,
     "is_vanity_number":false,
     "qualifies_for_hlr_lookup":false,
     "mccmnc":null,
     "mcc":null,
     "mnc":null,
     "original_network_name":null,
     "original_country_name":"Germany",
     "original_country_code":"DE",
     "regions":[
        "Munich"
     ],
     "timezones":[
        "Europe/Berlin"
     ],
     "info_text":"This is a landline number.",
     "cost":"0.0050",
     "timestamp":"2015-12-04 10:36:41.866283+00",
     "storage":"SYNC-API-NT-2015-12",
     "route":"LC1"
}

خصائص الاستجابة الناجحة

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`id`	string(12)	معرّف فريد مخصص لطلب الاستعلام هذا.	false
`number`	string	رقم الهاتف الذي تم تقييمه خلال طلب الاستعلام هذا.	false
`number_type`	string	نوع الرقم المكتشف. القيم المحتملة تشمل: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	يشير إلى ما إذا تم الحصول على معلومات نوع الرقم بنجاح. يُرجع `OK` في حالة النجاح، أو `FAILED` في حالة فشل الاستعلام.	false
`is_valid`	boolean	يشير إلى ما إذا كان رقم الهاتف صالحاً من الناحية الصياغية.	true
`invalid_reason`	string	رسالة نصية باللغة الإنجليزية توضح سبب اعتبار رقم الهاتف غير صالح (مثل "too short" أو "invalid prefix")، أو `null` إذا كان الرقم صالحاً.	true
`is_possibly_ported`	boolean	يشير إلى ما إذا كان رقم الهاتف قد تم نقله من مشغله الأصلي إلى مشغل آخر. للحصول على معلومات نهائية حول قابلية النقل، استخدم استعلامات MNP.	true
`is_vanity_number`	boolean	يشير إلى ما إذا كان رقم الهاتف رقماً مخصصاً، أي أنه يتضمن أحرفاً أبجدية.	true
`qualifies_for_hlr_lookup`	boolean	يشير إلى ما إذا كان رقم الهاتف مؤهلاً لاستعلامات إضافية من خلال استعلامات HLR.	true
`mccmnc`	string(5\|6)	سلسلة نصية مكونة من خمسة أو ستة أحرف تمثل MCCMNC (رمز الدولة المتنقل ورمز الشبكة المتنقلة) الذي يحدد الشبكة الأصلية لرقم الهاتف المتنقل.	true
`mcc`	string(3)	سلسلة نصية مكونة من ثلاثة أحرف تمثل MCC (رمز الدولة المتنقل) الذي يحدد الدولة المرتبطة بالشبكة المتنقلة الأصلية لرقم الهاتف.	true
`mnc`	string(2\|3)	سلسلة نصية مكونة من حرفين أو ثلاثة أحرف تمثل MNC (رمز الشبكة المتنقلة) الذي يحدد مشغل الشبكة المتنقلة الأصلي لرقم الهاتف.	true
`original_network_name`	string	سلسلة نصية باللغة الإنجليزية تحدد اسم مشغل الشبكة الأصلي لرقم الهاتف المتنقل المفحوص.	true
`original_country_name`	string	سلسلة نصية باللغة الإنجليزية تحدد الدولة الأصلية المرتبطة برقم الهاتف المتنقل المفحوص.	true
`original_country_code`	string(2)	رمز دولة ISO مكون من حرفين يشير إلى الدولة الأصلية لرقم الهاتف المتنقل المفحوص.	true
`regions`	array	قائمة بالسلاسل النصية المقروءة باللغة الإنجليزية التي تحدد المنطقة (المناطق) الجغرافية المرتبطة برقم الهاتف هذا.	true
`timezones`	array	قائمة بالمناطق الزمنية (بتنسيق Olson) المرتبطة برقم الهاتف هذا.	true
`info_text`	string	سلسلة نصية قد تحتوي على معلومات إضافية حول رقم الهاتف.	true
`cost`	string	قيمة عشرية ممثلة كسلسلة نصية، تشير إلى تكلفة هذا الاستعلام (باليورو).	true
`timestamp`	string	طابع زمني بتنسيق W3C (يتضمن المنطقة الزمنية) يشير إلى وقت إتمام الاستعلام.	true
`storage`	string	يحدد اسم التخزين حيث تم إلحاق نتائج الاستعلام. يتوافق هذا مع اسم التقرير المستخدم لتنزيلات CSV والتحليلات عبر واجهة الويب.	true
`route`	string(3)	معرّف مكون من ثلاثة أحرف يحدد المسار المستخدم لطلب الاستعلام هذا.	true

{
    "errors":[
        "Service unavailable."
    ]
}

معاملات استجابة الخطأ

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`errors[]`	string[]	قائمة من النصوص توضح الخطأ.	false

النوع	الوصف
LANDLINE	رقم هاتف أرضي.
MOBILE	رقم هاتف محمول. مؤهل لاستعلامات HLR للحصول على معلومات إضافية حول حالة الاتصال والشبكة وقابلية النقل والتجوال.
MOBILE_OR_LANDLINE	رقم هاتف أرضي أو محمول. قد يكون مؤهلاً لاستعلام HLR.
TOLL_FREE	رقم هاتف مجاني.
PREMIUM_RATE	رقم هاتف بتعرفة مميزة مع رسوم إضافية.
SHARED_COST	رقم هاتف بتكلفة مشتركة. عادةً ما يكون أقل تكلفة من أرقام الهواتف ذات التعرفة المميزة.
VOIP	رقم هاتف عبر بروتوكول الإنترنت (VoIP). يشمل أرقام TSoIP (خدمة الهاتف عبر بروتوكول الإنترنت).
PAGER	رقم جهاز النداء الآلي. عادةً بدون وظيفة صوتية.
UAN	رقم الوصول الموحد (رقم الشركة). قد يتم توجيهه إلى مكاتب محددة ولكنه يتيح استخدام رقم واحد للشركة.
VOICEMAIL	رقم هاتف البريد الصوتي.
UNKNOWN	تعذر تحديد نوع الرقم.

التمرير لأعلى

POST/nt-lookups محمي

تقوم هذه النقطة الطرفية بتنفيذ سلسلة من عمليات البحث غير المتزامنة عن نوع الرقم مع إرسال النتائج إلى خادمك عبر webhook. إنها مناسبة إذا كان هدفك الأساسي هو تحديد ما إذا كانت أرقام الهواتف المعطاة تنتمي إلى نطاقات الخطوط الأرضية أو الجوال أو الأسعار المميزة أو VoIP أو أجهزة النداء أو نطاقات خطط الترقيم الأخرى. محسّنة للمعالجة السريعة لأحجام كبيرة من الأرقام، هذه النقطة الطرفية مثالية للعمليات المجمعة (مثل تنظيف قواعد البيانات). للحركة المباشرة وحالات الاستخدام الحساسة للوقت، يرجى استخدام نقطة POST /nt-lookup الطرفية بدلاً من ذلك.

تحتاج إلى تحديد عنوان URL لـ webhook في إعدادات API كشرط أساسي لاستدعاء هذه النقطة الطرفية.

الطلب استجابة ناجحة استجابة خطأ Webhooks مرجع الأنواع

curl -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookups' \
          -d "@payload.json"

البيانات المرسلة

{
   "numbers":["+14156226819","+4989702626"],
   "route":null,
   "storage":null
}

معاملات الطلب

المفتاح	النوع	الوصف	افتراضي	إلزامي
`numbers`	array	مصفوفة من أرقام الهواتف بالتنسيق الدولي (مثل +14156226819 أو 004989702626). يمكن تضمين حد أقصى 1000 رقم لكل طلب.	null	إلزامي
`route`	string(3)	معرّف اختياري مكون من ثلاثة أحرف يحدد المسار لهذا البحث. اضبطه على `null` أو احذف هذه المعلمة لتطبيق خريطة التوجيه المخصصة أو السماح لنظامنا بتحديد المسار الأفضل تلقائياً لهذا الطلب.	null	اختياري
`storage`	string	معرّف تخزين اختياري يحدد التقرير الذي سيتم فيه تخزين النتائج للمراجعة اليدوية والتحليلات وإعداد التقارير. يضيف النظام تلقائياً طابعاً زمنياً بالشهر الحالي. إذا تم حذفه أو ضبطه على `null`، سيقوم النظام تلقائياً بتجميع النتائج حسب الشهر لأغراض إعداد التقارير.	null	اختياري

{
   "accepted":[
      {
         "id":"9f8a52cfa7d2",
         "number":"+905536939460"
      }
   ],
   "accepted_count":1,
   "rejected":[
      {
         "id":null,
         "number":"+31"
      }
   ],
   "rejected_count":2,
   "total_count":3,
   "cost":0.005,
   "storage":"ASYNC-API-NT-2020-08",
   "route":"LC1",
   "webhook_urls":[
      "https://your-server.com/endpoint"
   ]
}

خصائص الاستجابة الناجحة

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`accepted`	array	مصفوفة من الكائنات، يحتوي كل منها على معرّف فريد ورقم هاتف تم قبوله للمعالجة.	false
`accepted_count`	integer	العدد الإجمالي لأرقام الهواتف المقبولة للمعالجة.	false
`rejected`	array	مصفوفة من الكائنات، يحتوي كل منها على معرّف فريد ورقم هاتف تم رفضه للمعالجة. عادةً ما تكون هذه الأرقام غير صالحة، ولا يتم تطبيق أي رسوم.	false
`rejected_count`	integer	العدد الإجمالي لأرقام الهواتف التي تم رفضها للمعالجة.	false
`total_count`	integer	العدد الإجمالي لأرقام الهواتف المقبولة والمرفوضة التي تم إرسالها للمعالجة.	false
`cost`	string	سلسلة نصية تمثل قيمة عشرية تشير إلى التكلفة باليورو لعمليات البحث هذه.	false
`storage`	string	اسم التخزين (التقرير) حيث تم إلحاق نتائج البحث. يُستخدم هذا الاسم لتنزيلات CSV والتحليلات عبر واجهة الويب.	false
`route`	string(3)	معرّف مكون من ثلاثة أحرف يحدد المسار المستخدم لطلب البحث هذا.	false
`webhook_urls`	array	عناوين URL لـ webhook المكونة في إعدادات API الخاصة بك. يتم نشر النتائج مرة أخرى هنا.	false

{
    "errors":[
        "Service unavailable."
    ]
}

معاملات استجابة الخطأ

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`errors[]`	string[]	قائمة من النصوص توضح الخطأ.	false

معالجة الويب هوك

بمجرد الإرسال، تبدأ منصتنا في معالجة أرقام الهواتف المقدمة وترسل النتائج إلى عنوان URL للويب هوك المحدد مسبقاً على الخادم الخاص بك. يتم إرسال النتائج كطلب HTTP POST مع كائن JSON في نص الطلب.

المصادقة

قم بمصادقة الويب هوك من خلال فحص رأس HTTP الخاص بـ X-Signatures.

يحتوي رأس X-Signatures على قائمة توقيعات مفصولة بفاصلة منقوطة. يتم إنشاء كل توقيع في القائمة باستخدام أحد أسرار API المكونة في حسابك. للتحقق من الويب هوك، قم بإنشاء تجزئة SHA-256 باستخدام مفتاح API والسر ونص HTTP الخام، ثم قارنها بالتوقيعات الموجودة في القائمة.

التطابق يؤكد أن الطلب أصلي وموقّع بسر تتحكم فيه.

مثال على الكود

$signaturesHeader = (getallheaders() ?? [])['X-Signatures'] ?? ''; // list of signatures
$key = getenv('AUTH_KEY'); // Your API Key
$secret = getenv('AUTH_SECRET'); // Your API Secret
$payload = file_get_contents('php://input'); // The HTTP body of the incoming POST request

// Generate the expected signature
$expectedSignature = hash('sha256', $key . $secret . $payload);

// Split the header into individual signatures
$providedSignatures = explode(';', $signaturesHeader);

// Check if any signature matches
$valid = false;
foreach ($providedSignatures as $sig) {
    if (hash_equals($expectedSignature, $sig)) {
        $valid = true;
        break;
    }
}

يكون الطلب صالحاً إذا كان أي من التوقيعات المعطاة في الرأس يساوي تجزئة SHA256 المحسوبة من السلسلة المدمجة لمفتاح API والسر ونص HTTP.

تأكيد الاستلام

من المتوقع أن يستجيب الخادم الخاص بك برمز حالة HTTP 200 OK لتأكيد الاستلام الناجح. إذا تم إرجاع أي رمز استجابة آخر، أو حدث انقطاع في الاتصال (10 ثوانٍ)، أو نشأت أي مشكلة أخرى في التسليم، سيقوم النظام تلقائياً بإعادة محاولة الويب هوك بعد دقيقة واحدة. إذا استمر فشل الطلب، ستتبع إعادات المحاولة استراتيجية التراجع الأسي، مع محاولات لاحقة بعد 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 دقيقة.

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

حمولة الويب هوك

{
   "type":"NT",
   "results":[
      {
         "id":"9f8a52cfa7d2",
         "number":"+905536939460",
         "numbertype":"MOBILE",
         "state":"COMPLETED",
         "isvalid":"Yes",
         "invalidreason":null,
         "ispossiblyported":"Yes",
         "isvanitynumber":"No",
         "qualifiesforhlrlookup":"Yes",
         "originalcarrier":"Turk Telekom (AVEA)",
         "mccmnc":"28603",
         "mcc":"286",
         "mnc":"03",
         "countrycode":"TR",
         "regions":[
            "Turkey"
         ],
         "timezones":[
            "Europe\/Istanbul"
         ],
         "infotext":"This number qualifies for HLR lookups. Determine if this subscriber number is connected, absent or invalid by running an HLR lookup. This is a mobile number and might be in roaming state. Run an HLR lookup to obtain roaming information (if available). This number is possibly ported and the carrier information might be inaccurate. To obtain portability information run an HLR lookup.",
         "usercharge":"0.0050",
         "inserttime":"2020-08-13 01:57:15.897+0300",
         "storage":"ASYNC-API-NT-2020-08",
         "route":"LC1",
         "interface":"Async API"
      }
   ]
}

سمات حمولة Webhook

يحتوي كائن JSON على سمة type => NT إلى جانب سمة results التي تتضمن قائمة بكائنات البحث، كما هو موثق أدناه.

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`id`	string(12)	معرّف فريد مخصص لطلب الاستعلام هذا.	false
`number`	string	رقم الهاتف الذي تم تقييمه خلال طلب الاستعلام هذا.	false
`number_type`	string	نوع الرقم المكتشف. القيم المحتملة تشمل: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	يشير إلى ما إذا تم الحصول على معلومات نوع الرقم بنجاح. يُرجع `OK` في حالة النجاح، أو `FAILED` في حالة فشل الاستعلام.	false
`is_valid`	boolean	يشير إلى ما إذا كان رقم الهاتف صالحاً من الناحية الصياغية.	true
`invalid_reason`	string	رسالة نصية باللغة الإنجليزية توضح سبب اعتبار رقم الهاتف غير صالح (مثل "too short" أو "invalid prefix")، أو `null` إذا كان الرقم صالحاً.	true
`is_possibly_ported`	boolean	يشير إلى ما إذا كان رقم الهاتف قد تم نقله من مشغله الأصلي إلى مشغل آخر. للحصول على معلومات نهائية حول قابلية النقل، استخدم استعلامات MNP.	true
`is_vanity_number`	boolean	يشير إلى ما إذا كان رقم الهاتف رقماً مخصصاً، أي أنه يتضمن أحرفاً أبجدية.	true
`qualifies_for_hlr_lookup`	boolean	يشير إلى ما إذا كان رقم الهاتف مؤهلاً لاستعلامات إضافية من خلال استعلامات HLR.	true
`mccmnc`	string(5\|6)	سلسلة نصية مكونة من خمسة أو ستة أحرف تمثل MCCMNC (رمز الدولة المتنقل ورمز الشبكة المتنقلة) الذي يحدد الشبكة الأصلية لرقم الهاتف المتنقل.	true
`mcc`	string(3)	سلسلة نصية مكونة من ثلاثة أحرف تمثل MCC (رمز الدولة المتنقل) الذي يحدد الدولة المرتبطة بالشبكة المتنقلة الأصلية لرقم الهاتف.	true
`mnc`	string(2\|3)	سلسلة نصية مكونة من حرفين أو ثلاثة أحرف تمثل MNC (رمز الشبكة المتنقلة) الذي يحدد مشغل الشبكة المتنقلة الأصلي لرقم الهاتف.	true
`original_network_name`	string	سلسلة نصية باللغة الإنجليزية تحدد اسم مشغل الشبكة الأصلي لرقم الهاتف المتنقل المفحوص.	true
`original_country_name`	string	سلسلة نصية باللغة الإنجليزية تحدد الدولة الأصلية المرتبطة برقم الهاتف المتنقل المفحوص.	true
`original_country_code`	string(2)	رمز دولة ISO مكون من حرفين يشير إلى الدولة الأصلية لرقم الهاتف المتنقل المفحوص.	true
`regions`	array	قائمة بالسلاسل النصية المقروءة باللغة الإنجليزية التي تحدد المنطقة (المناطق) الجغرافية المرتبطة برقم الهاتف هذا.	true
`timezones`	array	قائمة بالمناطق الزمنية (بتنسيق Olson) المرتبطة برقم الهاتف هذا.	true
`info_text`	string	سلسلة نصية قد تحتوي على معلومات إضافية حول رقم الهاتف.	true
`cost`	string	قيمة عشرية ممثلة كسلسلة نصية، تشير إلى تكلفة هذا الاستعلام (باليورو).	true
`timestamp`	string	طابع زمني بتنسيق W3C (يتضمن المنطقة الزمنية) يشير إلى وقت إتمام الاستعلام.	true
`storage`	string	يحدد اسم التخزين حيث تم إلحاق نتائج الاستعلام. يتوافق هذا مع اسم التقرير المستخدم لتنزيلات CSV والتحليلات عبر واجهة الويب.	true
`route`	string(3)	معرّف مكون من ثلاثة أحرف يحدد المسار المستخدم لطلب الاستعلام هذا.	true

النوع	الوصف
LANDLINE	رقم هاتف أرضي.
MOBILE	رقم هاتف محمول. مؤهل لاستعلامات HLR للحصول على معلومات إضافية حول حالة الاتصال والشبكة وقابلية النقل والتجوال.
MOBILE_OR_LANDLINE	رقم هاتف أرضي أو محمول. قد يكون مؤهلاً لاستعلام HLR.
TOLL_FREE	رقم هاتف مجاني.
PREMIUM_RATE	رقم هاتف بتعرفة مميزة مع رسوم إضافية.
SHARED_COST	رقم هاتف بتكلفة مشتركة. عادةً ما يكون أقل تكلفة من أرقام الهواتف ذات التعرفة المميزة.
VOIP	رقم هاتف عبر بروتوكول الإنترنت (VoIP). يشمل أرقام TSoIP (خدمة الهاتف عبر بروتوكول الإنترنت).
PAGER	رقم جهاز النداء الآلي. عادةً بدون وظيفة صوتية.
UAN	رقم الوصول الموحد (رقم الشركة). قد يتم توجيهه إلى مكاتب محددة ولكنه يتيح استخدام رقم واحد للشركة.
VOICEMAIL	رقم هاتف البريد الصوتي.
UNKNOWN	تعذر تحديد نوع الرقم.

التمرير لأعلى

GET/routeمحمي

يسترجع المسار الذي سيتم اختياره تلقائياً عند تشغيل استعلام HLR دون تحديد معامل route.

يعتمد اختيار المسار التلقائي على خريطة التوجيه القابلة للاسترجاع من خلال نقطة النهاية GET /hlr-coverage، والتي تُستمد بشكل أساسي من GET /routing-map. يمكنك تخصيص خريطة التوجيه الخاصة بك وتحديد قواعد مخصصة في إعدادات الحساب.

الطلب استجابة ناجحة استجابة خطأ

curl 'https://www.hlr-lookups.com/api/v2/route?msisdn=+491788735000'

معاملات الطلب

المفتاح	النوع	الوصف	افتراضي	إلزامي
`msisdn`	string	رقم MSISDN الذي سيتم استرجاع معلومات التوجيه المحددة تلقائياً له.	null	إلزامي

{
   "route":"V11",
   "confidence_level":"HIGH",
   "mccmnc":"26203",
   "origin":"SCORE"
}

خصائص الاستجابة الناجحة

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`route`	string	المسار الموصى به.	false
`confidence_level`	string	مستوى الثقة الذي تم به اختيار هذا المسار، أي `LOW` أو `NORMAL` أو `HIGH` أو `MNP_FALLBACK`.	false
`mccmnc`	string	رمز MCCMNC المستند إلى خطة الترقيم لهذا الرقم.	false
`origin`	string	المصدر الذي يعتمد عليه قرار التوجيه، أي `SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`	false

{
    "errors":[
        "Service unavailable."
    ]
}

معاملات استجابة الخطأ

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`errors[]`	string[]	قائمة من النصوص توضح الخطأ.	false

التمرير لأعلى

GET/routesمحمي

تُرجع نقطة النهاية هذه قائمة بمسارات HLR وMNP وNT المتاحة. يتم شرح كل مسار مع ميزاته وقيوده في صفحة تفاصيل التوجيه.

الطلب استجابة ناجحة استجابة خطأ

curl 'https://www.hlr-lookups.com/api/v2/routes'

{
   "routes":{
      "HLR":[
         "V11",
         "E10",
         "MS9",
         "DV8",
         "SV3",
         "IP1"
      ],
      "MNP":[
         "PTX",
         "IP4"
      ],
      "NT":[
         "LC1"
      ]
   }
}

خصائص الاستجابة الناجحة

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`routes`	object	كائن يحتوي على المسارات مجمعة حسب نوع المسار.	false
`HLR\|MNP\|NT`	string[]	يحتوي على قائمة بمعرفات المسارات.	false

{
    "errors":[
        "Service unavailable."
    ]
}

معاملات استجابة الخطأ

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`errors[]`	string[]	قائمة من النصوص توضح الخطأ.	false

التمرير لأعلى

GET/routing-mapمحمي

يسترجع إعدادات التوجيه التلقائي المطبقة حالياً على استعلامات HLR لحسابك. يتم استخدام هذه الإعدادات الافتراضية عند إرسال استعلامات HLR دون تحديد معامل route. يمكنك تخصيص خريطة التوجيه وإنشاء قواعد مخصصة في إعدادات حسابك.

يتدرج التسلسل الهرمي للإعدادات من قواعد مستوى الدولة إلى قواعد مستوى MCCMNC، وأخيراً إلى تعيينات بادئات أرقام الهواتف الفردية. عملياً، هذا يعني أن تعيينات بادئات أرقام الهواتف الفردية لها الأولوية على تعيينات MCCMNC المتعارضة، والتي بدورها تتجاوز قواعد مستوى الدولة. يرجى ملاحظة أن الاحتياطي MNP يتجاوز أي قواعد مخصصة متعارضة عند تفعيله.

الطلب استجابة ناجحة استجابة خطأ

curl 'https://www.hlr-lookups.com/api/v2/routing-map'

{
   "routing":{
      "map":{
         "defaultRoute":"V11",
         "mnpFallback":true,
         "mccmncs":[
            {
               "mccmnc":20201,
               "countrycode":"GR",
               "route":"E10",
               "mno":"Cosmote",
               "confidence":"HIGH",
               "origin":"SCORE"
            }
         ],
         "prefixes":[
            {
               "countrycode":"DE",
               "cns":"+4917821",
               "route":"DV8",
               "mccmnc":"26203",
               "mno":"O2"
            }
         ],
         "countries":[
            {
               "countrycode":"US",
               "route":"DV8"
            }
         ]
      }
   }
}

خصائص الاستجابة الناجحة

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`default_route`	string	المسار الافتراضي المستخدم عندما لا يمكن تحديد خيار توجيه مفضل لرقم MSISDN ولا تنطبق قواعد توجيه مخصصة.	false
`mnp_fallback`	boolean	يشير إلى ما إذا كان الاحتياطي MNP مفعلاً. عند التفعيل وعدم دعم استعلامات HLR من قبل الشبكة (حالة الاتصال غير متوفرة)، سيقوم النظام بإجراء استعلام MNP بدلاً من ذلك.	false
`mccmncs`	array	تعيين رموز MCCMNC إلى مساراتها المحددة تلقائياً. عند إجراء استعلام HLR لرقم في MCCMNC معين، يتم استخدام المسار المقابل.	false
`mccmnc`	string(5\|6)	رمز MCCMNC المكون من خمسة أو ستة أحرف (مزيج من رمز الدولة المحمول ورمز شبكة الهاتف المحمول) الذي يحدد مشغل شبكة الهاتف المحمول.	false
`countrycode`	string(2)	رمز دولة ISO مكون من حرفين، يحدد دولة الشبكة.	false
`route`	string(3)	المسار المحدد للشبكة.	false
`mno`	string	العلامة التجارية الموجهة للمستهلك التي تعمل الشبكة تحتها.	false
`confidence`	string	مستوى الثقة الذي تم به الاختيار. القيم الممكنة هي: HIGH، NORMAL، LOW، MNP_REDIRECT. في حالة الأخيرة، يعيد النظام توجيه حركة المرور لهذه الشبكة إلى MNP، إذا كان هذا السلوك مفعلاً في حسابك. وإلا فإنه يستخدم المسار الافتراضي في الحساب.	false
`origin`	string	المصدر الذي يستند إليه الاختيار. القيم الممكنة هي: `SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`	false
`prefixes`	array	قائمة قواعد التوجيه المخصصة المستندة إلى البادئة والمكونة في حسابك، إن وجدت.	false
`countrycode`	string(2)	رمز دولة ISO مكون من حرفين، يحدد دولة البادئة.	false
`cns`	string	البادئة التي تنطبق عليها قاعدة التوجيه.	false
`route`	string(3)	المسار المحدد للبادئة.	false
`mccmnc`	string(5\|6)	رمز MCCMNC المكون من خمسة أو ستة أحرف (مزيج من رمز الدولة المحمول ورمز شبكة الهاتف المحمول) الذي يحدد مشغل شبكة الهاتف المحمول.	true
`mno`	string	العلامة التجارية الموجهة للمستهلك التي تعمل الشبكة تحتها.	true
`countries`	array	قائمة القواعد المخصصة المستندة إلى الدولة والمكونة في حسابك، إن وجدت.	false
`countrycode`	string(2)	رمز دولة ISO مكون من حرفين، يحدد الدولة.	false
`route`	string(3)	المسار المحدد للدولة.	false

{
    "errors":[
        "Service unavailable."
    ]
}

معاملات استجابة الخطأ

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`errors[]`	string[]	قائمة من النصوص توضح الخطأ.	false

التمرير لأعلى

GET/hlr-coverage محمي

يعرض رؤى تغطية HLR لدعم اتخاذ القرارات المستندة إلى البيانات. تساعدك هذه النقطة في تحليل خيارات التوجيه الفوري لـ HLR عبر شبكات الهاتف المحمول، وتحديد المسارات الأكثر فعالية للمناطق المستهدفة، وتكوين التوجيه التلقائي الخاص بك.

المسارات الموصى بها من GET /route تستند إلى بيانات التغطية المستردة هنا. بيانات التغطية متاحة أيضاً على صفحة تغطية الشبكة. يمكنك تخصيص خريطة التوجيه الخاصة بك وتحديد القواعد في إعدادات الحساب.

نوصي بالاطلاع على هذا الدليل للمساعدة في تفسير النتائج.

الطلب استجابة ناجحة استجابة خطأ مرجع الحالات

curl 'https://www.hlr-lookups.com/api/v2/hlr-coverage?countrycode=XX'

معاملات الطلب

المفتاح	النوع	الوصف	افتراضي	إلزامي
`countrycode`	string(2)	رمز دولة ISO مكون من حرفين إلزامي يستخدم لتصفية النتائج، بحيث يعرض فقط السجلات المرتبطة بالدولة المحددة.	null	إلزامي
`sample_size`	string	معامل اختياري يحدد حجم العينة. القيم الممكنة هي `LARGE` و `MEDIUM` و `SMALL`. العينات الأكبر تغطي إطاراً زمنياً أطول، والعينات الأصغر تغطي إطاراً زمنياً حديثاً جداً.	LARGE	اختياري

{
   "name":"Germany",
   "countrycode":"DE",
   "prefix":"+49",
   "mccs":[
      "262"
   ],
   "carriers":[
      {
         "mno":"Telekom",
         "mccmnc":"26201",
         "mcc":"262",
         "mnc":"01 ",
         "routes":[
            {
               "route":"V11",
               "selected":true,
               "selection_confidence":"HIGH",
               "n":361579,
               "CONNECTED":275273,
               "CONNECTED_PCT":76.13,
               "ABSENT":21529,
               "ABSENT_PCT":5.95,
               "INVALID_MSISDN":62582,
               "INVALID_MSISDN_PCT":17.3,
               "UNDETERMINED":2195,
               "UNDETERMINED_PCT":0.6
            },
            {
               "route":"E10",
               "selected":false,
               "selection_confidence":null,
               "n":122600,
               "CONNECTED":13721,
               "CONNECTED_PCT":11.19,
               "ABSENT":133,
               "ABSENT_PCT":0.1,
               "INVALID_MSISDN":55,
               "INVALID_MSISDN_PCT":0.04,
               "UNDETERMINED":108691,
               "UNDETERMINED_PCT":88.65
            }
         ]
      }
   ]
}

خصائص الاستجابة الناجحة

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`name`	string	اسم الدولة المحددة بالنص الإنجليزي.	false
`countrycode`	string(2)	رمز الدولة ISO المكون من حرفين للدولة المحددة.	false
`prefix`	string	رمز الاتصال الدولي للدولة المحددة.	false
`mccs`	string[]	قائمة برموز MCC (رموز الدولة للهاتف المحمول) المرتبطة بالدولة المحددة.	false
`carriers`	object[]	قائمة بكائنات شركات الاتصالات مع مقاييس الاتصال الخاصة بالمسار.	false
`mno`	string	اسم مشغل شبكة الهاتف المحمول بالنص الإنجليزي.	false
`mccmnc`	string	رمز MCCMNC الخاص بمشغل شبكة الهاتف المحمول.	false
`mcc`	string	رمز MCC (رمز الدولة للهاتف المحمول) الخاص بمشغل شبكة الهاتف المحمول.	false
`mnc`	string	رمز MNC (رمز شبكة الهاتف المحمول) الخاص بمشغل شبكة الهاتف المحمول.	false
`routes`	object[]	قائمة بنتائج الاتصال الخاصة بالمسار.	false
`route`	string	المسار الذي تنطبق عليه معلومات الاتصال.	false
`selected`	bool	يشير إلى ما إذا كان هذا هو المسار المحدد للتوجيه التلقائي.	false
`selection_confidence`	string	مستوى الثقة الذي تم به اختيار هذا المسار، أي `LOW` أو `NORMAL` أو `HIGH` أو `MNP_FALLBACK`. يحتوي على null إذا لم يكن هذا هو المسار المحدد.	true
`n`	int	العدد الإجمالي لعمليات البحث في هذه العينة.	false
`CONNECTED`	int	عدد عمليات بحث HLR التي أرجعت حالة CONNECTED.	false
`CONNECTED_PCT`	float	نسبة عمليات بحث HLR التي أرجعت حالة CONNECTED.	false
`ABSENT`	int	عدد عمليات بحث HLR التي أرجعت حالة ABSENT.	false
`ABSENT_PCT`	float	نسبة عمليات بحث HLR التي أرجعت حالة ABSENT.	false
`INVALID_MSISDN`	int	عدد عمليات بحث HLR التي أرجعت حالة INVALID_MSISDN.	false
`INVALID_MSISDN_PCT`	float	نسبة عمليات بحث HLR التي أرجعت حالة INVALID_MSISDN.	false
`UNDETERMINED`	int	عدد عمليات بحث HLR التي أرجعت حالة UNDETERMINED.	false
`UNDETERMINED_PCT`	float	نسبة عمليات بحث HLR التي أرجعت حالة UNDETERMINED.	false

{
    "errors":[
        "Service unavailable."
    ]
}

معاملات استجابة الخطأ

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`errors[]`	string[]	قائمة من النصوص توضح الخطأ.	false

الحالة	الوصف
CONNECTED	الرقم صالح، والجهاز المستهدف متصل حالياً بشبكة الهاتف المحمول. يجب أن تصل المكالمات والرسائل النصية والخدمات الأخرى إلى المستلم بنجاح.
ABSENT	الرقم صالح، لكن الجهاز المستهدف إما مغلق أو خارج نطاق تغطية الشبكة مؤقتاً. قد لا يتم تسليم الرسائل أو المكالمات حتى يعاود الجهاز الاتصال بالشبكة.
INVALID_MSISDN	الرقم غير صالح أو غير مخصص حالياً لأي مشترك على شبكة الهاتف المحمول. ستفشل المكالمات والرسائل إلى هذا الرقم.
UNDETERMINED	تعذر تحديد حالة الاتصال للرقم. قد يكون ذلك بسبب رقم غير صالح، أو استجابة خطأ SS7، أو عدم وجود اتصال مع مشغل الشبكة المستهدف. راجع رمز الخطأ وحقل الوصف الخاص به للحصول على تشخيصات إضافية.

التمرير لأعلى

GET/mnp-coverageمحمي

تُرجع نقطة النهاية هذه قائمة بمشغلي شبكات الهاتف المحمول، مع معرفات MCCMNC المقابلة لهم، والمدعومة حاليًا لعمليات الاستعلام عن إمكانية نقل أرقام الهاتف المحمول.

الطلب استجابة ناجحة استجابة خطأ

curl 'https://www.hlr-lookups.com/api/v2/mnp-coverage?countrycode=XX'

معاملات الطلب

المفتاح	النوع	الوصف	افتراضي	إلزامي
`countrycode`	string(2)	رمز الدولة الاختياري المكون من حرفين وفقًا لمعيار ISO، يُستخدم لتصفية نتائج MCCMNC وإرجاع البيانات المتعلقة بالدولة المحددة فقط.	null	اختياري

{
   "items":[
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26201",
         "mcc":"262",
         "mnc":"01 ",
         "brand":"Telekom",
         "operator":"Telekom Deutschland GmbH"
      },
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26202",
         "mcc":"262",
         "mnc":"02 ",
         "brand":"Vodafone",
         "operator":"Vodafone D2 GmbH"
      }
}

خصائص الاستجابة الناجحة

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`items[]`	array	قائمة بمشغلي شبكات الهاتف المحمول.	false
`country_name`	string	اسم الدولة باللغة الإنجليزية.	false
`country_code`	string(2)	رمز الدولة المكون من حرفين وفقًا لمعيار ISO.	false
`mccmnc`	string(5\|6)	رمز MCCMNC المكون من خمسة أو ستة أحرف (مزيج من رمز الدولة المحمول ورمز شبكة الهاتف المحمول) الذي يحدد مشغل شبكة الهاتف المحمول.	false
`mcc`	string(3)	رمز MCC المكون من ثلاثة أحرف (رمز الدولة المحمول) الذي يمثل دولة الشبكة.	false
`mnc`	string(2\|3)	رمز MNC المكون من حرفين أو ثلاثة أحرف (رمز شبكة الهاتف المحمول) الذي يمثل مشغل شبكة الهاتف المحمول المحدد.	false
`brand`	string	العلامة التجارية الموجهة للمستهلك التي تعمل الشبكة تحتها.	true
`operator`	string	الاسم القانوني لمشغل شبكة الهاتف المحمول.	true

{
    "errors":[
        "Service unavailable."
    ]
}

معاملات استجابة الخطأ

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`errors[]`	string[]	قائمة من النصوص توضح الخطأ.	false

التمرير لأعلى

GET/price-listمحمي

تُرجع نقطة النهاية هذه قائمة بالدول التي تدعم استعلامات MNP فقط، ولا تتوفر استعلامات HLR لهذه الوجهات.

الطلب استجابة ناجحة استجابة خطأ

curl 'https://www.hlr-lookups.com/api/v2/mnp-countries'

{
   "countries":[
      "AG",
      "AI",
      "AR",
      "AS",
      "AW",
      "BB",
      "BM",
      ...
      "US",
      "UY",
      "VC",
      "VE",
      "VG",
      "VN"
   ]
}

خصائص الاستجابة الناجحة

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`countries`	string[]	قائمة برموز الدول المكونة من حرفين وفقاً لمعيار ISO.	false

{
    "errors":[
        "Service unavailable."
    ]
}

معاملات استجابة الخطأ

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`errors[]`	string[]	قائمة من النصوص توضح الخطأ.	false

التمرير لأعلى

GET/mccmncsمحمي

تُرجع نقطة النهاية هذه قائمة شاملة بمشغلي شبكات الهاتف المحمول مع معرفات MCCMNC المقابلة لها ومعلومات سياقية إضافية.

الطلب استجابة ناجحة استجابة خطأ

curl 'https://www.hlr-lookups.com/api/v2/mccmncs?countrycode=XX'

معاملات الطلب

المفتاح	النوع	الوصف	افتراضي	إلزامي
`countrycode`	string(2)	رمز دولة ISO اختياري مكون من حرفين يُستخدم لتصفية نتائج MCCMNC، بحيث يُرجع السجلات المرتبطة بالدولة المحددة فقط.	null	اختياري

{
   "items":[
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26201",
         "mcc":"262",
         "mnc":"01 ",
         "brand":"Telekom",
         "operator":"Telekom Deutschland GmbH"
      },
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26202",
         "mcc":"262",
         "mnc":"02 ",
         "brand":"Vodafone",
         "operator":"Vodafone D2 GmbH"
      }
}

خصائص الاستجابة الناجحة

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`items`	object[]	قائمة بمشغلي شبكات الهاتف المحمول.	false
`country_name`	string	الاسم الكامل للدولة باللغة الإنجليزية.	false
`country_code`	string(2)	رمز دولة ISO مكون من حرفين يمثل دولة مشغل الهاتف المحمول.	false
`mccmnc`	string(5\|6)	سلسلة نصية مكونة من خمسة أو ستة أحرف تمثل MCCMNC، والتي تحدد مشغل شبكة الهاتف المحمول بشكل فريد.	false
`mcc`	string(3)	رمز الدولة للهاتف المحمول (MCC) المكون من ثلاثة أحرف والذي يحدد الدولة التي تعمل فيها شبكة الهاتف المحمول.	false
`mnc`	string(2\|3)	رمز الشبكة المحمولة (MNC) المكون من حرفين أو ثلاثة أحرف والذي يحدد شبكة الهاتف المحمول ضمن رمز MCC المعطى.	false
`brand`	string	الاسم التجاري الذي تعمل الشبكة تحته ويُعرف به من قبل المستهلكين.	true
`operator`	string	الاسم الرسمي لمشغل شبكة الهاتف المحمول، وهو عادةً الكيان القانوني الذي يدير الشبكة.	true
`parent_mccmnc`	string(5\|6)	سلسلة نصية مكونة من خمسة أو ستة أحرف تمثل MCCMNC لمشغل شبكة الهاتف المحمول الأصلي، إن وجد.	true

{
    "errors":[
        "Service unavailable."
    ]
}

معاملات استجابة الخطأ

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`errors[]`	string[]	قائمة من النصوص توضح الخطأ.	false

التمرير لأعلى

GET/priceمحمي

تُرجع هذه النقطة النهائية سعر استعلام HLR أو MNP أو NT.

الطلب استجابة ناجحة استجابة خطأ

curl 'https://www.hlr-lookups.com/api/v2/price?msisdn=+491788735000&route_type=HLR'

معاملات الطلب

المفتاح	النوع	الوصف	افتراضي	إلزامي
`msisdn`	string	رقم الهاتف المراد الحصول على سعره. بالتنسيق الدولي.	null	إلزامي
`route_type`	string	نوع المسار، أي `HLR` أو `MNP` أو `NT`.	null	إلزامي
`route`	string(3)	المسار الذي يجب حساب السعر له. يتم تعيينه افتراضياً إلى المسار المحدد بواسطة التوجيه التلقائي.	null	اختياري

{
   "price":{
      "amount":"0.01000",
      "msisdn":"+491788735000",
      "route_type":"HLR",
      "route":"DV8"
   }
}

خصائص الاستجابة الناجحة

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`price`	object	كائن يحتوي على تفاصيل التسعير.	false
`amount`	string	المبلغ باليورو.	false
`msisdn`	string	رقم MSISDN الذي ينطبق عليه هذا السعر.	false
`route_type`	string(2\|3)	نوع المسار الذي ينطبق عليه هذا السعر.	false
`route`	string(3)	المسار الذي ينطبق عليه هذا السعر.	false

{
    "errors":[
        "Service unavailable."
    ]
}

معاملات استجابة الخطأ

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`errors[]`	string[]	قائمة من النصوص توضح الخطأ.	false

التمرير لأعلى

GET/price-listمحمي

تُرجع نقطة النهاية هذه الأسعار المطبقة في حسابك.

الطلب استجابة ناجحة استجابة خطأ

curl 'https://www.hlr-lookups.com/api/v2/price-list'

{
   "pricing":[
      {
         "route":"V11",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"HLR",
         "price":"0.0090"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "countryname":"Germany",
         "mccmnc":"26201",
         "cns":null,
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "countryname":"Germany",
         "mccmnc":"26203",
         "cns":"4917821",
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "countryname":"Germany",
         "mccmnc":null,
         "cns":null,
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"PTX",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"MNP",
         "price":"0.00500"
      },
      ...
      {
         "route":"IP1",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"MIX",
         "price":"0.01000"
      },
      {
         "route":"LC1",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"NT",
         "price":"0.00500"
      }
   ]
}

خصائص الاستجابة الناجحة

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`pricing`	object[]	قائمة بالكائنات التي تحتوي على معلومات الأسعار.	false
`route`	string	المسار الذي ينطبق عليه هذا السعر.	false
`countrycode`	string	رمز الدولة المكون من حرفين وفقاً لمعيار ISO الذي ينطبق عليه هذا السعر للمسار المقابل، إن وُجد.	true
`countryname`	string	اسم الدولة باللغة الإنجليزية المطابق لرمز الدولة، إن وُجد.	true
`mccmnc`	string	رمز MCCMNC الذي ينطبق عليه هذا السعر للمسار المقابل، إن وُجد. يُلغي الأسعار على مستوى الدولة.	true
`cns`	string	بادئة الاتصال التي ينطبق عليها هذا السعر للمسار المقابل، إن وُجدت. تُلغي الأسعار على مستوى الدولة والأسعار على مستوى MCCMNC.	true
`route_type`	string	نوع المسار المقابل، أي `HLR` أو `MNP` أو `NT`.	false
`route_type`	string	السعر المقابل باليورو.	false

{
    "errors":[
        "Service unavailable."
    ]
}

معاملات استجابة الخطأ

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`errors[]`	string[]	قائمة من النصوص توضح الخطأ.	false

التمرير لأعلى

GET/balanceمحمي

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

الطلب استجابة ناجحة استجابة خطأ

curl 'https://www.hlr-lookups.com/api/v2/balance'

{
    "balance":"1002.90"
}

خصائص الاستجابة الناجحة

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`balance`	string	رصيد حسابك الحالي باليورو. قيمة عشرية من نوع نصي.	false

{
    "errors":[
        "Service unavailable."
    ]
}

معاملات استجابة الخطأ

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`errors[]`	string[]	قائمة من النصوص توضح الخطأ.	false

التمرير لأعلى

GET/pingعام

ترسل هذه النقطة طلب اختبار اتصال إلى الواجهة البرمجية، مما يوفر طريقة بسيطة لاختبار اتصالك بواجهة HLR Lookups البرمجية.

الطلب استجابة ناجحة استجابة خطأ

curl 'https://www.hlr-lookups.com/api/v2/ping'

{
    "success":true
}

خصائص الاستجابة الناجحة

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`success`	boolean	يشير إلى أن الطلب تمت معالجته بنجاح.	false

{
    "errors":[
        "Service unavailable."
    ]
}

معاملات استجابة الخطأ

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`errors[]`	string[]	قائمة من النصوص توضح الخطأ.	false

التمرير لأعلى

GET/timeعام

تُرجع نقطة النهاية هذه طابعًا زمنيًا من نوع Unix يمثل الوقت الحالي على خادم HLR Lookups. استخدمها لمزامنة ساعة الخادم الخاص بك عند إنشاء توقيع Digest-Auth للمصادقة، مما يضمن تصحيح أي اختلافات بين وقت الخادم الخاص بك ووقت خادم HLR Lookups.

الطلب استجابة ناجحة استجابة خطأ

curl 'https://www.hlr-lookups.com/api/v2/time'

{
    "time":1525898643
}

خصائص الاستجابة الناجحة

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`time`	integer	طابع زمني من نوع Unix يمثل الوقت الحالي لخادم HLR Lookups.	false

{
    "errors":[
        "Service unavailable."
    ]
}

معاملات استجابة الخطأ

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`errors[]`	string[]	قائمة من النصوص توضح الخطأ.	false

التمرير لأعلى

GET/auth-testمحمي

تُستخدم هذه النقطة كاختبار أولي لتطبيق Basic-Auth أو، ويُفضل، Digest-Auth.

طلب المصادقة الأساسية طلب مصادقة Digest استجابة ناجحة استجابة خطأ

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Basic: YOUR_API_KEY"

رؤوس الطلب

المفتاح	النوع	الوصف
`X-Basic`	string	تجزئة SHA256 لـ `YOUR_API_KEY:YOUR_API_SECRET`. قم بتضمين رمز النقطتين (:) في التجزئة.

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Digest-Key: YOUR_API_KEY" \
  -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
  -H "X-Digest-Timestamp: UNIX_TIMESTAMP"

رؤوس الطلب

المفتاح	النوع	الوصف
`X-Digest-Key`	string	مفتاح API الخاص بخدمة HLR Lookups
`X-Digest-Signature`	string	توقيع Digest-Auth الفريد (راجع المصادقة)
`X-Digest-Timestamp`	integer	الطابع الزمني Unix الحالي (راجع أيضاً `GET /time`)

{
    "success":true
}

خصائص الاستجابة الناجحة

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`success`	boolean	يشير إلى أن الطلب تمت معالجته بنجاح.	false

{
    "errors":[
        "Service unavailable."
    ]
}

معاملات استجابة الخطأ

الاسم	النوع	الوصف	قابل للقيمة الفارغة
`errors[]`	string[]	قائمة من النصوص توضح الخطأ.	false

التمرير لأعلى

وثائق واجهة برمجة التطبيقات القديمة

يرجى ملاحظة أن واجهة برمجة التطبيقات القديمة لم تعد مدعومة ومن المقرر إيقافها في المستقبل. نوصي بشدة بالترقية إلى الإصدار الأحدث في أقرب وقت ممكن.

إذا قمت بتطبيق واجهة برمجة تطبيقات HLR Lookups بين عامي 2013 وأوائل 2020، فأنت تستخدم واجهة برمجة التطبيقات القديمة. يرجى الرجوع إلى وثائق واجهة برمجة التطبيقات القديمة في هذه الحالة.

وثائق واجهة برمجة التطبيقات القديمة

وثائق API

البدء

استعلامات HLR

استعلامات MNP

استعلامات NT

التوجيه

الأسعار

الأدوات

البدء

استخدام واجهة برمجة تطبيقات HLR Lookups

مثال على الطلب

مثال على البيانات المرسلة

استجابة ناجحة application/json

خدمات الاستعلام الإضافية

استعلامات قابلية نقل الأرقام المحمولة (MNP)

استعلامات الكشف عن نوع الرقم (NT)

مجموعات تطوير البرمجيات (SDKs)

الأدوات

لست مطوراً؟

المصادقة

مفتاح API والسر

مصادقة HTTP الأساسية

موصى به: رأس X-Basic مع SHA256

طلب المصادقة الأساسية

رؤوس المصادقة الأساسية

مثال على الكود

مثال على الطلب

رؤوس الطلب

إنشاء التوقيع

مكونات توقيع Digest

أمثلة على الأكواد

المفاهيم

واجهة برمجة تطبيقات استعلام HLR المتزامنة

واجهة برمجة تطبيقات HLR غير المتزامنة

مجموعات تطوير البرمجيات (SDKs)

حزمة تطوير PHP

حزمة تطوير NodeJS

حزمة تطوير Ruby

POST/hlr-lookupمحمي

البيانات المرسلة

معاملات الطلب

خصائص الاستجابة الناجحة

معاملات استجابة الخطأ

POST/hlr-lookupsمحمي

البيانات المرسلة

معاملات الطلب

خصائص الاستجابة الناجحة

معاملات استجابة الخطأ

معالجة الويب هوك

المصادقة

مثال على الكود

تأكيد الاستلام

حمولة الويب هوك

سمات حمولة Webhook

POST/mnp-lookupمحمي

البيانات المرسلة

معاملات الطلب

خصائص الاستجابة الناجحة

معاملات استجابة الخطأ

POST/mnp-lookupsمحمي

البيانات المرسلة

معاملات الطلب

خصائص الاستجابة الناجحة

معاملات استجابة الخطأ

معالجة الويب هوك

المصادقة

مثال على الكود

تأكيد الاستلام

حمولة الويب هوك

سمات حمولة Webhook

POST/nt-lookupمحمي

البيانات المرسلة

معاملات الطلب

خصائص الاستجابة الناجحة

معاملات استجابة الخطأ

POST/nt-lookups محمي

البيانات المرسلة

معاملات الطلب

خصائص الاستجابة الناجحة

معاملات استجابة الخطأ