תחילת העבודה

תשתית הרשת הסלולרית העולמית פועלת על בסיס מערכת המכונה רשת איתות SS7. רשת זו מאפשרת החלפת נתוני מנויים, ניתוב שיחות, העברת SMS ועדכוני סטטוס קישוריות סלולרית בזמן אמת בין ספקים. כל רשת סלולרית מתחזקת רישום מיקום בית (HLR) - מסד נתונים מרכזי המאחסן פרטים חיוניים על מנוייה.

טכנולוגיית HLR Lookup מאפשרת לעסקים לבצע שאילתות במאגרים אלה ולקבל פרטי קישוריות ורשת חיים עבור כל מספר טלפון סלולרי. זה כולל האם הטלפון מופעל, לאיזו רשת הוא משויך כעת, האם הוא הועבר, האם המספר תקף או מושבת, והאם הוא בנדידה.

ממשק ה-API של HLR Lookups מספק גישה חלקה בזמן אמת לנתונים אלה, ומאפשר לעסקים לאמת מספרי טלפון סלולריים, לייעל ניתוב ולשפר תקשורת עם לקוחות. תיעוד זה ידריך אותך בשילוב HLR Lookups בתוכנה שלך, ויאפשר אחזור אוטומטי של מודיעין סלולרי בזמן אמת.

שימוש ב-API של 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 הבא:

דוגמת Payload

{
   "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)

ממשק ה-API של HLR Lookups עובד עם כל לקוח REST בכל שפת תכנות ופרסמנו SDKs עבור PHP, Ruby ו-NodeJS ב-GitHub שלנו כדי לעזור לך להתחיל במהירות.

כלים

כדי להבטיח חוויית פיתוח חלקה, אנו מציעים חבילת כלים מקיפה, כולל ניטור בקשות API ו-webhook בדפדפן, רישום כתובות IP ברשימה לבנה, אפשרויות אימות חזקות ו-נקודת קצה לבדיקת אימות.

לא מפתח?

ניתן לבצע חיפושי HLR ושאילתות ניידות מספרים ללא כל קידוד. למד עוד על לקוח האינטרנט הארגוני שלנו ותכונות הדיווח המבוססות על דפדפן.

אימות

כדי להבטיח אבטחה ובקרת גישה נאותה, רוב הבקשות ל-API של HLR Lookups דורשות אימות. נקודות קצה מסווגות כציבוריות או מוגנות. בעת גישה לנקודת קצה מוגנת, הבקשה שלך חייבת להיות מאומתת באמצעות מפתח ה-API והסוד שלך דרך שיטת Digest-Auth או Basic-Auth. Digest-Auth היא האפשרות המאובטחת יותר ומומלצת בחום. השתמש בנקודת הקצה GET /auth-test כדי לאמת את הגדרות האימות שלך.

מפתח API וסוד API

קבל את מפתח ה-API והסוד שלך מעמוד הגדרות API. ניתן גם להגדיר את שיטת האימות המועדפת עליך ולהפעיל רשימת כתובות IP מאושרות לאבטחה משופרת. אם אתה חושד שסוד ה-API שלך נפגע, תוכל ליצור חדש בכל עת.

Basic Auth Digest Auth רשימת IP מאושרת

אימות Basic סטנדרטי קל ליישום ונתמך באופן נרחב. ניתן לבצע אימות על ידי העברת מפתח ה-API והסוד שלך כזוג user:pass בבקשת HTTP.

HTTP Basic Auth

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:

בקשת Basic Auth

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

כותרות Basic Authentication

מפתח	סוג	תיאור
`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 API. כל בקשה חייבת לכלול את הכותרות הבאות: 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	מפתח ה-API הייחודי שלך ב-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 Signature

רכיב	סוג	תיאור
`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 API שלנו הוא פשוט ויעיל. עם תהליך אינטגרציה פשוט, תוכלו להתחיל לשאול רשתות סלולריות בזמן אמת לקבלת תובנות מיידיות על תקינות מספרי טלפון, סטטוס קישוריות ופרטי ניתוב.

בחירת ממשק ה-API המתאים תלויה בתרחיש השימוש הספציפי שלכם. אם אתם זקוקים לתוצאות בדיקה בזמן אמת עבור יישומים כמו טלפוניית VoIP, זיהוי הונאות או ניתוב SMS, ה-API הסינכרוני הוא הבחירה הטובה ביותר. עם זאת, אם תרחיש השימוש שלכם כולל עיבוד בנפחים גבוהים, בדיקות מרובות או אימות נתונים בקנה מידה גדול, ה-API האסינכרוני מציע ביצועים מיטביים עם יעילות רוחב פס ויכולות בדיקה אצווית.

הגדירו את ממשק ה-API לשימוש באחת מ-אפשרויות הניתוב המותאמות שלנו כדי לייעל מהירות, דיוק ועלות-תועלת. תוכלו גם לאחסן תוצאות בדיקה ב-אחסונים להורדת דוחות CSV ו-JSON בקלות, כמו גם לניתוח מתקדם דרך ממשק האינטרנט.

API לבדיקת HLR סינכרונית

נקודת הקצה POST /hlr-lookup מעבדת מספר טלפון סלולרי אחד (MSISDN) לכל בקשה ומחזירה תוצאות באופן מיידי בגוף תגובת ה-HTTP. התוצאות מעוצבות כ-JSON ומתאימות באופן אידיאלי ליישומי זמן אמת, כולל אימות מספרי טלפון, ניתוב שיחות ומסירת הודעות SMS.

קריאת API סינכרונית מורכבת מבקשת HTTP ותגובה ישירה. המערכת שלכם שולחת MSISDN בודד (מספר סלולרי) לכל בקשה ומקבלת תגובה מיידית המכילה תוצאות בדיקת HLR בזמן אמת בפורמט JSON. ממשק API זה מותאם לתרחישי שימוש הדורשים אימות מיידי ובדיקות קישוריות, כגון זיהוי הונאות, ניתוב שיחות VoIP ואופטימיזציה של שערי SMS.

API לבדיקת HLR אסינכרונית

נקודת הקצה POST /hlr-lookups מיועדת לעיבוד אצווי ובנפחים גבוהים, ומאפשרת לכם לשלוח עד 1,000 מספרי MSISDN לכל בקשה. במקום להחזיר תוצאות באופן מיידי, ממשק API זה משתמש ב-webhooks אוטומטיים כדי לשלוח תוצאות בהדרגה לשרת שלכם. תוצאות הבדיקה מוחזרות כאובייקטי JSON באמצעות קריאות HTTP POST חוזרות.

ממשק ה-API האסינכרוני מותאם למהירות, יעילות ומדרגיות. הוא מבטל בעיות זמן אחזור רשת הקשורות לקריאות סינכרוניות, מה שהופך אותו לאידיאלי עבור עסקים הזקוקים לבדיקות בתפוקה גבוהה. המערכת שלכם שולחת עד 1,000 מספרי MSISDN לכל בקשה, והפלטפורמה שלנו מעבדת אותם במקביל, ומעבירה תוצאות בחזרה לשרת שלכם באמצעות HTTP webhooks באצוות של עד 1,000 תוצאות לכל קריאה חוזרת.

ערכות פיתוח תוכנה (SDKs)

ערכות הפיתוח שלנו (SDKs) עבור PHP, NodeJS ו-Ruby מייעלות את תהליך האינטגרציה, ומאפשרות לכם להתחבר ל-API של 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	המספר תקין והמכשיר הנייד מחובר כעת לרשת הסלולרית. שיחות, הודעות SMS ושירותים נוספים אמורים להגיע למקבל בהצלחה.
ABSENT	המספר תקין, אך המכשיר הנייד כבוי או מחוץ לטווח הכיסוי הרשת באופן זמני. הודעות או שיחות עשויות שלא להימסר עד שהמכשיר יתחבר מחדש לרשת.
INVALID_MSISDN	המספר אינו תקין או אינו משויך כרגע לשום מנוי ברשת הסלולרית. שיחות והודעות למספר זה ייכשלו.
UNDETERMINED	לא ניתן היה לקבוע את מצב הקישוריות של המספר. הדבר עשוי לנבוע ממספר לא תקין, תגובת שגיאה מ-SS7 או מחוסר קישוריות עם מפעיל הרשת היעד. בדקו את קוד השגיאה ואת שדה התיאור שלו לקבלת אבחון נוסף.

גלול למעלה

POST/hlr-lookupsמוגן

מאתחל אצווה של בדיקות HLR אסינכרוניות, ומאחזר נתוני קישוריות ניידות וניידות בזמן אמת מספקי רשת. התוצאות מועברות באמצעות webhooks לשרת שלך. שיטה זו מותאמת לעיבוד כמויות גדולות של מספרים שאינם דורשים תגובות מיידיות, כגון ניקוי ואימות מאגרי מידע. עבור יישומים בזמן אמת כמו ניתוב שיחות או משלוח SMS, שקול להשתמש בנקודת קצה 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	כתובות ה-webhook המוגדרות בהגדרות API שלך. התוצאות נשלחות חזרה לכאן.	false

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

פרמטרי תגובת שגיאה

שם	סוג	תיאור	ניתן לערך ריק
`errors[]`	string[]	רשימת מחרוזות המסבירות את השגיאה.	false

עיבוד Webhooks

לאחר השליחה, הפלטפורמה שלנו מתחילה לעבד את מספרי הטלפון שסופקו ושולחת את התוצאות לכתובת ה-webhook שצוינה מראש בשרת שלך. התוצאות מועברות כבקשת HTTP POST עם אובייקט JSON בגוף הבקשה.

אימות

אמת את ה-webhook על ידי בדיקת כותרת ה-HTTP X-Signatures.

כותרת ה-X-Signatures מכילה רשימה מופרדת בנקודה-פסיק של חתימות. כל חתימה ברשימה נוצרת באמצעות אחד מסודות ה-API המוגדרים בחשבון שלך. כדי לאמת את ה-webhook, צור hash 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;
    }
}

הבקשה תקפה אם אחת מהחתימות שניתנו בכותרת שווה ל-hash SHA256 המחושב על המחרוזת המשולבת של מפתח ה-API, הסוד וגוף ה-HTTP שלך.

אישור קבלה

השרת שלך צריך להגיב עם קוד סטטוס HTTP 200 OK כדי לאשר קבלה מוצלחת. אם מוחזר קוד תגובה אחר, מתרחשת פסק זמן (10 שניות), או מתעוררת בעיית מסירה אחרת, המערכת תנסה שוב את ה-webhook באופן אוטומטי לאחר דקה אחת. אם הבקשה ממשיכה להיכשל, הניסיונות החוזרים יעקבו אחר אסטרטגיית backoff אקספוננציאלית, עם ניסיונות נוספים לאחר 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 דקות.

מנגנון הניסיון החוזר הזה מבטיח אמינות מקסימלית במסירת תוצאות החיפוש לתשתית שלך. הוא ממזער את הסיכון לאובדן נתונים עקב בעיות רשת זמניות או השבתת שרת.

מטען Webhook

{
   "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 Payload

אובייקט ה-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	המספר תקין והמכשיר הנייד מחובר כעת לרשת הסלולרית. שיחות, הודעות SMS ושירותים נוספים אמורים להגיע למקבל בהצלחה.
ABSENT	המספר תקין, אך המכשיר הנייד כבוי או מחוץ לטווח הכיסוי הרשת באופן זמני. הודעות או שיחות עשויות שלא להימסר עד שהמכשיר יתחבר מחדש לרשת.
INVALID_MSISDN	המספר אינו תקין או אינו משויך כרגע לשום מנוי ברשת הסלולרית. שיחות והודעות למספר זה ייכשלו.
UNDETERMINED	לא ניתן היה לקבוע את מצב הקישוריות של המספר. הדבר עשוי לנבוע ממספר לא תקין, תגובת שגיאה מ-SS7 או מחוסר קישוריות עם מפעיל הרשת היעד. בדקו את קוד השגיאה ואת שדה התיאור שלו לקבלת אבחון נוסף.

גלול למעלה

POST/mnp-lookupמוגן

מבצע בדיקת MNP סינכרונית ומספק מידע על ניידות מספרים ורשתות סלולריות. נקודת קצה זו מתאימה אם המטרה העיקרית שלך היא לחלץ את ה-MCCMNC הנוכחי של מספר טלפון סלולרי נתון ולאתר את הרשתות המקוריות והנוכחיות בזמן אמת.

לעיבוד אצווה של מערכי נתונים גדולים שאינם דורשים תוצאות מיידיות, שקול להשתמש ב-POST /mnp-lookups האסינכרוני, המותאם לעיבוד אצווה במהירות גבוהה.

שאילתות MNP קובעות באופן אמין מידע על ניידות ורשתות אך אינן מציינות אם מכשיר הטלפון הסלולרי מחובר כעת לרשת וזמין. כדי לחלץ מידע חי על קישוריות, אנא השתמש בנקודת הקצה 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 לשרת שלך. שיטה זו מותאמת לעיבוד כמויות גדולות של מספרים שאינם דורשים תגובות מיידיות, כגון ניקוי ואימות מאגרי מידע. עבור יישומים בזמן אמת כמו ניתוב שיחות או משלוח SMS, שקול להשתמש בנקודת קצה POST /mnp-lookup במקום זאת.

שאילתות MNP קובעות באופן אמין מידע על ניידות ורשתות אך אינן מציינות אם מכשיר הטלפון הסלולרי מחובר כעת לרשת וזמין. כדי לחלץ מידע חי על קישוריות, אנא השתמש בנקודת הקצה 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	כתובות ה-webhook המוגדרות בהגדרות API שלך. התוצאות נשלחות חזרה לכאן.	false

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

פרמטרי תגובת שגיאה

שם	סוג	תיאור	ניתן לערך ריק
`errors[]`	string[]	רשימת מחרוזות המסבירות את השגיאה.	false

עיבוד Webhooks

לאחר השליחה, הפלטפורמה שלנו מתחילה לעבד את מספרי הטלפון שסופקו ושולחת את התוצאות לכתובת ה-webhook שצוינה מראש בשרת שלך. התוצאות מועברות כבקשת HTTP POST עם אובייקט JSON בגוף הבקשה.

אימות

אמת את ה-webhook על ידי בדיקת כותרת ה-HTTP X-Signatures.

כותרת ה-X-Signatures מכילה רשימה מופרדת בנקודה-פסיק של חתימות. כל חתימה ברשימה נוצרת באמצעות אחד מסודות ה-API המוגדרים בחשבון שלך. כדי לאמת את ה-webhook, צור hash 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;
    }
}

הבקשה תקפה אם אחת מהחתימות שניתנו בכותרת שווה ל-hash SHA256 המחושב על המחרוזת המשולבת של מפתח ה-API, הסוד וגוף ה-HTTP שלך.

אישור קבלה

השרת שלך צריך להגיב עם קוד סטטוס HTTP 200 OK כדי לאשר קבלה מוצלחת. אם מוחזר קוד תגובה אחר, מתרחשת פסק זמן (10 שניות), או מתעוררת בעיית מסירה אחרת, המערכת תנסה שוב את ה-webhook באופן אוטומטי לאחר דקה אחת. אם הבקשה ממשיכה להיכשל, הניסיונות החוזרים יעקבו אחר אסטרטגיית backoff אקספוננציאלית, עם ניסיונות נוספים לאחר 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 דקות.

מנגנון הניסיון החוזר הזה מבטיח אמינות מקסימלית במסירת תוצאות החיפוש לתשתית שלך. הוא ממזער את הסיכון לאובדן נתונים עקב בעיות רשת זמניות או השבתת שרת.

מטען Webhook

{
    "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 Payload

אובייקט ה-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	מספר טלפון Voice over IP. כולל מספרי TSoIP (שירות טלפוניה על גבי IP).
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	כתובות ה-webhook המוגדרות בהגדרות API שלך. התוצאות נשלחות חזרה לכאן.	false

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

פרמטרי תגובת שגיאה

שם	סוג	תיאור	ניתן לערך ריק
`errors[]`	string[]	רשימת מחרוזות המסבירות את השגיאה.	false

עיבוד Webhooks

לאחר השליחה, הפלטפורמה שלנו מתחילה לעבד את מספרי הטלפון שסופקו ושולחת את התוצאות לכתובת ה-webhook שצוינה מראש בשרת שלך. התוצאות מועברות כבקשת HTTP POST עם אובייקט JSON בגוף הבקשה.

אימות

אמת את ה-webhook על ידי בדיקת כותרת ה-HTTP X-Signatures.

כותרת ה-X-Signatures מכילה רשימה מופרדת בנקודה-פסיק של חתימות. כל חתימה ברשימה נוצרת באמצעות אחד מסודות ה-API המוגדרים בחשבון שלך. כדי לאמת את ה-webhook, צור hash 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;
    }
}

הבקשה תקפה אם אחת מהחתימות שניתנו בכותרת שווה ל-hash SHA256 המחושב על המחרוזת המשולבת של מפתח ה-API, הסוד וגוף ה-HTTP שלך.

אישור קבלה

השרת שלך צריך להגיב עם קוד סטטוס HTTP 200 OK כדי לאשר קבלה מוצלחת. אם מוחזר קוד תגובה אחר, מתרחשת פסק זמן (10 שניות), או מתעוררת בעיית מסירה אחרת, המערכת תנסה שוב את ה-webhook באופן אוטומטי לאחר דקה אחת. אם הבקשה ממשיכה להיכשל, הניסיונות החוזרים יעקבו אחר אסטרטגיית backoff אקספוננציאלית, עם ניסיונות נוספים לאחר 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 דקות.

מנגנון הניסיון החוזר הזה מבטיח אמינות מקסימלית במסירת תוצאות החיפוש לתשתית שלך. הוא ממזער את הסיכון לאובדן נתונים עקב בעיות רשת זמניות או השבתת שרת.

מטען Webhook

{
   "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 Payload

אובייקט ה-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	מספר טלפון Voice over IP. כולל מספרי TSoIP (שירות טלפוניה על גבי IP).
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	המספר תקין והמכשיר הנייד מחובר כעת לרשת הסלולרית. שיחות, הודעות SMS ושירותים נוספים אמורים להגיע למקבל בהצלחה.
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ציבורי

נקודת קצה זו שולחת בקשת ping ל-API, ומספקת שיטה פשוטה לבדיקת החיבור שלך ל-API של 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.

בקשת Basic Auth בקשת Digest Auth תגובת הצלחה תגובת שגיאה

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

גלול למעלה

תיעוד API מדור קודם

שימו לב כי ה-API מדור קודם הוצא משימוש ומתוכנן להסרה בעתיד. אנו ממליצים בחום לשדרג לגרסה העדכנית בהקדם האפשרי.

אם יישמתם את HLR Lookups API שלנו בין 2013 לתחילת 2020, אתם משתמשים ב-API מדור קודם. במקרה זה, אנא עיינו בתיעוד API מדור קודם.

תיעוד API מדור קודם

תיעוד API

תחילת העבודה

בדיקות HLR

בדיקות MNP

בדיקות NT

ניתוב

תמחור

כלים

תחילת העבודה

שימוש ב-API של HLR Lookups

דוגמת בקשה

דוגמת Payload

תגובת הצלחה application/json

שירותי חיפוש נוספים

חיפושי ניידות מספרים (MNP)

חיפושי זיהוי סוג מספר (NT)

ערכות פיתוח תוכנה (SDKs)

כלים

לא מפתח?

אימות

מפתח API וסוד API

HTTP Basic Auth

מומלץ: כותרת X-Basic עם SHA256

בקשת Basic Auth

כותרות Basic Authentication

דוגמת קוד

דוגמת בקשה

כותרות בקשה

בניית החתימה

רכיבי Digest Signature

דוגמאות קוד

מושגים

API לבדיקת HLR סינכרונית

API לבדיקת HLR אסינכרונית

ערכות פיתוח תוכנה (SDKs)

SDK ל-PHP

SDK ל-NodeJS

SDK ל-Ruby

POST/hlr-lookupמוגן

מטען

פרמטרי בקשה

מאפייני תגובת הצלחה

פרמטרי תגובת שגיאה

POST/hlr-lookupsמוגן

מטען

פרמטרי בקשה

מאפייני תגובת הצלחה

פרמטרי תגובת שגיאה

עיבוד Webhooks

אימות

דוגמת קוד

אישור קבלה

מטען Webhook

מאפייני Webhook Payload

POST/mnp-lookupמוגן

מטען

פרמטרי בקשה

מאפייני תגובת הצלחה

פרמטרי תגובת שגיאה

POST/mnp-lookupsמוגן

מטען

פרמטרי בקשה

מאפייני תגובת הצלחה

פרמטרי תגובת שגיאה

עיבוד Webhooks

אימות

דוגמת קוד

אישור קבלה

מטען Webhook

מאפייני Webhook Payload

POST/nt-lookupמוגן

מטען

פרמטרי בקשה

מאפייני תגובת הצלחה

פרמטרי תגובת שגיאה

POST/nt-lookups מוגן

מטען

פרמטרי בקשה

מאפייני תגובת הצלחה

פרמטרי תגובת שגיאה