Fillimi

Infrastruktura globale e rrjetit celular funksionon në një sistem të njohur si rrjeti sinjalizues SS7. Ky rrjet lehtëson shkëmbimin e të dhënave të abonentëve, rutimin e thirrjeve, transmetimin e SMS-ve dhe përditësimet në kohë reale të statusit të lidhshmërisë celulare midis operatorëve. Çdo rrjet celular mban një Regjistër të Vendndodhjes Bazë (HLR) - një bazë të dhënash qendrore që ruan detaje thelbësore për abonentët e saj.

Teknologjia HLR Lookup mundëson bizneset të pyesin këto regjistrime dhe të marrin detaje të drejtpërdrejta të lidhshmërisë dhe rrjetit për çdo numër celular. Kjo përfshin nëse telefoni është i ndezur, në cilin rrjet është caktuar aktualisht, nëse është portuar, nëse numri është i vlefshëm apo i çaktivizuar, dhe nëse është në roaming.

API-ja HLR Lookups ofron qasje të qetë dhe në kohë reale në këto të dhëna, duke lejuar bizneset të verifikojnë numrat celularë, të optimizojnë rutimin dhe të përmirësojnë komunikimet me klientët. Kjo dokumentacion do t'ju udhëzojë nëpër integrimin e HLR Lookups në softuerin tuaj, duke mundësuar marrjen e automatizuar të inteligjencës celulare në kohë reale.

Përdorimi i API-së HLR Lookups

Ekzekutimi i pyetjeve HLR Lookup është i shpejtë, i sigurt dhe i drejtpërdrejtë. Pasi të jeni regjistruar dhe të keni marrë Çelësin tuaj API, mund të autentifikoheni dhe të filloni kërkime të menjëhershme me kërkesa të thjeshta HTTP POST, përmes POST /hlr-lookup. Alternativisht, mund të përpunoni grupe të mëdha të dhënash duke zgjedhur kërkesa të shpejta asinkrone API me rezultate të dërguara në serverin tuaj përmes webhook, siç shpjegohet në seksionin koncepte.

Shembull Kërkese

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"

Autentifikimi sigurohet përmes header-ave HTTP, dhe payload.json duhet të përmbajë (si minimum) objektin JSON të mëposhtëm:

Shembull Payload

{
   "msisdn": "+14156226819"
}

Pas ekzekutimit të suksesshëm, do të merrni një përgjigje që përmban detaje të lidhshmërisë në kohë reale për numrin celular të specifikuar.

Përgjigje e Suksesshme 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"
}

Për një analizë të plotë të atributeve të kërkesës dhe përgjigjes dhe statuseve të lidhshmërisë, shihni POST /hlr-lookup.

Shërbime Shtesë Kërkimi

Kërkim i Portabilitetit të Numrit Celular (MNP)

Përdorni kërkimet MNP për të përcaktuar pronësinë e rrjetit dhe detajet e portabilitetit pa pyetur lidhshmërinë në kohë reale. Nëse keni nevojë vetëm për MCCMNC të një numri, referojuni POST /mnp-lookup.

Kërkim i Zbulimit të Llojit të Numrit (NT)

Përcaktoni nëse një numër telefoni i përket një linje fikse, celulari, me tarifë premium, VoIP, pager ose gamave të tjera të planit të numërzimit me POST /nt-lookup.

Mjete Zhvillimi Softuerësh (SDK)

API-ja HLR Lookups funksionon me çdo klient REST në çdo gjuhë programimi dhe kemi publikuar SDK për PHP, Ruby dhe NodeJS në GitHub tonë për t'ju ndihmuar të filloni shpejt.

Mjete

Për të siguruar një përvojë të qetë zhvillimi, ofrojmë një grup gjithëpërfshirës mjetesh, duke përfshirë monitorimin e kërkesave API dhe webhook në shfletues, listën e bardhë të adresave IP, opsione të fuqishme autentifikimi dhe një endpoint testimi autentifikimi.

Nuk Jeni Zhvillues?

Kërkesat HLR Lookups dhe Portabilitetit të Numrit mund të kryhen pa asnjë kodim. Mësoni më shumë për klientin tonë të ndërmarrjes në web dhe veçoritë e raportimit të bazuara në shfletues.

Autentifikimi

Për të siguruar sigurinë dhe kontrollin e duhur të aksesit, shumica e kërkesave në API-në e HLR Lookups kërkojnë autentifikim. Pikat fundore kategorizohen si publike ose të mbrojtura. Kur aksesoni një pikë fundore të mbrojtur, kërkesa juaj duhet të autentifikohet duke përdorur çelësin dhe sekretin tuaj API përmes metodës Digest-Auth ose Basic-Auth. Digest-Auth është opsioni më i sigurt dhe rekomandohet fuqimisht. Përdorni pikën fundore GET /auth-test për të verifikuar konfigurimin tuaj të autentifikimit.

Çelësi API dhe Sekreti API

Merrni çelësin dhe sekretin tuaj API nga faqja e Cilësimeve të API. Gjithashtu mund të konfiguroni metodën tuaj të preferuar të autentifikimit dhe të aktivizoni listën e bardhë të adresave IP për siguri të përmirësuar. Nëse dyshoni se sekreti juaj API është kompromentuar, mund të gjeneroni një të ri në çdo kohë.

Basic Auth Digest Auth Lista e Lejuar IP

Autentifikimi Standard Basic është i lehtë për t'u implementuar dhe mbështetet gjerësisht. Mund të autentifikoheni duke kaluar çelësin dhe sekretin tuaj API si një çift user:pass në kërkesën HTTP.

HTTP Basic Auth

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

Kjo dërgon një header Authorization:

Authorization: Basic BASE64(YOUR_API_KEY:YOUR_API_SECRET)

E Rekomanduar: Header X-Basic me SHA256

Për siguri të përmirësuar, mund të dërgoni një hash SHA256 të kredencialeve tuaja në vend që t'i transmetoni direkt si base64. Për të përdorur këtë metodë, llogaritni hash-in e çiftit tuaj YOUR_API_KEY:YOUR_API_SECRET dhe dërgojeni përmes header-it X-Basic:

Kërkesë Basic Auth

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

Header-at e Autentifikimit Basic

Çelësi	Lloji	Përshkrimi
`X-Basic`	string	Hash SHA256 i `YOUR_API_KEY:YOUR_API_SECRET`. Përfshini simbolin e pikës së dy (:) në hash.	i detyrueshëm

Shembull Kodi

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

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

Digest-Auth është metoda e rekomandueshme për të siguruar aksesin në pikat fundore të mbrojtura të API-së HLR Lookup. Çdo kërkesë duhet të përfshijë header-at e mëposhtëm: X-Digest-Key, X-Digest-Signature dhe X-Digest-Timestamp, të cilët shpjegohen më poshtë.

Shembull Kërkese

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-at e Kërkesës

Çelësi	Lloji	Përshkrimi
`X-Digest-Key`	string	Çelësi juaj unik i API-së HLR Lookups.	i detyrueshëm
`X-Digest-Signature`	string	Një nënshkrim unik autentifikimi (shihni më poshtë).	i detyrueshëm
`X-Digest-Timestamp`	integer	Timestamp aktual Unix (shihni gjithashtu `GET /time`).	i detyrueshëm

Krijimi i Nënshkrimit

X-Digest-Signature krijohet duke përdorur një hash SHA256 HMAC, me sekretin tuaj API si çelës i përbashkët.

Vargu që do të hash-ohet strukturohet si më poshtë:

ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY

Simboli . përfaqëson bashkimin e vargut.

Komponentët e Nënshkrimit Digest

Komponenti	Lloji	Përshkrimi
`ENDPOINT_PATH`	string	Pika fundore e kërkuar API, p.sh., `/auth-test` me shkronja të vogla.
`UNIX_TIMESTAMP`	integer	Timestamp aktual Unix (duhet të jetë brenda 30 sekondave). Shihni `GET /time`.
`REQUEST_METHOD`	string	Metoda HTTP e përdorur, p.sh., `POST` ose `GET`.
`REQUEST_BODY`	string	Të dhënat e trupit të kërkesës. Vendosni në `null` për kërkesat `GET`.

Shembuj Kodi

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)

Lëviz Lart

Koncepte

Implementimi i kërkimeve HLR në çdo gjuhë programimi ose sistem përmes API-së tonë HTTP REST është i drejtpërdrejtë dhe efikas. Me një proces të thjeshtë integrimi, mund të filloni të pyesni rrjetet mobile në kohë reale për njohuri të menjëhershme mbi vlefshmërinë e numrit të telefonit, statusin e lidhjes dhe detajet e rutimit.

Zgjedhja e API-së së përshtatshme varet nga rasti juaj specifik i përdorimit. Nëse kërkoni rezultate kërkimi në kohë reale për aplikacione si telefonia VoIP, zbulimi i mashtrimeve ose rutimi i SMS-ve, API-ja sinkrone është zgjedhja më e mirë. Megjithatë, nëse rasti juaj i përdorimit përfshin përpunimin me volum të lartë, kërkime masive ose verifikimin e të dhënave në shkallë të gjerë, API-ja asinkrone ofron performancë të optimizuar me efikasitet të gjerësisë së brezit dhe aftësi kërkimesh në grupe.

Konfiguroni API-në për të përdorur një nga opsionet tona të personalizuara të rutimit për të optimizuar shpejtësinë, saktësinë dhe efikasitetin e kostos. Gjithashtu mund të ruani rezultatet e kërkimeve në depozita për shkarkime të lehta raportesh CSV dhe JSON, si dhe analiza të avancuara përmes ndërfaqes web.

API-ja Sinkrone e Kërkimit HLR

Pika fundore POST /hlr-lookup përpunon një numër telefoni celular (MSISDN) për kërkesë dhe kthen rezultatet menjëherë në trupin e përgjigjes HTTP. Rezultatet janë të formatuara si JSON dhe janë ideale për aplikacione në kohë reale, duke përfshirë validimin e numrit celular, rutimin e thirrjeve dhe dorëzimin e mesazheve SMS.

Një thirrje API sinkrone përbëhet nga një kërkesë dhe përgjigje e drejtpërdrejtë HTTP. Sistemi juaj dërgon një MSISDN të vetëm (numër celular) për kërkesë dhe merr një përgjigje të menjëhershme që përmban rezultate kërkimi HLR në kohë reale në format JSON. Kjo API është e optimizuar për rastet e përdorimit që kërkojnë verifikim të menjëhershëm dhe kontrolle lidhjeje, të tilla si zbulimi i mashtrimeve, rutimi i thirrjeve VoIP dhe optimizimi i gateway-it SMS.

API për Kërkime HLR Asinkrone

Pika fundore POST /hlr-lookups është projektuar për përpunimin masiv dhe me volum të lartë, duke ju lejuar të dërgoni deri në 1,000 MSISDN për kërkesë. Në vend që të kthejë rezultate menjëherë, kjo API përdor webhook-e të automatizuara për të dërguar rezultatet në mënyrë progresive në serverin tuaj. Rezultatet e kërkimit kthehen si objekte JSON përmes thirrjeve HTTP POST.

API-ja asinkrone është e optimizuar për shpejtësi, efikasitet dhe shkallëzueshmëri. Ajo eliminon problemet e vonesës së rrjetit të lidhura me thirrjet sinkrone, duke e bërë ideale për bizneset që kanë nevojë për kërkime me kapacitet të lartë. Sistemi juaj dërgon deri në 1,000 MSISDN për kërkesë, dhe platforma jonë i përpunon ato në paralel, duke dorëzuar rezultatet në serverin tuaj përmes webhook-eve HTTP në grupe deri në 1,000 rezultate për thirrje.

SDK-të (Kitet e Zhvillimit të Softuerit)

Kitet tona të Zhvillimit të Softuerit (SDK) për PHP, NodeJS dhe Ruby thjeshtojnë procesin e integrimit, duke ju mundësuar të lidheni me API-në e HLR Lookups në mënyrë efikase dhe me përpjekje minimale.

Këto SDK ofrojnë funksione të parakonstruara, menaxhim të autentifikimit dhe shablone të strukturuara për kërkesat API, duke reduktuar kohën e zhvillimit dhe duke siguruar praktikat më të mira.

Eksploroni listën tonë të plotë të SDK-ve të disponueshme në GitHub dhe filloni integrimin sot.

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

Shiko në 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   }

Shiko në 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)

Shiko në GitHub README.md

Lëviz Lart

POST/hlr-lookupe mbrojtur

Kryen një kërkesë HLR sinkrone, duke ofruar të dhëna në kohë reale për lidhshmërinë dhe portabilitetin e telefonave celularë drejtpërdrejt nga operatorët e rrjetit. Ky endpoint është ideal për skenarë me trafik të drejtpërdrejtë ku aplikacionet e ndjeshme ndaj kohës kërkojnë verifikim të menjëhershëm nëse një numër telefoni është aktualisht i arritshëm (i lidhur) ose i padisponueshëm (i fikur). Për më tepër, ndihmon në dallimin e numrave aktivë nga ata të pavlefshëm, të panjohur ose të rremë.

Për përpunimin masiv të grupeve të mëdha të dhënash që nuk kërkojnë rezultate të menjëhershme, konsideroni përdorimin e POST /hlr-lookups asinkron, i cili është optimizuar për përpunim me shpejtësi të lartë në grupe.

Nëse fokusi juaj kryesor është marrja e të dhënave të portabilitetit të numrave celularë (MCCMNC) dhe nuk keni nevojë për statusin e lidhshmërisë në kohë reale, POST /mnp-lookup ofron një alternativë ekonomike për pyetjet e portabilitetit të numrave celularë.

Kërkesë Përgjigje e Suksesshme Përgjigje Gabimi Referenca e Statusit

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

Ngarkesa

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

Parametrat e Kërkesës

Çelësi	Lloji	Përshkrimi	Parazgjedhur	I detyrueshëm
`msisdn`	string	Numri i telefonit celular (MSISDN) që do të kërkohet, dhënë në format ndërkombëtar (p.sh., +14156226819 ose 0014156226819). Kodet e shteteve duhet të përfshihen.	null	i detyrueshëm
`route`	string(3)	Një identifikues opsional me tre karaktere që specifikon rrugën për këtë kërkesë. Vendoseni në `null` ose lëreni këtë parametër për të aplikuar hartën tuaj të personalizuar të rrugëzimit ose për të lejuar sistemin tonë të përcaktojë automatikisht rrugën më të mirë për këtë kërkesë.	null	opsionale
`storage`	string	Një identifikues opsional ruajtjeje që specifikon raportin ku rezultatet do të ruhen për rishikim manual, analitikë dhe raportim. Sistemi automatikisht shton një vulë kohore me muajin aktual. Nëse lëhet jashtë ose vendoset në `null`, sistemi do të grupojë automatikisht rezultatet sipas muajit për qëllime raportimi.	null	opsionale

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

Atributet e Përgjigjes së Suksesshme

Emri	Lloji	Përshkrimi	I pranueshmë si null
`id`	string(12)	Një identifikues unik i caktuar për këtë kërkesë verifikimi.	false
`msisdn`	string	Numri i telefonit celular që po verifikohet, i formatuar në format ndërkombëtar (p.sh., +14156226819 ose 0014156226819).	false
`connectivity_status`	string	Tregon nëse statusi i lidhshmërisë së numrit është marrë me sukses. Vlerat e mundshme: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` , ose `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Një kod pesë ose gjashtë shifror Mobile Country Code (MCC) dhe Mobile Network Code (MNC) që identifikon rrjetin aktualisht të shoqëruar me numrin e telefonit.	true
`mcc`	string(3)	Një kod tre shifror Mobile Country Code (MCC) që identifikon vendin ku është regjistruar numri i telefonit.	true
`mnc`	string(2\|3)	Një kod dy ose tre shifror Mobile Network Code (MNC) që identifikon rrjetin specifik të cilit i përket numri i telefonit.	true
`imsi`	string	International Mobile Subscriber Identity (IMSI), një identifikues unik për kartën SIM të shoqëruar me këtë numër. Disponueshmëria varet nga konfigurimi i rrjetit.	true
`msin`	string(10)	Mobile Subscription Identification Number (MSIN) brenda bazës së të dhënave të operatorit celular. Disponueshmëria varet nga konfigurimi i rrjetit.	true
`msc`	string(12)	Mobile Switching Center (MSC) që aktualisht menaxhon komunikimet e këtij abonenti. Disponueshmëria varet nga konfigurimi i rrjetit.	true
`original_network_name`	string	Emri i operatorit origjinal (vendor) të rrjetit të shoqëruar me këtë numër.	true
`original_country_name`	string	Emri i plotë i vendit ku numri i telefonit celular është regjistruar fillimisht, i dhënë në anglisht.	true
`original_country_code`	string(2)	Kodi ISO dy karakteresh i vendit që përfaqëson vendin ku numri i telefonit është caktuar fillimisht.	true
`original_country_prefix`	string	Kodi ndërkombëtar i thirrjes (kodi i thirrjes së vendit) që korrespondon me vendin origjinal të numrit të telefonit celular.	true
`is_ported`	boolean	Tregon nëse numri celular është transferuar nga rrjeti i tij origjinal te një operator tjetër.	true
`ported_network_name`	string	Emri i operatorit të rrjetit te i cili numri celular është transferuar, nëse është e zbatueshme.	true
`ported_country_name`	string	Emri i vendit ku numri celular është transferuar, nëse është e zbatueshme.	true
`ported_country_code`	string(2)	Kodi ISO dy karakteresh i vendit që përfaqëson vendin ku numri celular është transferuar, nëse është e zbatueshme.	true
`ported_country_prefix`	string	Kodi ndërkombëtar i thirrjes (kodi i thirrjes së vendit) për vendin ku numri celular është transferuar, nëse është e zbatueshme.	true
`is_roaming`	boolean	Tregon nëse numri celular është aktualisht në roaming në një rrjet të huaj. Disponueshmëria e statusit të roaming-ut varet nga operatori i rrjetit celular.	true
`roaming_network_name`	string	Emri i rrjetit në të cilin numri celular është aktualisht në roaming, nëse është e zbatueshme.	true
`roaming_country_name`	string	Emri i vendit ku numri celular është aktualisht në roaming, nëse është e zbatueshme.	true
`roaming_country_code`	string(2)	Kodi ISO dy karakteresh i vendit ku numri celular është aktualisht në roaming, nëse është e zbatueshme.	true
`roaming_country_prefix`	string	Kodi ndërkombëtar i thirrjes (kodi i thirrjes së vendit) i vendit ku numri celular është aktualisht në roaming, nëse është e zbatueshme.	true
`cost`	string	Një vlerë dhjetore e paraqitur si string, që tregon koston e verifikimit në EUR.	true
`timestamp`	string	Një vulë kohore e formatuar sipas W3C duke përfshirë zonën kohore, që specifikon kur është përfunduar verifikimi.	true
`storage`	string	Emri i hapësirës ruajtëse ku janë ruajtur rezultatet e verifikimit. Kjo korrespondon me emrat e raporteve dhe shkarkimet CSV të disponueshme përmes ndërfaqes web.	true
`route`	string(3)	Një identifikues tre karakteresh që tregon metodën e drejtimit të përdorur për këtë kërkesë verifikimi.	true
`processing_status`	string	Rezultati i procesimit të verifikimit. Vlerat e mundshme: `COMPLETED` (i suksesshëm), `REJECTED` (rrjeti i paarritshëm, nuk është aplikuar tarifë), ose `FAILED` (ndodhi gabim gjatë procesimit).	false
`error_code`	integer	Një kod gabimi i brendshëm opsional që ofron informacion shtesë diagnostikues për mbështetjen e klientit.	true
`error_description`	string	Një shpjegim i shkurtër i kodit të dhënë të gabimit (nëse ka) në tekst të thjeshtë në anglisht.	true
`data_source`	string	Burimi i të dhënave të përdorur për këtë kërkesë. Vlerat e mundshme: `LIVE_HLR` (pyetje HLR në kohë reale) ose `MNP_DB` (bazë të dhënash statike e portabilitetit të numrit celular). Referojuni opsioneve të drejtimit për detaje.	false
`routing_instruction`	string	Një string i ndarë me dy pika që përshkruan udhëzimin e drejtimit të përdorur në kërkesë. Komponenti i parë është `STATIC` kur keni specifikuar një rrugë ose `AUTO` për drejtim automatik; komponenti i dytë është identifikuesi i rrugës, dhe për kërkesat e drejtimit automatik një komponent i tretë tregon origjinën në bazë të së cilës është marrë vendimi i drejtimit (p.sh. `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."
    ]
}

Parametrat e Përgjigjes së Gabimit

Emri	Lloji	Përshkrimi	I pranueshmë si null
`errors[]`	string[]	Një listë tekstesh që shpjegojnë gabimin.	false

Statusi	Përshkrimi
CONNECTED	Numri është i vlefshëm dhe pajisja e destinacionit është aktualisht e lidhur me rrjetin celular. Thirrjet, SMS-të dhe shërbimet e tjera duhet të arrijnë me sukses tek marrësi.
ABSENT	Numri është i vlefshëm, por pajisja e destinacionit është ose e fikur ose përkohësisht jashtë mbulimit të rrjetit. Mesazhet ose thirrjet mund të mos dërgohen derisa pajisja të rilidhet me rrjetin.
INVALID_MSISDN	Numri është i pavlefshëm ose nuk është aktualisht i caktuar për asnjë abonet në rrjetin celular. Thirrjet dhe mesazhet drejt këtij numri do të dështojnë.
UNDETERMINED	Statusi i lidhshmërisë së numrit nuk mund të përcaktohej. Kjo mund të jetë për shkak të një numri të pavlefshëm, përgjigje gabimi SS7, ose mungesë lidhshmërie me operatorin e rrjetit të destinacionit. Kontrolloni kodin e gabimit dhe fushën e përshkrimit për diagnostikime shtesë.

Lëviz Lart

POST/hlr-lookupse mbrojtur

Nis një grup kërkimesh HLR asinkrone, duke marrë të dhëna të drejtpërdrejta mbi lidhshmërinë dhe portabilitetin e telefonave celularë nga operatorët e rrjetit. Rezultatet dërgohen përmes webhook-ëve në serverin tuaj. Kjo metodë është optimizuar për përpunimin e vëllimeve të mëdha numrash që nuk kërkojnë përgjigje të menjëhershme, si pastrimi dhe verifikimi i bazës së të dhënave. Për aplikacione në kohë reale si rutimi i thirrjeve ose dërgimi i SMS, konsideroni përdorimin e endpoint-it POST /hlr-lookup në vend të kësaj.

Ky endpoint është ideal për përpunimin masiv kur qëllimi është identifikimi i numrave telefonikë që janë aktualisht të arritshëm (të lidhur) ose të padisponueshëm (telefoni i fikur), duke filtruar numrat e pavlefshëm, të pacaktuar ose të rremë. Përveç kësaj, ofron statusin e drejtpërdrejtë të portabilitetit (MCCMNC) së bashku me detajet e lidhshmërisë.

Para përdorimit të këtij endpoint, sigurohuni që një URL webhook është konfiguruar për të marrë rezultatet e kërkimeve në mënyrë asinkrone. Mund ta konfiguroni këtë në cilësimet e API.

Kërkesë Përgjigje e Suksesshme Përgjigje Gabimi Webhooks Referenca e Statusit

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

Ngarkesa

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

Parametrat e Kërkesës

Çelësi	Lloji	Përshkrimi	Parazgjedhur	I detyrueshëm
`msisdns`	array	Një listë numrash telefonash celularë (MSISDN) në format ndërkombëtar (p.sh. +14156226819 ose 0014156226819). Mund të përfshini deri në 1000 numra për kërkesë.	null	i detyrueshëm
`route`	string(3)	Një identifikues opsional me tre karaktere që specifikon rrugën për këtë kërkesë. Vendoseni në `null` ose lëreni këtë parametër për të aplikuar hartën tuaj të personalizuar të rrugëzimit ose për të lejuar sistemin tonë të përcaktojë automatikisht rrugën më të mirë për këtë kërkesë.	null	opsionale
`storage`	string	Një identifikues opsional ruajtjeje që specifikon raportin ku rezultatet do të ruhen për rishikim manual, analitikë dhe raportim. Sistemi automatikisht shton një vulë kohore me muajin aktual. Nëse lëhet jashtë ose vendoset në `null`, sistemi do të grupojë automatikisht rezultatet sipas muajit për qëllime raportimi.	null	opsionale

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

Atributet e Përgjigjes së Suksesshme

Emri	Lloji	Përshkrimi	I pranueshmë si null
`accepted`	array	Një listë objektesh që përmbajnë identifikues unikë dhe MSISDN që janë pranuar për përpunim.	false
`accepted_count`	integer	Numri total i MSISDN-ve të pranuara me sukses për përpunim.	false
`rejected`	array	Një listë objektesh që përmbajnë identifikues unikë dhe MSISDN që janë refuzuar për përpunim, zakonisht për shkak të numrave të pavlefshëm. Nuk aplikohet tarifë për hyrjet e refuzuara.	false
`rejected_count`	integer	Numri total i MSISDN-ve të refuzuara për shkak të gabimeve të validimit.	false
`total_count`	integer	Numri total i MSISDN-ve të pranuara dhe të refuzuara që janë dorëzuar për përpunim.	false
`cost`	string	Një vlerë dhjetore e paraqitur si string, që tregon koston totale në EUR për kërkesat e pranuara.	false
`storage`	string	Emri i hapësirës ruajtëse ku shtohen rezultatet e kërkimeve, të përdorura për raportim dhe shkarkime CSV përmes ndërfaqes web.	false
`route`	string(3\|4)	Një identifikues tre ose katër karakteresh që specifikon rrugën e përdorur për këtë kërkesë kërkimi. Përmban AUTO nëse është kërkuar rutim automatik bazuar në numër.	false
`webhook_urls`	array	URL-të e webhook-ëve të konfiguruar në cilësimet e API. Rezultatet dërgohen këtu.	false

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

Parametrat e Përgjigjes së Gabimit

Emri	Lloji	Përshkrimi	I pranueshmë si null
`errors[]`	string[]	Një listë tekstesh që shpjegojnë gabimin.	false

Përpunimi i Webhook-ave

Pasi të paraqitet, platforma jonë fillon përpunimin e numrave të telefonit të dhënë dhe dërgon rezultatet në URL-në e webhook-ut të specifikuar më parë në serverin tuaj. Rezultatet transmetohen si një kërkesë HTTP POST me një objekt JSON në trupin e kërkesës.

Autentifikimi

Autentifikoni webhook-un duke kontrolluar header-in HTTP X-Signatures.

Header-i X-Signatures përmban një listë nënshkrimesh të ndara me pikëpresje. Çdo nënshkrim në listë gjenerohet duke përdorur një nga sekretet API të konfiguruar në llogarinë tuaj. Për të verifikuar webhook-un, gjeneroni një hash SHA-256 duke përdorur çelësin tuaj API, sekretin dhe trupin e papërpunuar HTTP - më pas krahasojeni me nënshkrimet në listë.

Një përputhje konfirmon që kërkesa është autentike dhe e nënshkruar me një sekret që ju kontrolloni.

Shembull Kodi

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

Kërkesa është e vlefshme nëse ndonjë nga nënshkrimet e dhëna në header barazohet me një hash SHA256 të llogaritur mbi vargun e bashkuar të çelësit tuaj API, sekretit dhe trupit HTTP.

Konfirmimi i Marrjes

Pritet që serveri juaj të përgjigjet me një kod statusi HTTP 200 OK për të konfirmuar marrjen e suksesshme. Nëse kthehet ndonjë kod tjetër përgjigjeje, ndodh një timeout (10 sekonda), ose lind ndonjë problem tjetër dërgimi, sistemi do të riprovoj automatikisht webhook-un pas një minute. Nëse kërkesa vazhdon të dështojë, riprovimet do të ndjekin një strategji eksponenciale backoff, me përpjekje të mëvonshme pas 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minutash.

Ky mekanizëm riprovimi siguron besueshmëri maksimale në dërgimin e rezultateve të kërkimit në infrastrukturën tuaj. Ai minimizon rrezikun e humbjes së të dhënave për shkak të problemeve të përkohshme të rrjetit ose ndërprerjeve të serverit.

Ngarkesa e Webhook-ut

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

Atributet e Payload të Webhook

Objekti JSON përmban një atribut type => HLR së bashku me një atribut results që përfshin një listë objektesh kërkimi, siç dokumentohet më poshtë.

Emri	Lloji	Përshkrimi	I pranueshmë si null
`id`	string(12)	Një identifikues unik i caktuar për këtë kërkesë verifikimi.	false
`msisdn`	string	Numri i telefonit celular që po verifikohet, i formatuar në format ndërkombëtar (p.sh., +14156226819 ose 0014156226819).	false
`connectivity_status`	string	Tregon nëse statusi i lidhshmërisë së numrit është marrë me sukses. Vlerat e mundshme: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` , ose `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Një kod pesë ose gjashtë shifror Mobile Country Code (MCC) dhe Mobile Network Code (MNC) që identifikon rrjetin aktualisht të shoqëruar me numrin e telefonit.	true
`mcc`	string(3)	Një kod tre shifror Mobile Country Code (MCC) që identifikon vendin ku është regjistruar numri i telefonit.	true
`mnc`	string(2\|3)	Një kod dy ose tre shifror Mobile Network Code (MNC) që identifikon rrjetin specifik të cilit i përket numri i telefonit.	true
`imsi`	string	International Mobile Subscriber Identity (IMSI), një identifikues unik për kartën SIM të shoqëruar me këtë numër. Disponueshmëria varet nga konfigurimi i rrjetit.	true
`msin`	string(10)	Mobile Subscription Identification Number (MSIN) brenda bazës së të dhënave të operatorit celular. Disponueshmëria varet nga konfigurimi i rrjetit.	true
`msc`	string(12)	Mobile Switching Center (MSC) që aktualisht menaxhon komunikimet e këtij abonenti. Disponueshmëria varet nga konfigurimi i rrjetit.	true
`original_network_name`	string	Emri i operatorit origjinal (vendor) të rrjetit të shoqëruar me këtë numër.	true
`original_country_name`	string	Emri i plotë i vendit ku numri i telefonit celular është regjistruar fillimisht, i dhënë në anglisht.	true
`original_country_code`	string(2)	Kodi ISO dy karakteresh i vendit që përfaqëson vendin ku numri i telefonit është caktuar fillimisht.	true
`original_country_prefix`	string	Kodi ndërkombëtar i thirrjes (kodi i thirrjes së vendit) që korrespondon me vendin origjinal të numrit të telefonit celular.	true
`is_ported`	boolean	Tregon nëse numri celular është transferuar nga rrjeti i tij origjinal te një operator tjetër.	true
`ported_network_name`	string	Emri i operatorit të rrjetit te i cili numri celular është transferuar, nëse është e zbatueshme.	true
`ported_country_name`	string	Emri i vendit ku numri celular është transferuar, nëse është e zbatueshme.	true
`ported_country_code`	string(2)	Kodi ISO dy karakteresh i vendit që përfaqëson vendin ku numri celular është transferuar, nëse është e zbatueshme.	true
`ported_country_prefix`	string	Kodi ndërkombëtar i thirrjes (kodi i thirrjes së vendit) për vendin ku numri celular është transferuar, nëse është e zbatueshme.	true
`is_roaming`	boolean	Tregon nëse numri celular është aktualisht në roaming në një rrjet të huaj. Disponueshmëria e statusit të roaming-ut varet nga operatori i rrjetit celular.	true
`roaming_network_name`	string	Emri i rrjetit në të cilin numri celular është aktualisht në roaming, nëse është e zbatueshme.	true
`roaming_country_name`	string	Emri i vendit ku numri celular është aktualisht në roaming, nëse është e zbatueshme.	true
`roaming_country_code`	string(2)	Kodi ISO dy karakteresh i vendit ku numri celular është aktualisht në roaming, nëse është e zbatueshme.	true
`roaming_country_prefix`	string	Kodi ndërkombëtar i thirrjes (kodi i thirrjes së vendit) i vendit ku numri celular është aktualisht në roaming, nëse është e zbatueshme.	true
`cost`	string	Një vlerë dhjetore e paraqitur si string, që tregon koston e verifikimit në EUR.	true
`timestamp`	string	Një vulë kohore e formatuar sipas W3C duke përfshirë zonën kohore, që specifikon kur është përfunduar verifikimi.	true
`storage`	string	Emri i hapësirës ruajtëse ku janë ruajtur rezultatet e verifikimit. Kjo korrespondon me emrat e raporteve dhe shkarkimet CSV të disponueshme përmes ndërfaqes web.	true
`route`	string(3)	Një identifikues tre karakteresh që tregon metodën e drejtimit të përdorur për këtë kërkesë verifikimi.	true
`processing_status`	string	Rezultati i procesimit të verifikimit. Vlerat e mundshme: `COMPLETED` (i suksesshëm), `REJECTED` (rrjeti i paarritshëm, nuk është aplikuar tarifë), ose `FAILED` (ndodhi gabim gjatë procesimit).	false
`error_code`	integer	Një kod gabimi i brendshëm opsional që ofron informacion shtesë diagnostikues për mbështetjen e klientit.	true
`error_description`	string	Një shpjegim i shkurtër i kodit të dhënë të gabimit (nëse ka) në tekst të thjeshtë në anglisht.	true
`data_source`	string	Burimi i të dhënave të përdorur për këtë kërkesë. Vlerat e mundshme: `LIVE_HLR` (pyetje HLR në kohë reale) ose `MNP_DB` (bazë të dhënash statike e portabilitetit të numrit celular). Referojuni opsioneve të drejtimit për detaje.	false
`routing_instruction`	string	Një string i ndarë me dy pika që përshkruan udhëzimin e drejtimit të përdorur në kërkesë. Komponenti i parë është `STATIC` kur keni specifikuar një rrugë ose `AUTO` për drejtim automatik; komponenti i dytë është identifikuesi i rrugës, dhe për kërkesat e drejtimit automatik një komponent i tretë tregon origjinën në bazë të së cilës është marrë vendimi i drejtimit (p.sh. `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

Statusi	Përshkrimi
CONNECTED	Numri është i vlefshëm dhe pajisja e destinacionit është aktualisht e lidhur me rrjetin celular. Thirrjet, SMS-të dhe shërbimet e tjera duhet të arrijnë me sukses tek marrësi.
ABSENT	Numri është i vlefshëm, por pajisja e destinacionit është ose e fikur ose përkohësisht jashtë mbulimit të rrjetit. Mesazhet ose thirrjet mund të mos dërgohen derisa pajisja të rilidhet me rrjetin.
INVALID_MSISDN	Numri është i pavlefshëm ose nuk është aktualisht i caktuar për asnjë abonet në rrjetin celular. Thirrjet dhe mesazhet drejt këtij numri do të dështojnë.
UNDETERMINED	Statusi i lidhshmërisë së numrit nuk mund të përcaktohej. Kjo mund të jetë për shkak të një numri të pavlefshëm, përgjigje gabimi SS7, ose mungesë lidhshmërie me operatorin e rrjetit të destinacionit. Kontrolloni kodin e gabimit dhe fushën e përshkrimit për diagnostikime shtesë.

Lëviz Lart

POST/mnp-lookupe mbrojtur

Kryen një kërkesë MNP sinkrone dhe ofron informacion mbi portabilitetin e numrave celularë dhe rrjetin. Ky endpoint është i përshtatshëm nëse qëllimi juaj kryesor është të nxirrni MCCMNC aktual të një numri celular të caktuar dhe të identifikoni rrjetet origjinale dhe aktuale në kohë reale.

Për përpunimin masiv të grupeve të mëdha të dhënash që nuk kërkojnë rezultate të menjëhershme, konsideroni përdorimin e POST /mnp-lookups asinkron, i cili është optimizuar për përpunim me shpejtësi të lartë në grupe.

Kërkesat MNP përcaktojnë në mënyrë të besueshme informacionin mbi portabilitetin dhe rrjetin, por nuk tregojnë nëse telefoni celular i synuar është aktualisht i lidhur me një rrjet dhe i arritshëm. Për të nxjerrë informacion mbi lidhshmërinë në kohë reale, ju lutemi përdorni endpoint-in POST /hlr-lookup.

Kërkesë Përgjigje e Suksesshme Përgjigje Gabimi

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

Ngarkesa

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

Parametrat e Kërkesës

Çelësi	Lloji	Përshkrimi	Parazgjedhur	I detyrueshëm
`msisdn`	string	Numri i telefonit celular (MSISDN) që do të kërkohet, dhënë në format ndërkombëtar (p.sh., +14156226819 ose 0014156226819). Kodet e shteteve duhet të përfshihen.	null	i detyrueshëm
`route`	string(3)	Një identifikues opsional me tre karaktere që specifikon rrugën për këtë kërkesë. Vendoseni në `null` ose lëreni këtë parametër për të aplikuar hartën tuaj të personalizuar të rrugëzimit ose për të lejuar sistemin tonë të përcaktojë automatikisht rrugën më të mirë për këtë kërkesë.	null	opsionale
`storage`	string	Një identifikues opsional ruajtjeje që specifikon raportin ku rezultatet do të ruhen për rishikim manual, analitikë dhe raportim. Sistemi automatikisht shton një vulë kohore me muajin aktual. Nëse lëhet jashtë ose vendoset në `null`, sistemi do të grupojë automatikisht rezultatet sipas muajit për qëllime raportimi.	null	opsionale

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

Atributet e Përgjigjes së Suksesshme

Emri	Lloji	Përshkrimi	I pranueshmë si null
`id`	string(12)	Një identifikues unik me 12 karaktere për këtë kërkesë kontrolli.	false
`msisdn`	string	Numri i telefonit celular i vlerësuar në këtë kërkesë kontrolli.	false
`query_status`	string	Tregon nëse marrja e informacionit të portabilitetit dhe rrjetit ishte e suksesshme. Vlerat e mundshme janë `OK` ose `FAILED`.	false
`mccmnc`	string(5\|6)	Një MCCMNC me pesë ose gjashtë karaktere (kod i vendit celular dhe kod i rrjetit celular) që identifikon rrjetin të cilit i përket aktualisht numri i telefonit celular.	true
`mcc`	string(3)	Një MCC me tre karaktere (kod i vendit celular) që përfaqëson vendin e lidhur me rrjetin aktual të numrit të telefonit celular.	true
`mnc`	string(2\|3)	Një MNC me dy ose tre karaktere (kod i rrjetit celular) që identifikon operatorin aktual të rrjetit për numrin e telefonit celular.	true
`is_ported`	boolean	Tregon nëse numri i telefonit është transferuar nga rrjeti i tij origjinal tek një operator i ri.	true
`original_network_name`	string	Një varg arbitrar (në anglisht) që specifikon emrin e operatorit origjinal të rrjetit të numrit të telefonit celular të inspektuar.	true
`original_country_name`	string	Një varg arbitrar (në anglisht) që tregon vendin origjinal të numrit të telefonit celular të inspektuar.	true
`original_country_code`	string(2)	Një kod vendi ISO me dy karaktere që përfaqëson vendin origjinal të numrit të telefonit celular të inspektuar.	true
`original_country_prefix`	string	Kodi i thirrjes së vendit origjinal të lidhur me numrin e telefonit celular të inspektuar.	true
`ported_network_name`	string	Specifikon operatorin e rrjetit tek i cili është transferuar numri i telefonit celular i inspektuar, nëse është e zbatueshme.	true
`ported_country_name`	string	Specifikon vendin tek i cili është transferuar numri i telefonit celular i inspektuar, nëse është e zbatueshme.	true
`ported_country_code`	string(2)	Një kod vendi ISO me dy karaktere që përfaqëson vendin tek i cili është transferuar numri i telefonit celular i inspektuar, nëse është e zbatueshme.	true
`ported_country_prefix`	string	Kodi i thirrjes për vendin tek i cili është transferuar numri i telefonit celular i inspektuar, nëse është e zbatueshme.	true
`extra`	string	Një varg arbitrar që ofron detaje shtesë opsionale rreth numrit të telefonit.	true
`cost`	string	Një vlerë dhjetore, e paraqitur si varg, që tregon koston në EUR për këtë kontroll.	true
`timestamp`	string	Një vulë kohore e formatuar sipas W3C, duke përfshirë informacionin e zonës kohore, që tregon kur u krye kontrolli.	true
`storage`	string	Emri i ruajtjes (ose emri i raportit) në të cilin u shtuan rezultatet e kontrollit. Kjo përdoret për shkarkimet CSV dhe raportimin përmes ndërfaqes web.	true
`route`	string(3)	Një identifikues me tre karaktere që specifikon rrugën e përdorur për këtë kërkesë kontrolli.	true
`error_code`	integer	Një kod gabimi i brendshëm opsional që ofron kontekst shtesë për diagnostikimin e mbështetjes së klientit.	true

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

Parametrat e Përgjigjes së Gabimit

Emri	Lloji	Përshkrimi	I pranueshmë si null
`errors[]`	string[]	Një listë tekstesh që shpjegojnë gabimin.	false

Lëviz Lart

POST/mnp-lookupse mbrojtur

Inicion një grup kërkimesh asinkrone MNP (portabilitet i numrit celular), duke marrë MCCMNC-në aktuale dhe duke identifikuar rrjetet origjinale dhe aktuale në kohë reale. Rezultatet dërgohen përmes webhook-ëve në serverin tuaj. Kjo metodë është optimizuar për përpunimin e vëllimeve të mëdha numrash që nuk kërkojnë përgjigje të menjëhershme, si pastrimi dhe verifikimi i bazës së të dhënave. Për aplikacione në kohë reale si rutimi i thirrjeve ose dërgimi i SMS, konsideroni përdorimin e endpoint-it POST /mnp-lookup në vend të kësaj.

Kërkesat MNP përcaktojnë në mënyrë të besueshme informacionin mbi portabilitetin dhe rrjetin, por nuk tregojnë nëse telefoni celular i synuar është aktualisht i lidhur me një rrjet dhe i arritshëm. Për të nxjerrë informacion mbi lidhshmërinë në kohë reale, ju lutemi përdorni endpoint-in POST /hlr-lookups.

Para përdorimit të këtij endpoint, sigurohuni që një URL webhook është konfiguruar për të marrë rezultatet e kërkimeve në mënyrë asinkrone. Mund ta konfiguroni këtë në cilësimet e API.

Kërkesë Përgjigje e Suksesshme Përgjigje Gabimi Webhooks

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

Ngarkesa

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

Parametrat e Kërkesës

Çelësi	Lloji	Përshkrimi	Parazgjedhur	I detyrueshëm
`msisdns`	array	Një listë numrash telefonash celularë (MSISDN) në format ndërkombëtar (p.sh. +14156226819 ose 0014156226819). Mund të përfshini deri në 1000 numra për kërkesë.	null	i detyrueshëm
`route`	string(3)	Një identifikues me tre karaktere opsional që specifikon rrugën për këtë kërkim. Vendoseni në `null` ose lëreni këtë parametër për të aplikuar hartën tuaj të rutimit të personalizuar ose për ta lënë sistemin tonë të përcaktojë automatikisht rrugët më të mira për këtë kërkesë.	null	opsionale
`storage`	string	Një identifikues opsional ruajtjeje që specifikon raportin ku rezultatet do të ruhen për rishikim manual, analitikë dhe raportim. Sistemi automatikisht shton një vulë kohore me muajin aktual. Nëse lëhet jashtë ose vendoset në `null`, sistemi do të grupojë automatikisht rezultatet sipas muajit për qëllime raportimi.	null	opsionale

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

Atributet e Përgjigjes së Suksesshme

Emri	Lloji	Përshkrimi	I pranueshmë si null
`accepted`	array	Një listë objektesh që përmbajnë identifikues unikë dhe MSISDN që janë pranuar për përpunim.	false
`accepted_count`	integer	Numri total i MSISDN-ve të pranuara me sukses për përpunim.	false
`rejected`	array	Një listë objektesh që përmbajnë identifikues unikë dhe MSISDN që janë refuzuar për përpunim, zakonisht për shkak të numrave të pavlefshëm. Nuk aplikohet tarifë për hyrjet e refuzuara.	false
`rejected_count`	integer	Numri total i MSISDN-ve të refuzuara për shkak të gabimeve të validimit.	false
`total_count`	integer	Numri total i MSISDN-ve të pranuara dhe të refuzuara që janë dorëzuar për përpunim.	false
`cost`	string	Një vlerë dhjetore e paraqitur si string, që tregon koston totale në EUR për kërkesat e pranuara.	false
`storage`	string	Emri i hapësirës ruajtëse ku shtohen rezultatet e kërkimeve, të përdorura për raportim dhe shkarkime CSV përmes ndërfaqes web.	false
`route`	string(3)	Një identifikues me tre karaktere që specifikon rrugën e përdorur për këtë kërkesë kontrolli.	false
`webhook_urls`	array	URL-të e webhook-ëve të konfiguruar në cilësimet e API. Rezultatet dërgohen këtu.	false

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

Parametrat e Përgjigjes së Gabimit

Emri	Lloji	Përshkrimi	I pranueshmë si null
`errors[]`	string[]	Një listë tekstesh që shpjegojnë gabimin.	false

Përpunimi i Webhook-ave

Pasi të paraqitet, platforma jonë fillon përpunimin e numrave të telefonit të dhënë dhe dërgon rezultatet në URL-në e webhook-ut të specifikuar më parë në serverin tuaj. Rezultatet transmetohen si një kërkesë HTTP POST me një objekt JSON në trupin e kërkesës.

Autentifikimi

Autentifikoni webhook-un duke kontrolluar header-in HTTP X-Signatures.

Header-i X-Signatures përmban një listë nënshkrimesh të ndara me pikëpresje. Çdo nënshkrim në listë gjenerohet duke përdorur një nga sekretet API të konfiguruar në llogarinë tuaj. Për të verifikuar webhook-un, gjeneroni një hash SHA-256 duke përdorur çelësin tuaj API, sekretin dhe trupin e papërpunuar HTTP - më pas krahasojeni me nënshkrimet në listë.

Një përputhje konfirmon që kërkesa është autentike dhe e nënshkruar me një sekret që ju kontrolloni.

Shembull Kodi

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

Kërkesa është e vlefshme nëse ndonjë nga nënshkrimet e dhëna në header barazohet me një hash SHA256 të llogaritur mbi vargun e bashkuar të çelësit tuaj API, sekretit dhe trupit HTTP.

Konfirmimi i Marrjes

Pritet që serveri juaj të përgjigjet me një kod statusi HTTP 200 OK për të konfirmuar marrjen e suksesshme. Nëse kthehet ndonjë kod tjetër përgjigjeje, ndodh një timeout (10 sekonda), ose lind ndonjë problem tjetër dërgimi, sistemi do të riprovoj automatikisht webhook-un pas një minute. Nëse kërkesa vazhdon të dështojë, riprovimet do të ndjekin një strategji eksponenciale backoff, me përpjekje të mëvonshme pas 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minutash.

Ky mekanizëm riprovimi siguron besueshmëri maksimale në dërgimin e rezultateve të kërkimit në infrastrukturën tuaj. Ai minimizon rrezikun e humbjes së të dhënave për shkak të problemeve të përkohshme të rrjetit ose ndërprerjeve të serverit.

Ngarkesa e Webhook-ut

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

Atributet e Payload të Webhook

Objekti JSON përmban një atribut type => MNP së bashku me një atribut results që përfshin një listë objektesh kërkimi, siç dokumentohet më poshtë.

Emri	Lloji	Përshkrimi	I pranueshmë si null
`id`	string(12)	Një identifikues unik me 12 karaktere për këtë kërkesë kontrolli.	false
`msisdn`	string	Numri i telefonit celular i vlerësuar në këtë kërkesë kontrolli.	false
`query_status`	string	Tregon nëse marrja e informacionit të portabilitetit dhe rrjetit ishte e suksesshme. Vlerat e mundshme janë `OK` ose `FAILED`.	false
`mccmnc`	string(5\|6)	Një MCCMNC me pesë ose gjashtë karaktere (kod i vendit celular dhe kod i rrjetit celular) që identifikon rrjetin të cilit i përket aktualisht numri i telefonit celular.	true
`mcc`	string(3)	Një MCC me tre karaktere (kod i vendit celular) që përfaqëson vendin e lidhur me rrjetin aktual të numrit të telefonit celular.	true
`mnc`	string(2\|3)	Një MNC me dy ose tre karaktere (kod i rrjetit celular) që identifikon operatorin aktual të rrjetit për numrin e telefonit celular.	true
`is_ported`	boolean	Tregon nëse numri i telefonit është transferuar nga rrjeti i tij origjinal tek një operator i ri.	true
`original_network_name`	string	Një varg arbitrar (në anglisht) që specifikon emrin e operatorit origjinal të rrjetit të numrit të telefonit celular të inspektuar.	true
`original_country_name`	string	Një varg arbitrar (në anglisht) që tregon vendin origjinal të numrit të telefonit celular të inspektuar.	true
`original_country_code`	string(2)	Një kod vendi ISO me dy karaktere që përfaqëson vendin origjinal të numrit të telefonit celular të inspektuar.	true
`original_country_prefix`	string	Kodi i thirrjes së vendit origjinal të lidhur me numrin e telefonit celular të inspektuar.	true
`ported_network_name`	string	Specifikon operatorin e rrjetit tek i cili është transferuar numri i telefonit celular i inspektuar, nëse është e zbatueshme.	true
`ported_country_name`	string	Specifikon vendin tek i cili është transferuar numri i telefonit celular i inspektuar, nëse është e zbatueshme.	true
`ported_country_code`	string(2)	Një kod vendi ISO me dy karaktere që përfaqëson vendin tek i cili është transferuar numri i telefonit celular i inspektuar, nëse është e zbatueshme.	true
`ported_country_prefix`	string	Kodi i thirrjes për vendin tek i cili është transferuar numri i telefonit celular i inspektuar, nëse është e zbatueshme.	true
`extra`	string	Një varg arbitrar që ofron detaje shtesë opsionale rreth numrit të telefonit.	true
`cost`	string	Një vlerë dhjetore, e paraqitur si varg, që tregon koston në EUR për këtë kontroll.	true
`timestamp`	string	Një vulë kohore e formatuar sipas W3C, duke përfshirë informacionin e zonës kohore, që tregon kur u krye kontrolli.	true
`storage`	string	Emri i ruajtjes (ose emri i raportit) në të cilin u shtuan rezultatet e kontrollit. Kjo përdoret për shkarkimet CSV dhe raportimin përmes ndërfaqes web.	true
`route`	string(3)	Një identifikues me tre karaktere që specifikon rrugën e përdorur për këtë kërkesë kontrolli.	true
`error_code`	integer	Një kod gabimi i brendshëm opsional që ofron kontekst shtesë për diagnostikimin e mbështetjes së klientit.	true

Lëviz Lart

POST/nt-lookupe mbrojtur

Kryen një kërkesë sinkrone për llojin e numrit (NT). Ky endpoint është ideal nëse qëllimi juaj kryesor është të përcaktoni nëse numrat e telefonit të dhënë i përkasin intervaleve të planit të numrave për linjë fikse, celular, tarifë premium, VoIP, pager ose të tjerë në kohë reale.

Kërkesat NT zbulojnë në mënyrë të besueshme llojin e numrit të telefonit; megjithatë, ato nuk tregojnë nëse numri i synuar është aktualisht i lidhur me një rrjet dhe i arritshëm. Për të marrë informacion të drejtpërdrejtë mbi lidhshmërinë, ju lutemi përdorni endpoint-in POST /hlr-lookup.

Nëse rasti juaj i përdorimit kërkon informacion të saktë mbi rrjetin dhe portabilitetin (MCCMNC) por jo statusin e lidhshmërisë në kohë reale, ju lutemi përdorni endpoint-in POST /mnp-lookup për kërkesat e portabilitetit të numrave celularë.

Kërkesë Përgjigje e Suksesshme Përgjigje Gabimi Referencë e Llojit

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

Ngarkesa

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

Parametrat e Kërkesës

Çelësi	Lloji	Përshkrimi	Parazgjedhur	I detyrueshëm
`number`	string	Një numër telefoni në format ndërkombëtar (p.sh. +4989702626 ose 004989702626).	null	mandatory
`route`	string(3)	Një identifikues me tre karaktere opsional që specifikon rrugën për këtë kërkesë. Vendoseni në `null` ose lëreni këtë parametër për të aplikuar hartën tuaj të rrugëzimit të personalizuar ose për të lejuar sistemin tonë të përcaktojë automatikisht rrugët më të mira për këtë kërkesë.	null	opsionale
`storage`	string	Një identifikues opsional ruajtjeje që specifikon raportin ku rezultatet do të ruhen për rishikim manual, analitikë dhe raportim. Sistemi automatikisht shton një vulë kohore me muajin aktual. Nëse lëhet jashtë ose vendoset në `null`, sistemi do të grupojë automatikisht rezultatet sipas muajit për qëllime raportimi.	null	opsionale

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

Atributet e Përgjigjes së Suksesshme

Emri	Lloji	Përshkrimi	I pranueshmë si null
`id`	string(12)	Një identifikues unik i caktuar për këtë kërkesë verifikimi.	false
`number`	string	Numri i telefonit që u vlerësua gjatë kërkesës së këtij kërkimi.	false
`number_type`	string	Lloji i numrit të zbuluar. Vlerat e mundshme përfshijnë: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Tregon nëse informacioni i llojit të numrit u mor me sukses. Kthen `OK` nëse është i suksesshëm, ose `FAILED` nëse kërkimi dështoi.	false
`is_valid`	boolean	Tregon nëse numri i telefonit është sintaksisht i vlefshëm.	true
`invalid_reason`	string	Një mesazh në tekst të thjeshtë në anglisht që specifikon pse numri i telefonit konsiderohet i pavlefshëm (p.sh. "too short" ose "invalid prefix"), ose `null` nëse numri është i vlefshëm.	true
`is_possibly_ported`	boolean	Tregon nëse numri i telefonit mund të jetë transferuar nga operatori i tij origjinal te një operatori tjetër. Për informacion definitiv mbi portabilitetin, përdorni kërkesat MNP.	true
`is_vanity_number`	boolean	Tregon nëse numri i telefonit është një numër vanity, që do të thotë se përfshin karaktere alfabetike.	true
`qualifies_for_hlr_lookup`	boolean	Tregon nëse numri i telefonit është i përshtatshëm për pyetje shtesë përmes kërkesave HLR.	true
`mccmnc`	string(5\|6)	Një varg prej pesë ose gjashtë karakteresh që përfaqëson tuplën MCCMNC (kodi i vendit celular dhe kodi i rrjetit celular) që identifikon rrjetin origjinal të numrit të telefonit celular.	true
`mcc`	string(3)	Një varg prej tre karakteresh që përfaqëson MCC-në (kodin e vendit celular) që identifikon vendin e lidhur me rrjetin origjinal celular të numrit të telefonit.	true
`mnc`	string(2\|3)	Një varg prej dy ose tre karakteresh që përfaqëson MNC-në (kodin e rrjetit celular) që identifikon operatorin origjinal të rrjetit celular të numrit të telefonit.	true
`original_network_name`	string	Një varg arbitrar në tekst të thjeshtë në anglisht që specifikon emrin e operatorit origjinal të rrjetit të numrit të inspektuar të telefonit celular.	true
`original_country_name`	string	Një varg arbitrar në tekst të thjeshtë në anglisht që specifikon vendin origjinal të lidhur me numrin e inspektuar të telefonit celular.	true
`original_country_code`	string(2)	Një kod vendi ISO me dy karaktere që tregon vendin origjinal të numrit të inspektuar të telefonit celular.	true
`regions`	array	Një listë e vargëve të lexueshëm në anglisht që specifikojnë rajonin(et) gjeografik të lidhur me këtë numër telefoni.	true
`timezones`	array	Një listë e zonave kohore (në formatin Olson) të lidhura me këtë numër telefoni.	true
`info_text`	string	Një varg arbitrar që mund të përmbajë informacion shtesë rreth numrit të telefonit.	true
`cost`	string	Një vlerë dhjetore e paraqitur si varg, që tregon koston (në EUR) të këtij kërkimi.	true
`timestamp`	string	Një vulë kohore e formatuar sipas W3C (duke përfshirë zonën kohore) që tregon kur u përfundua kërkimi.	true
`storage`	string	Specifikon emrin e ruajtjes ku janë shtuar rezultatet e kërkimit. Kjo korrespondon me emrin e raportit të përdorur për shkarkimet CSV dhe analizat përmes ndërfaqes web.	true
`route`	string(3)	Një identifikues me tre karaktere që specifikon rrugën e përdorur për këtë kërkesë kontrolli.	true

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

Parametrat e Përgjigjes së Gabimit

Emri	Lloji	Përshkrimi	I pranueshmë si null
`errors[]`	string[]	Një listë tekstesh që shpjegojnë gabimin.	false

Lloji	Përshkrimi
LANDLINE	Numër telefoni fiks.
MOBILE	Numër telefoni celular. I përshtatshëm për kërkime HLR për të marrë informacion shtesë mbi statusin e lidhjes, rrjetin, portabilitetin dhe roaming-un.
MOBILE_OR_LANDLINE	Numër telefoni fiks ose celular. Mund të jetë i përshtatshëm për kërkime HLR.
TOLL_FREE	Numër telefoni pa pagesë.
PREMIUM_RATE	Numër telefoni me tarifë premium me tarifa shtesë.
SHARED_COST	Numër telefoni me kosto të ndarë. Zakonisht më pak i shtrenjtë se numrat me tarifë premium.
VOIP	Numër telefoni Voice over IP. Përfshin numra TSoIP (Telephony Service over IP).
PAGER	Numër telefoni për pager. Zakonisht pa funksionalitet zëri.
UAN	Numër me Akses Universal (Numër Kompanie). Mund të drejtohet në zyra specifike por lejon përdorimin e një numri të vetëm për kompaninë.
VOICEMAIL	Numër telefoni për postë zanore.
UNKNOWN	Lloji i numrit nuk mund të përcaktohej.

Lëviz Lart

POST/nt-lookups e mbrojtur

Ky endpoint kryen një seri kërkimesh asinkrone të llojit të numrit me rezultate të dërguara në serverin tuaj përmes webhook. Është i përshtatshëm nëse qëllimi juaj kryesor është të përcaktoni nëse numrat e telefonit të dhënë i përkasin intervaleve të planit të numerimit për linjë fikse, celular, tarifë premium, VoIP, pager ose të tjerë. I optimizuar për përpunimin e shpejtë të volumeve të mëdha numrash, ky endpoint është ideal për operacione masive (p.sh. pastrimi i bazës së të dhënave). Për trafik të drejtpërdrejtë dhe raste me kohë kritike, ju lutemi përdorni endpoint-in POST /nt-lookup.

Duhet të specifikoni një URL webhook në cilësimet e API si parakusht për të aktivizuar këtë endpoint.

Kërkesë Përgjigje e Suksesshme Përgjigje Gabimi Webhooks Referencë e Llojit

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

Ngarkesa

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

Parametrat e Kërkesës

Çelësi	Lloji	Përshkrimi	Parazgjedhur	I detyrueshëm
`numbers`	array	Një grup numrash telefoni në format ndërkombëtar (p.sh. +14156226819 ose 004989702626). Maksimumi i 1000 numrave mund të përfshihen për kërkesë.	null	i detyrueshëm
`route`	string(3)	Një identifikues me tre karaktere opsional që specifikon rrugën për këtë kërkesë. Vendoseni në `null` ose lëreni këtë parametër për të aplikuar hartën tuaj të rrugëzimit të personalizuar ose lini sistemin tonë të përcaktojë automatikisht rrugën më të mirë për këtë kërkesë.	null	opsionale
`storage`	string	Një identifikues opsional ruajtjeje që specifikon raportin ku rezultatet do të ruhen për rishikim manual, analitikë dhe raportim. Sistemi automatikisht shton një vulë kohore me muajin aktual. Nëse lëhet jashtë ose vendoset në `null`, sistemi do të grupojë automatikisht rezultatet sipas muajit për qëllime raportimi.	null	opsionale

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

Atributet e Përgjigjes së Suksesshme

Emri	Lloji	Përshkrimi	I pranueshmë si null
`accepted`	array	Një grup objektesh, secili që përmban një identifikues unik dhe një numër telefoni që është pranuar për përpunim.	false
`accepted_count`	integer	Numri total i numrave të telefonit të pranuar për përpunim.	false
`rejected`	array	Një grup objektesh, secili që përmban një identifikues unik dhe një numër telefoni që është refuzuar për përpunim. Zakonisht, këta numra janë të pavlefshëm dhe nuk aplikohet asnjë tarifë.	false
`rejected_count`	integer	Numri total i numrave të telefonit që janë refuzuar për përpunim.	false
`total_count`	integer	Numri total i numrave të telefonit të pranuar dhe të refuzuar që janë dorëzuar për përpunim.	false
`cost`	string	Një vlerë që përfaqëson një shumë dhjetore që tregon koston në EUR për këto kërkime.	false
`storage`	string	Emri i hapësirës ruajtëse (raportit) ku janë shtuar rezultatet e kërkimit. Ky emër përdoret për shkarkime CSV dhe analitikë përmes ndërfaqes web.	false
`route`	string(3)	Një identifikues me tre karaktere që specifikon rrugën e përdorur për këtë kërkesë kërkimi.	false
`webhook_urls`	array	URL-të e webhook-ëve të konfiguruar në cilësimet e API. Rezultatet dërgohen këtu.	false

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

Parametrat e Përgjigjes së Gabimit

Emri	Lloji	Përshkrimi	I pranueshmë si null
`errors[]`	string[]	Një listë tekstesh që shpjegojnë gabimin.	false

Përpunimi i Webhook-ave

Pasi të paraqitet, platforma jonë fillon përpunimin e numrave të telefonit të dhënë dhe dërgon rezultatet në URL-në e webhook-ut të specifikuar më parë në serverin tuaj. Rezultatet transmetohen si një kërkesë HTTP POST me një objekt JSON në trupin e kërkesës.

Autentifikimi

Autentifikoni webhook-un duke kontrolluar header-in HTTP X-Signatures.

Header-i X-Signatures përmban një listë nënshkrimesh të ndara me pikëpresje. Çdo nënshkrim në listë gjenerohet duke përdorur një nga sekretet API të konfiguruar në llogarinë tuaj. Për të verifikuar webhook-un, gjeneroni një hash SHA-256 duke përdorur çelësin tuaj API, sekretin dhe trupin e papërpunuar HTTP - më pas krahasojeni me nënshkrimet në listë.

Një përputhje konfirmon që kërkesa është autentike dhe e nënshkruar me një sekret që ju kontrolloni.

Shembull Kodi

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

Kërkesa është e vlefshme nëse ndonjë nga nënshkrimet e dhëna në header barazohet me një hash SHA256 të llogaritur mbi vargun e bashkuar të çelësit tuaj API, sekretit dhe trupit HTTP.

Konfirmimi i Marrjes

Pritet që serveri juaj të përgjigjet me një kod statusi HTTP 200 OK për të konfirmuar marrjen e suksesshme. Nëse kthehet ndonjë kod tjetër përgjigjeje, ndodh një timeout (10 sekonda), ose lind ndonjë problem tjetër dërgimi, sistemi do të riprovoj automatikisht webhook-un pas një minute. Nëse kërkesa vazhdon të dështojë, riprovimet do të ndjekin një strategji eksponenciale backoff, me përpjekje të mëvonshme pas 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minutash.

Ky mekanizëm riprovimi siguron besueshmëri maksimale në dërgimin e rezultateve të kërkimit në infrastrukturën tuaj. Ai minimizon rrezikun e humbjes së të dhënave për shkak të problemeve të përkohshme të rrjetit ose ndërprerjeve të serverit.

Ngarkesa e Webhook-ut

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

Atributet e Payload të Webhook

Objekti JSON përmban një atribut type => NT së bashku me një atribut results që përfshin një listë objektesh kërkimi, siç dokumentohet më poshtë.

Emri	Lloji	Përshkrimi	I pranueshmë si null
`id`	string(12)	Një identifikues unik i caktuar për këtë kërkesë verifikimi.	false
`number`	string	Numri i telefonit që u vlerësua gjatë kërkesës së këtij kërkimi.	false
`number_type`	string	Lloji i numrit të zbuluar. Vlerat e mundshme përfshijnë: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Tregon nëse informacioni i llojit të numrit u mor me sukses. Kthen `OK` nëse është i suksesshëm, ose `FAILED` nëse kërkimi dështoi.	false
`is_valid`	boolean	Tregon nëse numri i telefonit është sintaksisht i vlefshëm.	true
`invalid_reason`	string	Një mesazh në tekst të thjeshtë në anglisht që specifikon pse numri i telefonit konsiderohet i pavlefshëm (p.sh. "too short" ose "invalid prefix"), ose `null` nëse numri është i vlefshëm.	true
`is_possibly_ported`	boolean	Tregon nëse numri i telefonit mund të jetë transferuar nga operatori i tij origjinal te një operatori tjetër. Për informacion definitiv mbi portabilitetin, përdorni kërkesat MNP.	true
`is_vanity_number`	boolean	Tregon nëse numri i telefonit është një numër vanity, që do të thotë se përfshin karaktere alfabetike.	true
`qualifies_for_hlr_lookup`	boolean	Tregon nëse numri i telefonit është i përshtatshëm për pyetje shtesë përmes kërkesave HLR.	true
`mccmnc`	string(5\|6)	Një varg prej pesë ose gjashtë karakteresh që përfaqëson tuplën MCCMNC (kodi i vendit celular dhe kodi i rrjetit celular) që identifikon rrjetin origjinal të numrit të telefonit celular.	true
`mcc`	string(3)	Një varg prej tre karakteresh që përfaqëson MCC-në (kodin e vendit celular) që identifikon vendin e lidhur me rrjetin origjinal celular të numrit të telefonit.	true
`mnc`	string(2\|3)	Një varg prej dy ose tre karakteresh që përfaqëson MNC-në (kodin e rrjetit celular) që identifikon operatorin origjinal të rrjetit celular të numrit të telefonit.	true
`original_network_name`	string	Një varg arbitrar në tekst të thjeshtë në anglisht që specifikon emrin e operatorit origjinal të rrjetit të numrit të inspektuar të telefonit celular.	true
`original_country_name`	string	Një varg arbitrar në tekst të thjeshtë në anglisht që specifikon vendin origjinal të lidhur me numrin e inspektuar të telefonit celular.	true
`original_country_code`	string(2)	Një kod vendi ISO me dy karaktere që tregon vendin origjinal të numrit të inspektuar të telefonit celular.	true
`regions`	array	Një listë e vargëve të lexueshëm në anglisht që specifikojnë rajonin(et) gjeografik të lidhur me këtë numër telefoni.	true
`timezones`	array	Një listë e zonave kohore (në formatin Olson) të lidhura me këtë numër telefoni.	true
`info_text`	string	Një varg arbitrar që mund të përmbajë informacion shtesë rreth numrit të telefonit.	true
`cost`	string	Një vlerë dhjetore e paraqitur si varg, që tregon koston (në EUR) të këtij kërkimi.	true
`timestamp`	string	Një vulë kohore e formatuar sipas W3C (duke përfshirë zonën kohore) që tregon kur u përfundua kërkimi.	true
`storage`	string	Specifikon emrin e ruajtjes ku janë shtuar rezultatet e kërkimit. Kjo korrespondon me emrin e raportit të përdorur për shkarkimet CSV dhe analizat përmes ndërfaqes web.	true
`route`	string(3)	Një identifikues me tre karaktere që specifikon rrugën e përdorur për këtë kërkesë kontrolli.	true

Lloji	Përshkrimi
LANDLINE	Numër telefoni fiks.
MOBILE	Numër telefoni celular. I përshtatshëm për kërkime HLR për të marrë informacion shtesë mbi statusin e lidhjes, rrjetin, portabilitetin dhe roaming-un.
MOBILE_OR_LANDLINE	Numër telefoni fiks ose celular. Mund të jetë i përshtatshëm për kërkime HLR.
TOLL_FREE	Numër telefoni pa pagesë.
PREMIUM_RATE	Numër telefoni me tarifë premium me tarifa shtesë.
SHARED_COST	Numër telefoni me kosto të ndarë. Zakonisht më pak i shtrenjtë se numrat me tarifë premium.
VOIP	Numër telefoni Voice over IP. Përfshin numra TSoIP (Telephony Service over IP).
PAGER	Numër telefoni për pager. Zakonisht pa funksionalitet zëri.
UAN	Numër me Akses Universal (Numër Kompanie). Mund të drejtohet në zyra specifike por lejon përdorimin e një numri të vetëm për kompaninë.
VOICEMAIL	Numër telefoni për postë zanore.
UNKNOWN	Lloji i numrit nuk mund të përcaktohej.

Lëviz Lart

GET/routee mbrojtur

Merr rrugën që do të zgjidhet automatikisht kur ekzekutoni një kërkesë HLR pa specifikuar parametrin route.

Zgjedhja automatike e rrugës bazohet në hartën e routing-ut të marrshme me endpoint-in GET /hlr-coverage, e cila rrjedh kryesisht nga GET /routing-map. Mund të personalizoni hartën tuaj të routing-ut dhe të përcaktoni rregulla të personalizuara në cilësimet e llogarisë.

Kërkesë Përgjigje e Suksesshme Përgjigje Gabimi

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

Parametrat e Kërkesës

Çelësi	Lloji	Përshkrimi	Parazgjedhur	I detyrueshëm
`msisdn`	string	MSISDN-ja për të cilën do të merret informacioni i routing-ut të zgjedhur automatikisht.	null	i detyrueshëm

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

Atributet e Përgjigjes së Suksesshme

Emri	Lloji	Përshkrimi	I pranueshmë si null
`route`	string	Rruga e rekomanduar.	false
`confidence_level`	string	Niveli i besueshmërisë me të cilin është zgjedhur kjo rrugë, d.m.th. `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`.	false
`mccmnc`	string	MCCMNC-ja e bazuar në planin e numërimit për këtë numër.	false
`origin`	string	Origjina në të cilën bazohet vendimi i routing-ut, dmth. `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."
    ]
}

Parametrat e Përgjigjes së Gabimit

Emri	Lloji	Përshkrimi	I pranueshmë si null
`errors[]`	string[]	Një listë tekstesh që shpjegojnë gabimin.	false

Lëviz Lart

GET/routese mbrojtur

Ky endpoint kthen një listë të rrugëve të disponueshme HLR, MNP dhe NT. Çdo rrugë, së bashku me karakteristikat dhe kufizimet e saj, shpjegohet në faqen detaje rrugëzimi.

Kërkesë Përgjigje e Suksesshme Përgjigje Gabimi

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

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

Atributet e Përgjigjes së Suksesshme

Emri	Lloji	Përshkrimi	I pranueshmë si null
`routes`	object	Një objekt me rrugë të grupuara sipas llojit të rrugës.	false
`HLR\|MNP\|NT`	string[]	Përmban një listë identifikuesish të rrugëve.	false

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

Parametrat e Përgjigjes së Gabimit

Emri	Lloji	Përshkrimi	I pranueshmë si null
`errors[]`	string[]	Një listë tekstesh që shpjegojnë gabimin.	false

Lëviz Lart

GET/routing-mape mbrojtur

Merr konfigurimin e routimit të automatizuar që aktualisht aplikohet për HLR Lookups në llogarinë tuaj. Ky konfigurim i paracaktuar përdoret sa herë që dërgoni kërkesa HLR pa specifikuar parametrin route. Mund të personalizoni hartën tuaj të routimit dhe të krijoni rregulla të personalizuara në cilësimet e llogarisë.

Hierarkia e konfigurimit kalon nga rregullat në nivel vendi te rregullat në nivel MCCMNC, dhe më në fund te mapimi i prefikseve individuale të numrave telefonikë. Në praktikë, kjo do të thotë se mapimet e prefikseve individuale të numrave telefonikë kanë përparësi ndaj caktimeve MCCMNC në konflikt, të cilat nga ana tyre anashkalojnë rregullat në nivel vendi. Ju lutemi vini re se MNP fallback anashkalon çdo rregull të personalizuar në konflikt kur është i aktivizuar.

Kërkesë Përgjigje e Suksesshme Përgjigje Gabimi

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

Atributet e Përgjigjes së Suksesshme

Emri	Lloji	Përshkrimi	I pranueshmë si null
`default_route`	string	Rruga e paracaktuar që përdoret kur nuk mund të përcaktohet asnjë opsion i preferuar routimi për një MSISDN dhe nuk aplikohen rregulla të personalizuara routimi.	false
`mnp_fallback`	boolean	Tregon nëse MNP fallback është i aktivizuar. Kur është i aktivizuar dhe kërkesat HLR nuk mbështeten nga një rrjet (statusi i lidhshmërisë nuk është i disponueshëm), sistemi do të kryejë një kërkesë MNP në vend të saj.	false
`mccmncs`	array	Një mapim i kodeve MCCMNC me rrugët e tyre të zgjedhura automatikisht. Kur kryhet një kërkesë HLR për një numër në një MCCMNC të caktuar, përdoret rruga përkatëse.	false
`mccmnc`	string(5\|6)	Një MCCMNC me pesë ose gjashtë karaktere (kombinim i kodit të shtetit celular dhe kodit të rrjetit celular) që identifikon operatorin e rrjetit celular.	false
`countrycode`	string(2)	Një kod vendi ISO me dy karaktere, që identifikon vendin e rrjetit.	false
`route`	string(3)	Rruga e zgjedhur për rrjetin.	false
`mno`	string	Marka e orientuar drejt konsumatorit nën të cilën operon ky rrjet.	false
`confidence`	string	Niveli i besueshmërisë me të cilin është bërë zgjedhja. Vlerat e mundshme janë: HIGH, NORMAL, LOW, MNP_REDIRECT. Në rastin e të fundit, sistemi ridrejton trafikun për këtë rrjet në MNP, nëse ky sjellje është e aktivizuar në llogarinë tuaj. Përndryshe përdor rrugën e paracaktuar në llogari.	false
`origin`	string	Burimi në të cilin bazohet zgjedhja. Vlerat e mundshme janë: `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	Një listë e rregullave të personalizuara të routimit bazuar në prefikse të konfiguruara në llogarinë tuaj, nëse ka.	false
`countrycode`	string(2)	Një kod vendi ISO me dy karaktere, që identifikon vendin e prefiksit.	false
`cns`	string	Prefiksi për të cilin aplikohet rregulla e routimit.	false
`route`	string(3)	Rruga e zgjedhur për prefiksin.	false
`mccmnc`	string(5\|6)	Një MCCMNC me pesë ose gjashtë karaktere (kombinim i kodit të shtetit celular dhe kodit të rrjetit celular) që identifikon operatorin e rrjetit celular.	true
`mno`	string	Marka e orientuar drejt konsumatorit nën të cilën operon ky rrjet.	true
`countries`	array	Një listë e rregullave të personalizuara bazuar në vend të konfiguruara në llogarinë tuaj, nëse ka.	false
`countrycode`	string(2)	Një kod vendi ISO me dy karaktere, që identifikon vendin.	false
`route`	string(3)	Rruga e zgjedhur për vendin.	false

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

Parametrat e Përgjigjes së Gabimit

Emri	Lloji	Përshkrimi	I pranueshmë si null
`errors[]`	string[]	Një listë tekstesh që shpjegojnë gabimin.	false

Lëviz Lart

GET/hlr-coverage e mbrojtur

Kthen informacione mbi mbulimin HLR për të mbështetur vendimmarrjen e bazuar në të dhëna. Ky endpoint ju ndihmon të analizoni opsionet e routing-ut HLR në kohë reale nëpër rrjetet celulare, të identifikoni rrugët më efektive për rajonet tuaja të synuara dhe të konfiguroni routing-un tuaj automatik.

Rrugët e rekomanduara nga GET /route bazohen në të dhënat e mbulimit të marra këtu. Të dhënat e mbulimit janë gjithashtu të disponueshme në faqen mbulimi i rrjetit. Mund të personalizoni më tej hartën tuaj të routing-ut dhe të përcaktoni rregulla në cilësimet e llogarisë.

Rekomandojmë të njiheni me këtë udhëzues për të ndihmuar në interpretimin e rezultateve.

Kërkesë Përgjigje e Suksesshme Përgjigje Gabimi Referenca e Statusit

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

Parametrat e Kërkesës

Çelësi	Lloji	Përshkrimi	Parazgjedhur	I detyrueshëm
`countrycode`	string(2)	Një kod vendi ISO me dy shkronja i detyrueshëm që përdoret për të filtruar rezultatet, duke kthyer vetëm rekordet e lidhura me vendin e specifikuar.	null	i detyrueshëm
`sample_size`	string	Një parametër opsional që specifikon madhësinë e mostrës. Vlerat e mundshme janë `LARGE`, `MEDIUM`, `SMALL`. Mostrat më të mëdha mbulojnë një periudhë kohore më të gjatë, mostrat më të vogla mbulojnë një periudhë kohore shumë të fundit.	LARGE	opsionale

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

Atributet e Përgjigjes së Suksesshme

Emri	Lloji	Përshkrimi	I pranueshmë si null
`name`	string	Emri i vendit të zgjedhur në tekst të thjeshtë anglisht.	false
`countrycode`	string(2)	Kodi ISO me dy karaktere i vendit të zgjedhur.	false
`prefix`	string	Prefiksi ndërkombëtar i telefonimit të vendit të zgjedhur.	false
`mccs`	string[]	Një listë e MCC-ve (kodeve të vendeve celulare) të lidhura me vendin e zgjedhur.	false
`carriers`	object[]	Një listë e objekteve të operatorëve me metrika të lidhshmërisë specifike për rrugë.	false
`mno`	string	Emri i operatorit të rrjetit celular në tekst të thjeshtë anglisht.	false
`mccmnc`	string	MCCMNC e operatorit të rrjetit celular.	false
`mcc`	string	MCC (kodi i vendit celular) i operatorit të rrjetit celular.	false
`mnc`	string	MNC (kodi i rrjetit celular) i operatorit të rrjetit celular.	false
`routes`	object[]	Një listë e rezultateve të lidhshmërisë specifike për rrugë.	false
`route`	string	Rruga për të cilën aplikohen informacionet e lidhshmërisë.	false
`selected`	bool	Tregon nëse kjo është rruga e zgjedhur për routing automatik.	false
`selection_confidence`	string	Niveli i besueshmërisë me të cilin është zgjedhur kjo rrugë, d.m.th. `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`. Përmban null nëse kjo nuk është rruga e zgjedhur.	true
`n`	int	Numri total i kërkimeve në këtë mostër.	false
`CONNECTED`	int	Numri i kërkimeve HLR që kanë kthyer statusin CONNECTED.	false
`CONNECTED_PCT`	float	Përqindja e kërkimeve HLR që kanë kthyer statusin CONNECTED.	false
`ABSENT`	int	Numri i kërkimeve HLR që kanë kthyer statusin ABSENT.	false
`ABSENT_PCT`	float	Përqindja e kërkimeve HLR që kanë kthyer statusin ABSENT.	false
`INVALID_MSISDN`	int	Numri i kërkimeve HLR që kanë kthyer statusin INVALID_MSISDN.	false
`INVALID_MSISDN_PCT`	float	Përqindja e kërkimeve HLR që kanë kthyer statusin INVALID_MSISDN.	false
`UNDETERMINED`	int	Numri i kërkimeve HLR që kanë kthyer statusin UNDETERMINED.	false
`UNDETERMINED_PCT`	float	Përqindja e kërkimeve HLR që kanë kthyer statusin UNDETERMINED.	false

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

Parametrat e Përgjigjes së Gabimit

Emri	Lloji	Përshkrimi	I pranueshmë si null
`errors[]`	string[]	Një listë tekstesh që shpjegojnë gabimin.	false

Statusi	Përshkrimi
CONNECTED	Numri është i vlefshëm dhe pajisja e destinacionit është aktualisht e lidhur me rrjetin celular. Thirrjet, SMS-të dhe shërbimet e tjera duhet të arrijnë me sukses tek marrësi.
ABSENT	Numri është i vlefshëm, por pajisja e destinacionit është ose e fikur ose përkohësisht jashtë mbulimit të rrjetit. Mesazhet ose thirrjet mund të mos dërgohen derisa pajisja të rilidhet me rrjetin.
INVALID_MSISDN	Numri është i pavlefshëm ose nuk është aktualisht i caktuar për asnjë abonet në rrjetin celular. Thirrjet dhe mesazhet drejt këtij numri do të dështojnë.
UNDETERMINED	Statusi i lidhshmërisë së numrit nuk mund të përcaktohej. Kjo mund të jetë për shkak të një numri të pavlefshëm, përgjigje gabimi SS7, ose mungesë lidhshmërie me operatorin e rrjetit të destinacionit. Kontrolloni kodin e gabimit dhe fushën e përshkrimit për diagnostikime shtesë.

Lëviz Lart

GET/mnp-coveragee mbrojtur

Ky endpoint kthen një listë të operatorëve të rrjeteve celulare, së bashku me identifikuesit e tyre përkatës MCCMNC, që aktualisht mbështeten për kërkime të portabilitetit të numrave celularë.

Kërkesë Përgjigje e Suksesshme Përgjigje Gabimi

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

Parametrat e Kërkesës

Çelësi	Lloji	Përshkrimi	Parazgjedhur	I detyrueshëm
`countrycode`	string(2)	Një kod shteti me dy shkronja ISO opsional që përdoret për të filtruar rezultatet MCCMNC, duke kthyer vetëm të dhënat relevante për shtetin e specifikuar.	null	opsionale

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

Atributet e Përgjigjes së Suksesshme

Emri	Lloji	Përshkrimi	I pranueshmë si null
`items[]`	array	Një listë e operatorëve të rrjeteve celulare.	false
`country_name`	string	Emri i shtetit në anglisht.	false
`country_code`	string(2)	Një kod shteti me dy shkronja ISO.	false
`mccmnc`	string(5\|6)	Një MCCMNC me pesë ose gjashtë karaktere (kombinim i kodit të shtetit celular dhe kodit të rrjetit celular) që identifikon operatorin e rrjetit celular.	false
`mcc`	string(3)	Një MCC me tre karaktere (kod shteti celular) që përfaqëson shtetin e rrjetit.	false
`mnc`	string(2\|3)	Një MNC me dy ose tre karaktere (kod rrjeti celular) që përfaqëson operatorin specifik të rrjetit celular.	false
`brand`	string	Marka e orientuar drejt konsumatorit nën të cilën operon ky rrjet.	true
`operator`	string	Emri ligjor i operatorit të rrjetit celular.	true

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

Parametrat e Përgjigjes së Gabimit

Emri	Lloji	Përshkrimi	I pranueshmë si null
`errors[]`	string[]	Një listë tekstesh që shpjegojnë gabimin.	false

Lëviz Lart

GET/price-liste mbrojtur

Ky endpoint kthen një listë të vendeve ku mbështeten vetëm kërkime MNP, dhe pyetjet HLR nuk janë të disponueshme për këto destinacione.

Kërkesë Përgjigje e Suksesshme Përgjigje Gabimi

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

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

Atributet e Përgjigjes së Suksesshme

Emri	Lloji	Përshkrimi	I pranueshmë si null
`countries`	string[]	Një listë e kodeve ISO të vendeve me dy karaktere.	false

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

Parametrat e Përgjigjes së Gabimit

Emri	Lloji	Përshkrimi	I pranueshmë si null
`errors[]`	string[]	Një listë tekstesh që shpjegojnë gabimin.	false

Lëviz Lart

GET/mccmncse mbrojtur

Ky endpoint kthen një listë gjithëpërfshirëse të operatorëve të rrjeteve celulare së bashku me identifikuesit e tyre përkatës MCCMNC dhe informacione shtesë kontekstuale.

Kërkesë Përgjigje e Suksesshme Përgjigje Gabimi

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

Parametrat e Kërkesës

Çelësi	Lloji	Përshkrimi	Parazgjedhur	I detyrueshëm
`countrycode`	string(2)	Një kod shteti ISO me dy shkronja opsional që përdoret për të filtruar rezultatet MCCMNC, duke kthyer vetëm regjistrimet e lidhura me shtetin e specifikuar.	null	opsionale

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

Atributet e Përgjigjes së Suksesshme

Emri	Lloji	Përshkrimi	I pranueshmë si null
`items`	object[]	Një listë e operatorëve të rrjeteve celulare.	false
`country_name`	string	Emri i plotë i shtetit në anglisht.	false
`country_code`	string(2)	Një kod shteti ISO me dy shkronja që përfaqëson shtetin e operatorit celular.	false
`mccmnc`	string(5\|6)	Një varg me pesë ose gjashtë karaktere që përfaqëson MCCMNC-në, e cila identifikon në mënyrë unike operatorin e rrjetit celular.	false
`mcc`	string(3)	Një Kod Shteti Celular (MCC) me tre karaktere që identifikon shtetin ku operon rrjeti celular.	false
`mnc`	string(2\|3)	Një Kod Rrjeti Celular (MNC) me dy ose tre karaktere që specifikon rrjetin celular brenda MCC-së së dhënë.	false
`brand`	string	Emri komercial i markës nën të cilin operon rrjeti dhe njihet nga konsumatorët.	true
`operator`	string	Emri zyrtar i operatorit të rrjetit celular, zakonisht entiteti ligjor që menaxhon rrjetin.	true
`parent_mccmnc`	string(5\|6)	Një varg me pesë ose gjashtë karaktere që përfaqëson MCCMNC-në e operatorit mëmë të rrjetit celular, nëse ekziston.	true

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

Parametrat e Përgjigjes së Gabimit

Emri	Lloji	Përshkrimi	I pranueshmë si null
`errors[]`	string[]	Një listë tekstesh që shpjegojnë gabimin.	false

Lëviz Lart

GET/pricee mbrojtur

Ky endpoint kthen çmimin për një kërkesë HLR, MNP ose NT.

Kërkesë Përgjigje e Suksesshme Përgjigje Gabimi

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

Parametrat e Kërkesës

Çelësi	Lloji	Përshkrimi	Parazgjedhur	I detyrueshëm
`msisdn`	string	Numri i telefonit për të cilin dëshironi të merrni çmimin. Në format ndërkombëtar.	null	i detyrueshëm
`route_type`	string	Lloji i rrugës, d.m.th. `HLR`, `MNP`, `NT`.	null	i detyrueshëm
`route`	string(3)	Rruga për të cilën duhet të llogaritet çmimi. Paracaktohet në rrugën e përcaktuar nga rutimi i automatizuar.	null	opsionale

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

Atributet e Përgjigjes së Suksesshme

Emri	Lloji	Përshkrimi	I pranueshmë si null
`price`	object	Një objekt me detaje çmimi.	false
`amount`	string	Shuma në EUR.	false
`msisdn`	string	MSISDN për të cilin aplikohet ky çmim.	false
`route_type`	string(2\|3)	Lloji i rrugës për të cilën aplikohet ky çmim.	false
`route`	string(3)	Rruga për të cilën aplikohet ky çmim.	false

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

Parametrat e Përgjigjes së Gabimit

Emri	Lloji	Përshkrimi	I pranueshmë si null
`errors[]`	string[]	Një listë tekstesh që shpjegojnë gabimin.	false

Lëviz Lart

GET/price-liste mbrojtur

Ky endpoint kthen çmimet në llogarinë tuaj.

Kërkesë Përgjigje e Suksesshme Përgjigje Gabimi

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

Atributet e Përgjigjes së Suksesshme

Emri	Lloji	Përshkrimi	I pranueshmë si null
`pricing`	object[]	Një listë objektesh me informacion çmimesh.	false
`route`	string	Rruga për të cilën aplikohet ky çmim.	false
`countrycode`	string	Kodi ISO me dy karaktere i vendit për të cilin aplikohet ky çmim për rrugën përkatëse, nëse ka.	true
`countryname`	string	Emri i vendit në anglisht që korrespondon me kodin e vendit, nëse ka.	true
`mccmnc`	string	MCCMNC për të cilin aplikohet ky çmim për rrugën përkatëse, nëse ka. Anashkalon çmimin në nivel vendi.	true
`cns`	string	Prefiksi i telefonimit për të cilin aplikohet ky çmim për rrugën përkatëse, nëse ka. Anashkalon çmimin në nivel vendi dhe çmimin në nivel MCCMNC.	true
`route_type`	string	Lloji i rrugës përkatëse, d.m.th. `HLR`, `MNP`, `NT`.	false
`route_type`	string	Çmimi përkatës në EUR.	false

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

Parametrat e Përgjigjes së Gabimit

Emri	Lloji	Përshkrimi	I pranueshmë si null
`errors[]`	string[]	Një listë tekstesh që shpjegojnë gabimin.	false

Lëviz Lart

GET/balancee mbrojtur

Ky endpoint merr balancën aktuale të llogarisë suaj, duke ju lejuar të automatizoni proceset bazuar në statusin tuaj të kredisë. Funksionon në mënyrë të qetë me emailet e njoftimit për kredi të ulët që mund të konfiguroni në faqen e pagesave.

Kërkesë Përgjigje e Suksesshme Përgjigje Gabimi

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

{
    "balance":"1002.90"
}

Atributet e Përgjigjes së Suksesshme

Emri	Lloji	Përshkrimi	I pranueshmë si null
`balance`	string	Balanca aktuale e llogarisë suaj në EUR. Një vlerë dhjetore e tipit string.	false

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

Parametrat e Përgjigjes së Gabimit

Emri	Lloji	Përshkrimi	I pranueshmë si null
`errors[]`	string[]	Një listë tekstesh që shpjegojnë gabimin.	false

Lëviz Lart

GET/pingpublik

Ky endpoint dërgon një kërkesë ping në API, duke ofruar një metodë të thjeshtë për të testuar lidhjen tuaj me API-në e HLR Lookups.

Kërkesë Përgjigje e Suksesshme Përgjigje Gabimi

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

{
    "success":true
}

Atributet e Përgjigjes së Suksesshme

Emri	Lloji	Përshkrimi	I pranueshmë si null
`success`	boolean	Tregon se kërkesa është përpunuar me sukses.	false

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

Parametrat e Përgjigjes së Gabimit

Emri	Lloji	Përshkrimi	I pranueshmë si null
`errors[]`	string[]	Një listë tekstesh që shpjegojnë gabimin.	false

Lëviz Lart

GET/timepublik

Ky endpoint kthen një vulë kohore Unix që përfaqëson kohën aktuale në serverin e HLR Lookups. Përdoreni për të sinkronizuar orën e serverit tuaj kur gjeneroni nënshkrimin Digest-Auth për autentifikim, duke siguruar që çdo mospërputhje midis kohës së serverit tuaj dhe kohës së serverit HLR Lookups të korrigjohet.

Kërkesë Përgjigje e Suksesshme Përgjigje Gabimi

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

{
    "time":1525898643
}

Atributet e Përgjigjes së Suksesshme

Emri	Lloji	Përshkrimi	I pranueshmë si null
`time`	integer	Vulë kohore Unix që përfaqëson kohën aktuale të serverit HLR Lookups.	false

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

Parametrat e Përgjigjes së Gabimit

Emri	Lloji	Përshkrimi	I pranueshmë si null
`errors[]`	string[]	Një listë tekstesh që shpjegojnë gabimin.	false

Lëviz Lart

GET/auth-teste mbrojtur

Ky endpoint shërben si test fillestar për implementimin tuaj Basic-Auth ose, më mirë, Digest-Auth.

Kërkesë Basic Auth Kërkesë Digest Auth Përgjigje e Suksesshme Përgjigje Gabimi

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

Header-at e Kërkesës

Çelësi	Lloji	Përshkrimi
`X-Basic`	string	Hash SHA256 i `YOUR_API_KEY:YOUR_API_SECRET`. Përfshini simbolin e pikës së dy (:) 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-at e Kërkesës

Çelësi	Lloji	Përshkrimi
`X-Digest-Key`	string	Çelësi juaj API për HLR Lookups
`X-Digest-Signature`	string	Nënshkrim unik Digest-Auth (shihni autentifikimin)
`X-Digest-Timestamp`	integer	Kohëmatësi aktual Unix (shihni gjithashtu `GET /time`)

{
    "success":true
}

Atributet e Përgjigjes së Suksesshme

Emri	Lloji	Përshkrimi	I pranueshmë si null
`success`	boolean	Tregon se kërkesa është përpunuar me sukses.	false

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

Parametrat e Përgjigjes së Gabimit

Emri	Lloji	Përshkrimi	I pranueshmë si null
`errors[]`	string[]	Një listë tekstesh që shpjegojnë gabimin.	false

Lëviz Lart

Dokumentacioni i API-së së Vjetër

Ju lutemi vini re se API-ja e vjetër është nxjerrë jashtë përdorimit dhe është planifikuar për pensionim në të ardhmen. Ne rekomandojmë fuqimisht përditësimin në versionin më të fundit sa më shpejt të jetë e mundur.

Nëse keni implementuar API-në tonë të HLR Lookups midis viteve 2013 dhe fillimit të vitit 2020, ju po përdorni API-në tonë të vjetër. Ju lutemi referojuni dokumentacionit tonë të API-së së vjetër në atë rast.

Dokumentacioni i API-së së Vjetër

Dokumentacioni i API

Fillimi

Kërkim HLR

Kërkim MNP

Kërkim NT

Rutim

Çmimet

Mjete

Fillimi

Përdorimi i API-së HLR Lookups

Shembull Kërkese

Shembull Payload

Përgjigje e Suksesshme application/json

Shërbime Shtesë Kërkimi

Kërkim i Portabilitetit të Numrit Celular (MNP)

Kërkim i Zbulimit të Llojit të Numrit (NT)

Mjete Zhvillimi Softuerësh (SDK)

Mjete

Nuk Jeni Zhvillues?

Autentifikimi

Çelësi API dhe Sekreti API

HTTP Basic Auth

E Rekomanduar: Header X-Basic me SHA256

Kërkesë Basic Auth

Header-at e Autentifikimit Basic

Shembull Kodi

Shembull Kërkese

Header-at e Kërkesës

Krijimi i Nënshkrimit

Komponentët e Nënshkrimit Digest

Shembuj Kodi

Koncepte

API-ja Sinkrone e Kërkimit HLR

API për Kërkime HLR Asinkrone

SDK-të (Kitet e Zhvillimit të Softuerit)

SDK PHP

SDK NodeJS

SDK Ruby

POST/hlr-lookupe mbrojtur

Ngarkesa

Parametrat e Kërkesës

Atributet e Përgjigjes së Suksesshme

Parametrat e Përgjigjes së Gabimit

POST/hlr-lookupse mbrojtur

Ngarkesa

Parametrat e Kërkesës

Atributet e Përgjigjes së Suksesshme

Parametrat e Përgjigjes së Gabimit

Përpunimi i Webhook-ave

Autentifikimi

Shembull Kodi

Konfirmimi i Marrjes

Ngarkesa e Webhook-ut

Atributet e Payload të Webhook

POST/mnp-lookupe mbrojtur

Ngarkesa

Parametrat e Kërkesës

Atributet e Përgjigjes së Suksesshme

Parametrat e Përgjigjes së Gabimit

POST/mnp-lookupse mbrojtur

Ngarkesa

Parametrat e Kërkesës

Atributet e Përgjigjes së Suksesshme

Parametrat e Përgjigjes së Gabimit

Përpunimi i Webhook-ave

Autentifikimi

Shembull Kodi

Konfirmimi i Marrjes

Ngarkesa e Webhook-ut

Atributet e Payload të Webhook

POST/nt-lookupe mbrojtur

Ngarkesa

Parametrat e Kërkesës

Atributet e Përgjigjes së Suksesshme

Parametrat e Përgjigjes së Gabimit

POST/nt-lookups e mbrojtur

Ngarkesa

Parametrat e Kërkesës

Atributet e Përgjigjes së Suksesshme

Parametrat e Përgjigjes së Gabimit