Pradžia

Pasaulinė mobiliojo tinklo infrastruktūra veikia SS7 signalizacijos tinklo pagrindu. Šis tinklas užtikrina abonentų duomenų mainus, skambučių maršrutizavimą, SMS perdavimą ir realaus laiko mobiliojo ryšio būsenos atnaujinimus tarp operatorių. Kiekvienas mobilusis tinklas valdo namų vietos registrą (HLR) - pagrindinę duomenų bazę, kurioje saugoma esminė informacija apie jo abonentus.

HLR užklausos technologija leidžia įmonėms užklausti šiuos registrus ir gauti realaus laiko ryšio bei tinklo informaciją apie bet kurį mobiliojo telefono numerį. Tai apima informaciją, ar telefonas yra įjungtas, kuriam tinklui jis šiuo metu priskirtas, ar numeris buvo perkeltas, ar numeris yra galiojantis ar išjungtas, ir ar jis yra tarptinkliniame ryšyje.

HLR Lookups API suteikia sklandžią, realaus laiko prieigą prie šių duomenų, leidžiančią įmonėms patikrinti mobiliuosius numerius, optimizuoti maršrutizavimą ir pagerinti komunikaciją su klientais. Ši dokumentacija padės integruoti HLR Lookups į jūsų programinę įrangą, įgalinant automatinį realaus laiko mobiliosios žvalgybos duomenų gavimą.

HLR Lookups API naudojimas

HLR užklausų vykdymas yra greitas, saugus ir paprastas. Kai užsiregistruosite ir gausite savo API raktą, galėsite autentifikuotis ir inicijuoti momentines užklausas paprastais HTTP POST užklausomis per POST /hlr-lookup. Taip pat galite apdoroti didelius duomenų rinkinius pasirinkdami greitas asinchronines API užklausas, kurių rezultatai perduodami į jūsų serverį per webhook, kaip paaiškinta koncepcijų skyriuje.

Užklausos pavyzdys

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"

Autentifikacija teikiama per HTTP antraštes, o payload.json turėtų (bent jau) turėti šį JSON objektą:

Duomenų pavyzdys

{
   "msisdn": "+14156226819"
}

Sėkmingai įvykdžius užklausą, gausite atsakymą su realaus laiko ryšio informacija apie nurodytą mobiliojo telefono numerį.

Sėkmingo atsakymo pavyzdys 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"
}

Išsamų užklausos ir atsakymo atributų bei ryšio būsenų aprašymą rasite POST /hlr-lookup.

Papildomos užklausų paslaugos

Mobiliųjų numerių perkėlimo (MNP) užklausos

Naudokite MNP užklausas, kad nustatytumėte tinklo nuosavybę ir perkėlimo informaciją be realaus laiko ryšio užklausų. Jei jums reikia tik numerio MCCMNC, žr. POST /mnp-lookup.

Numerio tipo nustatymo (NT) užklausos

Nustatykite, ar telefono numeris priklauso fiksuotojo ryšio linijai, mobiliajam, mokamam, VoIP, pranešimų gavikliui ar kitoms numeracijos plano kategorijoms su POST /nt-lookup.

Programinės įrangos kūrimo rinkiniai (SDK)

HLR Lookups API veikia su bet kuriuo REST klientu bet kuria programavimo kalba, ir mes paskelbėme SDK PHP, Ruby ir NodeJS mūsų GitHub platformoje, kad padėtume greitai pradėti.

Įrankiai

Siekdami užtikrinti sklandžią kūrimo patirtį, siūlome išsamų įrankių rinkinį, įskaitant naršyklėje veikiančią API užklausų ir webhook stebėseną, IP adresų baltąjį sąrašą, patikimas autentifikacijos parinktis ir autentifikacijos testinį galutinį tašką.

Ne programuotojas?

HLR užklausas ir numerių perkėlimo užklausas galima atlikti be programavimo. Sužinokite daugiau apie mūsų įmonių žiniatinklio klientą ir naršyklėje veikiančias ataskaitų funkcijas.

Autentifikacija

Siekiant užtikrinti saugumą ir tinkamą prieigos kontrolę, daugumai užklausų HLR Lookups API reikalinga autentifikacija. Galutiniai taškai skirstomi į viešus arba apsaugotus. Kreipdamiesi į apsaugotą galutinį tašką, jūsų užklausa turi būti autentifikuota naudojant API raktą ir slaptąjį kodą per Digest-Auth arba Basic-Auth metodą. Digest-Auth yra saugesnis variantas ir yra primygtinai rekomenduojamas. Naudokite GET /auth-test galutinį tašką, kad patikrintumėte savo autentifikacijos nustatymus.

API raktas ir API slaptasis kodas

Gaukite savo API raktą ir slaptąjį kodą API nustatymų puslapyje. Taip pat galite sukonfigūruoti pageidaujamą autentifikacijos metodą ir įjungti IP adresų baltąjį sąrašą papildomam saugumui. Jei įtariate, kad jūsų API slaptasis kodas buvo pažeistas, bet kuriuo metu galite sugeneruoti naują.

Pagrindinė autentifikacija Digest autentifikacija IP Baltasis Sąrašas

Standartinė pagrindinė autentifikacija yra lengvai įgyvendinama ir plačiai palaikoma. Galite autentifikuotis perduodami savo API raktą ir slaptąjį kodą kaip user:pass porą HTTP užklausoje.

HTTP pagrindinė autentifikacija

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

Tai siunčia Authorization antraštę:

Authorization: Basic BASE64(YOUR_API_KEY:YOUR_API_SECRET)

Rekomenduojama: X-Basic antraštė su SHA256

Siekiant pagerinto saugumo, galite siųsti SHA256 maišą savo prisijungimo duomenų vietoj jų tiesioginio perdavimo kaip base64. Norėdami naudoti šį metodą, apskaičiuokite savo YOUR_API_KEY:YOUR_API_SECRET poros maišą ir siųskite jį per X-Basic antraštę:

Pagrindinės autentifikacijos užklausa

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

Pagrindinės autentifikacijos antraštės

Raktas	Tipas	Aprašymas
`X-Basic`	string	SHA256 maišas `YOUR_API_KEY:YOUR_API_SECRET`. Į maišą įtraukite dvitaškio simbolį (:).	privalomas

Kodo pavyzdys

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

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

Digest-Auth yra rekomenduojamas metodas prieigai prie apsaugotų HLR Lookup API galutinių taškų užtikrinti. Kiekviena užklausa turi turėti šias antraštes: X-Digest-Key, X-Digest-Signature ir X-Digest-Timestamp, kurios paaiškintos žemiau.

Užklausos pavyzdys

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"

Užklausos antraštės

Raktas	Tipas	Aprašymas
`X-Digest-Key`	string	Jūsų unikalus HLR Lookups API raktas.	privalomas
`X-Digest-Signature`	string	Unikalus autentifikacijos parašas (žr. žemiau).	privalomas
`X-Digest-Timestamp`	integer	Dabartinė Unix laiko žyma (taip pat žr. `GET /time`).	privalomas

Parašo sudarymas

X-Digest-Signature sukuriamas naudojant SHA256 HMAC maišą, o jūsų API slaptasis kodas naudojamas kaip bendras raktas.

Maišuojama eilutė sudaryta taip:

ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY

. simbolis reiškia eilučių sujungimą.

Digest parašo komponentai

Komponentas	Tipas	Aprašymas
`ENDPOINT_PATH`	string	Užklaustas API galutinis taškas, pvz., `/auth-test` mažosiomis raidėmis.
`UNIX_TIMESTAMP`	integer	Dabartinė Unix laiko žyma (turi būti per 30 sekundžių). Žr. `GET /time`.
`REQUEST_METHOD`	string	Naudojamas HTTP metodas, pvz., `POST` arba `GET`.
`REQUEST_BODY`	string	Užklausos turinio duomenys. Nustatykite į `null` `GET` užklausoms.

Kodo pavyzdžiai

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)

Slinkti aukštyn

Sąvokos

HLR užklausų įdiegimas bet kokia programavimo kalba ar sistemoje naudojant mūsų HTTP REST API yra paprastas ir efektyvus. Su paprasta integracijos procedūra galite pradėti užklausas mobiliuosiuose tinkluose realiu laiku ir iškart gauti informaciją apie telefono numerio galiojimą, ryšio būseną ir maršrutizavimo detales.

Tinkamo API pasirinkimas priklauso nuo jūsų konkretaus panaudojimo atvejo. Jei jums reikalingi realaus laiko užklausų rezultatai tokioms programoms kaip VoIP telefonija, sukčiavimo aptikimas ar SMS maršrutizavimas, geriausias pasirinkimas yra sinchroninis API. Tačiau jei jūsų panaudojimo atvejis apima didelio kiekio apdorojimą, masines užklausas ar didelio masto duomenų tikrinimą, asinchroninis API siūlo optimizuotą našumą su pralaidumo efektyvumu ir masinių užklausų galimybėmis.

Sukonfigūruokite API naudoti vieną iš mūsų pritaikytų maršrutizavimo parinkčių, kad optimizuotumėte greitį, tikslumą ir kaštų efektyvumą. Taip pat galite saugoti užklausų rezultatus saugyklose, kad lengvai atsisiųstumėte CSV ir JSON ataskaitas bei naudotumėte išplėstinę analitiką per žiniatinklio sąsają.

Sinchroninis HLR užklausų API

POST /hlr-lookup galinis taškas apdoroja vieną mobiliojo telefono numerį (MSISDN) vienai užklausai ir grąžina rezultatus iškart HTTP atsakymo turinyje. Rezultatai pateikiami JSON formatu ir yra idealūs realaus laiko programoms, įskaitant mobiliojo numerio patvirtinimą, skambučių maršrutizavimą ir SMS žinučių pristatymą.

Sinchroninį API kvietimą sudaro tiesioginė HTTP užklausa ir atsakymas. Jūsų sistema pateikia vieną MSISDN (mobilųjį numerį) vienai užklausai ir gauna nedelsiantį atsakymą su realaus laiko HLR užklausos rezultatais JSON formatu. Šis API yra optimizuotas panaudojimo atvejams, kuriems reikalingas akimirksnis patvirtinimas ir ryšio patikrinimai, pavyzdžiui, sukčiavimo aptikimas, VoIP skambučių maršrutizavimas ir SMS šliuzų optimizavimas.

Asinchroninė HLR užklausų API

POST /hlr-lookups galinis taškas yra skirtas masiniam ir didelio kiekio apdorojimui, leidžiantis pateikti iki 1,000 MSISDN vienai užklausai. Vietoj to, kad grąžintų rezultatus iškart, šis API naudoja automatinius webhook'us, kad palaipsniui siųstų rezultatus į jūsų serverį. Užklausų rezultatai grąžinami kaip JSON objektai per HTTP POST atgalinius iškvietimus.

Asinchroninis API yra optimizuotas greičiui, efektyvumui ir išplečiamumui. Jis pašalina tinklo vėlavimo problemas, susijusias su sinchroniniais kvietimais, todėl yra idealus įmonėms, kurioms reikalingos didelio našumo užklausos. Jūsų sistema pateikia iki 1,000 MSISDN vienai užklausai, o mūsų platforma juos apdoroja lygiagrečiai, grąžindama rezultatus į jūsų serverį per HTTP webhook'us paketais iki 1,000 rezultatų vienam atgaliniam iškvietimui.

SDK (programinės įrangos kūrimo rinkiniai)

Mūsų programinės įrangos kūrimo rinkiniai (SDK) PHP, NodeJS ir Ruby kalboms supaprastina integracijos procesą, leidžiant efektyviai ir minimaliai pastangų prisijungti prie HLR Lookups API.

Šie SDK suteikia iš anksto sukurtas funkcijas, autentifikavimo valdymą ir struktūrizuotus API užklausų šablonus, sumažinant kūrimo laiką ir užtikrinant geriausią praktiką.

Peržiūrėkite visą turimų SDK sąrašą GitHub platformoje ir pradėkite integruoti jau šiandien.

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

Peržiūrėti 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   }

Peržiūrėti 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)

Peržiūrėti GitHub README.md

Slinkti aukštyn

POST/hlr-lookupapsaugota

Atlieka sinchroninį HLR užklausą, pateikdama realaus laiko mobiliojo telefono ryšio ir pernešamumo duomenis tiesiogiai iš tinklo operatorių. Ši galutinė užklausa yra ideali tiesioginiam srautui, kai laiko jautrioms programoms reikalingas momentinis patvirtinimas, ar telefono numeris šiuo metu yra pasiekiamas (prijungtas) ar nepasiekiamas (išjungtas). Be to, ji padeda atskirti aktyvius numerius nuo netinkamų, nežinomų ar netikrų.

Didelių duomenų rinkinių paketiniam apdorojimui, kai nereikalingi momentiniai rezultatai, rekomenduojame naudoti asinchroninę POST /hlr-lookups, kuri optimizuota didelio greičio paketiniam apdorojimui.

Jei jūsų pagrindinis tikslas yra gauti mobiliojo numerio pernešamumo duomenis (MCCMNC) ir jums nereikalinga tiesioginė ryšio būsena, POST /mnp-lookup suteikia ekonomišką alternatyvą mobiliojo numerio pernešamumo užklausoms.

Užklausa Sėkmingo atsakymo pavyzdys Klaidos atsakymo pavyzdys Būsenų žinynas

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

Duomenys

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

Užklausos parametrai

Raktas	Tipas	Aprašymas	Numatytasis	Privalomas
`msisdn`	string	Mobiliojo telefono numeris (MSISDN), kurį reikia užklausti, pateiktas tarptautiniu formatu (pvz., +14156226819 arba 0014156226819). Šalies kodai yra privalomi.	null	privalomas
`route`	string(3)	Neprivalomas trijų simbolių identifikatorius, nurodantis šios užklausos maršrutą. Nustatykite į `null` arba praleiskite šį parametrą, kad pritaikytumėte savo pasirinktinį maršrutizavimo planą arba leistumėte mūsų sistemai automatiškai nustatyti geriausią maršrutą šiai užklausai.	null	neprivaloma
`storage`	string	Neprivalomas saugyklos identifikatorius, nurodantis ataskaitą, kurioje rezultatai bus saugomi rankiniam peržiūrėjimui, analitikai ir ataskaitoms. Sistema automatiškai prideda laiko žymą su einamuoju mėnesiu. Jei praleista arba nustatyta į `null`, sistema automatiškai sugrupuos rezultatus pagal mėnesį ataskaitų tikslais.	null	neprivaloma

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

Sėkmingo atsakymo atributai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`id`	string(12)	Unikalus identifikatorius, priskirtas šiam užklausos paieškos užklausai.	false
`msisdn`	string	Mobilaus telefono numeris, apie kurį teiraujamasi, suformatuotas tarptautiniu formatu (pvz., +14156226819 arba 0014156226819).	false
`connectivity_status`	string	Nurodo, ar numerio ryšio būsena buvo sėkmingai gauta. Galimos reikšmės: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` arba `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Penkių arba šešių skaitmenų mobiliojo ryšio šalies kodas (MCC) ir mobiliojo ryšio tinklo kodas (MNC), identifikuojantis tinklą, kuris šiuo metu susietas su telefono numeriu.	true
`mcc`	string(3)	Trijų skaitmenų mobiliojo ryšio šalies kodas (MCC), identifikuojantis šalį, kurioje užregistruotas telefono numeris.	true
`mnc`	string(2\|3)	Dviejų arba trijų skaitmenų mobiliojo ryšio tinklo kodas (MNC), identifikuojantis konkretų tinklą, kuriam priklauso telefono numeris.	true
`imsi`	string	Tarptautinis mobilaus abonento identifikatorius (IMSI) - unikalus SIM kortelės, susietos su šiuo numeriu, identifikatorius. Prieinamumas priklauso nuo tinklo konfigūracijos.	true
`msin`	string(10)	Mobilios prenumeratos identifikacinis numeris (MSIN) mobiliojo operatoriaus duomenų bazėje. Prieinamumas priklauso nuo tinklo konfigūracijos.	true
`msc`	string(12)	Mobiliojo ryšio komutacijos centras (MSC), šiuo metu tvarkantis šio abonento ryšius. Prieinamumas priklauso nuo tinklo konfigūracijos.	true
`original_network_name`	string	Pradinio (gimtojo) tinklo operatoriaus pavadinimas, susietas su šiuo numeriu.	true
`original_country_name`	string	Pilnas šalies, kurioje buvo iš pradžių užregistruotas mobilaus telefono numeris, pavadinimas anglų kalba.	true
`original_country_code`	string(2)	Dviejų simbolių ISO šalies kodas, nurodantis šalį, kurioje telefono numeris buvo pirmą kartą priskirtas.	true
`original_country_prefix`	string	Tarptautinis skambinimo kodas (šalies skambinimo kodas), atitinkantis pradinę mobilaus telefono numerio šalį.	true
`is_ported`	boolean	Nurodo, ar mobilusis numeris buvo perkeltas iš pradinio tinklo pas kitą operatorių.	true
`ported_network_name`	string	Tinklo operatoriaus, pas kurį buvo perkeltas mobilusis numeris, pavadinimas (jei taikoma).	true
`ported_country_name`	string	Šalies, į kurią buvo perkeltas mobilusis numeris, pavadinimas (jei taikoma).	true
`ported_country_code`	string(2)	Dviejų simbolių ISO šalies kodas, nurodantis šalį, į kurią buvo perkeltas mobilusis numeris (jei taikoma).	true
`ported_country_prefix`	string	Tarptautinis skambinimo kodas (šalies skambinimo kodas) šaliai, į kurią buvo perkeltas mobilusis numeris (jei taikoma).	true
`is_roaming`	boolean	Nurodo, ar mobilusis numeris šiuo metu veikia tarptautiniame ryšyje (roaming) užsienio tinkle. Tarptautinio ryšio būsenos prieinamumas priklauso nuo mobiliojo ryšio operatoriaus.	true
`roaming_network_name`	string	Tinklo, kuriame mobilusis numeris šiuo metu veikia tarptautiniame ryšyje, pavadinimas (jei taikoma).	true
`roaming_country_name`	string	Šalies, kurioje mobilusis numeris šiuo metu veikia tarptautiniame ryšyje, pavadinimas (jei taikoma).	true
`roaming_country_code`	string(2)	Dviejų simbolių ISO šalies kodas šalies, kurioje mobilusis numeris šiuo metu veikia tarptautiniame ryšyje (jei taikoma).	true
`roaming_country_prefix`	string	Tarptautinis skambinimo kodas (šalies skambinimo kodas) šalies, kurioje mobilusis numeris šiuo metu veikia tarptautiniame ryšyje (jei taikoma).	true
`cost`	string	Dešimtainė reikšmė, pateikta kaip eilutė, nurodanti paieškos kainą eurais.	true
`timestamp`	string	W3C formato laiko žyma su laiko juosta, nurodanti, kada paieška buvo užbaigta.	true
`storage`	string	Saugyklos, kurioje buvo išsaugoti paieškos rezultatai, pavadinimas. Tai atitinka ataskaitų pavadinimus ir CSV atsisiuntimus, prieinamus per žiniatinklio sąsają.	true
`route`	string(3)	Trijų simbolių identifikatorius, nurodantis maršrutizavimo metodą, naudotą šiai paieškos užklausai.	true
`processing_status`	string	Paieškos apdorojimo rezultatas. Galimos reikšmės: `COMPLETED` (sėkminga), `REJECTED` (tinklas nepasiekiamas, mokestis netaikomas) arba `FAILED` (apdorojimo metu įvyko klaida).	false
`error_code`	integer	Neprivalomas vidinis klaidos kodas, pateikiantis papildomą diagnostinę informaciją klientų aptarnavimui.	true
`error_description`	string	Trumpas nurodyto klaidos kodo (jei yra) paaiškinimas anglų kalba paprastu tekstu.	true
`data_source`	string	Duomenų šaltinis, naudotas šiai užklausai. Galimos reikšmės: `LIVE_HLR` (realiaus laiko HLR užklausa) arba `MNP_DB` (statinė mobiliojo numerio perkėlimo duomenų bazė). Daugiau informacijos rasite maršrutizavimo parinktyse.	false
`routing_instruction`	string	Dvitaškiu atskirta eilutė, aprašanti užklausoje naudotą maršrutizavimo instrukciją. Pirmasis komponentas yra `STATIC`, kai nurodėte maršrutą, arba `AUTO` automatiniam maršrutizavimui; antrasis komponentas yra maršruto identifikatorius, o automatinio maršrutizavimo užklausoms trečiasis komponentas rodo kilmę, pagal kurią priimtas maršrutizavimo sprendimas (t.y. `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."
    ]
}

Klaidos atsakymo parametrai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`errors[]`	string[]	Eilučių sąrašas, paaiškinantis klaidą.	false

Būsena	Aprašymas
CONNECTED	Numeris galiojantis, o tikslinė įranga šiuo metu prijungta prie mobiliojo tinklo. Skambučiai, SMS ir kitos paslaugos turėtų pasiekti gavėją sėkmingai.
ABSENT	Numeris galiojantis, tačiau tikslinė įranga yra išjungta arba laikinai neturi tinklo aprėpties. Žinutės ar skambučiai gali būti nepristatyti, kol įrenginys vėl prisijungs prie tinklo.
INVALID_MSISDN	Numeris negaliojantis arba šiuo metu nėra priskirtas jokiam mobiliojo tinklo abonentui. Skambučiai ir žinutės šiuo numeriu nepavyks.
UNDETERMINED	Numerio ryšio būsenos nustatyti nepavyko. Tai gali būti dėl negaliojančio numerio, SS7 klaidos atsakymo arba ryšio su tiksliniu tinklo operatoriumi trūkumo. Peržiūrėkite klaidos kodą ir jo aprašymo lauką papildomai diagnostikai.

Slinkti aukštyn

POST/hlr-lookupsapsaugota

Inicijuoja asinchroninių HLR užklausų paketą, gaunant aktualius mobiliojo telefono ryšio ir perkėlimo duomenis iš tinklo operatorių. Rezultatai pristatomi per webhook į jūsų serverį. Šis metodas optimizuotas dideliems numerių kiekiams apdoroti, kai nereikia momentinio atsako, pavyzdžiui, duomenų bazės valymui ir patikrinimui. Realaus laiko programoms, tokioms kaip skambučių maršrutizavimas ar SMS pristatymas, rekomenduojame naudoti POST /hlr-lookup galutinį tašką.

Šis galutinis taškas idealiai tinka masinio apdorojimo užduotims, kai tikslas yra identifikuoti telefono numerius, kurie šiuo metu yra pasiekiami (prijungti) arba nepasiekiami (telefonas išjungtas), kartu filtruojant negaliojančius, nepriskirtus ar netikrus numerius. Be to, pateikiama aktuali perkėlimo būsena (MCCMNC) kartu su ryšio informacija.

Prieš naudojant šį galutinį tašką, įsitikinkite, kad sukonfigūruotas webhook URL, kuris asinchroniškai gaus užklausų rezultatus. Tai galite nustatyti savo API nustatymuose.

Užklausa Sėkmingo atsakymo pavyzdys Klaidos atsakymo pavyzdys Webhooks Būsenų žinynas

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

Duomenys

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

Užklausos parametrai

Raktas	Tipas	Aprašymas	Numatytasis	Privalomas
`msisdns`	array	Mobiliųjų telefonų numerių (MSISDN) masyvas tarptautiniu formatu (pvz., +14156226819 arba 0014156226819). Galite įtraukti iki 1000 numerių vienoje užklausoje.	null	privalomas
`route`	string(3)	Neprivalomas trijų simbolių identifikatorius, nurodantis šios užklausos maršrutą. Nustatykite į `null` arba praleiskite šį parametrą, kad pritaikytumėte savo pasirinktinį maršrutizavimo planą arba leistumėte mūsų sistemai automatiškai nustatyti geriausią maršrutą šiai užklausai.	null	neprivaloma
`storage`	string	Neprivalomas saugyklos identifikatorius, nurodantis ataskaitą, kurioje rezultatai bus saugomi rankiniam peržiūrėjimui, analitikai ir ataskaitoms. Sistema automatiškai prideda laiko žymą su einamuoju mėnesiu. Jei praleista arba nustatyta į `null`, sistema automatiškai sugrupuos rezultatus pagal mėnesį ataskaitų tikslais.	null	neprivaloma

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

Sėkmingo atsakymo atributai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`accepted`	array	Objektų sąrašas su unikaliais identifikatoriais ir MSISDN numeriais, kurie buvo priimti apdoroti.	false
`accepted_count`	integer	Bendras sėkmingai priimtų apdoroti MSISDN numerių kiekis.	false
`rejected`	array	Objektų sąrašas su unikaliais identifikatoriais ir MSISDN numeriais, kurie buvo atmesti apdoroti, paprastai dėl negaliojančių numerių. Už atmestus įrašus mokestis netaikomas.	false
`rejected_count`	integer	Bendras MSISDN numerių, atmestų dėl tikrinimo klaidų, kiekis.	false
`total_count`	integer	Bendras priimtų ir atmestų MSISDN numerių, pateiktų apdoroti, skaičius.	false
`cost`	string	Dešimtainė reikšmė, pateikta kaip eilutė, nurodanti bendrą kainą eurais už priimtas užklausas.	false
`storage`	string	Saugyklos, kurioje pridedami užklausų rezultatai, pavadinimas, naudojamas ataskaitoms ir CSV atsisiuntimams per žiniatinklio sąsają.	false
`route`	string(3\|4)	Trijų ar keturių simbolių identifikatorius, nurodantis šiai užklausai naudotą maršrutą. Jei buvo prašoma automatinio maršruto parinkimo pagal numerį, rodoma AUTO.	false
`webhook_urls`	array	Webhook URL, sukonfigūruoti jūsų API nustatymuose. Rezultatai siunčiami čia.	false

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

Klaidos atsakymo parametrai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`errors[]`	string[]	Eilučių sąrašas, paaiškinantis klaidą.	false

Webhook'ų apdorojimas

Pateikus užklausą, mūsų platforma pradeda apdoroti pateiktus telefono numerius ir siunčia rezultatus į anksčiau nurodytą webhook URL adresą jūsų serveryje. Rezultatai perduodami kaip HTTP POST užklausa su JSON objektu užklausos turinyje.

Autentifikacija

Autentifikuokite webhook'ą patikrinę X-Signatures HTTP antraštę.

X-Signatures antraštė yra kabliataškiais atskirtas parašų sąrašas. Kiekvienas sąraše esantis parašas generuojamas naudojant vieną iš jūsų paskyroje sukonfigūruotų API slaptažodžių. Norėdami patikrinti webhook'ą, sugeneruokite SHA-256 maišą naudodami savo API raktą, slaptažodį ir neapdorotą HTTP turinį, tada palyginkite jį su sąraše esančiais parašais.

Sutapimas patvirtina, kad užklausa yra autentiška ir pasirašyta jūsų kontroliuojamu slaptažodžiu.

Kodo pavyzdys

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

Užklausa yra galiojanti, jei bet kuris antraštėje nurodytas parašas sutampa su SHA256 maišu, apskaičiuotu iš sujungtos jūsų API rakto, slaptažodžio ir HTTP turinio eilutės.

Gavimo patvirtinimas

Tikimasi, kad jūsų serveris atsakys HTTP būsenos kodu 200 OK, patvirtindamas sėkmingą gavimą. Jei grąžinamas bet kuris kitas atsakymo kodas, įvyksta skirtasis laikas (10 sekundžių) arba iškyla bet kokia kita pristatymo problema, sistema automatiškai pakartotinai bandys siųsti webhook'ą po vienos minutės. Jei užklausa ir toliau nepavyksta, pakartotiniai bandymai bus vykdomi pagal eksponentinio atidėjimo strategiją, su paskesniais bandymais po 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minučių.

Šis pakartotinio bandymo mechanizmas užtikrina maksimalų patikimumą pristatant užklausų rezultatus į jūsų infrastruktūrą. Tai sumažina duomenų praradimo riziką dėl laikinų tinklo problemų ar serverio prastovos.

Webhook'o duomenys

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

Webhook duomenų atributai

JSON objektas turi atributą type => HLR kartu su atributu results, kuriame pateikiamas užklausų objektų sąrašas, kaip aprašyta toliau.

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`id`	string(12)	Unikalus identifikatorius, priskirtas šiam užklausos paieškos užklausai.	false
`msisdn`	string	Mobilaus telefono numeris, apie kurį teiraujamasi, suformatuotas tarptautiniu formatu (pvz., +14156226819 arba 0014156226819).	false
`connectivity_status`	string	Nurodo, ar numerio ryšio būsena buvo sėkmingai gauta. Galimos reikšmės: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` arba `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Penkių arba šešių skaitmenų mobiliojo ryšio šalies kodas (MCC) ir mobiliojo ryšio tinklo kodas (MNC), identifikuojantis tinklą, kuris šiuo metu susietas su telefono numeriu.	true
`mcc`	string(3)	Trijų skaitmenų mobiliojo ryšio šalies kodas (MCC), identifikuojantis šalį, kurioje užregistruotas telefono numeris.	true
`mnc`	string(2\|3)	Dviejų arba trijų skaitmenų mobiliojo ryšio tinklo kodas (MNC), identifikuojantis konkretų tinklą, kuriam priklauso telefono numeris.	true
`imsi`	string	Tarptautinis mobilaus abonento identifikatorius (IMSI) - unikalus SIM kortelės, susietos su šiuo numeriu, identifikatorius. Prieinamumas priklauso nuo tinklo konfigūracijos.	true
`msin`	string(10)	Mobilios prenumeratos identifikacinis numeris (MSIN) mobiliojo operatoriaus duomenų bazėje. Prieinamumas priklauso nuo tinklo konfigūracijos.	true
`msc`	string(12)	Mobiliojo ryšio komutacijos centras (MSC), šiuo metu tvarkantis šio abonento ryšius. Prieinamumas priklauso nuo tinklo konfigūracijos.	true
`original_network_name`	string	Pradinio (gimtojo) tinklo operatoriaus pavadinimas, susietas su šiuo numeriu.	true
`original_country_name`	string	Pilnas šalies, kurioje buvo iš pradžių užregistruotas mobilaus telefono numeris, pavadinimas anglų kalba.	true
`original_country_code`	string(2)	Dviejų simbolių ISO šalies kodas, nurodantis šalį, kurioje telefono numeris buvo pirmą kartą priskirtas.	true
`original_country_prefix`	string	Tarptautinis skambinimo kodas (šalies skambinimo kodas), atitinkantis pradinę mobilaus telefono numerio šalį.	true
`is_ported`	boolean	Nurodo, ar mobilusis numeris buvo perkeltas iš pradinio tinklo pas kitą operatorių.	true
`ported_network_name`	string	Tinklo operatoriaus, pas kurį buvo perkeltas mobilusis numeris, pavadinimas (jei taikoma).	true
`ported_country_name`	string	Šalies, į kurią buvo perkeltas mobilusis numeris, pavadinimas (jei taikoma).	true
`ported_country_code`	string(2)	Dviejų simbolių ISO šalies kodas, nurodantis šalį, į kurią buvo perkeltas mobilusis numeris (jei taikoma).	true
`ported_country_prefix`	string	Tarptautinis skambinimo kodas (šalies skambinimo kodas) šaliai, į kurią buvo perkeltas mobilusis numeris (jei taikoma).	true
`is_roaming`	boolean	Nurodo, ar mobilusis numeris šiuo metu veikia tarptautiniame ryšyje (roaming) užsienio tinkle. Tarptautinio ryšio būsenos prieinamumas priklauso nuo mobiliojo ryšio operatoriaus.	true
`roaming_network_name`	string	Tinklo, kuriame mobilusis numeris šiuo metu veikia tarptautiniame ryšyje, pavadinimas (jei taikoma).	true
`roaming_country_name`	string	Šalies, kurioje mobilusis numeris šiuo metu veikia tarptautiniame ryšyje, pavadinimas (jei taikoma).	true
`roaming_country_code`	string(2)	Dviejų simbolių ISO šalies kodas šalies, kurioje mobilusis numeris šiuo metu veikia tarptautiniame ryšyje (jei taikoma).	true
`roaming_country_prefix`	string	Tarptautinis skambinimo kodas (šalies skambinimo kodas) šalies, kurioje mobilusis numeris šiuo metu veikia tarptautiniame ryšyje (jei taikoma).	true
`cost`	string	Dešimtainė reikšmė, pateikta kaip eilutė, nurodanti paieškos kainą eurais.	true
`timestamp`	string	W3C formato laiko žyma su laiko juosta, nurodanti, kada paieška buvo užbaigta.	true
`storage`	string	Saugyklos, kurioje buvo išsaugoti paieškos rezultatai, pavadinimas. Tai atitinka ataskaitų pavadinimus ir CSV atsisiuntimus, prieinamus per žiniatinklio sąsają.	true
`route`	string(3)	Trijų simbolių identifikatorius, nurodantis maršrutizavimo metodą, naudotą šiai paieškos užklausai.	true
`processing_status`	string	Paieškos apdorojimo rezultatas. Galimos reikšmės: `COMPLETED` (sėkminga), `REJECTED` (tinklas nepasiekiamas, mokestis netaikomas) arba `FAILED` (apdorojimo metu įvyko klaida).	false
`error_code`	integer	Neprivalomas vidinis klaidos kodas, pateikiantis papildomą diagnostinę informaciją klientų aptarnavimui.	true
`error_description`	string	Trumpas nurodyto klaidos kodo (jei yra) paaiškinimas anglų kalba paprastu tekstu.	true
`data_source`	string	Duomenų šaltinis, naudotas šiai užklausai. Galimos reikšmės: `LIVE_HLR` (realiaus laiko HLR užklausa) arba `MNP_DB` (statinė mobiliojo numerio perkėlimo duomenų bazė). Daugiau informacijos rasite maršrutizavimo parinktyse.	false
`routing_instruction`	string	Dvitaškiu atskirta eilutė, aprašanti užklausoje naudotą maršrutizavimo instrukciją. Pirmasis komponentas yra `STATIC`, kai nurodėte maršrutą, arba `AUTO` automatiniam maršrutizavimui; antrasis komponentas yra maršruto identifikatorius, o automatinio maršrutizavimo užklausoms trečiasis komponentas rodo kilmę, pagal kurią priimtas maršrutizavimo sprendimas (t.y. `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

Būsena	Aprašymas
CONNECTED	Numeris galiojantis, o tikslinė įranga šiuo metu prijungta prie mobiliojo tinklo. Skambučiai, SMS ir kitos paslaugos turėtų pasiekti gavėją sėkmingai.
ABSENT	Numeris galiojantis, tačiau tikslinė įranga yra išjungta arba laikinai neturi tinklo aprėpties. Žinutės ar skambučiai gali būti nepristatyti, kol įrenginys vėl prisijungs prie tinklo.
INVALID_MSISDN	Numeris negaliojantis arba šiuo metu nėra priskirtas jokiam mobiliojo tinklo abonentui. Skambučiai ir žinutės šiuo numeriu nepavyks.
UNDETERMINED	Numerio ryšio būsenos nustatyti nepavyko. Tai gali būti dėl negaliojančio numerio, SS7 klaidos atsakymo arba ryšio su tiksliniu tinklo operatoriumi trūkumo. Peržiūrėkite klaidos kodą ir jo aprašymo lauką papildomai diagnostikai.

Slinkti aukštyn

POST/mnp-lookupapsaugota

Atlieka sinchroninę MNP užklausą ir pateikia mobiliojo numerio perkeliamumą bei tinklo informaciją. Šis galinis taškas tinka, jei pagrindinis jūsų tikslas yra gauti dabartinį konkretaus mobiliojo telefono numerio MCCMNC ir nustatyti pradinius bei dabartinius tinklus realiuoju laiku.

Didelių duomenų rinkinių paketiniam apdorojimui, kai nereikalingi momentiniai rezultatai, rekomenduojame naudoti asinchroninę POST /mnp-lookups, kuri optimizuota didelio greičio paketiniam apdorojimui.

MNP užklausos patikimai nustato perkeliamumą ir tinklo informaciją, tačiau nenurodo, ar tikslinis mobilusis telefonas šiuo metu yra prijungtas prie tinklo ir pasiekiamas. Norėdami gauti tiesioginę ryšio informaciją, naudokite POST /hlr-lookup galinį tašką.

Užklausa Sėkmingo atsakymo pavyzdys Klaidos atsakymo pavyzdys

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

Duomenys

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

Užklausos parametrai

Raktas	Tipas	Aprašymas	Numatytasis	Privalomas
`msisdn`	string	Mobiliojo telefono numeris (MSISDN), kurį reikia užklausti, pateiktas tarptautiniu formatu (pvz., +14156226819 arba 0014156226819). Šalies kodai yra privalomi.	null	privalomas
`route`	string(3)	Neprivalomas trijų simbolių identifikatorius, nurodantis šios užklausos maršrutą. Nustatykite į `null` arba praleiskite šį parametrą, kad pritaikytumėte savo pasirinktinį maršrutizavimo planą arba leistumėte mūsų sistemai automatiškai nustatyti geriausią maršrutą šiai užklausai.	null	neprivaloma
`storage`	string	Neprivalomas saugyklos identifikatorius, nurodantis ataskaitą, kurioje rezultatai bus saugomi rankiniam peržiūrėjimui, analitikai ir ataskaitoms. Sistema automatiškai prideda laiko žymą su einamuoju mėnesiu. Jei praleista arba nustatyta į `null`, sistema automatiškai sugrupuos rezultatus pagal mėnesį ataskaitų tikslais.	null	neprivaloma

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

Sėkmingo atsakymo atributai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`id`	string(12)	Unikalus 12 simbolių identifikatorius šiam užklausos tikrinimui.	false
`msisdn`	string	Mobiliojo telefono numeris, įvertintas šioje užklausos patikroje.	false
`query_status`	string	Nurodo, ar perkeliamumų ir tinklo informacijos gavimas buvo sėkmingas. Galimos reikšmės: `OK` arba `FAILED`.	false
`mccmnc`	string(5\|6)	Penkių arba šešių simbolių MCCMNC (mobiliosios šalies kodas ir mobilaus tinklo kodo pora), identifikuojantis tinklą, kuriam šiuo metu priklauso mobiliojo telefono numeris.	true
`mcc`	string(3)	Trijų simbolių MCC (mobiliosios šalies kodas), nurodantis šalį, susietą su mobiliojo telefono numerio dabartiniu tinklu.	true
`mnc`	string(2\|3)	Dviejų arba trijų simbolių MNC (mobiliojo tinklo kodas), identifikuojantis dabartinį tinklo operatorių mobiliojo telefono numeriui.	true
`is_ported`	boolean	Nurodo, ar telefono numeris buvo perkeltas iš pradinio tinklo pas naują operatorių.	true
`original_network_name`	string	Savavališka eilutė (anglų kalba), nurodanti tikrinamo mobiliojo telefono numerio pradinio tinklo operatoriaus pavadinimą.	true
`original_country_name`	string	Savavališka eilutė (anglų kalba), nurodanti tikrinamo mobiliojo telefono numerio pradinę šalį.	true
`original_country_code`	string(2)	Dviejų simbolių ISO šalies kodas, nurodantis tikrinamo mobiliojo telefono numerio pradinę šalį.	true
`original_country_prefix`	string	Pradinės šalies, susietos su tikrinamu mobiliojo telefono numeriu, skambinimo kodas.	true
`ported_network_name`	string	Nurodo tinklo operatorių, pas kurį buvo perkeltas tikrinamas mobiliojo telefono numeris, jei taikoma.	true
`ported_country_name`	string	Nurodo šalį, į kurią buvo perkeltas tikrinamas mobiliojo telefono numeris, jei taikoma.	true
`ported_country_code`	string(2)	Dviejų simbolių ISO šalies kodas, nurodantis šalį, į kurią buvo perkeltas tikrinamas mobiliojo telefono numeris, jei taikoma.	true
`ported_country_prefix`	string	Šalies, į kurią buvo perkeltas tikrinamas mobiliojo telefono numeris, skambinimo kodas, jei taikoma.	true
`extra`	string	Savavališka eilutė, pateikianti pasirenkamą papildomą informaciją apie telefono numerį.	true
`cost`	string	Dešimtainė reikšmė, pateikta kaip eilutė, nurodanti šios užklausos kainą eurais.	true
`timestamp`	string	W3C formato laiko žyma su laiko juostos informacija, nurodanti, kada užklausa buvo užbaigta.	true
`storage`	string	Saugyklos pavadinimas (arba ataskaitos pavadinimas), prie kurio buvo pridėti užklausos rezultatai. Tai naudojama CSV atsisiuntimams ir ataskaitoms per internetinę sąsają.	true
`route`	string(3)	Trijų simbolių identifikatorius, nurodantis maršrutą, naudotą šiai užklausai.	true
`error_code`	integer	Pasirenkamas vidinis klaidos kodas, pateikiantis papildomą kontekstą klientų aptarnavimo diagnostikai.	true

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

Klaidos atsakymo parametrai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`errors[]`	string[]	Eilučių sąrašas, paaiškinantis klaidą.	false

Slinkti aukštyn

POST/mnp-lookupsapsaugota

Inicijuoja asinchroninių MNP (mobiliojo numerio perkėlimo) užklausų paketą, gaunant dabartinį MCCMNC ir tiksliai nustatant pradinius ir dabartinius tinklus realiuoju laiku. Rezultatai pristatomi per webhook į jūsų serverį. Šis metodas optimizuotas dideliems numerių kiekiams apdoroti, kai nereikia momentinio atsako, pavyzdžiui, duomenų bazės valymui ir patikrinimui. Realaus laiko programoms, tokioms kaip skambučių maršrutizavimas ar SMS pristatymas, rekomenduojame naudoti POST /mnp-lookup galutinį tašką.

MNP užklausos patikimai nustato perkeliamumą ir tinklo informaciją, tačiau nenurodo, ar tikslinis mobilusis telefonas šiuo metu yra prijungtas prie tinklo ir pasiekiamas. Norėdami gauti tiesioginę ryšio informaciją, naudokite POST /hlr-lookups galinį tašką.

Prieš naudojant šį galutinį tašką, įsitikinkite, kad sukonfigūruotas webhook URL, kuris asinchroniškai gaus užklausų rezultatus. Tai galite nustatyti savo API nustatymuose.

Užklausa Sėkmingo atsakymo pavyzdys Klaidos atsakymo pavyzdys Webhooks

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

Duomenys

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

Užklausos parametrai

Raktas	Tipas	Aprašymas	Numatytasis	Privalomas
`msisdns`	array	Mobiliųjų telefonų numerių (MSISDN) masyvas tarptautiniu formatu (pvz., +14156226819 arba 0014156226819). Galite įtraukti iki 1000 numerių vienoje užklausoje.	null	privalomas
`route`	string(3)	Neprivalomas trijų simbolių identifikatorius, nurodantis šios užklausos maršrutą. Nustatykite į `null` arba praleiskite šį parametrą, kad pritaikytumėte savo pasirinktinį maršrutizavimo planą arba leistumėte mūsų sistemai automatiškai nustatyti geriausius maršrutus šiai užklausai.	null	neprivaloma
`storage`	string	Neprivalomas saugyklos identifikatorius, nurodantis ataskaitą, kurioje rezultatai bus saugomi rankiniam peržiūrėjimui, analitikai ir ataskaitoms. Sistema automatiškai prideda laiko žymą su einamuoju mėnesiu. Jei praleista arba nustatyta į `null`, sistema automatiškai sugrupuos rezultatus pagal mėnesį ataskaitų tikslais.	null	neprivaloma

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

Sėkmingo atsakymo atributai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`accepted`	array	Objektų sąrašas su unikaliais identifikatoriais ir MSISDN numeriais, kurie buvo priimti apdoroti.	false
`accepted_count`	integer	Bendras sėkmingai priimtų apdoroti MSISDN numerių kiekis.	false
`rejected`	array	Objektų sąrašas su unikaliais identifikatoriais ir MSISDN numeriais, kurie buvo atmesti apdoroti, paprastai dėl negaliojančių numerių. Už atmestus įrašus mokestis netaikomas.	false
`rejected_count`	integer	Bendras MSISDN numerių, atmestų dėl tikrinimo klaidų, kiekis.	false
`total_count`	integer	Bendras priimtų ir atmestų MSISDN numerių, pateiktų apdoroti, skaičius.	false
`cost`	string	Dešimtainė reikšmė, pateikta kaip eilutė, nurodanti bendrą kainą eurais už priimtas užklausas.	false
`storage`	string	Saugyklos, kurioje pridedami užklausų rezultatai, pavadinimas, naudojamas ataskaitoms ir CSV atsisiuntimams per žiniatinklio sąsają.	false
`route`	string(3)	Trijų simbolių identifikatorius, nurodantis maršrutą, naudotą šiai užklausai.	false
`webhook_urls`	array	Webhook URL, sukonfigūruoti jūsų API nustatymuose. Rezultatai siunčiami čia.	false

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

Klaidos atsakymo parametrai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`errors[]`	string[]	Eilučių sąrašas, paaiškinantis klaidą.	false

Webhook'ų apdorojimas

Pateikus užklausą, mūsų platforma pradeda apdoroti pateiktus telefono numerius ir siunčia rezultatus į anksčiau nurodytą webhook URL adresą jūsų serveryje. Rezultatai perduodami kaip HTTP POST užklausa su JSON objektu užklausos turinyje.

Autentifikacija

Autentifikuokite webhook'ą patikrinę X-Signatures HTTP antraštę.

X-Signatures antraštė yra kabliataškiais atskirtas parašų sąrašas. Kiekvienas sąraše esantis parašas generuojamas naudojant vieną iš jūsų paskyroje sukonfigūruotų API slaptažodžių. Norėdami patikrinti webhook'ą, sugeneruokite SHA-256 maišą naudodami savo API raktą, slaptažodį ir neapdorotą HTTP turinį, tada palyginkite jį su sąraše esančiais parašais.

Sutapimas patvirtina, kad užklausa yra autentiška ir pasirašyta jūsų kontroliuojamu slaptažodžiu.

Kodo pavyzdys

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

Užklausa yra galiojanti, jei bet kuris antraštėje nurodytas parašas sutampa su SHA256 maišu, apskaičiuotu iš sujungtos jūsų API rakto, slaptažodžio ir HTTP turinio eilutės.

Gavimo patvirtinimas

Tikimasi, kad jūsų serveris atsakys HTTP būsenos kodu 200 OK, patvirtindamas sėkmingą gavimą. Jei grąžinamas bet kuris kitas atsakymo kodas, įvyksta skirtasis laikas (10 sekundžių) arba iškyla bet kokia kita pristatymo problema, sistema automatiškai pakartotinai bandys siųsti webhook'ą po vienos minutės. Jei užklausa ir toliau nepavyksta, pakartotiniai bandymai bus vykdomi pagal eksponentinio atidėjimo strategiją, su paskesniais bandymais po 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minučių.

Šis pakartotinio bandymo mechanizmas užtikrina maksimalų patikimumą pristatant užklausų rezultatus į jūsų infrastruktūrą. Tai sumažina duomenų praradimo riziką dėl laikinų tinklo problemų ar serverio prastovos.

Webhook'o duomenys

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

Webhook duomenų atributai

JSON objektas turi atributą type => MNP kartu su atributu results, kuriame pateikiamas užklausų objektų sąrašas, kaip aprašyta toliau.

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`id`	string(12)	Unikalus 12 simbolių identifikatorius šiam užklausos tikrinimui.	false
`msisdn`	string	Mobiliojo telefono numeris, įvertintas šioje užklausos patikroje.	false
`query_status`	string	Nurodo, ar perkeliamumų ir tinklo informacijos gavimas buvo sėkmingas. Galimos reikšmės: `OK` arba `FAILED`.	false
`mccmnc`	string(5\|6)	Penkių arba šešių simbolių MCCMNC (mobiliosios šalies kodas ir mobilaus tinklo kodo pora), identifikuojantis tinklą, kuriam šiuo metu priklauso mobiliojo telefono numeris.	true
`mcc`	string(3)	Trijų simbolių MCC (mobiliosios šalies kodas), nurodantis šalį, susietą su mobiliojo telefono numerio dabartiniu tinklu.	true
`mnc`	string(2\|3)	Dviejų arba trijų simbolių MNC (mobiliojo tinklo kodas), identifikuojantis dabartinį tinklo operatorių mobiliojo telefono numeriui.	true
`is_ported`	boolean	Nurodo, ar telefono numeris buvo perkeltas iš pradinio tinklo pas naują operatorių.	true
`original_network_name`	string	Savavališka eilutė (anglų kalba), nurodanti tikrinamo mobiliojo telefono numerio pradinio tinklo operatoriaus pavadinimą.	true
`original_country_name`	string	Savavališka eilutė (anglų kalba), nurodanti tikrinamo mobiliojo telefono numerio pradinę šalį.	true
`original_country_code`	string(2)	Dviejų simbolių ISO šalies kodas, nurodantis tikrinamo mobiliojo telefono numerio pradinę šalį.	true
`original_country_prefix`	string	Pradinės šalies, susietos su tikrinamu mobiliojo telefono numeriu, skambinimo kodas.	true
`ported_network_name`	string	Nurodo tinklo operatorių, pas kurį buvo perkeltas tikrinamas mobiliojo telefono numeris, jei taikoma.	true
`ported_country_name`	string	Nurodo šalį, į kurią buvo perkeltas tikrinamas mobiliojo telefono numeris, jei taikoma.	true
`ported_country_code`	string(2)	Dviejų simbolių ISO šalies kodas, nurodantis šalį, į kurią buvo perkeltas tikrinamas mobiliojo telefono numeris, jei taikoma.	true
`ported_country_prefix`	string	Šalies, į kurią buvo perkeltas tikrinamas mobiliojo telefono numeris, skambinimo kodas, jei taikoma.	true
`extra`	string	Savavališka eilutė, pateikianti pasirenkamą papildomą informaciją apie telefono numerį.	true
`cost`	string	Dešimtainė reikšmė, pateikta kaip eilutė, nurodanti šios užklausos kainą eurais.	true
`timestamp`	string	W3C formato laiko žyma su laiko juostos informacija, nurodanti, kada užklausa buvo užbaigta.	true
`storage`	string	Saugyklos pavadinimas (arba ataskaitos pavadinimas), prie kurio buvo pridėti užklausos rezultatai. Tai naudojama CSV atsisiuntimams ir ataskaitoms per internetinę sąsają.	true
`route`	string(3)	Trijų simbolių identifikatorius, nurodantis maršrutą, naudotą šiai užklausai.	true
`error_code`	integer	Pasirenkamas vidinis klaidos kodas, pateikiantis papildomą kontekstą klientų aptarnavimo diagnostikai.	true

Slinkti aukštyn

POST/nt-lookupapsaugota

Atlieka sinchroninę numerio tipo (NT) užklausą. Šis galinis taškas idealiai tinka, jei pagrindinis jūsų tikslas yra nustatyti, ar nurodyti telefono numeriai priklauso stacionariųjų, mobiliųjų, aukščiausios tarifų, VoIP, pranešimų gaviklių ar kitų numeracijos planų diapazonams realiuoju laiku.

NT užklausos patikimai nustato telefono numerio tipą, tačiau jos nerodo, ar paskirties numeris šiuo metu prijungtas prie tinklo ir pasiekiamas. Norėdami gauti tiesioginę ryšio informaciją, naudokite POST /hlr-lookup galinį tašką.

Jei jūsų naudojimo atveju reikalinga tiksli tinklo ir perkeliamų numerių informacija (MCCMNC), bet nereikia tiesioginės ryšio būsenos, naudokite POST /mnp-lookup galinį tašką mobiliųjų numerių perkeliamumui užklausti.

Užklausa Sėkmingo atsakymo pavyzdys Klaidos atsakymo pavyzdys Tipų nuoroda

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

Duomenys

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

Užklausos parametrai

Raktas	Tipas	Aprašymas	Numatytasis	Privalomas
`number`	string	Telefono numeris tarptautiniu formatu (pvz., +4989702626 arba 004989702626).	null	mandatory
`route`	string(3)	Neprivalomas trijų simbolių identifikatorius, nurodantis šios užklausos maršrutą. Nustatykite `null` arba praleiskite šį parametrą, kad pritaikytumėte savo pasirinktinį maršrutų planą arba leistumėte mūsų sistemai automatiškai nustatyti geriausius maršrutus šiai užklausai.	null	neprivaloma
`storage`	string	Neprivalomas saugyklos identifikatorius, nurodantis ataskaitą, kurioje rezultatai bus saugomi rankiniam peržiūrėjimui, analitikai ir ataskaitoms. Sistema automatiškai prideda laiko žymą su einamuoju mėnesiu. Jei praleista arba nustatyta į `null`, sistema automatiškai sugrupuos rezultatus pagal mėnesį ataskaitų tikslais.	null	neprivaloma

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

Sėkmingo atsakymo atributai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`id`	string(12)	Unikalus identifikatorius, priskirtas šiam užklausos paieškos užklausai.	false
`number`	string	Telefono numeris, kuris buvo įvertintas šios užklausos metu.	false
`number_type`	string	Nustatytas numerio tipas. Galimos reikšmės: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Nurodo, ar numerio tipo informacija buvo sėkmingai gauta. Grąžina `OK`, jei sėkminga, arba `FAILED`, jei užklausa nepavyko.	false
`is_valid`	boolean	Nurodo, ar telefono numeris yra sintaksiškai teisingas.	true
`invalid_reason`	string	Paprastas tekstinis pranešimas anglų kalba, nurodantis, kodėl telefono numeris laikomas neteisingas (pvz., "too short" arba "invalid prefix"), arba `null`, jei numeris teisingas.	true
`is_possibly_ported`	boolean	Nurodo, ar telefono numeris galėjo būti perkeltas iš pradinio operatoriaus į kitą ryšio tiekėją. Tiksliai perkėlimo informacijai naudokite MNP užklausas.	true
`is_vanity_number`	boolean	Nurodo, ar telefono numeris yra vanitinis numeris, t. y. ar jis turi raidžių simbolių.	true
`qualifies_for_hlr_lookup`	boolean	Nurodo, ar telefono numeris tinkamas papildomoms užklausoms per HLR užklausas.	true
`mccmnc`	string(5\|6)	Penkių arba šešių simbolių eilutė, nurodanti MCCMNC porą (mobiliojo ryšio šalies kodas ir mobiliojo tinklo kodas), kuri identifikuoja pradinį mobiliojo telefono numerio tinklą.	true
`mcc`	string(3)	Trijų simbolių eilutė, nurodanti MCC (mobiliojo ryšio šalies kodas), kuri identifikuoja šalį, susijusią su pradiniu telefono numerio mobiluoju tinklu.	true
`mnc`	string(2\|3)	Dviejų arba trijų simbolių eilutė, nurodanti MNC (mobiliojo tinklo kodas), kuri identifikuoja pradinį telefono numerio mobiliojo tinklo operatorių.	true
`original_network_name`	string	Savavališka anglų kalba parašyta tekstinė eilutė, nurodanti pradinio tinklo operatoriaus pavadinimą patikrinto mobiliojo telefono numerio.	true
`original_country_name`	string	Savavališka anglų kalba parašyta tekstinė eilutė, nurodanti pradinę šalį, susijusią su patikrintu mobiliuoju telefono numeriu.	true
`original_country_code`	string(2)	Dviejų simbolių ISO šalies kodas, nurodantis pradinę patikrinto mobiliojo telefono numerio šalį.	true
`regions`	array	Suprantamų anglų kalbos eilučių sąrašas, nurodantis geografinį regioną (-us), susijusį (-ius) su šiuo telefono numeriu.	true
`timezones`	array	Laiko juostų (Olson formatu) sąrašas, susijęs su šiuo telefono numeriu.	true
`info_text`	string	Savavališka eilutė, kuri gali turėti papildomos informacijos apie telefono numerį.	true
`cost`	string	Dešimtainė reikšmė, pateikta kaip eilutė, nurodanti šios užklausos kainą (EUR).	true
`timestamp`	string	W3C formato laiko žymė (su laiko juosta), nurodanti, kada užklausa buvo užbaigta.	true
`storage`	string	Nurodo saugyklos pavadinimą, kur užklausos rezultatai buvo pridėti. Tai atitinka ataskaitos pavadinimą, naudojamą CSV atsisiuntimams ir analitikai per žiniatinklio sąsają.	true
`route`	string(3)	Trijų simbolių identifikatorius, nurodantis maršrutą, naudotą šiai užklausai.	true

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

Klaidos atsakymo parametrai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`errors[]`	string[]	Eilučių sąrašas, paaiškinantis klaidą.	false

Tipas	Aprašymas
LANDLINE	Fiksuotojo ryšio telefono numeris.
MOBILE	Mobiliojo ryšio telefono numeris. Tinkamas HLR užklausoms, kad būtų gauta papildoma informacija apie ryšio būseną, tinklą, perkėlimą ir tarptinklinį ryšį.
MOBILE_OR_LANDLINE	Fiksuotojo arba mobiliojo ryšio telefono numeris. Gali būti tinkamas HLR užklausai.
TOLL_FREE	Nemokamas telefono numeris.
PREMIUM_RATE	Papildomai apmokestinamas telefono numeris su papildomomis išlaidomis.
SHARED_COST	Dalinai apmokestinamas telefono numeris. Paprastai pigesnis nei papildomai apmokestinami telefono numeriai.
VOIP	Balso perdavimo per IP telefono numeris. Apima TSoIP telefono numerius (telefonijos paslauga per IP).
PAGER	Pranešimų gaviklio telefono numeris. Paprastai neturi balso funkcijos.
UAN	Universalaus prieigos numeris (įmonės numeris). Gali būti nukreiptas į konkrečius padalinius, tačiau leidžia naudoti vieną numerį visai įmonei.
VOICEMAIL	Balso pašto telefono numeris.
UNKNOWN	Numerio tipo nustatyti nepavyko.

Slinkti aukštyn

POST/nt-lookups apsaugota

Šis galinis taškas inicijuoja asinchroninių numerio tipo užklausų seriją, o rezultatai grąžinami į jūsų serverį per webhook. Tai tinka, jei jūsų pagrindinis tikslas yra nustatyti, ar nurodyti telefono numeriai priklauso fiksuoto ryšio, mobiliojo ryšio, aukščiausios tarifo kategorijos, VoIP, pranešimų gaviklio ar kitų numeracijos plano diapazonams. Optimizuotas greitam didelių numerių kiekių apdorojimui, šis galinis taškas idealiai tinka masinėms operacijoms (pvz., duomenų bazės valymui). Tiesioginiam srautui ir laiko kritiniams atvejams naudokite POST /nt-lookup galinį tašką.

Norint naudoti šį galutinį tašką, reikia nurodyti webhook URL savo API nustatymuose.

Užklausa Sėkmingo atsakymo pavyzdys Klaidos atsakymo pavyzdys Webhooks Tipų nuoroda

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

Duomenys

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

Užklausos parametrai

Raktas	Tipas	Aprašymas	Numatytasis	Privalomas
`numbers`	array	Telefono numerių masyvas tarptautiniu formatu (pvz., +14156226819 arba 004989702626). Maksimaliai 1000 numerių gali būti įtraukta į vieną užklausą.	null	privalomas
`route`	string(3)	Neprivalomas trijų simbolių identifikatorius, nurodantis šios užklausos maršrutą. Nustatykite `null` arba praleiskite šį parametrą, kad būtų taikomas jūsų individualus maršrutizavimo žemėlapis arba leiskite mūsų sistemai automatiškai nustatyti geriausią maršrutą šiai užklausai.	null	neprivaloma
`storage`	string	Neprivalomas saugyklos identifikatorius, nurodantis ataskaitą, kurioje rezultatai bus saugomi rankiniam peržiūrėjimui, analitikai ir ataskaitoms. Sistema automatiškai prideda laiko žymą su einamuoju mėnesiu. Jei praleista arba nustatyta į `null`, sistema automatiškai sugrupuos rezultatus pagal mėnesį ataskaitų tikslais.	null	neprivaloma

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

Sėkmingo atsakymo atributai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`accepted`	array	Objektų masyvas, kur kiekvienas objektas turi unikalų identifikatorių ir telefono numerį, priimtą apdorojimui.	false
`accepted_count`	integer	Bendras telefono numerių, priimtų apdorojimui, skaičius.	false
`rejected`	array	Objektų masyvas, kur kiekvienas objektas turi unikalų identifikatorių ir telefono numerį, atmestą apdorojimui. Paprastai šie numeriai yra netinkami ir mokestis netaikomas.	false
`rejected_count`	integer	Bendras telefono numerių, atmestų apdorojimui, skaičius.	false
`total_count`	integer	Bendras priimtų ir atmestų telefono numerių, pateiktų apdorojimui, skaičius.	false
`cost`	string	Eilutė, nurodanti dešimtainę reikšmę, kuri rodo šių užklausų kainą eurais.	false
`storage`	string	Saugyklos (ataskaitos) pavadinimas, kurioje buvo pridėti užklausos rezultatai. Šis pavadinimas naudojamas CSV atsisiuntimams ir analitikai per žiniatinklio sąsają.	false
`route`	string(3)	Trijų simbolių identifikatorius, nurodantis šiai užklausai naudotą maršrutą.	false
`webhook_urls`	array	Webhook URL, sukonfigūruoti jūsų API nustatymuose. Rezultatai siunčiami čia.	false

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

Klaidos atsakymo parametrai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`errors[]`	string[]	Eilučių sąrašas, paaiškinantis klaidą.	false

Webhook'ų apdorojimas

Pateikus užklausą, mūsų platforma pradeda apdoroti pateiktus telefono numerius ir siunčia rezultatus į anksčiau nurodytą webhook URL adresą jūsų serveryje. Rezultatai perduodami kaip HTTP POST užklausa su JSON objektu užklausos turinyje.

Autentifikacija

Autentifikuokite webhook'ą patikrinę X-Signatures HTTP antraštę.

X-Signatures antraštė yra kabliataškiais atskirtas parašų sąrašas. Kiekvienas sąraše esantis parašas generuojamas naudojant vieną iš jūsų paskyroje sukonfigūruotų API slaptažodžių. Norėdami patikrinti webhook'ą, sugeneruokite SHA-256 maišą naudodami savo API raktą, slaptažodį ir neapdorotą HTTP turinį, tada palyginkite jį su sąraše esančiais parašais.

Sutapimas patvirtina, kad užklausa yra autentiška ir pasirašyta jūsų kontroliuojamu slaptažodžiu.

Kodo pavyzdys

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

Užklausa yra galiojanti, jei bet kuris antraštėje nurodytas parašas sutampa su SHA256 maišu, apskaičiuotu iš sujungtos jūsų API rakto, slaptažodžio ir HTTP turinio eilutės.

Gavimo patvirtinimas

Tikimasi, kad jūsų serveris atsakys HTTP būsenos kodu 200 OK, patvirtindamas sėkmingą gavimą. Jei grąžinamas bet kuris kitas atsakymo kodas, įvyksta skirtasis laikas (10 sekundžių) arba iškyla bet kokia kita pristatymo problema, sistema automatiškai pakartotinai bandys siųsti webhook'ą po vienos minutės. Jei užklausa ir toliau nepavyksta, pakartotiniai bandymai bus vykdomi pagal eksponentinio atidėjimo strategiją, su paskesniais bandymais po 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minučių.

Šis pakartotinio bandymo mechanizmas užtikrina maksimalų patikimumą pristatant užklausų rezultatus į jūsų infrastruktūrą. Tai sumažina duomenų praradimo riziką dėl laikinų tinklo problemų ar serverio prastovos.

Webhook'o duomenys

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

Webhook duomenų atributai

JSON objektas turi atributą type => NT kartu su atributu results, kuriame pateikiamas užklausų objektų sąrašas, kaip aprašyta toliau.

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`id`	string(12)	Unikalus identifikatorius, priskirtas šiam užklausos paieškos užklausai.	false
`number`	string	Telefono numeris, kuris buvo įvertintas šios užklausos metu.	false
`number_type`	string	Nustatytas numerio tipas. Galimos reikšmės: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Nurodo, ar numerio tipo informacija buvo sėkmingai gauta. Grąžina `OK`, jei sėkminga, arba `FAILED`, jei užklausa nepavyko.	false
`is_valid`	boolean	Nurodo, ar telefono numeris yra sintaksiškai teisingas.	true
`invalid_reason`	string	Paprastas tekstinis pranešimas anglų kalba, nurodantis, kodėl telefono numeris laikomas neteisingas (pvz., "too short" arba "invalid prefix"), arba `null`, jei numeris teisingas.	true
`is_possibly_ported`	boolean	Nurodo, ar telefono numeris galėjo būti perkeltas iš pradinio operatoriaus į kitą ryšio tiekėją. Tiksliai perkėlimo informacijai naudokite MNP užklausas.	true
`is_vanity_number`	boolean	Nurodo, ar telefono numeris yra vanitinis numeris, t. y. ar jis turi raidžių simbolių.	true
`qualifies_for_hlr_lookup`	boolean	Nurodo, ar telefono numeris tinkamas papildomoms užklausoms per HLR užklausas.	true
`mccmnc`	string(5\|6)	Penkių arba šešių simbolių eilutė, nurodanti MCCMNC porą (mobiliojo ryšio šalies kodas ir mobiliojo tinklo kodas), kuri identifikuoja pradinį mobiliojo telefono numerio tinklą.	true
`mcc`	string(3)	Trijų simbolių eilutė, nurodanti MCC (mobiliojo ryšio šalies kodas), kuri identifikuoja šalį, susijusią su pradiniu telefono numerio mobiluoju tinklu.	true
`mnc`	string(2\|3)	Dviejų arba trijų simbolių eilutė, nurodanti MNC (mobiliojo tinklo kodas), kuri identifikuoja pradinį telefono numerio mobiliojo tinklo operatorių.	true
`original_network_name`	string	Savavališka anglų kalba parašyta tekstinė eilutė, nurodanti pradinio tinklo operatoriaus pavadinimą patikrinto mobiliojo telefono numerio.	true
`original_country_name`	string	Savavališka anglų kalba parašyta tekstinė eilutė, nurodanti pradinę šalį, susijusią su patikrintu mobiliuoju telefono numeriu.	true
`original_country_code`	string(2)	Dviejų simbolių ISO šalies kodas, nurodantis pradinę patikrinto mobiliojo telefono numerio šalį.	true
`regions`	array	Suprantamų anglų kalbos eilučių sąrašas, nurodantis geografinį regioną (-us), susijusį (-ius) su šiuo telefono numeriu.	true
`timezones`	array	Laiko juostų (Olson formatu) sąrašas, susijęs su šiuo telefono numeriu.	true
`info_text`	string	Savavališka eilutė, kuri gali turėti papildomos informacijos apie telefono numerį.	true
`cost`	string	Dešimtainė reikšmė, pateikta kaip eilutė, nurodanti šios užklausos kainą (EUR).	true
`timestamp`	string	W3C formato laiko žymė (su laiko juosta), nurodanti, kada užklausa buvo užbaigta.	true
`storage`	string	Nurodo saugyklos pavadinimą, kur užklausos rezultatai buvo pridėti. Tai atitinka ataskaitos pavadinimą, naudojamą CSV atsisiuntimams ir analitikai per žiniatinklio sąsają.	true
`route`	string(3)	Trijų simbolių identifikatorius, nurodantis maršrutą, naudotą šiai užklausai.	true

Tipas	Aprašymas
LANDLINE	Fiksuotojo ryšio telefono numeris.
MOBILE	Mobiliojo ryšio telefono numeris. Tinkamas HLR užklausoms, kad būtų gauta papildoma informacija apie ryšio būseną, tinklą, perkėlimą ir tarptinklinį ryšį.
MOBILE_OR_LANDLINE	Fiksuotojo arba mobiliojo ryšio telefono numeris. Gali būti tinkamas HLR užklausai.
TOLL_FREE	Nemokamas telefono numeris.
PREMIUM_RATE	Papildomai apmokestinamas telefono numeris su papildomomis išlaidomis.
SHARED_COST	Dalinai apmokestinamas telefono numeris. Paprastai pigesnis nei papildomai apmokestinami telefono numeriai.
VOIP	Balso perdavimo per IP telefono numeris. Apima TSoIP telefono numerius (telefonijos paslauga per IP).
PAGER	Pranešimų gaviklio telefono numeris. Paprastai neturi balso funkcijos.
UAN	Universalaus prieigos numeris (įmonės numeris). Gali būti nukreiptas į konkrečius padalinius, tačiau leidžia naudoti vieną numerį visai įmonei.
VOICEMAIL	Balso pašto telefono numeris.
UNKNOWN	Numerio tipo nustatyti nepavyko.

Slinkti aukštyn

GET/routeapsaugota

Grąžina maršrutą, kuris bus automatiškai pasirinktas, kai vykdysite HLR užklausą nenurodydami route parametro.

Automatinis maršruto pasirinkimas grindžiamas maršrutizavimo schema, kurią galima gauti naudojant GET /hlr-coverage galutinį tašką ir kuri daugiausia sudaroma iš GET /routing-map. Galite pritaikyti savo maršrutizavimo schemą ir nustatyti individualias taisykles savo paskyros nustatymuose.

Užklausa Sėkmingo atsakymo pavyzdys Klaidos atsakymo pavyzdys

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

Užklausos parametrai

Raktas	Tipas	Aprašymas	Numatytasis	Privalomas
`msisdn`	string	MSISDN numeris, kuriam norite gauti automatiškai parinktą maršrutizavimo informaciją.	null	privalomas

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

Sėkmingo atsakymo atributai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`route`	string	Rekomenduojamas maršrutas.	false
`confidence_level`	string	Pasitikėjimo lygis, kuriuo buvo pasirinktas šis maršrutas, t. y. `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`.	false
`mccmnc`	string	Šio numerio MCCMNC, pagrįstas numeracijos planu.	false
`origin`	string	Kilmė, kuria grindžiamas maršrutizavimo sprendimas, t. y. `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."
    ]
}

Klaidos atsakymo parametrai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`errors[]`	string[]	Eilučių sąrašas, paaiškinantis klaidą.	false

Slinkti aukštyn

GET/routesapsaugota

Šis galinis taškas grąžina prieinamų HLR, MNP ir NT maršrutų sąrašą. Kiekvienas maršrutas, kartu su jo funkcijomis ir apribojimais, yra aprašytas maršrutizavimo detalių puslapyje.

Užklausa Sėkmingo atsakymo pavyzdys Klaidos atsakymo pavyzdys

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

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

Sėkmingo atsakymo atributai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`routes`	object	Objektas su maršrutais, sugrupuotais pagal maršruto tipą.	false
`HLR\|MNP\|NT`	string[]	Apima maršrutų identifikatorių sąrašą.	false

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

Klaidos atsakymo parametrai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`errors[]`	string[]	Eilučių sąrašas, paaiškinantis klaidą.	false

Slinkti aukštyn

GET/routing-mapapsaugota

Gauna automatizuoto maršrutizavimo konfigūraciją, šiuo metu taikomą HLR užklausoms jūsų paskyroje. Ši numatytoji konfigūracija naudojama, kai pateikiate HLR užklausas nenurodydami route parametro. Galite pritaikyti savo maršrutizavimo schemą ir sukurti pasirinktinius taisykles savo paskyros nustatymuose.

Konfigūracijos hierarchija kaskadiškai pereina nuo šalies lygio taisyklių prie MCCMNC lygio taisyklių ir galiausiai prie atskirų telefono numerio prefiksų susiejimų. Praktiškai tai reiškia, kad atskiri telefono numerio prefikso susiejimai turi pirmenybę prieš prieštaraujančius MCCMNC priskyrimus, kurie savo ruožtu pakeičia šalies lygio taisykles. Atkreipkite dėmesį, kad MNP atsarginė funkcija pakeičia bet kokias prieštaraujančias pasirinktines taisykles, kai yra įjungta.

Užklausa Sėkmingo atsakymo pavyzdys Klaidos atsakymo pavyzdys

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

Sėkmingo atsakymo atributai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`default_route`	string	Numatytasis maršrutas, naudojamas kai negalima nustatyti pageidaujamos maršrutizavimo parinkties MSISDN numeriui ir netaikomos pasirinktinės maršrutizavimo taisyklės.	false
`mnp_fallback`	boolean	Nurodo, ar įjungta MNP atsarginė funkcija. Kai įjungta ir tinklas nepalaiko HLR užklausų (ryšio būsena nepasiekiama), sistema vietoj to atliks MNP užklausą.	false
`mccmncs`	array	MCCMNC kodų susiejimas su jų automatiškai pasirinktais maršrutais. Atliekant HLR užklausą nurodyto MCCMNC numeriui, naudojamas atitinkamas maršrutas.	false
`mccmnc`	string(5\|6)	Penkių arba šešių simbolių MCCMNC (mobiliojo šalies kodo ir mobiliojo tinklo kodo kombinacija), identifikuojanti mobiliojo tinklo operatorių.	false
`countrycode`	string(2)	Dviejų simbolių ISO šalies kodas, identifikuojantis tinklo šalį.	false
`route`	string(3)	Pasirinktas maršrutas tinklui.	false
`mno`	string	Vartotojams matomas prekės ženklas, kuriuo veikia šis tinklas.	false
`confidence`	string	Pasirinkimo patikimumo lygis. Galimos reikšmės: HIGH, NORMAL, LOW, MNP_REDIRECT. Pastaruoju atveju sistema nukreipia šio tinklo srautą į MNP, jei ši funkcija įjungta jūsų paskyroje. Priešingu atveju naudojamas numatytasis paskyros maršrutas.	false
`origin`	string	Šaltinis, kuriuo grindžiamas pasirinkimas. Galimos reikšmės: `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	Jūsų paskyroje sukonfigūruotų pasirinktinių prefiksais pagrįstų maršrutizavimo taisyklių sąrašas, jei tokių yra.	false
`countrycode`	string(2)	Dviejų simbolių ISO šalies kodas, identifikuojantis prefikso šalį.	false
`cns`	string	Prefiksas, kuriam taikoma maršrutizavimo taisyklė.	false
`route`	string(3)	Pasirinktas maršrutas prefiksui.	false
`mccmnc`	string(5\|6)	Penkių arba šešių simbolių MCCMNC (mobiliojo šalies kodo ir mobiliojo tinklo kodo kombinacija), identifikuojanti mobiliojo tinklo operatorių.	true
`mno`	string	Vartotojams matomas prekės ženklas, kuriuo veikia šis tinklas.	true
`countries`	array	Jūsų paskyroje sukonfigūruotų pasirinktinių šalimis pagrįstų taisyklių sąrašas, jei tokių yra.	false
`countrycode`	string(2)	Dviejų simbolių ISO šalies kodas, identifikuojantis šalį.	false
`route`	string(3)	Pasirinktas maršrutas šaliai.	false

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

Klaidos atsakymo parametrai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`errors[]`	string[]	Eilučių sąrašas, paaiškinantis klaidą.	false

Slinkti aukštyn

GET/hlr-coverage apsaugota

Grąžina HLR aprėpties įžvalgas, padedančias priimti duomenimis pagrįstus sprendimus. Šis galinis taškas padeda analizuoti realaus laiko HLR maršrutizavimo galimybes mobiliuosiuose tinkluose, nustatyti efektyviausius kelius jūsų tikslinėms regionams ir konfigūruoti automatinį maršrutizavimą.

Rekomenduojami maršrutai iš GET /route yra pagrįsti čia gautais aprėpties duomenimis. Aprėpties duomenys taip pat prieinami tinklo aprėpties puslapyje. Galite toliau pritaikyti savo maršrutizavimo žemėlapį ir apibrėžti taisykles paskyros nustatymuose.

Rekomenduojame susipažinti su šiuo vadovu, kuris padės interpretuoti rezultatus.

Užklausa Sėkmingo atsakymo pavyzdys Klaidos atsakymo pavyzdys Būsenų žinynas

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

Užklausos parametrai

Raktas	Tipas	Aprašymas	Numatytasis	Privalomas
`countrycode`	string(2)	Privalomas dviejų raidžių ISO šalies kodas, naudojamas rezultatams filtruoti, grąžinant tik su nurodyta šalimi susijusius įrašus.	null	privalomas
`sample_size`	string	Neprivalomas parametras, nurodantis imties dydį. Galimos reikšmės: `LARGE`, `MEDIUM`, `SMALL`. Didesnės imtys apima ilgesnį laikotarpį, mažesnės imtys apima labai naujausią laikotarpį.	LARGE	neprivaloma

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

Sėkmingo atsakymo atributai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`name`	string	Pasirinktos šalies pavadinimas anglų kalba.	false
`countrycode`	string(2)	Dviejų simbolių ISO šalies kodas pasirinktos šalies.	false
`prefix`	string	Tarptautinis skambinimo kodas pasirinktos šalies.	false
`mccs`	string[]	MCC (mobiliųjų šalies kodų) sąrašas, susietas su pasirinkta šalimi.	false
`carriers`	object[]	Operatorių objektų sąrašas su konkrečiam maršrutui būdingais ryšio rodikliais.	false
`mno`	string	Mobiliojo tinklo operatoriaus pavadinimas anglų kalba.	false
`mccmnc`	string	Mobiliojo tinklo operatoriaus MCCMNC.	false
`mcc`	string	Mobiliojo tinklo operatoriaus MCC (mobiliojo šalies kodas).	false
`mnc`	string	Mobiliojo tinklo operatoriaus MNC (mobiliojo tinklo kodas).	false
`routes`	object[]	Konkrečiam maršrutui būdingų ryšio rezultatų sąrašas.	false
`route`	string	Maršrutas, kuriam taikoma ryšio informacija.	false
`selected`	bool	Nurodo, ar tai yra pasirinktas maršrutas automatiniam maršrutizavimui.	false
`selection_confidence`	string	Pasitikėjimo lygis, kuriuo buvo pasirinktas šis maršrutas, t. y. `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`. Yra null, jei tai nėra pasirinktas maršrutas.	true
`n`	int	Bendras užklausų skaičius šioje imtyje.	false
`CONNECTED`	int	HLR užklausų, grąžinusių CONNECTED būseną, skaičius.	false
`CONNECTED_PCT`	float	HLR užklausų, grąžinusių CONNECTED būseną, procentas.	false
`ABSENT`	int	HLR užklausų, grąžinusių ABSENT būseną, skaičius.	false
`ABSENT_PCT`	float	HLR užklausų, grąžinusių ABSENT būseną, procentas.	false
`INVALID_MSISDN`	int	HLR užklausų, grąžinusių INVALID_MSISDN būseną, skaičius.	false
`INVALID_MSISDN_PCT`	float	HLR užklausų, grąžinusių INVALID_MSISDN būseną, procentas.	false
`UNDETERMINED`	int	HLR užklausų, grąžinusių UNDETERMINED būseną, skaičius.	false
`UNDETERMINED_PCT`	float	HLR užklausų, grąžinusių UNDETERMINED būseną, procentas.	false

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

Klaidos atsakymo parametrai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`errors[]`	string[]	Eilučių sąrašas, paaiškinantis klaidą.	false

Būsena	Aprašymas
CONNECTED	Numeris galiojantis, o tikslinė įranga šiuo metu prijungta prie mobiliojo tinklo. Skambučiai, SMS ir kitos paslaugos turėtų pasiekti gavėją sėkmingai.
ABSENT	Numeris galiojantis, tačiau tikslinė įranga yra išjungta arba laikinai neturi tinklo aprėpties. Žinutės ar skambučiai gali būti nepristatyti, kol įrenginys vėl prisijungs prie tinklo.
INVALID_MSISDN	Numeris negaliojantis arba šiuo metu nėra priskirtas jokiam mobiliojo tinklo abonentui. Skambučiai ir žinutės šiuo numeriu nepavyks.
UNDETERMINED	Numerio ryšio būsenos nustatyti nepavyko. Tai gali būti dėl negaliojančio numerio, SS7 klaidos atsakymo arba ryšio su tiksliniu tinklo operatoriumi trūkumo. Peržiūrėkite klaidos kodą ir jo aprašymo lauką papildomai diagnostikai.

Slinkti aukštyn

GET/mnp-coverageapsaugota

Šis galinis taškas grąžina mobiliųjų tinklų operatorių sąrašą kartu su atitinkamais MCCMNC identifikatoriais, kurie šiuo metu palaikomi mobiliojo numerio perkeliamumui tikrinti.

Užklausa Sėkmingo atsakymo pavyzdys Klaidos atsakymo pavyzdys

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

Užklausos parametrai

Raktas	Tipas	Aprašymas	Numatytasis	Privalomas
`countrycode`	string(2)	Neprivalomas dviejų raidžių ISO šalies kodas, naudojamas MCCMNC rezultatams filtruoti, grąžinant tik nurodytos šalies duomenis.	null	neprivaloma

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

Sėkmingo atsakymo atributai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`items[]`	array	Mobiliųjų tinklų operatorių sąrašas.	false
`country_name`	string	Šalies pavadinimas anglų kalba.	false
`country_code`	string(2)	Dviejų raidžių ISO šalies kodas.	false
`mccmnc`	string(5\|6)	Penkių arba šešių simbolių MCCMNC (mobiliojo šalies kodo ir mobiliojo tinklo kodo kombinacija), identifikuojanti mobiliojo tinklo operatorių.	false
`mcc`	string(3)	Trijų simbolių MCC (mobiliojo šalies kodas), nurodantis tinklo šalį.	false
`mnc`	string(2\|3)	Dviejų arba trijų simbolių MNC (mobiliojo tinklo kodas), nurodantis konkretų mobiliojo tinklo operatorių.	false
`brand`	string	Vartotojams matomas prekės ženklas, kuriuo veikia šis tinklas.	true
`operator`	string	Juridinis mobiliojo tinklo operatoriaus pavadinimas.	true

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

Klaidos atsakymo parametrai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`errors[]`	string[]	Eilučių sąrašas, paaiškinantis klaidą.	false

Slinkti aukštyn

GET/price-listapsaugota

Šis endpoint grąžina šalių, kuriose palaikomos tik MNP užklausos, sąrašą - HLR užklausos šioms kryptims neprieinamos.

Užklausa Sėkmingo atsakymo pavyzdys Klaidos atsakymo pavyzdys

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

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

Sėkmingo atsakymo atributai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`countries`	string[]	Dviejų simbolių ISO šalių kodų sąrašas.	false

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

Klaidos atsakymo parametrai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`errors[]`	string[]	Eilučių sąrašas, paaiškinantis klaidą.	false

Slinkti aukštyn

GET/mccmncsapsaugota

Šis galinis taškas grąžina išsamų mobiliųjų tinklų operatorių sąrašą kartu su atitinkamais MCCMNC identifikatoriais ir papildoma kontekstine informacija.

Užklausa Sėkmingo atsakymo pavyzdys Klaidos atsakymo pavyzdys

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

Užklausos parametrai

Raktas	Tipas	Aprašymas	Numatytasis	Privalomas
`countrycode`	string(2)	Neprivalomas dviejų raidžių ISO šalies kodas, naudojamas MCCMNC rezultatams filtruoti, grąžinant tik su nurodyta šalimi susijusius įrašus.	null	neprivaloma

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

Sėkmingo atsakymo atributai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`items`	object[]	Mobiliųjų tinklų operatorių sąrašas.	false
`country_name`	string	Pilnas šalies pavadinimas anglų kalba.	false
`country_code`	string(2)	Dviejų raidžių ISO šalies kodas, nurodantis mobiliojo operatoriaus šalį.	false
`mccmnc`	string(5\|6)	Penkių arba šešių simbolių eilutė, nurodanti MCCMNC, kuris unikaliai identifikuoja mobiliojo tinklo operatorių.	false
`mcc`	string(3)	Trijų simbolių mobiliojo ryšio šalies kodas (MCC), identifikuojantis šalį, kurioje veikia mobilusis tinklas.	false
`mnc`	string(2\|3)	Dviejų arba trijų simbolių mobiliojo tinklo kodas (MNC), nurodantis mobilųjį tinklą pagal nurodytą MCC.	false
`brand`	string	Komercinis prekės ženklo pavadinimas, pagal kurį tinklas veikia ir yra atpažįstamas vartotojų.	true
`operator`	string	Oficialus mobiliojo tinklo operatoriaus pavadinimas, paprastai juridinis subjektas, valdantis tinklą.	true
`parent_mccmnc`	string(5\|6)	Penkių arba šešių simbolių eilutė, nurodanti pagrindinio mobiliojo tinklo operatoriaus MCCMNC, jei toks yra.	true

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

Klaidos atsakymo parametrai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`errors[]`	string[]	Eilučių sąrašas, paaiškinantis klaidą.	false

Slinkti aukštyn

GET/priceapsaugota

Šis galinis taškas grąžina HLR, MNP arba NT užklausos kainą.

Užklausa Sėkmingo atsakymo pavyzdys Klaidos atsakymo pavyzdys

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

Užklausos parametrai

Raktas	Tipas	Aprašymas	Numatytasis	Privalomas
`msisdn`	string	Telefono numeris, kurio kaina turi būti gauta. Tarptautiniu formatu.	null	privalomas
`route_type`	string	Maršruto tipas, t. y. `HLR`, `MNP`, `NT`.	null	privalomas
`route`	string(3)	Maršrutas, kuriam turėtų būti apskaičiuota kaina. Pagal numatytuosius nustatymus naudojamas automatinio maršrutizavimo nustatytas maršrutas.	null	neprivaloma

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

Sėkmingo atsakymo atributai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`price`	object	Objektas su kainodaros informacija.	false
`amount`	string	Suma eurais.	false
`msisdn`	string	MSISDN, kuriam taikoma ši kaina.	false
`route_type`	string(2\|3)	Maršruto tipas, kuriam taikoma ši kaina.	false
`route`	string(3)	Maršrutas, kuriam taikoma ši kaina.	false

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

Klaidos atsakymo parametrai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`errors[]`	string[]	Eilučių sąrašas, paaiškinantis klaidą.	false

Slinkti aukštyn

GET/price-listapsaugota

Šis endpoint grąžina jūsų paskyros kainodarą.

Užklausa Sėkmingo atsakymo pavyzdys Klaidos atsakymo pavyzdys

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

Sėkmingo atsakymo atributai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`pricing`	object[]	Objektų sąrašas su kainodaros informacija.	false
`route`	string	Maršrutas, kuriam taikoma ši kainodara.	false
`countrycode`	string	Dviejų simbolių ISO šalies kodas, kuriam taikoma ši kainodara atitinkamam maršrutui, jei taikoma.	true
`countryname`	string	Angliškas šalies pavadinimas, atitinkantis šalies kodą, jei taikoma.	true
`mccmnc`	string	MCCMNC kodas, kuriam taikoma ši kainodara atitinkamam maršrutui, jei taikoma. Pakeičia šalies lygio kainodarą.	true
`cns`	string	Rinkimo prefiksas, kuriam taikoma ši kainodara atitinkamam maršrutui, jei taikoma. Pakeičia šalies lygio kainodarą ir MCCMNC lygio kainodarą.	true
`route_type`	string	Atitinkamas maršruto tipas, t.y. `HLR`, `MNP`, `NT`.	false
`route_type`	string	Atitinkama kaina eurais.	false

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

Klaidos atsakymo parametrai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`errors[]`	string[]	Eilučių sąrašas, paaiškinantis klaidą.	false

Slinkti aukštyn

GET/balanceapsaugota

Šis metodas grąžina dabartinę jūsų paskyros būseną, leidžiančią automatizuoti procesus pagal jūsų kreditų statusą. Jis sklandžiai veikia su mažo kredito pranešimais el. paštu, kuriuos galite konfigūruoti mokėjimų puslapyje.

Užklausa Sėkmingo atsakymo pavyzdys Klaidos atsakymo pavyzdys

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

{
    "balance":"1002.90"
}

Sėkmingo atsakymo atributai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`balance`	string	Dabartinė jūsų paskyros būsena eurais. Dešimtainė string tipo reikšmė.	false

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

Klaidos atsakymo parametrai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`errors[]`	string[]	Eilučių sąrašas, paaiškinantis klaidą.	false

Slinkti aukštyn

GET/pingviešas

Šis galinis taškas siunčia ping užklausą į API, suteikdamas paprastą metodą jūsų ryšiui su HLR Lookups API patikrinti.

Užklausa Sėkmingo atsakymo pavyzdys Klaidos atsakymo pavyzdys

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

{
    "success":true
}

Sėkmingo atsakymo atributai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`success`	boolean	Rodo, kad užklausa buvo sėkmingai apdorota.	false

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

Klaidos atsakymo parametrai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`errors[]`	string[]	Eilučių sąrašas, paaiškinantis klaidą.	false

Slinkti aukštyn

GET/timeviešas

Šis galinis taškas grąžina Unix laiko žymą, atspindinčią dabartinį laiką HLR Lookups serveryje. Naudokite jį savo serverio laikrodžio sinchronizavimui generuojant Digest-Auth parašą autentifikacijai, užtikrinant, kad bet kokie neatitikimai tarp jūsų serverio laiko ir HLR Lookups serverio laiko būtų ištaisyti.

Užklausa Sėkmingo atsakymo pavyzdys Klaidos atsakymo pavyzdys

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

{
    "time":1525898643
}

Sėkmingo atsakymo atributai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`time`	integer	Unix laiko žyma, atspindinti dabartinį HLR Lookups serverio laiką.	false

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

Klaidos atsakymo parametrai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`errors[]`	string[]	Eilučių sąrašas, paaiškinantis klaidą.	false

Slinkti aukštyn

GET/auth-testapsaugota

Šis galinis taškas skirtas pradinio Basic-Auth arba, geriau, Digest-Auth įgyvendinimo testavimui.

Pagrindinės autentifikacijos užklausa Digest Auth užklausa Sėkmingo atsakymo pavyzdys Klaidos atsakymo pavyzdys

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

Užklausos antraštės

Raktas	Tipas	Aprašymas
`X-Basic`	string	SHA256 maišas `YOUR_API_KEY:YOUR_API_SECRET`. Į maišą įtraukite dvitaškio simbolį (:).

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"

Užklausos antraštės

Raktas	Tipas	Aprašymas
`X-Digest-Key`	string	Jūsų HLR Lookups API raktas
`X-Digest-Signature`	string	Unikalus Digest-Auth parašas (žr. autentifikacija)
`X-Digest-Timestamp`	integer	Dabartinis Unix laiko žymė (taip pat žr. `GET /time`)

{
    "success":true
}

Sėkmingo atsakymo atributai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`success`	boolean	Rodo, kad užklausa buvo sėkmingai apdorota.	false

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

Klaidos atsakymo parametrai

Vardas ir pavardė	Tipas	Aprašymas	Gali būti tuščias
`errors[]`	string[]	Eilučių sąrašas, paaiškinantis klaidą.	false

Slinkti aukštyn

Senojo API dokumentacija

Atkreipkite dėmesį, kad senasis API yra nebenaudojamas ir ateityje bus visiškai nutrauktas. Primygtinai rekomenduojame kuo greičiau atnaujinti į naujausią versiją.

Jei įdiegėte mūsų HLR Lookups API nuo 2013 iki 2020 metų pradžios, naudojate senąjį API. Tokiu atveju žiūrėkite mūsų senojo API dokumentaciją.

Senojo API dokumentacija

API dokumentacija

Pradžia

HLR užklausos

MNP užklausos

NT užklausos

Maršrutizavimas

Kainoraštis

Įrankiai

Pradžia

HLR Lookups API naudojimas

Užklausos pavyzdys

Duomenų pavyzdys

Sėkmingo atsakymo pavyzdys application/json

Papildomos užklausų paslaugos

Mobiliųjų numerių perkėlimo (MNP) užklausos

Numerio tipo nustatymo (NT) užklausos

Programinės įrangos kūrimo rinkiniai (SDK)

Įrankiai

Ne programuotojas?

Autentifikacija

API raktas ir API slaptasis kodas

HTTP pagrindinė autentifikacija

Rekomenduojama: X-Basic antraštė su SHA256

Pagrindinės autentifikacijos užklausa

Pagrindinės autentifikacijos antraštės

Kodo pavyzdys

Užklausos pavyzdys

Užklausos antraštės

Parašo sudarymas

Digest parašo komponentai

Kodo pavyzdžiai

Sąvokos

Sinchroninis HLR užklausų API

Asinchroninė HLR užklausų API

SDK (programinės įrangos kūrimo rinkiniai)

PHP SDK

NodeJS SDK

Ruby SDK

POST/hlr-lookupapsaugota

Duomenys

Užklausos parametrai

Sėkmingo atsakymo atributai

Klaidos atsakymo parametrai

POST/hlr-lookupsapsaugota

Duomenys

Užklausos parametrai

Sėkmingo atsakymo atributai

Klaidos atsakymo parametrai

Webhook'ų apdorojimas

Autentifikacija

Kodo pavyzdys

Gavimo patvirtinimas

Webhook'o duomenys

Webhook duomenų atributai

POST/mnp-lookupapsaugota

Duomenys

Užklausos parametrai

Sėkmingo atsakymo atributai

Klaidos atsakymo parametrai

POST/mnp-lookupsapsaugota

Duomenys

Užklausos parametrai

Sėkmingo atsakymo atributai

Klaidos atsakymo parametrai

Webhook'ų apdorojimas

Autentifikacija

Kodo pavyzdys

Gavimo patvirtinimas

Webhook'o duomenys

Webhook duomenų atributai

POST/nt-lookupapsaugota

Duomenys

Užklausos parametrai

Sėkmingo atsakymo atributai

Klaidos atsakymo parametrai

POST/nt-lookups apsaugota

Duomenys

Užklausos parametrai

Sėkmingo atsakymo atributai

Klaidos atsakymo parametrai