Primii pași

Infrastructura globală a rețelelor mobile funcționează pe baza unui sistem cunoscut sub numele de rețea de semnalizare SS7. Această rețea facilitează schimbul de date despre abonați, rutarea apelurilor, transmiterea SMS-urilor și actualizările în timp real ale stării de conectivitate mobilă între operatori. Fiecare rețea mobilă menține un Home Location Register (HLR) - o bază de date centrală care stochează detalii esențiale despre abonații săi.

Tehnologia HLR Lookup permite companiilor să interogheze aceste registre și să obțină detalii live despre conectivitate și rețea pentru orice număr de telefon mobil. Aceasta include dacă telefonul este pornit, la ce rețea este alocat în prezent, dacă a fost portat, dacă numărul este valid sau dezactivat și dacă se află în roaming.

API-ul HLR Lookups oferă acces transparent, în timp real, la aceste date, permițând companiilor să verifice numerele mobile, să optimizeze rutarea și să îmbunătățească comunicarea cu clienții. Această documentație vă va ghida prin procesul de integrare a HLR Lookups în software-ul dumneavoastră, permițând obținerea automată de informații mobile în timp real.

Utilizarea API-ului HLR Lookups

Executarea interogărilor HLR Lookup este rapidă, sigură și simplă. După ce v-ați înregistrat și ați obținut cheia API, puteți să vă autentificați și să inițiați interogări instantanee cu simple cereri HTTP POST, prin POST /hlr-lookup. Alternativ, puteți procesa seturi mari de date optând pentru cereri API asincrone rapide cu rezultate trimise înapoi către serverul dumneavoastră prin webhook, conform explicațiilor din secțiunea concepte.

Exemplu de cerere

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"

Autentificarea se furnizează prin headere HTTP, iar payload.json ar trebui să conțină (cel puțin) următorul obiect JSON:

Exemplu de payload

{
   "msisdn": "+14156226819"
}

După executarea cu succes, veți primi un răspuns conținând detalii de conectivitate în timp real pentru numărul mobil specificat.

Răspuns de Succes 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"
}

Pentru o detaliere completă a atributelor de cerere și răspuns și a stărilor de conectivitate, consultați POST /hlr-lookup.

Servicii suplimentare de interogare

Interogări de portabilitate a numerelor mobile (MNP)

Utilizați interogările MNP pentru a determina deținerea rețelei și detaliile de portabilitate fără a interoga conectivitatea în timp real. Dacă aveți nevoie doar de MCCMNC-ul unui număr, consultați POST /mnp-lookup.

Interogări de detectare a tipului de număr (NT)

Determinați dacă un număr de telefon aparține unei linii fixe, mobile, cu tarif premium, VoIP, pager sau altor intervale din planul de numerotare cu POST /nt-lookup.

Kituri de dezvoltare software (SDK-uri)

API-ul HLR Lookups funcționează cu orice client REST în orice limbaj de programare și am publicat SDK-uri pentru PHP, Ruby și NodeJS pe GitHub pentru a vă ajuta să începeți rapid.

Instrumente

Pentru a asigura o experiență de dezvoltare fără probleme, oferim o suită completă de instrumente, inclusiv monitorizare în browser a cererilor API și webhook-urilor, listare albă de adrese IP, opțiuni robuste de autentificare și un endpoint de testare a autentificării.

Nu sunteți dezvoltator?

Interogările HLR Lookups și de portabilitate a numerelor pot fi efectuate fără nicio programare. Aflați mai multe despre clientul web enterprise și funcțiile de raportare bazate pe browser.

Autentificare

Pentru a asigura securitatea și controlul adecvat al accesului, majoritatea cererilor către API-ul HLR Lookups necesită autentificare. Endpoint-urile sunt clasificate ca fiind publice sau protejate. Când accesați un endpoint protejat, cererea dvs. trebuie autentificată folosind cheia API și secretul dvs. prin metoda Digest-Auth sau Basic-Auth. Digest-Auth este opțiunea mai sigură și este puternic recomandată. Utilizați endpoint-ul GET /auth-test pentru a verifica configurația de autentificare.

Cheie API și Secret API

Obțineți cheia API și secretul dvs. din pagina Setări API. Puteți configura, de asemenea, metoda de autentificare preferată și puteți activa lista albă de adrese IP pentru securitate sporită. Dacă suspectați că secretul API a fost compromis, puteți genera unul nou oricând.

Basic Auth Digest Auth Lista IP Permise

Autentificarea Basic standard este ușor de implementat și larg acceptată. Vă puteți autentifica transmițând cheia API și secretul ca pereche user:pass în cererea HTTP.

HTTP Basic Auth

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

Aceasta trimite un header Authorization:

Authorization: Basic BASE64(YOUR_API_KEY:YOUR_API_SECRET)

Recomandat: Header X-Basic cu SHA256

Pentru securitate îmbunătățită, puteți trimite un hash SHA256 al credențialelor dvs. în loc să le transmiteți direct ca base64. Pentru a utiliza această metodă, calculați hash-ul perechii YOUR_API_KEY:YOUR_API_SECRET și trimiteți-l prin header-ul X-Basic:

Cerere Basic Auth

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

Header-e de autentificare Basic

Cheie	Tip	Descriere
`X-Basic`	string	Hash SHA256 al `YOUR_API_KEY:YOUR_API_SECRET`. Includeți simbolul două puncte (:) în hash.	obligatoriu

Exemplu de cod

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

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

Digest-Auth este metoda recomandată pentru securizarea accesului la endpoint-urile protejate ale API-ului HLR Lookup. Fiecare cerere trebuie să includă următoarele header-e: X-Digest-Key, X-Digest-Signature și X-Digest-Timestamp, care sunt explicate mai jos.

Exemplu de cerere

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"

Header-e de cerere

Cheie	Tip	Descriere
`X-Digest-Key`	string	Cheia API unică HLR Lookups.	obligatoriu
`X-Digest-Signature`	string	O semnătură de autentificare unică (vezi mai jos).	obligatoriu
`X-Digest-Timestamp`	integer	Timestamp Unix curent (vezi și `GET /time`).	obligatoriu

Construirea semnăturii

X-Digest-Signature este creat folosind un hash HMAC SHA256, cu secretul API ca cheie partajată.

Șirul de caractere care urmează a fi hash-uit este structurat după cum urmează:

ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY

Simbolul . reprezintă concatenarea șirurilor de caractere.

Componente semnătură Digest

Componentă	Tip	Descriere
`ENDPOINT_PATH`	string	Endpoint-ul API solicitat, de ex., `/auth-test` cu litere mici.
`UNIX_TIMESTAMP`	integer	Timestamp Unix curent (trebuie să fie în intervalul de 30 de secunde). Vezi `GET /time`.
`REQUEST_METHOD`	string	Metoda HTTP utilizată, de ex., `POST` sau `GET`.
`REQUEST_BODY`	string	Datele din corpul cererii. Setați la `null` pentru cererile `GET`.

Exemple de cod

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)

Derulați în sus

Concepte

Implementarea interogărilor HLR în orice limbaj de programare sau sistem prin intermediul API-ului nostru HTTP REST este simplă și eficientă. Cu un proces de integrare simplu, puteți începe să interogați rețelele mobile în timp real pentru informații instantanee despre validitatea numerelor de telefon, starea conectivității și detaliile de rutare.

Selectarea API-ului potrivit depinde de cazul dumneavoastră specific de utilizare. Dacă aveți nevoie de rezultate de interogare în timp real pentru aplicații precum telefonia VoIP, detectarea fraudelor sau rutarea SMS, API-ul sincron este cea mai bună alegere. Cu toate acestea, dacă cazul dumneavoastră de utilizare implică procesare de mare volum, interogări în masă sau verificare de date la scară largă, API-ul asincron oferă performanță optimizată cu eficiență a lățimii de bandă și capabilități de interogare în loturi.

Configurați API-ul pentru a utiliza una dintre opțiunile noastre personalizate de rutare pentru a optimiza viteza, acuratețea și raportul cost-eficiență. De asemenea, puteți stoca rezultatele interogărilor în spații de stocare pentru descărcări ușoare de rapoarte CSV și JSON, precum și analize avansate prin intermediul interfeței web.

API de Interogare HLR Sincron

Endpoint-ul POST /hlr-lookup procesează un singur număr de telefon mobil (MSISDN) per cerere și returnează rezultatele instantaneu în corpul răspunsului HTTP. Rezultatele sunt formatate ca JSON și sunt ideale pentru aplicații în timp real, inclusiv validarea numerelor mobile, rutarea apelurilor și livrarea mesajelor SMS.

Un apel API sincron constă dintr-o cerere și un răspuns HTTP directe. Sistemul dumneavoastră trimite un singur MSISDN (număr mobil) per cerere și primește un răspuns imediat care conține rezultate de interogare HLR în timp real în format JSON. Acest API este optimizat pentru cazuri de utilizare care necesită verificare instantanee și verificări de conectivitate, cum ar fi detectarea fraudelor, rutarea apelurilor VoIP și optimizarea gateway-urilor SMS.

API HLR Lookup asincron

Endpoint-ul POST /hlr-lookups este conceput pentru procesare în masă și de mare volum, permițându-vă să trimiteți până la 1,000 MSISDN-uri per cerere. În loc să returneze rezultatele instantaneu, acest API utilizează webhook-uri automate pentru a trimite rezultatele progresiv către serverul dumneavoastră. Rezultatele interogărilor sunt returnate ca obiecte JSON prin intermediul callback-urilor HTTP POST.

API-ul asincron este optimizat pentru viteză, eficiență și scalabilitate. Elimină problemele de latență a rețelei asociate cu apelurile sincrone, făcându-l ideal pentru afacerile care necesită interogări cu debit ridicat. Sistemul dumneavoastră trimite până la 1,000 MSISDN-uri per cerere, iar platforma noastră le procesează în paralel, livrând rezultatele înapoi către serverul dumneavoastră prin intermediul webhook-urilor HTTP în loturi de până la 1,000 rezultate per callback.

SDK-uri (Kituri de Dezvoltare Software)

Kiturile noastre de dezvoltare software (SDK-uri) pentru PHP, NodeJS și Ruby simplifică procesul de integrare, permițându-vă să vă conectați la API-ul HLR Lookups eficient și cu efort minim.

Aceste SDK-uri oferă funcții pre-construite, gestionarea autentificării și șabloane structurate de cereri API, reducând timpul de dezvoltare și asigurând respectarea celor mai bune practici.

Explorați lista completă a SDK-urilor disponibile pe GitHub și începeți integrarea astăzi.

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);

Vizualizare pe 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   }

Vizualizare pe 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)

Vizualizare pe GitHub README.md

Derulați în sus

POST/hlr-lookupprotejat

Efectuează o interogare HLR sincronă, furnizând date în timp real despre conectivitatea și portabilitatea numerelor de telefon mobile direct de la operatorii de rețea. Acest endpoint este ideal pentru scenarii de trafic live în care aplicațiile sensibile la timp necesită verificarea imediată dacă un număr de telefon este în prezent accesibil (conectat) sau indisponibil (oprit). În plus, ajută la distingerea numerelor active de cele invalide, necunoscute sau false.

Pentru procesarea în bloc a seturilor mari de date care nu necesită rezultate instantanee, luați în considerare utilizarea POST /hlr-lookups asincron, care este optimizat pentru procesarea rapidă în loturi.

Dacă scopul dvs. principal este obținerea datelor de portabilitate a numerelor mobile (MCCMNC) și nu aveți nevoie de starea de conectivitate live, POST /mnp-lookup oferă o alternativă rentabilă pentru interogările de portabilitate a numerelor mobile.

Cerere Răspuns de Succes Răspuns de Eroare Referință Statusuri

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

Payload

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

Parametri Cerere

Cheie	Tip	Descriere	Implicit	Obligatoriu
`msisdn`	string	Numărul de telefon mobil (MSISDN) care urmează să fie interogat, furnizat în format internațional (de ex., +14156226819 sau 0014156226819). Prefixele țării trebuie incluse.	null	obligatoriu
`route`	string(3)	Un identificator opțional de trei caractere care specifică ruta pentru această interogare. Setați la `null` sau omiteți acest parametru pentru a aplica harta de rutare personalizată sau pentru a permite sistemului nostru să determine automat cea mai bună rută pentru această interogare.	null	opțional
`storage`	string	Un identificator opțional de stocare care specifică raportul în care vor fi stocate rezultatele pentru revizuire manuală, analiză și raportare. Sistemul adaugă automat un marcaj temporal cu luna curentă. Dacă este omis sau setat la `null`, sistemul va grupa automat rezultatele pe lună în scopuri de raportare.	null	opțional

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

Atribute Răspuns de Succes

Nume	Tip	Descriere	Anulabil
`id`	string(12)	Un identificator unic atribuit acestei solicitări de interogare.	false
`msisdn`	string	Numărul de telefon mobil interogat, formatat în format internațional (de exemplu, +14156226819 sau 0014156226819).	false
`connectivity_status`	string	Indică dacă starea de conectivitate a numărului a fost obținută cu succes. Valori posibile: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` sau `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Un cod de țară mobilă (MCC) și cod de rețea mobilă (MNC) de cinci sau șase cifre care identifică rețeaua asociată în prezent cu numărul de telefon.	true
`mcc`	string(3)	Un cod de țară mobilă (MCC) de trei cifre care identifică țara în care este înregistrat numărul de telefon.	true
`mnc`	string(2\|3)	Un cod de rețea mobilă (MNC) de două sau trei cifre care identifică rețeaua specifică căreia îi aparține numărul de telefon.	true
`imsi`	string	Identitatea internațională a abonatului mobil (IMSI), un identificator unic pentru cardul SIM asociat cu acest număr. Disponibilitatea depinde de configurația rețelei.	true
`msin`	string(10)	Numărul de identificare a abonamentului mobil (MSIN) din baza de date a operatorului mobil. Disponibilitatea depinde de configurația rețelei.	true
`msc`	string(12)	Centrul de comutare mobilă (MSC) care gestionează în prezent comunicațiile acestui abonat. Disponibilitatea depinde de configurația rețelei.	true
`original_network_name`	string	Numele operatorului de rețea original (nativ) asociat cu acest număr.	true
`original_country_name`	string	Numele complet al țării în care a fost înregistrat inițial numărul de telefon mobil, furnizat în limba engleză.	true
`original_country_code`	string(2)	Codul de țară ISO cu două caractere care reprezintă țara în care a fost atribuit inițial numărul de telefon.	true
`original_country_prefix`	string	Codul de apelare internațional (codul de apelare a țării) corespunzător țării originale a numărului de telefon mobil.	true
`is_ported`	boolean	Indică dacă numărul mobil a fost portat de la rețeaua sa originală la un alt operator.	true
`ported_network_name`	string	Numele operatorului de rețea la care a fost portat numărul mobil, dacă este cazul.	true
`ported_country_name`	string	Numele țării în care a fost portat numărul mobil, dacă este cazul.	true
`ported_country_code`	string(2)	Codul de țară ISO cu două caractere care reprezintă țara în care a fost portat numărul mobil, dacă este cazul.	true
`ported_country_prefix`	string	Codul de apelare internațional (codul de apelare a țării) pentru țara în care a fost portat numărul mobil, dacă este cazul.	true
`is_roaming`	boolean	Indică dacă numărul mobil se află în prezent în roaming pe o rețea străină. Disponibilitatea stării de roaming depinde de operatorul de rețea mobilă.	true
`roaming_network_name`	string	Numele rețelei pe care se află în prezent în roaming numărul mobil, dacă este cazul.	true
`roaming_country_name`	string	Numele țării în care se află în prezent în roaming numărul mobil, dacă este cazul.	true
`roaming_country_code`	string(2)	Codul de țară ISO cu două caractere al țării în care se află în prezent în roaming numărul mobil, dacă este cazul.	true
`roaming_country_prefix`	string	Codul de apelare internațional (codul de apelare a țării) al țării în care se află în prezent în roaming numărul mobil, dacă este cazul.	true
`cost`	string	O valoare zecimală reprezentată ca șir de caractere, indicând costul interogării în EUR.	true
`timestamp`	string	Un marcaj temporal în format W3C, incluzând fusul orar, specificând când a fost finalizată interogarea.	true
`storage`	string	Numele spațiului de stocare în care au fost salvate rezultatele interogării. Acesta corespunde numelor de rapoarte și descărcărilor CSV disponibile prin interfața web.	true
`route`	string(3)	Un identificator de trei caractere care indică metoda de rutare utilizată pentru această solicitare de interogare.	true
`processing_status`	string	Rezultatul procesării interogării. Valori posibile: `COMPLETED` (cu succes), `REJECTED` (rețea inaccesibilă, fără taxare aplicată) sau `FAILED` (eroare apărută în timpul procesării).	false
`error_code`	integer	Un cod de eroare intern opțional care oferă informații suplimentare de diagnosticare pentru asistența clienților.	true
`error_description`	string	O explicație succintă a codului de eroare dat (dacă există) în text simplu în limba engleză.	true
`data_source`	string	Sursa de date utilizată pentru această solicitare. Valori posibile: `LIVE_HLR` (interogare HLR în timp real) sau `MNP_DB` (bază de date statică de portabilitate a numărului mobil). Consultați opțiunile de rutare pentru detalii.	false
`routing_instruction`	string	Un șir delimitat prin două puncte care descrie instrucțiunea de rutare utilizată în solicitare. Prima componentă este `STATIC` când ați specificat o rută sau `AUTO` pentru rutare automată; a doua componentă este identificatorul rutei, iar pentru solicitările de rutare automată, o a treia componentă arată originea pe baza căreia s-a luat decizia de rutare (adică `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."
    ]
}

Parametri Răspuns Eroare

Nume	Tip	Descriere	Anulabil
`errors[]`	string[]	O listă de șiruri care explică eroarea.	false

Status	Descriere
CONNECTED	Numărul este valid, iar terminalul destinatar este conectat în prezent la rețeaua mobilă. Apelurile, SMS-urile și alte servicii ar trebui să ajungă cu succes la destinatar.
ABSENT	Numărul este valid, dar terminalul destinatar este fie oprit, fie temporar în afara acoperirii rețelei. Mesajele sau apelurile pot să nu fie livrate până când dispozitivul se reconectează la rețea.
INVALID_MSISDN	Numărul este invalid sau nu este alocat în prezent niciunui abonat în rețeaua mobilă. Apelurile și mesajele către acest număr vor eșua.
UNDETERMINED	Starea de conectivitate a numărului nu a putut fi determinată. Acest lucru se poate datora unui număr invalid, unui răspuns de eroare SS7 sau lipsei de conectivitate cu operatorul de rețea destinatar. Verificați codul de eroare și câmpul de descriere pentru diagnostice suplimentare.

Derulați în sus

POST/hlr-lookupsprotejat

Inițiază un lot de interogări HLR asincrone, obținând date live despre conectivitatea și portabilitatea telefoanelor mobile de la operatorii de rețea. Rezultatele sunt livrate prin webhooks către serverul dumneavoastră. Această metodă este optimizată pentru procesarea volumelor mari de numere care nu necesită răspunsuri imediate, cum ar fi curățarea și verificarea bazelor de date. Pentru aplicații în timp real, precum rutarea apelurilor sau livrarea SMS-urilor, luați în considerare utilizarea endpoint-ului POST /hlr-lookup.

Acest endpoint este ideal pentru procesarea în masă atunci când scopul este identificarea numerelor de telefon care sunt în prezent accesibile (conectate) sau indisponibile (telefon oprit), filtrând în același timp numerele invalide, nealocate sau false. În plus, oferă statutul live de portabilitate (MCCMNC) alături de detaliile de conectivitate.

Înainte de a utiliza acest endpoint, asigurați-vă că este configurat un URL webhook pentru a primi rezultatele interogărilor în mod asincron. Puteți configura acest lucru în setările API.

Cerere Răspuns de Succes Răspuns de Eroare Webhooks Referință Statusuri

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

Payload

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

Parametri Cerere

Cheie	Tip	Descriere	Implicit	Obligatoriu
`msisdns`	array	O matrice de numere de telefon mobile (MSISDN-uri) în format internațional (de exemplu +14156226819 sau 0014156226819). Puteți include până la 1000 numere per cerere.	null	obligatoriu
`route`	string(3)	Un identificator opțional de trei caractere care specifică ruta pentru această interogare. Setați la `null` sau omiteți acest parametru pentru a aplica harta de rutare personalizată sau pentru a permite sistemului nostru să determine automat cea mai bună rută pentru această interogare.	null	opțional
`storage`	string	Un identificator opțional de stocare care specifică raportul în care vor fi stocate rezultatele pentru revizuire manuală, analiză și raportare. Sistemul adaugă automat un marcaj temporal cu luna curentă. Dacă este omis sau setat la `null`, sistemul va grupa automat rezultatele pe lună în scopuri de raportare.	null	opțional

{
   "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"
   ]
}

Atribute Răspuns de Succes

Nume	Tip	Descriere	Anulabil
`accepted`	array	O listă de obiecte care conțin identificatori unici și MSISDN-uri care au fost acceptate pentru procesare.	false
`accepted_count`	integer	Numărul total de MSISDN-uri acceptate cu succes pentru procesare.	false
`rejected`	array	O listă de obiecte care conțin identificatori unici și MSISDN-uri care au fost respinse pentru procesare, de obicei din cauza numerelor invalide. Nu se aplică nicio taxă pentru intrările respinse.	false
`rejected_count`	integer	Numărul total de MSISDN-uri respinse din cauza erorilor de validare.	false
`total_count`	integer	Numărul total de MSISDN-uri acceptate și respinse care au fost trimise pentru procesare.	false
`cost`	string	O valoare zecimală reprezentată ca șir de caractere, indicând costul total în EUR pentru interogările acceptate.	false
`storage`	string	Numele spațiului de stocare unde sunt adăugate rezultatele interogărilor, utilizat pentru raportare și descărcări CSV prin interfața web.	false
`route`	string(3\|4)	Un identificator de trei sau patru caractere care specifică ruta utilizată pentru această cerere de interogare. Conține AUTO dacă s-a solicitat rutare automată bazată pe număr.	false
`webhook_urls`	array	URL-urile webhook configurate în setările API. Rezultatele sunt trimise înapoi aici.	false

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

Parametri Răspuns Eroare

Nume	Tip	Descriere	Anulabil
`errors[]`	string[]	O listă de șiruri care explică eroarea.	false

Procesarea Webhook-urilor

Odată trimise, platforma noastră începe procesarea numerelor de telefon furnizate și trimite rezultatele către URL-ul webhook specificat anterior pe serverul dumneavoastră. Rezultatele sunt transmise ca o cerere HTTP POST cu un obiect JSON în corpul cererii.

Autentificare

Autentificați webhook-ul prin verificarea antetului HTTP X-Signatures.

Antetul X-Signatures conține o listă de semnături separate prin punct și virgulă. Fiecare semnătură din listă este generată folosind unul dintre secretele API configurate în contul dumneavoastră. Pentru a verifica webhook-ul, generați un hash SHA-256 folosind cheia API, secretul și corpul HTTP brut - apoi comparați-l cu semnăturile din listă.

O potrivire confirmă că cererea este autentică și semnată cu un secret pe care îl controlați.

Exemplu de cod

$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;
    }
}

Cererea este validă dacă oricare dintre semnăturile furnizate în antet este egală cu un hash SHA256 calculat asupra șirului concatenat format din cheia API, secret și corpul HTTP.

Confirmarea Primirii

Se așteaptă ca serverul dumneavoastră să răspundă cu un cod de status HTTP 200 OK pentru a confirma primirea cu succes. Dacă este returnat orice alt cod de răspuns, apare un timeout (10 secunde) sau apare orice altă problemă de livrare, sistemul va reîncerca automat webhook-ul după un minut. Dacă cererea continuă să eșueze, reîncercările vor urma o strategie de backoff exponențial, cu încercări ulterioare după 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minute.

Acest mecanism de reîncercare asigură fiabilitate maximă în livrarea rezultatelor de interogare către infrastructura dumneavoastră. Minimizează riscul de pierdere a datelor din cauza problemelor temporare de rețea sau a indisponibilității serverului.

Payload 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"
      }
   ]
}

Atribute Payload Webhook

Obiectul JSON conține un atribut type => HLR alături de un atribut results care include o listă de obiecte de interogare, conform documentației de mai jos.

Nume	Tip	Descriere	Anulabil
`id`	string(12)	Un identificator unic atribuit acestei solicitări de interogare.	false
`msisdn`	string	Numărul de telefon mobil interogat, formatat în format internațional (de exemplu, +14156226819 sau 0014156226819).	false
`connectivity_status`	string	Indică dacă starea de conectivitate a numărului a fost obținută cu succes. Valori posibile: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` sau `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Un cod de țară mobilă (MCC) și cod de rețea mobilă (MNC) de cinci sau șase cifre care identifică rețeaua asociată în prezent cu numărul de telefon.	true
`mcc`	string(3)	Un cod de țară mobilă (MCC) de trei cifre care identifică țara în care este înregistrat numărul de telefon.	true
`mnc`	string(2\|3)	Un cod de rețea mobilă (MNC) de două sau trei cifre care identifică rețeaua specifică căreia îi aparține numărul de telefon.	true
`imsi`	string	Identitatea internațională a abonatului mobil (IMSI), un identificator unic pentru cardul SIM asociat cu acest număr. Disponibilitatea depinde de configurația rețelei.	true
`msin`	string(10)	Numărul de identificare a abonamentului mobil (MSIN) din baza de date a operatorului mobil. Disponibilitatea depinde de configurația rețelei.	true
`msc`	string(12)	Centrul de comutare mobilă (MSC) care gestionează în prezent comunicațiile acestui abonat. Disponibilitatea depinde de configurația rețelei.	true
`original_network_name`	string	Numele operatorului de rețea original (nativ) asociat cu acest număr.	true
`original_country_name`	string	Numele complet al țării în care a fost înregistrat inițial numărul de telefon mobil, furnizat în limba engleză.	true
`original_country_code`	string(2)	Codul de țară ISO cu două caractere care reprezintă țara în care a fost atribuit inițial numărul de telefon.	true
`original_country_prefix`	string	Codul de apelare internațional (codul de apelare a țării) corespunzător țării originale a numărului de telefon mobil.	true
`is_ported`	boolean	Indică dacă numărul mobil a fost portat de la rețeaua sa originală la un alt operator.	true
`ported_network_name`	string	Numele operatorului de rețea la care a fost portat numărul mobil, dacă este cazul.	true
`ported_country_name`	string	Numele țării în care a fost portat numărul mobil, dacă este cazul.	true
`ported_country_code`	string(2)	Codul de țară ISO cu două caractere care reprezintă țara în care a fost portat numărul mobil, dacă este cazul.	true
`ported_country_prefix`	string	Codul de apelare internațional (codul de apelare a țării) pentru țara în care a fost portat numărul mobil, dacă este cazul.	true
`is_roaming`	boolean	Indică dacă numărul mobil se află în prezent în roaming pe o rețea străină. Disponibilitatea stării de roaming depinde de operatorul de rețea mobilă.	true
`roaming_network_name`	string	Numele rețelei pe care se află în prezent în roaming numărul mobil, dacă este cazul.	true
`roaming_country_name`	string	Numele țării în care se află în prezent în roaming numărul mobil, dacă este cazul.	true
`roaming_country_code`	string(2)	Codul de țară ISO cu două caractere al țării în care se află în prezent în roaming numărul mobil, dacă este cazul.	true
`roaming_country_prefix`	string	Codul de apelare internațional (codul de apelare a țării) al țării în care se află în prezent în roaming numărul mobil, dacă este cazul.	true
`cost`	string	O valoare zecimală reprezentată ca șir de caractere, indicând costul interogării în EUR.	true
`timestamp`	string	Un marcaj temporal în format W3C, incluzând fusul orar, specificând când a fost finalizată interogarea.	true
`storage`	string	Numele spațiului de stocare în care au fost salvate rezultatele interogării. Acesta corespunde numelor de rapoarte și descărcărilor CSV disponibile prin interfața web.	true
`route`	string(3)	Un identificator de trei caractere care indică metoda de rutare utilizată pentru această solicitare de interogare.	true
`processing_status`	string	Rezultatul procesării interogării. Valori posibile: `COMPLETED` (cu succes), `REJECTED` (rețea inaccesibilă, fără taxare aplicată) sau `FAILED` (eroare apărută în timpul procesării).	false
`error_code`	integer	Un cod de eroare intern opțional care oferă informații suplimentare de diagnosticare pentru asistența clienților.	true
`error_description`	string	O explicație succintă a codului de eroare dat (dacă există) în text simplu în limba engleză.	true
`data_source`	string	Sursa de date utilizată pentru această solicitare. Valori posibile: `LIVE_HLR` (interogare HLR în timp real) sau `MNP_DB` (bază de date statică de portabilitate a numărului mobil). Consultați opțiunile de rutare pentru detalii.	false
`routing_instruction`	string	Un șir delimitat prin două puncte care descrie instrucțiunea de rutare utilizată în solicitare. Prima componentă este `STATIC` când ați specificat o rută sau `AUTO` pentru rutare automată; a doua componentă este identificatorul rutei, iar pentru solicitările de rutare automată, o a treia componentă arată originea pe baza căreia s-a luat decizia de rutare (adică `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

Status	Descriere
CONNECTED	Numărul este valid, iar terminalul destinatar este conectat în prezent la rețeaua mobilă. Apelurile, SMS-urile și alte servicii ar trebui să ajungă cu succes la destinatar.
ABSENT	Numărul este valid, dar terminalul destinatar este fie oprit, fie temporar în afara acoperirii rețelei. Mesajele sau apelurile pot să nu fie livrate până când dispozitivul se reconectează la rețea.
INVALID_MSISDN	Numărul este invalid sau nu este alocat în prezent niciunui abonat în rețeaua mobilă. Apelurile și mesajele către acest număr vor eșua.
UNDETERMINED	Starea de conectivitate a numărului nu a putut fi determinată. Acest lucru se poate datora unui număr invalid, unui răspuns de eroare SS7 sau lipsei de conectivitate cu operatorul de rețea destinatar. Verificați codul de eroare și câmpul de descriere pentru diagnostice suplimentare.

Derulați în sus

POST/mnp-lookupprotejat

Efectuează o interogare MNP sincronă și furnizează informații despre portabilitatea numerelor mobile și rețea. Acest endpoint este potrivit dacă obiectivul dvs. principal este să extrageți MCCMNC-ul curent al unui număr de telefon mobil și să identificați rețelele originale și actuale în timp real.

Pentru procesarea în bloc a seturilor mari de date care nu necesită rezultate instantanee, luați în considerare utilizarea POST /mnp-lookups asincron, care este optimizat pentru procesarea rapidă în loturi.

Interogările MNP determină în mod fiabil informațiile despre portabilitate și rețea, dar nu indică dacă telefonul mobil țintă este conectat în prezent la o rețea și accesibil. Pentru a extrage informații despre conectivitate în timp real, vă rugăm să utilizați endpoint-ul POST /hlr-lookup.

Cerere Răspuns de Succes Răspuns de Eroare

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

Payload

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

Parametri Cerere

Cheie	Tip	Descriere	Implicit	Obligatoriu
`msisdn`	string	Numărul de telefon mobil (MSISDN) care urmează să fie interogat, furnizat în format internațional (de ex., +14156226819 sau 0014156226819). Prefixele țării trebuie incluse.	null	obligatoriu
`route`	string(3)	Un identificator opțional de trei caractere care specifică ruta pentru această interogare. Setați la `null` sau omiteți acest parametru pentru a aplica harta de rutare personalizată sau pentru a permite sistemului nostru să determine automat cea mai bună rută pentru această interogare.	null	opțional
`storage`	string	Un identificator opțional de stocare care specifică raportul în care vor fi stocate rezultatele pentru revizuire manuală, analiză și raportare. Sistemul adaugă automat un marcaj temporal cu luna curentă. Dacă este omis sau setat la `null`, sistemul va grupa automat rezultatele pe lună în scopuri de raportare.	null	opțional

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

Atribute Răspuns de Succes

Nume	Tip	Descriere	Anulabil
`id`	string(12)	Un identificator unic de 12 caractere pentru această interogare.	false
`msisdn`	string	Numărul de telefon mobil evaluat în această cerere de interogare.	false
`query_status`	string	Indică dacă obținerea informațiilor de portabilitate și rețea a reușit. Valorile posibile sunt `OK` sau `FAILED`.	false
`mccmnc`	string(5\|6)	Un MCCMNC de cinci sau șase caractere (codul țării mobile și codul rețelei mobile) care identifică rețeaua căreia îi aparține în prezent numărul de telefon mobil.	true
`mcc`	string(3)	Un MCC de trei caractere (codul țării mobile) reprezentând țara asociată cu rețeaua actuală a numărului de telefon mobil.	true
`mnc`	string(2\|3)	Un MNC de două sau trei caractere (codul rețelei mobile) care identifică operatorul de rețea actual pentru numărul de telefon mobil.	true
`is_ported`	boolean	Indică dacă numărul de telefon a fost portat de la rețeaua sa inițială la un operator nou.	true
`original_network_name`	string	Un șir arbitrar (în limba engleză) care specifică numele operatorului de rețea inițial al numărului de telefon mobil inspectat.	true
`original_country_name`	string	Un șir arbitrar (în limba engleză) care indică țara inițială a numărului de telefon mobil inspectat.	true
`original_country_code`	string(2)	Un cod de țară ISO de două caractere reprezentând țara inițială a numărului de telefon mobil inspectat.	true
`original_country_prefix`	string	Prefixul de apel al țării inițiale asociate cu numărul de telefon mobil inspectat.	true
`ported_network_name`	string	Specifică operatorul de rețea la care a fost portat numărul de telefon mobil inspectat, dacă este cazul.	true
`ported_country_name`	string	Specifică țara la care a fost portat numărul de telefon mobil inspectat, dacă este cazul.	true
`ported_country_code`	string(2)	Un cod de țară ISO de două caractere reprezentând țara la care a fost portat numărul de telefon mobil inspectat, dacă este cazul.	true
`ported_country_prefix`	string	Prefixul de apel pentru țara la care a fost portat numărul de telefon mobil inspectat, dacă este cazul.	true
`extra`	string	Un șir arbitrar care furnizează detalii suplimentare opționale despre numărul de telefon.	true
`cost`	string	O valoare zecimală, reprezentată ca șir de caractere, indicând costul în EUR pentru această interogare.	true
`timestamp`	string	Un marcaj temporal formatat W3C, incluzând informații despre fusul orar, indicând când a fost finalizată interogarea.	true
`storage`	string	Numele de stocare (sau numele raportului) la care au fost adăugate rezultatele interogării. Acesta este utilizat pentru descărcări CSV și raportare prin interfața web.	true
`route`	string(3)	Un identificator de trei caractere care specifică ruta utilizată pentru această cerere de interogare.	true
`error_code`	integer	Un cod de eroare intern opțional care furnizează context suplimentar pentru diagnosticarea suportului clienți.	true

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

Parametri Răspuns Eroare

Nume	Tip	Descriere	Anulabil
`errors[]`	string[]	O listă de șiruri care explică eroarea.	false

Derulați în sus

POST/mnp-lookupsprotejat

Inițiază un lot de interogări MNP (portabilitate număr mobil) asincrone, recuperând MCCMNC-ul curent și identificând rețelele originale și actuale în timp real. Rezultatele sunt livrate prin webhooks către serverul dumneavoastră. Această metodă este optimizată pentru procesarea volumelor mari de numere care nu necesită răspunsuri imediate, cum ar fi curățarea și verificarea bazelor de date. Pentru aplicații în timp real, precum rutarea apelurilor sau livrarea SMS-urilor, luați în considerare utilizarea endpoint-ului POST /mnp-lookup.

Interogările MNP determină în mod fiabil informațiile despre portabilitate și rețea, dar nu indică dacă telefonul mobil țintă este conectat în prezent la o rețea și accesibil. Pentru a extrage informații despre conectivitate în timp real, vă rugăm să utilizați endpoint-ul POST /hlr-lookups.

Înainte de a utiliza acest endpoint, asigurați-vă că este configurat un URL webhook pentru a primi rezultatele interogărilor în mod asincron. Puteți configura acest lucru în setările API.

Cerere Răspuns de Succes Răspuns de Eroare Webhooks

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

Payload

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

Parametri Cerere

Cheie	Tip	Descriere	Implicit	Obligatoriu
`msisdns`	array	O matrice de numere de telefon mobile (MSISDN-uri) în format internațional (de exemplu +14156226819 sau 0014156226819). Puteți include până la 1000 numere per cerere.	null	obligatoriu
`route`	string(3)	Un identificator opțional de trei caractere care specifică ruta pentru această interogare. Setați la `null` sau omiteți acest parametru pentru a aplica harta de rutare personalizată sau pentru a permite sistemului nostru să determine automat cele mai bune rute pentru această solicitare.	null	opțional
`storage`	string	Un identificator opțional de stocare care specifică raportul în care vor fi stocate rezultatele pentru revizuire manuală, analiză și raportare. Sistemul adaugă automat un marcaj temporal cu luna curentă. Dacă este omis sau setat la `null`, sistemul va grupa automat rezultatele pe lună în scopuri de raportare.	null	opțional

{
   "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"
   ]
}

Atribute Răspuns de Succes

Nume	Tip	Descriere	Anulabil
`accepted`	array	O listă de obiecte care conțin identificatori unici și MSISDN-uri care au fost acceptate pentru procesare.	false
`accepted_count`	integer	Numărul total de MSISDN-uri acceptate cu succes pentru procesare.	false
`rejected`	array	O listă de obiecte care conțin identificatori unici și MSISDN-uri care au fost respinse pentru procesare, de obicei din cauza numerelor invalide. Nu se aplică nicio taxă pentru intrările respinse.	false
`rejected_count`	integer	Numărul total de MSISDN-uri respinse din cauza erorilor de validare.	false
`total_count`	integer	Numărul total de MSISDN-uri acceptate și respinse care au fost trimise pentru procesare.	false
`cost`	string	O valoare zecimală reprezentată ca șir de caractere, indicând costul total în EUR pentru interogările acceptate.	false
`storage`	string	Numele spațiului de stocare unde sunt adăugate rezultatele interogărilor, utilizat pentru raportare și descărcări CSV prin interfața web.	false
`route`	string(3)	Un identificator de trei caractere care specifică ruta utilizată pentru această cerere de interogare.	false
`webhook_urls`	array	URL-urile webhook configurate în setările API. Rezultatele sunt trimise înapoi aici.	false

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

Parametri Răspuns Eroare

Nume	Tip	Descriere	Anulabil
`errors[]`	string[]	O listă de șiruri care explică eroarea.	false

Procesarea Webhook-urilor

Odată trimise, platforma noastră începe procesarea numerelor de telefon furnizate și trimite rezultatele către URL-ul webhook specificat anterior pe serverul dumneavoastră. Rezultatele sunt transmise ca o cerere HTTP POST cu un obiect JSON în corpul cererii.

Autentificare

Autentificați webhook-ul prin verificarea antetului HTTP X-Signatures.

Antetul X-Signatures conține o listă de semnături separate prin punct și virgulă. Fiecare semnătură din listă este generată folosind unul dintre secretele API configurate în contul dumneavoastră. Pentru a verifica webhook-ul, generați un hash SHA-256 folosind cheia API, secretul și corpul HTTP brut - apoi comparați-l cu semnăturile din listă.

O potrivire confirmă că cererea este autentică și semnată cu un secret pe care îl controlați.

Exemplu de cod

$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;
    }
}

Cererea este validă dacă oricare dintre semnăturile furnizate în antet este egală cu un hash SHA256 calculat asupra șirului concatenat format din cheia API, secret și corpul HTTP.

Confirmarea Primirii

Se așteaptă ca serverul dumneavoastră să răspundă cu un cod de status HTTP 200 OK pentru a confirma primirea cu succes. Dacă este returnat orice alt cod de răspuns, apare un timeout (10 secunde) sau apare orice altă problemă de livrare, sistemul va reîncerca automat webhook-ul după un minut. Dacă cererea continuă să eșueze, reîncercările vor urma o strategie de backoff exponențial, cu încercări ulterioare după 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minute.

Acest mecanism de reîncercare asigură fiabilitate maximă în livrarea rezultatelor de interogare către infrastructura dumneavoastră. Minimizează riscul de pierdere a datelor din cauza problemelor temporare de rețea sau a indisponibilității serverului.

Payload 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
        }
    ]
}

Atribute Payload Webhook

Obiectul JSON conține un atribut type => MNP alături de un atribut results care include o listă de obiecte de interogare, conform documentației de mai jos.

Nume	Tip	Descriere	Anulabil
`id`	string(12)	Un identificator unic de 12 caractere pentru această interogare.	false
`msisdn`	string	Numărul de telefon mobil evaluat în această cerere de interogare.	false
`query_status`	string	Indică dacă obținerea informațiilor de portabilitate și rețea a reușit. Valorile posibile sunt `OK` sau `FAILED`.	false
`mccmnc`	string(5\|6)	Un MCCMNC de cinci sau șase caractere (codul țării mobile și codul rețelei mobile) care identifică rețeaua căreia îi aparține în prezent numărul de telefon mobil.	true
`mcc`	string(3)	Un MCC de trei caractere (codul țării mobile) reprezentând țara asociată cu rețeaua actuală a numărului de telefon mobil.	true
`mnc`	string(2\|3)	Un MNC de două sau trei caractere (codul rețelei mobile) care identifică operatorul de rețea actual pentru numărul de telefon mobil.	true
`is_ported`	boolean	Indică dacă numărul de telefon a fost portat de la rețeaua sa inițială la un operator nou.	true
`original_network_name`	string	Un șir arbitrar (în limba engleză) care specifică numele operatorului de rețea inițial al numărului de telefon mobil inspectat.	true
`original_country_name`	string	Un șir arbitrar (în limba engleză) care indică țara inițială a numărului de telefon mobil inspectat.	true
`original_country_code`	string(2)	Un cod de țară ISO de două caractere reprezentând țara inițială a numărului de telefon mobil inspectat.	true
`original_country_prefix`	string	Prefixul de apel al țării inițiale asociate cu numărul de telefon mobil inspectat.	true
`ported_network_name`	string	Specifică operatorul de rețea la care a fost portat numărul de telefon mobil inspectat, dacă este cazul.	true
`ported_country_name`	string	Specifică țara la care a fost portat numărul de telefon mobil inspectat, dacă este cazul.	true
`ported_country_code`	string(2)	Un cod de țară ISO de două caractere reprezentând țara la care a fost portat numărul de telefon mobil inspectat, dacă este cazul.	true
`ported_country_prefix`	string	Prefixul de apel pentru țara la care a fost portat numărul de telefon mobil inspectat, dacă este cazul.	true
`extra`	string	Un șir arbitrar care furnizează detalii suplimentare opționale despre numărul de telefon.	true
`cost`	string	O valoare zecimală, reprezentată ca șir de caractere, indicând costul în EUR pentru această interogare.	true
`timestamp`	string	Un marcaj temporal formatat W3C, incluzând informații despre fusul orar, indicând când a fost finalizată interogarea.	true
`storage`	string	Numele de stocare (sau numele raportului) la care au fost adăugate rezultatele interogării. Acesta este utilizat pentru descărcări CSV și raportare prin interfața web.	true
`route`	string(3)	Un identificator de trei caractere care specifică ruta utilizată pentru această cerere de interogare.	true
`error_code`	integer	Un cod de eroare intern opțional care furnizează context suplimentar pentru diagnosticarea suportului clienți.	true

Derulați în sus

POST/nt-lookupprotejat

Execută o interogare sincronă de tip număr (NT). Acest endpoint este ideal dacă scopul principal este să determinați dacă numerele de telefon furnizate aparțin intervalelor de numerotare pentru telefonie fixă, mobilă, tarif premium, VoIP, pager sau alte categorii în timp real.

Interogările NT detectează în mod fiabil tipul de număr de telefon; cu toate acestea, ele nu indică dacă numărul țintă este conectat în prezent la o rețea și accesibil. Pentru a extrage informații despre conectivitatea live, vă rugăm să utilizați endpoint-ul POST /hlr-lookup.

Dacă cazul dumneavoastră de utilizare necesită informații precise despre rețea și portabilitate (MCCMNC), dar nu și starea de conectivitate live, vă rugăm să utilizați endpoint-ul POST /mnp-lookup pentru interogări de portabilitate a numerelor mobile.

Cerere Răspuns de Succes Răspuns de Eroare Referință Tipuri

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

Payload

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

Parametri Cerere

Cheie	Tip	Descriere	Implicit	Obligatoriu
`number`	string	Un număr de telefon în format internațional (de exemplu +4989702626 sau 004989702626).	null	mandatory
`route`	string(3)	Un identificator opțional de trei caractere care specifică ruta pentru această interogare. Setați la `null` sau omiteți acest parametru pentru a aplica harta de rutare personalizată sau pentru a permite sistemului nostru să determine automat cele mai bune rute pentru această solicitare.	null	opțional
`storage`	string	Un identificator opțional de stocare care specifică raportul în care vor fi stocate rezultatele pentru revizuire manuală, analiză și raportare. Sistemul adaugă automat un marcaj temporal cu luna curentă. Dacă este omis sau setat la `null`, sistemul va grupa automat rezultatele pe lună în scopuri de raportare.	null	opțional

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

Atribute Răspuns de Succes

Nume	Tip	Descriere	Anulabil
`id`	string(12)	Un identificator unic atribuit acestei solicitări de interogare.	false
`number`	string	Numărul de telefon care a fost evaluat în timpul acestei solicitări de interogare.	false
`number_type`	string	Tipul de număr detectat. Valorile posibile includ: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Indică dacă informațiile despre tipul de număr au fost obținute cu succes. Returnează `OK` în caz de succes sau `FAILED` dacă interogarea a eșuat.	false
`is_valid`	boolean	Indică dacă numărul de telefon este sintactic valid.	true
`invalid_reason`	string	Un mesaj în text simplu în limba engleză care specifică de ce numărul de telefon este considerat invalid (de ex. "too short" sau "invalid prefix"), sau `null` dacă numărul este valid.	true
`is_possibly_ported`	boolean	Indică dacă numărul de telefon ar fi putut fi portat de la operatorul original către un alt operator. Pentru informații definitive despre portabilitate, utilizați interogări MNP.	true
`is_vanity_number`	boolean	Indică dacă numărul de telefon este un număr vanity, adică include caractere alfabetice.	true
`qualifies_for_hlr_lookup`	boolean	Indică dacă numărul de telefon este eligibil pentru interogări suplimentare prin interogări HLR.	true
`mccmnc`	string(5\|6)	Un șir de cinci sau șase caractere care reprezintă tuplul MCCMNC (codul țării mobile și codul rețelei mobile) ce identifică rețeaua originală a numărului de telefon mobil.	true
`mcc`	string(3)	Un șir de trei caractere care reprezintă MCC (codul țării mobile) ce identifică țara asociată cu rețeaua mobilă originală a numărului de telefon.	true
`mnc`	string(2\|3)	Un șir de două sau trei caractere care reprezintă MNC (codul rețelei mobile) ce identifică operatorul rețelei mobile originale a numărului de telefon.	true
`original_network_name`	string	Un șir arbitrar în text simplu în limba engleză care specifică numele operatorului rețelei originale a numărului de telefon mobil inspectat.	true
`original_country_name`	string	Un șir arbitrar în text simplu în limba engleză care specifică țara originală asociată cu numărul de telefon mobil inspectat.	true
`original_country_code`	string(2)	Un cod de țară ISO de două caractere care indică țara originală a numărului de telefon mobil inspectat.	true
`regions`	array	O listă de șiruri lizibile în limba engleză care specifică regiunea sau regiunile geografice asociate cu acest număr de telefon.	true
`timezones`	array	O listă de fusuri orare (în format Olson) asociate cu acest număr de telefon.	true
`info_text`	string	Un șir arbitrar care poate conține informații suplimentare despre numărul de telefon.	true
`cost`	string	O valoare zecimală reprezentată ca șir, care indică costul (în EUR) al acestei interogări.	true
`timestamp`	string	Un marcaj temporal în format W3C (incluzând fusul orar) care indică momentul când interogarea a fost finalizată.	true
`storage`	string	Specifică numele stocării unde rezultatele interogării au fost adăugate. Acesta corespunde numelui raportului utilizat pentru descărcări CSV și analize prin interfața web.	true
`route`	string(3)	Un identificator de trei caractere care specifică ruta utilizată pentru această cerere de interogare.	true

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

Parametri Răspuns Eroare

Nume	Tip	Descriere	Anulabil
`errors[]`	string[]	O listă de șiruri care explică eroarea.	false

Tip	Descriere
LANDLINE	Număr de telefon fix.
MOBILE	Număr de telefon mobil. Calificat pentru interogări HLR pentru obținerea de informații suplimentare despre starea conexiunii, rețea, portabilitate și roaming.
MOBILE_OR_LANDLINE	Număr de telefon fix sau mobil. Poate fi calificat pentru interogare HLR.
TOLL_FREE	Număr de telefon gratuit.
PREMIUM_RATE	Număr de telefon cu tarif majorat și costuri suplimentare.
SHARED_COST	Număr de telefon cu cost partajat. De obicei mai puțin costisitor decât numerele cu tarif majorat.
VOIP	Număr de telefon Voice over IP. Include numere TSoIP (Telephony Service over IP).
PAGER	Număr de pager. De obicei fără funcționalitate vocală.
UAN	Număr de Acces Universal (Număr de Companie). Poate fi direcționat către birouri specifice, dar permite utilizarea unui singur număr pentru întreaga companie.
VOICEMAIL	Număr de telefon pentru mesagerie vocală.
UNKNOWN	Tipul numărului nu a putut fi determinat.

Derulați în sus

POST/nt-lookups protejat

Acest endpoint inițiază o serie de interogări asincrone de tip număr, cu rezultate transmise înapoi către serverul dumneavoastră prin webhook. Este potrivit dacă scopul dumneavoastră principal este să determinați dacă numerele de telefon date aparțin categoriilor de telefonie fixă, mobilă, tarif premium, VoIP, pager sau alte intervale din planul de numerotare. Optimizat pentru procesarea rapidă a unor volume mari de numere, acest endpoint este ideal pentru operațiuni în masă (de exemplu, sanitizarea bazelor de date). Pentru trafic live și cazuri de utilizare critice din punct de vedere temporal, vă rugăm să utilizați în schimb endpoint-ul POST /nt-lookup.

Trebuie să specificați un URL webhook în setările API ca precondiție pentru a invoca acest endpoint.

Cerere Răspuns de Succes Răspuns de Eroare Webhooks Referință Tipuri

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

Payload

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

Parametri Cerere

Cheie	Tip	Descriere	Implicit	Obligatoriu
`numbers`	array	O matrice de numere de telefon în format internațional (de exemplu, +14156226819 sau 004989702626). Maxim 1000 numere pot fi incluse per cerere.	null	obligatoriu
`route`	string(3)	Un identificator opțional de trei caractere care specifică ruta pentru această interogare. Setați la `null` sau omiteți acest parametru pentru a aplica harta de rutare personalizată sau pentru a permite sistemului nostru să determine automat cea mai bună rută pentru această cerere.	null	opțional
`storage`	string	Un identificator opțional de stocare care specifică raportul în care vor fi stocate rezultatele pentru revizuire manuală, analiză și raportare. Sistemul adaugă automat un marcaj temporal cu luna curentă. Dacă este omis sau setat la `null`, sistemul va grupa automat rezultatele pe lună în scopuri de raportare.	null	opțional

{
   "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"
   ]
}

Atribute Răspuns de Succes

Nume	Tip	Descriere	Anulabil
`accepted`	array	O matrice de obiecte, fiecare conținând un identificator unic și un număr de telefon care a fost acceptat pentru procesare.	false
`accepted_count`	integer	Numărul total de numere de telefon acceptate pentru procesare.	false
`rejected`	array	O matrice de obiecte, fiecare conținând un identificator unic și un număr de telefon care a fost respins pentru procesare. De obicei, aceste numere sunt invalide și nu se aplică nicio taxă.	false
`rejected_count`	integer	Numărul total de numere de telefon care au fost respinse pentru procesare.	false
`total_count`	integer	Numărul total de numere de telefon acceptate și respinse care au fost trimise pentru procesare.	false
`cost`	string	Un șir reprezentând o valoare zecimală care indică costul în EUR pentru aceste interogări.	false
`storage`	string	Numele spațiului de stocare (raport) unde au fost adăugate rezultatele interogării. Acest nume este utilizat pentru descărcări CSV și analize prin interfața web.	false
`route`	string(3)	Un identificator de trei caractere care specifică ruta utilizată pentru această cerere de interogare.	false
`webhook_urls`	array	URL-urile webhook configurate în setările API. Rezultatele sunt trimise înapoi aici.	false

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

Parametri Răspuns Eroare

Nume	Tip	Descriere	Anulabil
`errors[]`	string[]	O listă de șiruri care explică eroarea.	false

Procesarea Webhook-urilor

Odată trimise, platforma noastră începe procesarea numerelor de telefon furnizate și trimite rezultatele către URL-ul webhook specificat anterior pe serverul dumneavoastră. Rezultatele sunt transmise ca o cerere HTTP POST cu un obiect JSON în corpul cererii.

Autentificare

Autentificați webhook-ul prin verificarea antetului HTTP X-Signatures.

Antetul X-Signatures conține o listă de semnături separate prin punct și virgulă. Fiecare semnătură din listă este generată folosind unul dintre secretele API configurate în contul dumneavoastră. Pentru a verifica webhook-ul, generați un hash SHA-256 folosind cheia API, secretul și corpul HTTP brut - apoi comparați-l cu semnăturile din listă.

O potrivire confirmă că cererea este autentică și semnată cu un secret pe care îl controlați.

Exemplu de cod

$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;
    }
}

Cererea este validă dacă oricare dintre semnăturile furnizate în antet este egală cu un hash SHA256 calculat asupra șirului concatenat format din cheia API, secret și corpul HTTP.

Confirmarea Primirii

Se așteaptă ca serverul dumneavoastră să răspundă cu un cod de status HTTP 200 OK pentru a confirma primirea cu succes. Dacă este returnat orice alt cod de răspuns, apare un timeout (10 secunde) sau apare orice altă problemă de livrare, sistemul va reîncerca automat webhook-ul după un minut. Dacă cererea continuă să eșueze, reîncercările vor urma o strategie de backoff exponențial, cu încercări ulterioare după 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minute.

Acest mecanism de reîncercare asigură fiabilitate maximă în livrarea rezultatelor de interogare către infrastructura dumneavoastră. Minimizează riscul de pierdere a datelor din cauza problemelor temporare de rețea sau a indisponibilității serverului.

Payload 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"
      }
   ]
}

Atribute Payload Webhook

Obiectul JSON conține un atribut type => NT alături de un atribut results care include o listă de obiecte de interogare, conform documentației de mai jos.

Nume	Tip	Descriere	Anulabil
`id`	string(12)	Un identificator unic atribuit acestei solicitări de interogare.	false
`number`	string	Numărul de telefon care a fost evaluat în timpul acestei solicitări de interogare.	false
`number_type`	string	Tipul de număr detectat. Valorile posibile includ: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Indică dacă informațiile despre tipul de număr au fost obținute cu succes. Returnează `OK` în caz de succes sau `FAILED` dacă interogarea a eșuat.	false
`is_valid`	boolean	Indică dacă numărul de telefon este sintactic valid.	true
`invalid_reason`	string	Un mesaj în text simplu în limba engleză care specifică de ce numărul de telefon este considerat invalid (de ex. "too short" sau "invalid prefix"), sau `null` dacă numărul este valid.	true
`is_possibly_ported`	boolean	Indică dacă numărul de telefon ar fi putut fi portat de la operatorul original către un alt operator. Pentru informații definitive despre portabilitate, utilizați interogări MNP.	true
`is_vanity_number`	boolean	Indică dacă numărul de telefon este un număr vanity, adică include caractere alfabetice.	true
`qualifies_for_hlr_lookup`	boolean	Indică dacă numărul de telefon este eligibil pentru interogări suplimentare prin interogări HLR.	true
`mccmnc`	string(5\|6)	Un șir de cinci sau șase caractere care reprezintă tuplul MCCMNC (codul țării mobile și codul rețelei mobile) ce identifică rețeaua originală a numărului de telefon mobil.	true
`mcc`	string(3)	Un șir de trei caractere care reprezintă MCC (codul țării mobile) ce identifică țara asociată cu rețeaua mobilă originală a numărului de telefon.	true
`mnc`	string(2\|3)	Un șir de două sau trei caractere care reprezintă MNC (codul rețelei mobile) ce identifică operatorul rețelei mobile originale a numărului de telefon.	true
`original_network_name`	string	Un șir arbitrar în text simplu în limba engleză care specifică numele operatorului rețelei originale a numărului de telefon mobil inspectat.	true
`original_country_name`	string	Un șir arbitrar în text simplu în limba engleză care specifică țara originală asociată cu numărul de telefon mobil inspectat.	true
`original_country_code`	string(2)	Un cod de țară ISO de două caractere care indică țara originală a numărului de telefon mobil inspectat.	true
`regions`	array	O listă de șiruri lizibile în limba engleză care specifică regiunea sau regiunile geografice asociate cu acest număr de telefon.	true
`timezones`	array	O listă de fusuri orare (în format Olson) asociate cu acest număr de telefon.	true
`info_text`	string	Un șir arbitrar care poate conține informații suplimentare despre numărul de telefon.	true
`cost`	string	O valoare zecimală reprezentată ca șir, care indică costul (în EUR) al acestei interogări.	true
`timestamp`	string	Un marcaj temporal în format W3C (incluzând fusul orar) care indică momentul când interogarea a fost finalizată.	true
`storage`	string	Specifică numele stocării unde rezultatele interogării au fost adăugate. Acesta corespunde numelui raportului utilizat pentru descărcări CSV și analize prin interfața web.	true
`route`	string(3)	Un identificator de trei caractere care specifică ruta utilizată pentru această cerere de interogare.	true

Tip	Descriere
LANDLINE	Număr de telefon fix.
MOBILE	Număr de telefon mobil. Calificat pentru interogări HLR pentru obținerea de informații suplimentare despre starea conexiunii, rețea, portabilitate și roaming.
MOBILE_OR_LANDLINE	Număr de telefon fix sau mobil. Poate fi calificat pentru interogare HLR.
TOLL_FREE	Număr de telefon gratuit.
PREMIUM_RATE	Număr de telefon cu tarif majorat și costuri suplimentare.
SHARED_COST	Număr de telefon cu cost partajat. De obicei mai puțin costisitor decât numerele cu tarif majorat.
VOIP	Număr de telefon Voice over IP. Include numere TSoIP (Telephony Service over IP).
PAGER	Număr de pager. De obicei fără funcționalitate vocală.
UAN	Număr de Acces Universal (Număr de Companie). Poate fi direcționat către birouri specifice, dar permite utilizarea unui singur număr pentru întreaga companie.
VOICEMAIL	Număr de telefon pentru mesagerie vocală.
UNKNOWN	Tipul numărului nu a putut fi determinat.

Derulați în sus

GET/routeprotejat

Returnează ruta care va fi selectată automat când efectuați o interogare HLR fără a specifica parametrul route.

Selecția automată a rutei se bazează pe harta de rutare disponibilă prin endpoint-ul GET /hlr-coverage, care este derivată în principal din GET /routing-map. Puteți personaliza harta de rutare și defini reguli personalizate în setările contului.

Cerere Răspuns de Succes Răspuns de Eroare

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

Parametri Cerere

Cheie	Tip	Descriere	Implicit	Obligatoriu
`msisdn`	string	MSISDN-ul pentru care se returnează informațiile de rutare selectate automat.	null	obligatoriu

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

Atribute Răspuns de Succes

Nume	Tip	Descriere	Anulabil
`route`	string	Ruta recomandata.	false
`confidence_level`	string	Nivelul de încredere cu care a fost selectată această rută, adică `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`.	false
`mccmnc`	string	MCCMNC bazat pe planul de numerotare pentru acest număr.	false
`origin`	string	Originea pe baza căreia se ia decizia de rutare, adică `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."
    ]
}

Parametri Răspuns Eroare

Nume	Tip	Descriere	Anulabil
`errors[]`	string[]	O listă de șiruri care explică eroarea.	false

Derulați în sus

GET/routesprotejat

Acest endpoint returnează o listă cu rutele HLR, MNP și NT disponibile. Fiecare rută, împreună cu caracteristicile și limitările sale, este explicată pe pagina detalii rutare.

Cerere Răspuns de Succes Răspuns de Eroare

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

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

Atribute Răspuns de Succes

Nume	Tip	Descriere	Anulabil
`routes`	object	Un obiect cu rute grupate pe tipuri de rută.	false
`HLR\|MNP\|NT`	string[]	Conține o listă de identificatori de rută.	false

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

Parametri Răspuns Eroare

Nume	Tip	Descriere	Anulabil
`errors[]`	string[]	O listă de șiruri care explică eroarea.	false

Derulați în sus

GET/routing-mapprotejat

Returnează configurația de rutare automată aplicată în prezent pentru interogările HLR din contul dvs. Această configurație implicită este utilizată ori de câte ori trimiteți interogări HLR fără a specifica un parametru route. Puteți personaliza harta de rutare și crea reguli personalizate în setările contului.

Ierarhia configurației cascadează de la reguli la nivel de țară la reguli la nivel MCCMNC și, în final, la mapări individuale de prefixe de numere de telefon. În practică, aceasta înseamnă că mapările individuale de prefixe de numere de telefon au prioritate față de atribuirile MCCMNC conflictuale, care la rândul lor suprascriu regulile la nivel de țară. Vă rugăm să rețineți că fallback-ul MNP suprascrie orice reguli personalizate conflictuale atât timp cât este activat.

Cerere Răspuns de Succes Răspuns de Eroare

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"
            }
         ]
      }
   }
}

Atribute Răspuns de Succes

Nume	Tip	Descriere	Anulabil
`default_route`	string	Ruta implicită utilizată când nu se poate determina nicio opțiune de rutare preferată pentru un MSISDN și nu se aplică reguli de rutare personalizate.	false
`mnp_fallback`	boolean	Indică dacă fallback-ul MNP este activat. Când este activat și interogările HLR nu sunt suportate de o rețea (starea conectivității indisponibilă), sistemul va efectua o interogare MNP în schimb.	false
`mccmncs`	array	O mapare a codurilor MCCMNC la rutele lor selectate automat. Când se efectuează o interogare HLR pentru un număr dintr-un anumit MCCMNC, se utilizează ruta corespunzătoare.	false
`mccmnc`	string(5\|6)	Un MCCMNC (combinație de cod de țară mobil și cod de rețea mobilă) din cinci sau șase caractere care identifică operatorul de rețea mobilă.	false
`countrycode`	string(2)	Un cod de țară ISO cu două caractere, care identifică țara rețelei.	false
`route`	string(3)	Ruta selectată pentru rețea.	false
`mno`	string	Brandul comercial sub care operează această rețea.	false
`confidence`	string	Nivelul de încredere cu care a fost efectuată selecția. Valorile posibile sunt: HIGH, NORMAL, LOW, MNP_REDIRECT. În cazul celei din urmă, sistemul redirecționează traficul către această rețea la MNP, dacă acest comportament este activat în contul dvs. Altfel, utilizează ruta implicită din cont.	false
`origin`	string	Originea pe baza căreia se face selecția. Valorile posibile sunt: `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	O listă de reguli de rutare personalizate bazate pe prefixe configurate în contul dvs., dacă există.	false
`countrycode`	string(2)	Un cod de țară ISO cu două caractere, care identifică țara prefixului.	false
`cns`	string	Prefixul la care se aplică regula de rutare.	false
`route`	string(3)	Ruta selectată pentru prefix.	false
`mccmnc`	string(5\|6)	Un MCCMNC (combinație de cod de țară mobil și cod de rețea mobilă) din cinci sau șase caractere care identifică operatorul de rețea mobilă.	true
`mno`	string	Brandul comercial sub care operează această rețea.	true
`countries`	array	O listă de reguli personalizate bazate pe țară configurate în contul dvs., dacă există.	false
`countrycode`	string(2)	Un cod de țară ISO cu două caractere, care identifică țara.	false
`route`	string(3)	Ruta selectată pentru țară.	false

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

Parametri Răspuns Eroare

Nume	Tip	Descriere	Anulabil
`errors[]`	string[]	O listă de șiruri care explică eroarea.	false

Derulați în sus

GET/hlr-coverage protejat

Returnează informații detaliate despre acoperirea HLR pentru a sprijini luarea deciziilor bazate pe date. Acest endpoint vă ajută să analizați opțiunile de rutare HLR în timp real în rețelele mobile, să identificați cele mai eficiente căi pentru regiunile țintă și să configurați rutarea automată.

Rutele recomandate de GET /route se bazează pe datele de acoperire obținute aici. Datele de acoperire sunt disponibile și pe pagina acoperire rețea. Puteți personaliza în continuare harta de rutare și defini reguli în setările contului.

Vă recomandăm să vă familiarizați cu acest ghid pentru a interpreta rezultatele.

Cerere Răspuns de Succes Răspuns de Eroare Referință Statusuri

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

Parametri Cerere

Cheie	Tip	Descriere	Implicit	Obligatoriu
`countrycode`	string(2)	Un cod de țară ISO obligatoriu cu două litere utilizat pentru filtrarea rezultatelor, returnând doar înregistrările asociate cu țara specificată.	null	obligatoriu
`sample_size`	string	Un parametru opțional care specifică dimensiunea eșantionului. Valorile posibile sunt `LARGE`, `MEDIUM`, `SMALL`. Eșantioanele mai mari acoperă o perioadă mai lungă, eșantioanele mai mici acoperă o perioadă foarte recentă.	LARGE	opțional

{
   "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
            }
         ]
      }
   ]
}

Atribute Răspuns de Succes

Nume	Tip	Descriere	Anulabil
`name`	string	Numele țării selectate în limba engleză.	false
`countrycode`	string(2)	Codul de țară ISO cu două caractere al țării selectate.	false
`prefix`	string	Prefixul internațional de apelare al țării selectate.	false
`mccs`	string[]	O listă de MCC-uri (coduri mobile de țară) asociate cu țara selectată.	false
`carriers`	object[]	O listă de obiecte operator cu metrici de conectivitate specifice rutei.	false
`mno`	string	Numele operatorului de rețea mobilă în limba engleză.	false
`mccmnc`	string	MCCMNC-ul operatorului de rețea mobilă.	false
`mcc`	string	MCC-ul operatorului de rețea mobilă (cod mobil de țară).	false
`mnc`	string	MNC-ul operatorului de rețea mobilă (cod de rețea mobilă).	false
`routes`	object[]	O listă de rezultate de conectivitate specifice rutei.	false
`route`	string	Ruta la care se aplică informațiile de conectivitate.	false
`selected`	bool	Indică dacă aceasta este ruta selectată pentru rutarea automată.	false
`selection_confidence`	string	Nivelul de încredere cu care a fost selectată această rută, adică `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`. Conține null dacă aceasta nu este ruta selectată.	true
`n`	int	Numărul total de interogări din acest eșantion.	false
`CONNECTED`	int	Numărul de interogări HLR care au returnat statusul CONNECTED.	false
`CONNECTED_PCT`	float	Procentul de interogări HLR care au returnat statusul CONNECTED.	false
`ABSENT`	int	Numărul de interogări HLR care au returnat statusul ABSENT.	false
`ABSENT_PCT`	float	Procentul de interogări HLR care au returnat statusul ABSENT.	false
`INVALID_MSISDN`	int	Numărul de interogări HLR care au returnat statusul INVALID_MSISDN.	false
`INVALID_MSISDN_PCT`	float	Procentul de interogări HLR care au returnat statusul INVALID_MSISDN.	false
`UNDETERMINED`	int	Numărul de interogări HLR care au returnat statusul UNDETERMINED.	false
`UNDETERMINED_PCT`	float	Procentul de interogări HLR care au returnat statusul UNDETERMINED.	false

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

Parametri Răspuns Eroare

Nume	Tip	Descriere	Anulabil
`errors[]`	string[]	O listă de șiruri care explică eroarea.	false

Status	Descriere
CONNECTED	Numărul este valid, iar terminalul destinatar este conectat în prezent la rețeaua mobilă. Apelurile, SMS-urile și alte servicii ar trebui să ajungă cu succes la destinatar.
ABSENT	Numărul este valid, dar terminalul destinatar este fie oprit, fie temporar în afara acoperirii rețelei. Mesajele sau apelurile pot să nu fie livrate până când dispozitivul se reconectează la rețea.
INVALID_MSISDN	Numărul este invalid sau nu este alocat în prezent niciunui abonat în rețeaua mobilă. Apelurile și mesajele către acest număr vor eșua.
UNDETERMINED	Starea de conectivitate a numărului nu a putut fi determinată. Acest lucru se poate datora unui număr invalid, unui răspuns de eroare SS7 sau lipsei de conectivitate cu operatorul de rețea destinatar. Verificați codul de eroare și câmpul de descriere pentru diagnostice suplimentare.

Derulați în sus

GET/mnp-coverageprotejat

Acest endpoint returnează o listă de operatori de rețele mobile, împreună cu identificatorii MCCMNC corespunzători, care sunt în prezent suportați pentru interogări de portabilitate a numerelor mobile.

Cerere Răspuns de Succes Răspuns de Eroare

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

Parametri Cerere

Cheie	Tip	Descriere	Implicit	Obligatoriu
`countrycode`	string(2)	Un cod de țară ISO opțional din două litere, utilizat pentru a filtra rezultatele MCCMNC, returnând doar datele relevante pentru țara specificată.	null	opțional

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

Atribute Răspuns de Succes

Nume	Tip	Descriere	Anulabil
`items[]`	array	O listă de operatori de rețele mobile.	false
`country_name`	string	Numele țării în limba engleză.	false
`country_code`	string(2)	Un cod de țară ISO din două litere.	false
`mccmnc`	string(5\|6)	Un MCCMNC (combinație de cod de țară mobil și cod de rețea mobilă) din cinci sau șase caractere care identifică operatorul de rețea mobilă.	false
`mcc`	string(3)	Un MCC (cod de țară mobil) din trei caractere care reprezintă țara rețelei.	false
`mnc`	string(2\|3)	Un MNC (cod de rețea mobilă) din două sau trei caractere care reprezintă operatorul specific de rețea mobilă.	false
`brand`	string	Brandul comercial sub care operează această rețea.	true
`operator`	string	Denumirea legală a operatorului de rețea mobilă.	true

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

Parametri Răspuns Eroare

Nume	Tip	Descriere	Anulabil
`errors[]`	string[]	O listă de șiruri care explică eroarea.	false

Derulați în sus

GET/price-listprotejat

Acest endpoint returnează o listă de țări unde sunt disponibile doar interogări MNP, iar interogările HLR nu sunt disponibile pentru aceste destinații.

Cerere Răspuns de Succes Răspuns de Eroare

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

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

Atribute Răspuns de Succes

Nume	Tip	Descriere	Anulabil
`countries`	string[]	O listă de coduri de țară ISO cu două caractere.	false

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

Parametri Răspuns Eroare

Nume	Tip	Descriere	Anulabil
`errors[]`	string[]	O listă de șiruri care explică eroarea.	false

Derulați în sus

GET/mccmncsprotejat

Acest endpoint returnează o listă completă de operatori de rețele mobile împreună cu identificatorii MCCMNC corespunzători și informații contextuale suplimentare.

Cerere Răspuns de Succes Răspuns de Eroare

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

Parametri Cerere

Cheie	Tip	Descriere	Implicit	Obligatoriu
`countrycode`	string(2)	Un cod de țară ISO opțional format din două litere, utilizat pentru filtrarea rezultatelor MCCMNC, returnând doar înregistrările asociate cu țara specificată.	null	opțional

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

Atribute Răspuns de Succes

Nume	Tip	Descriere	Anulabil
`items`	object[]	O listă de operatori de rețele mobile.	false
`country_name`	string	Numele complet al țării în limba engleză.	false
`country_code`	string(2)	Un cod de țară ISO format din două litere care reprezintă țara operatorului mobil.	false
`mccmnc`	string(5\|6)	Un șir de cinci sau șase caractere reprezentând MCCMNC, care identifică în mod unic operatorul de rețea mobilă.	false
`mcc`	string(3)	Un cod de țară mobilă (MCC) format din trei caractere care identifică țara în care operează rețeaua mobilă.	false
`mnc`	string(2\|3)	Un cod de rețea mobilă (MNC) format din două sau trei caractere care specifică rețeaua mobilă în cadrul MCC-ului dat.	false
`brand`	string	Numele de brand comercial sub care operează rețeaua și este recunoscută de consumatori.	true
`operator`	string	Numele oficial al operatorului de rețea mobilă, de obicei entitatea juridică care gestionează rețeaua.	true
`parent_mccmnc`	string(5\|6)	Un șir de cinci sau șase caractere reprezentând MCCMNC-ul operatorului de rețea mobilă părinte, dacă există.	true

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

Parametri Răspuns Eroare

Nume	Tip	Descriere	Anulabil
`errors[]`	string[]	O listă de șiruri care explică eroarea.	false

Derulați în sus

GET/priceprotejat

Acest endpoint returnează prețul pentru o interogare HLR, MNP sau NT.

Cerere Răspuns de Succes Răspuns de Eroare

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

Parametri Cerere

Cheie	Tip	Descriere	Implicit	Obligatoriu
`msisdn`	string	Numărul de telefon pentru care se solicită prețul. În format internațional.	null	obligatoriu
`route_type`	string	Tipul de rută, adică `HLR`, `MNP`, `NT`.	null	obligatoriu
`route`	string(3)	Ruta pentru care trebuie calculat prețul. Implicit, se folosește ruta determinată de rutarea automată.	null	opțional

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

Atribute Răspuns de Succes

Nume	Tip	Descriere	Anulabil
`price`	object	Un obiect cu detalii de tarifare.	false
`amount`	string	Suma în EUR.	false
`msisdn`	string	MSISDN-ul pentru care se aplică acest preț.	false
`route_type`	string(2\|3)	Tipul de rută pentru care se aplică acest preț.	false
`route`	string(3)	Ruta pentru care se aplică acest preț.	false

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

Parametri Răspuns Eroare

Nume	Tip	Descriere	Anulabil
`errors[]`	string[]	O listă de șiruri care explică eroarea.	false

Derulați în sus

GET/price-listprotejat

Acest endpoint returnează tarifele din contul dumneavoastră.

Cerere Răspuns de Succes Răspuns de Eroare

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"
      }
   ]
}

Atribute Răspuns de Succes

Nume	Tip	Descriere	Anulabil
`pricing`	object[]	O listă de obiecte cu informații de tarifare.	false
`route`	string	Ruta la care se aplică această tarifare.	false
`countrycode`	string	Codul de țară ISO cu două caractere la care se aplică această tarifare pentru ruta corespunzătoare, dacă este cazul.	true
`countryname`	string	Numele țării în limba engleză corespunzător codului de țară, dacă este cazul.	true
`mccmnc`	string	MCCMNC la care se aplică această tarifare pentru ruta corespunzătoare, dacă este cazul. Suprascrie tarifarea la nivel de țară.	true
`cns`	string	Prefixul de apelare la care se aplică această tarifare pentru ruta corespunzătoare, dacă este cazul. Suprascrie tarifarea la nivel de țară și tarifarea la nivel MCCMNC.	true
`route_type`	string	Tipul de rută corespunzător, adică `HLR`, `MNP`, `NT`.	false
`route_type`	string	Prețul corespunzător în EUR.	false

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

Parametri Răspuns Eroare

Nume	Tip	Descriere	Anulabil
`errors[]`	string[]	O listă de șiruri care explică eroarea.	false

Derulați în sus

GET/balanceprotejat

Acest endpoint returnează soldul curent al contului dvs., permițându-vă să automatizați procese în funcție de starea creditului. Funcționează perfect cu notificările prin email pentru credit scăzut pe care le puteți configura în pagina de plăți.

Cerere Răspuns de Succes Răspuns de Eroare

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

{
    "balance":"1002.90"
}

Atribute Răspuns de Succes

Nume	Tip	Descriere	Anulabil
`balance`	string	Soldul curent al contului dvs. în EUR. O valoare zecimală de tip string.	false

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

Parametri Răspuns Eroare

Nume	Tip	Descriere	Anulabil
`errors[]`	string[]	O listă de șiruri care explică eroarea.	false

Derulați în sus

GET/pingpublic

Acest endpoint trimite o cerere ping către API, oferind o metodă simplă de testare a conexiunii dvs. la API-ul HLR Lookups.

Cerere Răspuns de Succes Răspuns de Eroare

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

{
    "success":true
}

Atribute Răspuns de Succes

Nume	Tip	Descriere	Anulabil
`success`	boolean	Indică faptul că cererea a fost procesată cu succes.	false

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

Parametri Răspuns Eroare

Nume	Tip	Descriere	Anulabil
`errors[]`	string[]	O listă de șiruri care explică eroarea.	false

Derulați în sus

GET/timepublic

Acest endpoint returnează un timestamp Unix reprezentând ora curentă pe serverul HLR Lookups. Utilizați-l pentru a sincroniza ceasul serverului dvs. atunci când generați semnătura Digest-Auth pentru autentificare, asigurându-vă că orice discrepanțe între ora serverului dvs. și ora serverului HLR Lookups sunt corectate.

Cerere Răspuns de Succes Răspuns de Eroare

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

{
    "time":1525898643
}

Atribute Răspuns de Succes

Nume	Tip	Descriere	Anulabil
`time`	integer	Timestamp Unix reprezentând ora curentă a serverului HLR Lookups.	false

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

Parametri Răspuns Eroare

Nume	Tip	Descriere	Anulabil
`errors[]`	string[]	O listă de șiruri care explică eroarea.	false

Derulați în sus

GET/auth-testprotejat

Acest endpoint servește ca test inițial pentru implementarea Basic-Auth sau, de preferință, Digest-Auth.

Cerere Basic Auth Cerere Digest Auth Răspuns de Succes Răspuns de Eroare

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

Header-e de cerere

Cheie	Tip	Descriere
`X-Basic`	string	Hash SHA256 al `YOUR_API_KEY:YOUR_API_SECRET`. Includeți simbolul două puncte (:) în hash.

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"

Header-e de cerere

Cheie	Tip	Descriere
`X-Digest-Key`	string	Cheia API HLR Lookups
`X-Digest-Signature`	string	Semnătură unică Digest-Auth (vezi autentificare)
`X-Digest-Timestamp`	integer	Timestamp Unix curent (vezi și `GET /time`)

{
    "success":true
}

Atribute Răspuns de Succes

Nume	Tip	Descriere	Anulabil
`success`	boolean	Indică faptul că cererea a fost procesată cu succes.	false

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

Parametri Răspuns Eroare

Nume	Tip	Descriere	Anulabil
`errors[]`	string[]	O listă de șiruri care explică eroarea.	false

Derulați în sus

Documentație API Vechi

Vă rugăm să rețineți că API-ul vechi este depreciat și va fi retras în viitor. Vă recomandăm insistent să treceți la ultima versiune cât mai curând posibil.

Dacă ați implementat API-ul nostru HLR Lookups între 2013 și începutul anului 2020, utilizați API-ul nostru vechi. Vă rugăm să consultați documentația API vechi în acest caz.

Documentație API Vechi

Documentație API

Primii pași

Interogări HLR

Interogări MNP

Interogări NT

Rutare

Prețuri

Instrumente

Primii pași

Utilizarea API-ului HLR Lookups

Exemplu de cerere

Exemplu de payload

Răspuns de Succes application/json

Servicii suplimentare de interogare

Interogări de portabilitate a numerelor mobile (MNP)

Interogări de detectare a tipului de număr (NT)

Kituri de dezvoltare software (SDK-uri)

Instrumente

Nu sunteți dezvoltator?

Autentificare

Cheie API și Secret API

HTTP Basic Auth

Recomandat: Header X-Basic cu SHA256

Cerere Basic Auth

Header-e de autentificare Basic

Exemplu de cod

Exemplu de cerere

Header-e de cerere

Construirea semnăturii

Componente semnătură Digest

Exemple de cod

Concepte

API de Interogare HLR Sincron

API HLR Lookup asincron

SDK-uri (Kituri de Dezvoltare Software)

SDK PHP

SDK NodeJS

SDK Ruby

POST/hlr-lookupprotejat

Payload

Parametri Cerere

Atribute Răspuns de Succes

Parametri Răspuns Eroare

POST/hlr-lookupsprotejat

Payload

Parametri Cerere

Atribute Răspuns de Succes

Parametri Răspuns Eroare

Procesarea Webhook-urilor

Autentificare

Exemplu de cod

Confirmarea Primirii

Payload Webhook

Atribute Payload Webhook

POST/mnp-lookupprotejat

Payload

Parametri Cerere

Atribute Răspuns de Succes

Parametri Răspuns Eroare

POST/mnp-lookupsprotejat

Payload

Parametri Cerere

Atribute Răspuns de Succes

Parametri Răspuns Eroare

Procesarea Webhook-urilor

Autentificare

Exemplu de cod

Confirmarea Primirii

Payload Webhook

Atribute Payload Webhook

POST/nt-lookupprotejat

Payload

Parametri Cerere

Atribute Răspuns de Succes

Parametri Răspuns Eroare

POST/nt-lookups protejat

Payload

Parametri Cerere

Atribute Răspuns de Succes

Parametri Răspuns Eroare