Začíname

Globálna infraštruktúra mobilných sietí funguje na systéme známom ako signalizačná sieť SS7. Táto sieť umožňuje výmenu údajov o účastníkoch, smerovanie hovorov, prenos SMS a aktualizácie stavu mobilného pripojenia v reálnom čase medzi operátormi. Každá mobilná sieť udržiava Home Location Register (HLR) - hlavnú databázu, ktorá uchováva základné údaje o svojich účastníkoch.

Technológia HLR Lookup umožňuje firmám vyhľadávať v týchto registroch a získavať aktuálne informácie o pripojení a sieti pre akékoľvek mobilné telefónne číslo. Zahŕňa to informácie o tom, či je telefón zapnutý, ku ktorej sieti je aktuálne priradený, či bol prenášaný, či je číslo platné alebo deaktivované a či je v roamingu.

HLR Lookups API poskytuje bezproblémový prístup k týmto údajom v reálnom čase, čo umožňuje firmám overiť mobilné čísla, optimalizovať smerovanie a zlepšiť komunikáciu so zákazníkmi. Táto dokumentácia vás prevedie integráciou HLR Lookups do vášho softvéru a umožní automatizované získavanie mobilných informácií v reálnom čase.

Používanie HLR Lookups API

Vykonávanie HLR Lookup dotazov je rýchle, bezpečné a jednoduché. Po registrácii a získaní API kľúča sa môžete autentifikovať a iniciovať okamžité vyhľadávania pomocou jednoduchých HTTP POST požiadaviek cez POST /hlr-lookup. Prípadne môžete spracovať veľké súbory údajov použitím rýchlych asynchrónnych API požiadaviek s výsledkami odoslanými späť na váš server cez webhook, ako je vysvetlené v sekcii koncepty.

Príklad požiadavky

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"

Autentifikácia sa poskytuje cez HTTP hlavičky a payload.json by mal (minimálne) obsahovať nasledujúci JSON objekt:

Príklad údajov

{
   "msisdn": "+14156226819"
}

Po úspešnom vykonaní dostanete odpoveď obsahujúcu podrobnosti o pripojení v reálnom čase pre zadané mobilné číslo.

Úspešná odpoveď 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"
}

Pre kompletný prehľad atribútov požiadavky a odpovede a stavov pripojenia pozrite POST /hlr-lookup.

Doplnkové vyhľadávacie služby

Vyhľadávanie prenositeľnosti čísel (MNP)

Použite MNP vyhľadávanie na zistenie vlastníctva siete a podrobností o prenositeľnosti bez dopytovania pripojenia v reálnom čase. Ak potrebujete len MCCMNC čísla, pozrite POST /mnp-lookup.

Detekcia typu čísla (NT)

Zistite, či telefónne číslo patrí k pevnej linke, mobilnému telefónu, prémiové tarife, VoIP, pageru alebo iným rozsahom číslovacieho plánu pomocou POST /nt-lookup.

Vývojové súpravy (SDK)

HLR Lookups API funguje s akýmkoľvek REST klientom v akomkoľvek programovacom jazyku a publikovali sme SDK pre PHP, Ruby a NodeJS na našom GitHube, aby sme vám pomohli rýchlo začať.

Nástroje

Pre bezproblémový vývoj ponúkame komplexnú sadu nástrojov vrátane monitorovania API požiadaviek a webhookov v prehliadači, whitelist IP adries, robustných autentifikačných možností a autentifikačného testovacieho endpointu.

Nie ste vývojár?

HLR Lookups a dotazy na prenositeľnosť čísel možno vykonávať bez akéhokoľvek programovania. Zistite viac o našom podnikovom webovom klientovi a reportovacích funkciách v prehliadači.

Autentifikácia

Na zabezpečenie bezpečnosti a správnej kontroly prístupu vyžaduje väčšina požiadaviek na HLR Lookups API autentifikáciu. Endpointy sú kategorizované ako verejné alebo chránené. Pri prístupe k chránenému endpointu musí byť vaša požiadavka autentifikovaná pomocou vášho API kľúča a tajného kódu prostredníctvom metódy Digest-Auth alebo Basic-Auth. Digest-Auth je bezpečnejšia možnosť a dôrazne sa odporúča. Použite endpoint GET /auth-test na overenie vášho nastavenia autentifikácie.

API kľúč a API tajný kód

Získajte váš API kľúč a tajný kód na stránke Nastavenia API. Môžete tiež nakonfigurovať vašu preferovanú metódu autentifikácie a povoliť whitelistovanie IP adries pre zvýšenú bezpečnosť. Ak máte podozrenie, že váš API tajný kód bol kompromitovaný, môžete kedykoľvek vygenerovať nový.

Basic Auth Digest Auth IP Whitelist

Štandardná Basic Authentication je jednoduchá na implementáciu a široko podporovaná. Môžete sa autentifikovať odoslaním vášho API kľúča a tajného kódu ako páru user:pass v HTTP požiadavke.

HTTP Basic Auth

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

Toto odošle hlavičku Authorization:

Authorization: Basic BASE64(YOUR_API_KEY:YOUR_API_SECRET)

Odporúčané: X-Basic hlavička so SHA256

Pre vyššiu bezpečnosť môžete odoslať SHA256 hash vašich prihlasovacích údajov namiesto ich priameho prenosu ako base64. Na použitie tejto metódy vypočítajte hash vášho páru YOUR_API_KEY:YOUR_API_SECRET a odošlite ho prostredníctvom hlavičky X-Basic:

Basic Auth požiadavka

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

Hlavičky Basic Authentication

Kľúč	Typ	Popis
`X-Basic`	string	SHA256 hash `YOUR_API_KEY:YOUR_API_SECRET`. Zahrňte do hashu symbol dvojbodky (:).	povinné

Príklad kódu

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

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

Digest-Auth je odporúčaná metóda na zabezpečenie prístupu k chráneným endpointom HLR Lookup API. Každá požiadavka musí obsahovať nasledujúce hlavičky: X-Digest-Key, X-Digest-Signature a X-Digest-Timestamp, ktoré sú vysvetlené nižšie.

Príklad požiadavky

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"

Hlavičky požiadavky

Kľúč	Typ	Popis
`X-Digest-Key`	string	Váš jedinečný HLR Lookups API kľúč.	povinné
`X-Digest-Signature`	string	Jedinečný autentifikačný podpis (pozri nižšie).	povinné
`X-Digest-Timestamp`	integer	Aktuálny Unix timestamp (pozri tiež `GET /time`).	povinné

Vytvorenie podpisu

X-Digest-Signature sa vytvára pomocou SHA256 HMAC hashu s vaším API tajným kódom ako zdieľaným kľúčom.

Reťazec na hashovanie je štruktúrovaný nasledovne:

ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY

Symbol . predstavuje zreťazenie reťazcov.

Komponenty Digest Signature

Komponent	Typ	Popis
`ENDPOINT_PATH`	string	Požadovaný API endpoint, napr. `/auth-test` malými písmenami.
`UNIX_TIMESTAMP`	integer	Aktuálny Unix timestamp (musí byť v rozmedzí 30 sekúnd). Pozri `GET /time`.
`REQUEST_METHOD`	string	Použitá HTTP metóda, napr. `POST` alebo `GET`.
`REQUEST_BODY`	string	Dáta tela požiadavky. Nastavte na `null` pre `GET` požiadavky.

Príklady kódu

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)

Posunúť hore

Koncepty

Implementácia HLR vyhľadávaní v akomkoľvek programovacom jazyku alebo systéme prostredníctvom nášho HTTP REST API je jednoduchá a efektívna. Vďaka jednoduchému procesu integrácie môžete začať dotazovať mobilné siete v reálnom čase a získavať okamžité informácie o platnosti telefónnych čísel, stave konektivity a smerovacích detailoch.

Výber vhodného API závisí od vášho konkrétneho prípadu použitia. Ak potrebujete výsledky vyhľadávania v reálnom čase pre aplikácie ako VoIP telefónia, detekcia podvodov alebo SMS smerovanie, synchrónne API je najlepšou voľbou. Ak však váš prípad použitia zahŕňa vysokoobjemové spracovanie, hromadné vyhľadávania alebo rozsiahlu verifikáciu dát, asynchrónne API ponúka optimalizovaný výkon s efektívnym využitím šírky pásma a možnosťami dávkového vyhľadávania.

Nakonfigurujte API tak, aby používalo jednu z našich vlastných možností smerovania na optimalizáciu rýchlosti, presnosti a nákladovej efektívnosti. Výsledky vyhľadávania môžete tiež ukladať do úložísk pre jednoduché stiahnutie CSV a JSON reportov, ako aj pokročilú analytiku prostredníctvom webového rozhrania.

Synchrónne HLR Lookup API

Endpoint POST /hlr-lookup spracováva jedno mobilné telefónne číslo (MSISDN) na požiadavku a okamžite vracia výsledky v tele HTTP odpovede. Výsledky sú formátované ako JSON a sú ideálne pre aplikácie v reálnom čase, vrátane validácie mobilných čísel, smerovania hovorov a doručovania SMS správ.

Synchrónne API volanie pozostáva z priameho HTTP požiadavku a odpovede. Váš systém odošle jedno MSISDN (mobilné číslo) na požiadavku a okamžite dostane odpoveď obsahujúcu výsledky HLR vyhľadávania v reálnom čase vo formáte JSON. Toto API je optimalizované pre prípady použitia, ktoré vyžadujú okamžitú verifikáciu a kontrolu konektivity, ako je detekcia podvodov, VoIP smerovanie hovorov a optimalizácia SMS brány.

Asynchrónne HLR Lookup API

Endpoint POST /hlr-lookups je navrhnutý pre hromadné a vysokoobjemové spracovanie, čo vám umožňuje odoslať až 1,000 MSISDN na požiadavku. Namiesto okamžitého vrátenia výsledkov toto API používa automatizované webhooky na postupné odosielanie výsledkov na váš server. Výsledky vyhľadávania sú vrátené ako JSON objekty prostredníctvom HTTP POST callbackov.

Asynchrónne API je optimalizované pre rýchlosť, efektívnosť a škálovateľnosť. Eliminuje problémy so sieťovou latenciou spojené so synchrónnym volaním, čo ho robí ideálnym pre firmy potrebujúce vyhľadávania s vysokou priepustnosťou. Váš systém odošle až 1,000 MSISDN na požiadavku a naša platforma ich spracuje paralelne, pričom doručí výsledky späť na váš server prostredníctvom HTTP webhookov v dávkach až 1,000 výsledkov na callback.

SDK (Software Development Kits)

Naše Software Development Kits (SDK) pre PHP, NodeJS a Ruby zefektívňujú proces integrácie a umožňujú vám pripojiť sa k HLR Lookups API efektívne a s minimálnym úsilím.

Tieto SDK poskytujú predpripravené funkcie, správu autentifikácie a štruktúrované šablóny API požiadaviek, čím skracujú čas vývoja a zabezpečujú osvedčené postupy.

Preskúmajte náš kompletný zoznam dostupných SDK na GitHub a začnite s integráciou ešte dnes.

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

Zobraziť na 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   }

Zobraziť na 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)

Zobraziť na GitHub README.md

Posunúť hore

POST/hlr-lookupchránené

Vykonáva synchrónne HLR vyhľadávanie, ktoré poskytuje údaje o pripojení a prenositeľnosti mobilných telefónov v reálnom čase priamo od sieťových operátorov. Tento endpoint je ideálny pre scenáre živej prevádzky, kde časovo citlivé aplikácie vyžadujú okamžité overenie, či je telefónne číslo aktuálne dostupné (pripojené) alebo nedostupné (vypnuté). Okrem toho pomáha rozlíšiť aktívne čísla od neplatných, neznámych alebo falošných.

Pre hromadné zpracovanie veľkých dátových súborov, ktoré nevyžadujú okamžité výsledky, zvážte použitie asynchrónneho POST /hlr-lookups, ktorý je optimalizovaný pre vysokorýchlostné dávkové spracovanie.

Ak je vašou hlavnou prioritou získavanie údajov o prenositeľnosti mobilných čísel (MCCMNC) a nepotrebujete stav živého pripojenia, POST /mnp-lookup poskytuje nákladovo efektívnu alternatívu pre dotazy na prenositeľnosť mobilných čísel.

Požiadavka Úspešná odpoveď Chybová odpoveď Referencia stavov

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

Dáta požiadavky

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

Parametre požiadavky

Kľúč	Typ	Popis	Predvolené	Povinné
`msisdn`	string	Číslo mobilného telefónu (MSISDN), ktoré má byť vyhľadané, uvedené v medzinárodnom formáte (napr. +14156226819 alebo 0014156226819). Predvoľby krajín musia byť uvedené.	null	povinné
`route`	string(3)	Voliteľný trojznakový identifikátor určujúci trasu pre toto vyhľadávanie. Nastavte na `null` alebo vynechajte tento parameter na použitie vašej vlastnej mapy smerovania alebo nechajte náš systém automaticky určiť najlepšiu trasu pre toto vyhľadávanie.	null	voliteľné
`storage`	string	Voliteľný identifikátor úložiska určujúci správu, do ktorej sa uložia výsledky na manuálne preskúmanie, analýzu a reporting. Systém automaticky pridáva časovú značku s aktuálnym mesiacom. Ak je vynechaný alebo nastavený na `null`, systém automaticky zoskupí výsledky podľa mesiaca na účely reportingu.	null	voliteľné

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

Atribúty úspešnej odpovede

Meno	Typ	Popis	Voliteľný
`id`	string(12)	Jedinečný identifikátor priradený k tejto vyhľadávacej požiadavke.	false
`msisdn`	string	Mobilné telefónne číslo, ktoré sa vyhľadáva, formátované v medzinárodnom formáte (napr. +14156226819 alebo 0014156226819).	false
`connectivity_status`	string	Označuje, či sa úspešne získal stav pripojenia čísla. Možné hodnoty: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` alebo `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Päť- alebo šesťmiestny kód krajiny mobilnej siete (MCC) a kód mobilnej siete (MNC) identifikujúci sieť aktuálne priradenú k telefónnemu číslu.	true
`mcc`	string(3)	Trojmiestny kód krajiny mobilnej siete (MCC) identifikujúci krajinu, v ktorej je telefónne číslo registrované.	true
`mnc`	string(2\|3)	Dvoj- alebo trojmiestny kód mobilnej siete (MNC) identifikujúci konkrétnu sieť, ku ktorej telefónne číslo patrí.	true
`imsi`	string	Medzinárodná identita mobilného účastníka (IMSI), jedinečný identifikátor SIM karty priradenej k tomuto číslu. Dostupnosť závisí od konfigurácie siete.	true
`msin`	string(10)	Identifikačné číslo mobilného predplatného (MSIN) v databáze mobilného operátora. Dostupnosť závisí od konfigurácie siete.	true
`msc`	string(12)	Centrum prepájania mobilných hovorov (MSC) aktuálne obsluhujúce komunikáciu tohto účastníka. Dostupnosť závisí od konfigurácie siete.	true
`original_network_name`	string	Pôvodný (natívny) názov sieťového operátora priradený k tomuto číslu.	true
`original_country_name`	string	Úplný názov krajiny, v ktorej bolo mobilné telefónne číslo pôvodne registrované, uvedený v angličtine.	true
`original_country_code`	string(2)	Dvojznakový ISO kód krajiny reprezentujúci krajinu, v ktorej bolo telefónne číslo prvýkrát pridelené.	true
`original_country_prefix`	string	Medzinárodné predvolené číslo (kód krajiny) zodpovedajúce pôvodnej krajine mobilného telefónneho čísla.	true
`is_ported`	boolean	Označuje, či bolo mobilné číslo prenesené z pôvodnej siete k inému operátorovi.	true
`ported_network_name`	string	Názov sieťového operátora, ku ktorému bolo mobilné číslo prenesené, ak je to relevantné.	true
`ported_country_name`	string	Názov krajiny, do ktorej bolo mobilné číslo prenesené, ak je to relevantné.	true
`ported_country_code`	string(2)	Dvojznakový ISO kód krajiny reprezentujúci krajinu, do ktorej bolo mobilné číslo prenesené, ak je to relevantné.	true
`ported_country_prefix`	string	Medzinárodné predvolené číslo (kód krajiny) pre krajinu, do ktorej bolo mobilné číslo prenesené, ak je to relevantné.	true
`is_roaming`	boolean	Označuje, či mobilné číslo aktuálne roamuje v zahraničnej sieti. Dostupnosť stavu roamingu závisí od mobilného sieťového operátora.	true
`roaming_network_name`	string	Názov siete, v ktorej mobilné číslo aktuálne roamuje, ak je to relevantné.	true
`roaming_country_name`	string	Názov krajiny, v ktorej mobilné číslo aktuálne roamuje, ak je to relevantné.	true
`roaming_country_code`	string(2)	Dvojznakový ISO kód krajiny, v ktorej mobilné číslo aktuálne roamuje, ak je to relevantné.	true
`roaming_country_prefix`	string	Medzinárodné predvolené číslo (kód krajiny) krajiny, v ktorej mobilné číslo aktuálne roamuje, ak je to relevantné.	true
`cost`	string	Desatinná hodnota reprezentovaná ako reťazec, označujúca náklady na vyhľadávanie v EUR.	true
`timestamp`	string	Časová pečiatka vo formáte W3C vrátane časového pásma, určujúca kedy bolo vyhľadávanie dokončené.	true
`storage`	string	Názov úložiska, kde boli uložené výsledky vyhľadávania. Zodpovedá názvom reportov a CSV súborov dostupných cez webové rozhranie.	true
`route`	string(3)	Trojznakový identifikátor označujúci metódu smerovania použitú pre túto vyhľadávaciu požiadavku.	true
`processing_status`	string	Výsledok spracovania vyhľadávania. Možné hodnoty: `COMPLETED` (úspešné), `REJECTED` (sieť nedostupná, bez poplatku) alebo `FAILED` (počas spracovania došlo k chybe).	false
`error_code`	integer	Voliteľný interný kód chyby poskytujúci dodatočné diagnostické informácie pre zákaznícku podporu.	true
`error_description`	string	Stručné vysvetlenie daného kódu chyby (ak existuje) v angličtine ako obyčajný text.	true
`data_source`	string	Zdroj dát použitý pre túto požiadavku. Možné hodnoty: `LIVE_HLR` (HLR dotaz v reálnom čase) alebo `MNP_DB` (statická databáza prenositeľnosti mobilných čísel). Podrobnosti nájdete v možnostiach smerovania.	false
`routing_instruction`	string	Reťazec oddelený dvojbodkou popisujúci inštrukciu smerovania použitú v požiadavke. Prvý komponent je `STATIC`, keď ste zadali trasu, alebo `AUTO` pre automatické smerovanie; druhý komponent je identifikátor trasy a pri požiadavkách automatického smerovania tretí komponent zobrazuje pôvod, na základe ktorého sa rozhodlo o smerovaní (t.j. `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."
    ]
}

Parametre chybovej odpovede

Meno	Typ	Popis	Voliteľný
`errors[]`	string[]	Zoznam reťazcov vysvetľujúcich chybu.	false

Stav	Popis
CONNECTED	Číslo je platné a cieľové zariadenie je momentálne pripojené k mobilnej sieti. Hovory, SMS a ďalšie služby by mali príjemcu úspešne zastihnúť.
ABSENT	Číslo je platné, ale cieľové zariadenie je buď vypnuté alebo dočasne mimo dosahu siete. Správy alebo hovory nemusia byť doručené, kým sa zariadenie znovu nepripojí k sieti.
INVALID_MSISDN	Číslo je neplatné alebo momentálne nie je priradené žiadnemu účastníkovi v mobilnej sieti. Hovory a správy na toto číslo zlyhajú.
UNDETERMINED	Stav pripojenia čísla nebolo možné určiť. Môže to byť spôsobené neplatným číslom, chybovou odpoveďou SS7 alebo nedostatočným pripojením k cieľovému mobilnému operátorovi. Pre ďalšiu diagnostiku skontrolujte kód chyby a jeho popis.

Posunúť hore

POST/hlr-lookupschránené

Spúšťa dávku asynchrónnych HLR vyhľadávaní, ktoré získavajú aktuálne údaje o konektivite mobilných telefónov a prenositeľnosti čísel od sieťových operátorov. Výsledky sa doručujú prostredníctvom webhookov na váš server. Táto metóda je optimalizovaná pre spracovanie veľkého množstva čísel, ktoré nevyžadujú okamžité odpovede, ako je čistenie a overovanie databáz. Pre aplikácie v reálnom čase, ako je smerovanie hovorov alebo doručovanie SMS, zvážte použitie koncového bodu POST /hlr-lookup.

Tento koncový bod je ideálny pre hromadné zpracovanie, keď je cieľom identifikovať telefónne čísla, ktoré sú aktuálne dostupné (pripojené) alebo nedostupné (telefón vypnutý), a zároveň odfiltrovať neplatné, nepriradené alebo falošné čísla. Okrem toho poskytuje aktuálny stav prenositeľnosti (MCCMNC) spolu s údajmi o konektivite.

Pred použitím tohto koncového bodu sa uistite, že je nakonfigurovaná webhook URL adresa na asynchrónne prijímanie výsledkov vyhľadávania. Môžete to nastaviť v nastaveniach API.

Požiadavka Úspešná odpoveď Chybová odpoveď Webhooky Referencia stavov

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

Dáta požiadavky

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

Parametre požiadavky

Kľúč	Typ	Popis	Predvolené	Povinné
`msisdns`	array	Pole mobilných telefónnych čísel (MSISDN) v medzinárodnom formáte (napr. +14156226819 alebo 0014156226819). Do jednej požiadavky môžete zahrnúť až 1000 čísel.	null	povinné
`route`	string(3)	Voliteľný trojznakový identifikátor určujúci trasu pre toto vyhľadávanie. Nastavte na `null` alebo vynechajte tento parameter na použitie vašej vlastnej mapy smerovania alebo nechajte náš systém automaticky určiť najlepšiu trasu pre toto vyhľadávanie.	null	voliteľné
`storage`	string	Voliteľný identifikátor úložiska určujúci správu, do ktorej sa uložia výsledky na manuálne preskúmanie, analýzu a reporting. Systém automaticky pridáva časovú značku s aktuálnym mesiacom. Ak je vynechaný alebo nastavený na `null`, systém automaticky zoskupí výsledky podľa mesiaca na účely reportingu.	null	voliteľné

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

Atribúty úspešnej odpovede

Meno	Typ	Popis	Voliteľný
`accepted`	array	Zoznam objektov obsahujúcich jedinečné identifikátory a MSISDN, ktoré boli prijaté na spracovanie.	false
`accepted_count`	integer	Celkový počet MSISDN úspešne prijatých na spracovanie.	false
`rejected`	array	Zoznam objektov obsahujúcich jedinečné identifikátory a MSISDN, ktoré boli zamietnuté na spracovanie, zvyčajne z dôvodu neplatných čísel. Za zamietnuté položky sa neúčtuje poplatok.	false
`rejected_count`	integer	Celkový počet MSISDN zamietnutých z dôvodu chýb pri validácii.	false
`total_count`	integer	Celkový počet prijatých a zamietnutých MSISDN, ktoré boli odoslané na spracovanie.	false
`cost`	string	Desatinná hodnota reprezentovaná ako reťazec, ktorá udává celkové náklady v EUR za prijaté vyhľadávania.	false
`storage`	string	Názov úložiska, do ktorého sa pridávajú výsledky vyhľadávania, používaný na vytváranie reportov a sťahovanie CSV súborov cez webové rozhranie.	false
`route`	string(3\|4)	Tri alebo štvorznakový identifikátor určujúci trasu použitú pre túto požiadavku vyhľadávania. Obsahuje AUTO, ak bolo požadované automatické smerovanie na základe čísla.	false
`webhook_urls`	array	Webhook URL adresy nakonfigurované vo vašich nastaveniach API. Výsledky sa sem odosielajú späť.	false

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

Parametre chybovej odpovede

Meno	Typ	Popis	Voliteľný
`errors[]`	string[]	Zoznam reťazcov vysvetľujúcich chybu.	false

Spracovanie webhookov

Po odoslaní začne naša platforma spracovávať poskytnuté telefónne čísla a výsledky posiela na vami predtým zadanú webhook URL adresu na vašom serveri. Výsledky sú prenášané ako HTTP POST požiadavka s JSON objektom v tele požiadavky.

Autentifikácia

Overte webhook kontrolou HTTP hlavičky X-Signatures.

Hlavička X-Signatures obsahuje zoznam podpisov oddelených bodkočiarkou. Každý podpis v zozname je vygenerovaný pomocou jedného z API tajných kľúčov nakonfigurovaných vo vašom účte. Pre overenie webhooku vygenerujte SHA-256 hash pomocou vášho API kľúča, tajného kľúča a pôvodného HTTP tela - potom ho porovnajte s podpismi v zozname.

Zhoda potvrdzuje, že požiadavka je autentická a podpísaná tajným kľúčom, ktorý máte pod kontrolou.

Príklad kódu

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

Požiadavka je platná, ak sa ktorýkoľvek z podpisov uvedených v hlavičke zhoduje so SHA256 hashom vypočítaným zo spojeného reťazca vášho API kľúča, tajného kľúča a HTTP tela.

Potvrdenie prijatia

Váš server by mal odpovedať HTTP stavovým kódom 200 OK na potvrdenie úspešného prijatia. Ak je vrátený akýkoľvek iný kód odpovede, dôjde k vypršaniu časového limitu (10 sekúnd) alebo vznikne akýkoľvek iný problém s doručením, systém automaticky zopakuje webhook po jednej minúte. Ak požiadavka naďalej zlyhá, opakovania budú nasledovať stratégiu exponenciálneho spomalenia s ďalšími pokusmi po 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minútach.

Tento mechanizmus opakovania zabezpečuje maximálnu spoľahlivosť pri doručovaní výsledkov vyhľadávania do vašej infraštruktúry. Minimalizuje riziko straty dát v dôsledku dočasných problémov so sieťou alebo výpadku servera.

Obsah webhooku

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

Atribúty webhook payloadu

JSON objekt obsahuje atribút type => HLR spolu s atribútom results, ktorý zahŕňa zoznam objektov vyhľadávania, ako je zdokumentované nižšie.

Meno	Typ	Popis	Voliteľný
`id`	string(12)	Jedinečný identifikátor priradený k tejto vyhľadávacej požiadavke.	false
`msisdn`	string	Mobilné telefónne číslo, ktoré sa vyhľadáva, formátované v medzinárodnom formáte (napr. +14156226819 alebo 0014156226819).	false
`connectivity_status`	string	Označuje, či sa úspešne získal stav pripojenia čísla. Možné hodnoty: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` alebo `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Päť- alebo šesťmiestny kód krajiny mobilnej siete (MCC) a kód mobilnej siete (MNC) identifikujúci sieť aktuálne priradenú k telefónnemu číslu.	true
`mcc`	string(3)	Trojmiestny kód krajiny mobilnej siete (MCC) identifikujúci krajinu, v ktorej je telefónne číslo registrované.	true
`mnc`	string(2\|3)	Dvoj- alebo trojmiestny kód mobilnej siete (MNC) identifikujúci konkrétnu sieť, ku ktorej telefónne číslo patrí.	true
`imsi`	string	Medzinárodná identita mobilného účastníka (IMSI), jedinečný identifikátor SIM karty priradenej k tomuto číslu. Dostupnosť závisí od konfigurácie siete.	true
`msin`	string(10)	Identifikačné číslo mobilného predplatného (MSIN) v databáze mobilného operátora. Dostupnosť závisí od konfigurácie siete.	true
`msc`	string(12)	Centrum prepájania mobilných hovorov (MSC) aktuálne obsluhujúce komunikáciu tohto účastníka. Dostupnosť závisí od konfigurácie siete.	true
`original_network_name`	string	Pôvodný (natívny) názov sieťového operátora priradený k tomuto číslu.	true
`original_country_name`	string	Úplný názov krajiny, v ktorej bolo mobilné telefónne číslo pôvodne registrované, uvedený v angličtine.	true
`original_country_code`	string(2)	Dvojznakový ISO kód krajiny reprezentujúci krajinu, v ktorej bolo telefónne číslo prvýkrát pridelené.	true
`original_country_prefix`	string	Medzinárodné predvolené číslo (kód krajiny) zodpovedajúce pôvodnej krajine mobilného telefónneho čísla.	true
`is_ported`	boolean	Označuje, či bolo mobilné číslo prenesené z pôvodnej siete k inému operátorovi.	true
`ported_network_name`	string	Názov sieťového operátora, ku ktorému bolo mobilné číslo prenesené, ak je to relevantné.	true
`ported_country_name`	string	Názov krajiny, do ktorej bolo mobilné číslo prenesené, ak je to relevantné.	true
`ported_country_code`	string(2)	Dvojznakový ISO kód krajiny reprezentujúci krajinu, do ktorej bolo mobilné číslo prenesené, ak je to relevantné.	true
`ported_country_prefix`	string	Medzinárodné predvolené číslo (kód krajiny) pre krajinu, do ktorej bolo mobilné číslo prenesené, ak je to relevantné.	true
`is_roaming`	boolean	Označuje, či mobilné číslo aktuálne roamuje v zahraničnej sieti. Dostupnosť stavu roamingu závisí od mobilného sieťového operátora.	true
`roaming_network_name`	string	Názov siete, v ktorej mobilné číslo aktuálne roamuje, ak je to relevantné.	true
`roaming_country_name`	string	Názov krajiny, v ktorej mobilné číslo aktuálne roamuje, ak je to relevantné.	true
`roaming_country_code`	string(2)	Dvojznakový ISO kód krajiny, v ktorej mobilné číslo aktuálne roamuje, ak je to relevantné.	true
`roaming_country_prefix`	string	Medzinárodné predvolené číslo (kód krajiny) krajiny, v ktorej mobilné číslo aktuálne roamuje, ak je to relevantné.	true
`cost`	string	Desatinná hodnota reprezentovaná ako reťazec, označujúca náklady na vyhľadávanie v EUR.	true
`timestamp`	string	Časová pečiatka vo formáte W3C vrátane časového pásma, určujúca kedy bolo vyhľadávanie dokončené.	true
`storage`	string	Názov úložiska, kde boli uložené výsledky vyhľadávania. Zodpovedá názvom reportov a CSV súborov dostupných cez webové rozhranie.	true
`route`	string(3)	Trojznakový identifikátor označujúci metódu smerovania použitú pre túto vyhľadávaciu požiadavku.	true
`processing_status`	string	Výsledok spracovania vyhľadávania. Možné hodnoty: `COMPLETED` (úspešné), `REJECTED` (sieť nedostupná, bez poplatku) alebo `FAILED` (počas spracovania došlo k chybe).	false
`error_code`	integer	Voliteľný interný kód chyby poskytujúci dodatočné diagnostické informácie pre zákaznícku podporu.	true
`error_description`	string	Stručné vysvetlenie daného kódu chyby (ak existuje) v angličtine ako obyčajný text.	true
`data_source`	string	Zdroj dát použitý pre túto požiadavku. Možné hodnoty: `LIVE_HLR` (HLR dotaz v reálnom čase) alebo `MNP_DB` (statická databáza prenositeľnosti mobilných čísel). Podrobnosti nájdete v možnostiach smerovania.	false
`routing_instruction`	string	Reťazec oddelený dvojbodkou popisujúci inštrukciu smerovania použitú v požiadavke. Prvý komponent je `STATIC`, keď ste zadali trasu, alebo `AUTO` pre automatické smerovanie; druhý komponent je identifikátor trasy a pri požiadavkách automatického smerovania tretí komponent zobrazuje pôvod, na základe ktorého sa rozhodlo o smerovaní (t.j. `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

Stav	Popis
CONNECTED	Číslo je platné a cieľové zariadenie je momentálne pripojené k mobilnej sieti. Hovory, SMS a ďalšie služby by mali príjemcu úspešne zastihnúť.
ABSENT	Číslo je platné, ale cieľové zariadenie je buď vypnuté alebo dočasne mimo dosahu siete. Správy alebo hovory nemusia byť doručené, kým sa zariadenie znovu nepripojí k sieti.
INVALID_MSISDN	Číslo je neplatné alebo momentálne nie je priradené žiadnemu účastníkovi v mobilnej sieti. Hovory a správy na toto číslo zlyhajú.
UNDETERMINED	Stav pripojenia čísla nebolo možné určiť. Môže to byť spôsobené neplatným číslom, chybovou odpoveďou SS7 alebo nedostatočným pripojením k cieľovému mobilnému operátorovi. Pre ďalšiu diagnostiku skontrolujte kód chyby a jeho popis.

Posunúť hore

POST/mnp-lookupchránené

Vykoná synchrónne MNP vyhľadávanie a poskytuje informácie o prenositeľnosti mobilných čísel a sieti. Tento endpoint je vhodný, ak je vaším primárnym cieľom extrahovať aktuálne MCCMNC daného mobilného telefónneho čísla a určiť pôvodnú a aktuálnu sieť v reálnom čase.

Pre hromadné zpracovanie veľkých dátových súborov, ktoré nevyžadujú okamžité výsledky, zvážte použitie asynchrónneho POST /mnp-lookups, ktorý je optimalizovaný pre vysokorýchlostné dávkové spracovanie.

MNP dotazy spoľahlivo určujú prenositeľnosť a informácie o sieti, ale neindikujú, či je cieľový mobilný telefón momentálne pripojený k sieti a dostupný. Pre získanie informácií o živom pripojení použite prosím endpoint POST /hlr-lookup.

Požiadavka Úspešná odpoveď Chybová odpoveď

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

Dáta požiadavky

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

Parametre požiadavky

Kľúč	Typ	Popis	Predvolené	Povinné
`msisdn`	string	Číslo mobilného telefónu (MSISDN), ktoré má byť vyhľadané, uvedené v medzinárodnom formáte (napr. +14156226819 alebo 0014156226819). Predvoľby krajín musia byť uvedené.	null	povinné
`route`	string(3)	Voliteľný trojznakový identifikátor určujúci trasu pre toto vyhľadávanie. Nastavte na `null` alebo vynechajte tento parameter na použitie vašej vlastnej mapy smerovania alebo nechajte náš systém automaticky určiť najlepšiu trasu pre toto vyhľadávanie.	null	voliteľné
`storage`	string	Voliteľný identifikátor úložiska určujúci správu, do ktorej sa uložia výsledky na manuálne preskúmanie, analýzu a reporting. Systém automaticky pridáva časovú značku s aktuálnym mesiacom. Ak je vynechaný alebo nastavený na `null`, systém automaticky zoskupí výsledky podľa mesiaca na účely reportingu.	null	voliteľné

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

Atribúty úspešnej odpovede

Meno	Typ	Popis	Voliteľný
`id`	string(12)	Jedinečný 12-znakový identifikátor pre toto vyhľadávanie.	false
`msisdn`	string	Mobilné telefónne číslo vyhodnotené v tejto požiadavke na vyhľadávanie.	false
`query_status`	string	Označuje, či bolo získanie informácií o prenositeľnosti a sieti úspešné. Možné hodnoty sú `OK` alebo `FAILED`.	false
`mccmnc`	string(5\|6)	Päť- alebo šesťznakový MCCMNC (kombinácia kódu krajiny mobilnej siete a kódu mobilnej siete), ktorý identifikuje sieť, do ktorej mobilné telefónne číslo aktuálne patrí.	true
`mcc`	string(3)	Trojznakový MCC (kód krajiny mobilnej siete) reprezentujúci krajinu spojenú s aktuálnou sieťou mobilného telefónneho čísla.	true
`mnc`	string(2\|3)	Dva- alebo trojznakový MNC (kód mobilnej siete), ktorý identifikuje aktuálneho sieťového operátora pre mobilné telefónne číslo.	true
`is_ported`	boolean	Označuje, či bolo telefónne číslo prenesené z pôvodnej siete k novému operátorovi.	true
`original_network_name`	string	Ľubovoľný reťazec (v angličtine) špecifikujúci názov pôvodného sieťového operátora skúmaného mobilného telefónneho čísla.	true
`original_country_name`	string	Ľubovoľný reťazec (v angličtine) označujúci pôvodnú krajinu skúmaného mobilného telefónneho čísla.	true
`original_country_code`	string(2)	Dvojznakový ISO kód krajiny reprezentujúci pôvodnú krajinu skúmaného mobilného telefónneho čísla.	true
`original_country_prefix`	string	Predvoľba pôvodnej krajiny spojenej so skúmaným mobilným telefónnym číslom.	true
`ported_network_name`	string	Špecifikuje sieťového operátora, ku ktorému bolo skúmané mobilné telefónne číslo prenesené, ak je to relevantné.	true
`ported_country_name`	string	Špecifikuje krajinu, do ktorej bolo skúmané mobilné telefónne číslo prenesené, ak je to relevantné.	true
`ported_country_code`	string(2)	Dvojznakový ISO kód krajiny reprezentujúci krajinu, do ktorej bolo skúmané mobilné telefónne číslo prenesené, ak je to relevantné.	true
`ported_country_prefix`	string	Predvoľba krajiny, do ktorej bolo skúmané mobilné telefónne číslo prenesené, ak je to relevantné.	true
`extra`	string	Ľubovoľný reťazec poskytujúci voliteľné doplňujúce informácie o telefónnom čísle.	true
`cost`	string	Desatinná hodnota, reprezentovaná ako reťazec, označujúca náklady v EUR za toto vyhľadávanie.	true
`timestamp`	string	Časová pečiatka vo formáte W3C, vrátane informácií o časovom pásme, označujúca čas dokončenia vyhľadávania.	true
`storage`	string	Názov úložiska (alebo názov reportu), do ktorého boli pripojené výsledky vyhľadávania. Používa sa na stiahnutie CSV a vytváranie reportov prostredníctvom webového rozhrania.	true
`route`	string(3)	Trojznakový identifikátor špecifikujúci trasu použitú pre túto požiadavku na vyhľadávanie.	true
`error_code`	integer	Voliteľný interný kód chyby poskytujúci dodatočný kontext pre diagnostiku zákazníckej podpory.	true

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

Parametre chybovej odpovede

Meno	Typ	Popis	Voliteľný
`errors[]`	string[]	Zoznam reťazcov vysvetľujúcich chybu.	false

Posunúť hore

POST/mnp-lookupschránené

Spustí dávku asynchrónnych MNP (prenositeľnosť mobilných čísel) vyhľadávaní, ktoré získavajú aktuálny MCCMNC a v reálnom čase určujú pôvodnú a súčasnú sieť. Výsledky sa doručujú prostredníctvom webhookov na váš server. Táto metóda je optimalizovaná pre spracovanie veľkého množstva čísel, ktoré nevyžadujú okamžité odpovede, ako je čistenie a overovanie databáz. Pre aplikácie v reálnom čase, ako je smerovanie hovorov alebo doručovanie SMS, zvážte použitie koncového bodu POST /mnp-lookup.

MNP dotazy spoľahlivo určujú prenositeľnosť a informácie o sieti, ale neindikujú, či je cieľový mobilný telefón momentálne pripojený k sieti a dostupný. Pre získanie informácií o živom pripojení použite prosím endpoint POST /hlr-lookups.

Pred použitím tohto koncového bodu sa uistite, že je nakonfigurovaná webhook URL adresa na asynchrónne prijímanie výsledkov vyhľadávania. Môžete to nastaviť v nastaveniach API.

Požiadavka Úspešná odpoveď Chybová odpoveď Webhooky

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

Dáta požiadavky

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

Parametre požiadavky

Kľúč	Typ	Popis	Predvolené	Povinné
`msisdns`	array	Pole mobilných telefónnych čísel (MSISDN) v medzinárodnom formáte (napr. +14156226819 alebo 0014156226819). Do jednej požiadavky môžete zahrnúť až 1000 čísel.	null	povinné
`route`	string(3)	Voliteľný trojznakový identifikátor určujúci trasu pre toto vyhľadávanie. Nastavte na `null` alebo vynechajte tento parameter pre použitie vašej vlastnej mapy smerovania alebo nechajte náš systém automaticky určiť najlepšie trasy pre túto požiadavku.	null	voliteľné
`storage`	string	Voliteľný identifikátor úložiska určujúci správu, do ktorej sa uložia výsledky na manuálne preskúmanie, analýzu a reporting. Systém automaticky pridáva časovú značku s aktuálnym mesiacom. Ak je vynechaný alebo nastavený na `null`, systém automaticky zoskupí výsledky podľa mesiaca na účely reportingu.	null	voliteľné

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

Atribúty úspešnej odpovede

Meno	Typ	Popis	Voliteľný
`accepted`	array	Zoznam objektov obsahujúcich jedinečné identifikátory a MSISDN, ktoré boli prijaté na spracovanie.	false
`accepted_count`	integer	Celkový počet MSISDN úspešne prijatých na spracovanie.	false
`rejected`	array	Zoznam objektov obsahujúcich jedinečné identifikátory a MSISDN, ktoré boli zamietnuté na spracovanie, zvyčajne z dôvodu neplatných čísel. Za zamietnuté položky sa neúčtuje poplatok.	false
`rejected_count`	integer	Celkový počet MSISDN zamietnutých z dôvodu chýb pri validácii.	false
`total_count`	integer	Celkový počet prijatých a zamietnutých MSISDN, ktoré boli odoslané na spracovanie.	false
`cost`	string	Desatinná hodnota reprezentovaná ako reťazec, ktorá udává celkové náklady v EUR za prijaté vyhľadávania.	false
`storage`	string	Názov úložiska, do ktorého sa pridávajú výsledky vyhľadávania, používaný na vytváranie reportov a sťahovanie CSV súborov cez webové rozhranie.	false
`route`	string(3)	Trojznakový identifikátor špecifikujúci trasu použitú pre túto požiadavku na vyhľadávanie.	false
`webhook_urls`	array	Webhook URL adresy nakonfigurované vo vašich nastaveniach API. Výsledky sa sem odosielajú späť.	false

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

Parametre chybovej odpovede

Meno	Typ	Popis	Voliteľný
`errors[]`	string[]	Zoznam reťazcov vysvetľujúcich chybu.	false

Spracovanie webhookov

Po odoslaní začne naša platforma spracovávať poskytnuté telefónne čísla a výsledky posiela na vami predtým zadanú webhook URL adresu na vašom serveri. Výsledky sú prenášané ako HTTP POST požiadavka s JSON objektom v tele požiadavky.

Autentifikácia

Overte webhook kontrolou HTTP hlavičky X-Signatures.

Hlavička X-Signatures obsahuje zoznam podpisov oddelených bodkočiarkou. Každý podpis v zozname je vygenerovaný pomocou jedného z API tajných kľúčov nakonfigurovaných vo vašom účte. Pre overenie webhooku vygenerujte SHA-256 hash pomocou vášho API kľúča, tajného kľúča a pôvodného HTTP tela - potom ho porovnajte s podpismi v zozname.

Zhoda potvrdzuje, že požiadavka je autentická a podpísaná tajným kľúčom, ktorý máte pod kontrolou.

Príklad kódu

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

Požiadavka je platná, ak sa ktorýkoľvek z podpisov uvedených v hlavičke zhoduje so SHA256 hashom vypočítaným zo spojeného reťazca vášho API kľúča, tajného kľúča a HTTP tela.

Potvrdenie prijatia

Váš server by mal odpovedať HTTP stavovým kódom 200 OK na potvrdenie úspešného prijatia. Ak je vrátený akýkoľvek iný kód odpovede, dôjde k vypršaniu časového limitu (10 sekúnd) alebo vznikne akýkoľvek iný problém s doručením, systém automaticky zopakuje webhook po jednej minúte. Ak požiadavka naďalej zlyhá, opakovania budú nasledovať stratégiu exponenciálneho spomalenia s ďalšími pokusmi po 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minútach.

Tento mechanizmus opakovania zabezpečuje maximálnu spoľahlivosť pri doručovaní výsledkov vyhľadávania do vašej infraštruktúry. Minimalizuje riziko straty dát v dôsledku dočasných problémov so sieťou alebo výpadku servera.

Obsah webhooku

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

Atribúty webhook payloadu

JSON objekt obsahuje atribút type => MNP spolu s atribútom results, ktorý zahŕňa zoznam objektov vyhľadávania, ako je zdokumentované nižšie.

Meno	Typ	Popis	Voliteľný
`id`	string(12)	Jedinečný 12-znakový identifikátor pre toto vyhľadávanie.	false
`msisdn`	string	Mobilné telefónne číslo vyhodnotené v tejto požiadavke na vyhľadávanie.	false
`query_status`	string	Označuje, či bolo získanie informácií o prenositeľnosti a sieti úspešné. Možné hodnoty sú `OK` alebo `FAILED`.	false
`mccmnc`	string(5\|6)	Päť- alebo šesťznakový MCCMNC (kombinácia kódu krajiny mobilnej siete a kódu mobilnej siete), ktorý identifikuje sieť, do ktorej mobilné telefónne číslo aktuálne patrí.	true
`mcc`	string(3)	Trojznakový MCC (kód krajiny mobilnej siete) reprezentujúci krajinu spojenú s aktuálnou sieťou mobilného telefónneho čísla.	true
`mnc`	string(2\|3)	Dva- alebo trojznakový MNC (kód mobilnej siete), ktorý identifikuje aktuálneho sieťového operátora pre mobilné telefónne číslo.	true
`is_ported`	boolean	Označuje, či bolo telefónne číslo prenesené z pôvodnej siete k novému operátorovi.	true
`original_network_name`	string	Ľubovoľný reťazec (v angličtine) špecifikujúci názov pôvodného sieťového operátora skúmaného mobilného telefónneho čísla.	true
`original_country_name`	string	Ľubovoľný reťazec (v angličtine) označujúci pôvodnú krajinu skúmaného mobilného telefónneho čísla.	true
`original_country_code`	string(2)	Dvojznakový ISO kód krajiny reprezentujúci pôvodnú krajinu skúmaného mobilného telefónneho čísla.	true
`original_country_prefix`	string	Predvoľba pôvodnej krajiny spojenej so skúmaným mobilným telefónnym číslom.	true
`ported_network_name`	string	Špecifikuje sieťového operátora, ku ktorému bolo skúmané mobilné telefónne číslo prenesené, ak je to relevantné.	true
`ported_country_name`	string	Špecifikuje krajinu, do ktorej bolo skúmané mobilné telefónne číslo prenesené, ak je to relevantné.	true
`ported_country_code`	string(2)	Dvojznakový ISO kód krajiny reprezentujúci krajinu, do ktorej bolo skúmané mobilné telefónne číslo prenesené, ak je to relevantné.	true
`ported_country_prefix`	string	Predvoľba krajiny, do ktorej bolo skúmané mobilné telefónne číslo prenesené, ak je to relevantné.	true
`extra`	string	Ľubovoľný reťazec poskytujúci voliteľné doplňujúce informácie o telefónnom čísle.	true
`cost`	string	Desatinná hodnota, reprezentovaná ako reťazec, označujúca náklady v EUR za toto vyhľadávanie.	true
`timestamp`	string	Časová pečiatka vo formáte W3C, vrátane informácií o časovom pásme, označujúca čas dokončenia vyhľadávania.	true
`storage`	string	Názov úložiska (alebo názov reportu), do ktorého boli pripojené výsledky vyhľadávania. Používa sa na stiahnutie CSV a vytváranie reportov prostredníctvom webového rozhrania.	true
`route`	string(3)	Trojznakový identifikátor špecifikujúci trasu použitú pre túto požiadavku na vyhľadávanie.	true
`error_code`	integer	Voliteľný interný kód chyby poskytujúci dodatočný kontext pre diagnostiku zákazníckej podpory.	true

Posunúť hore

POST/nt-lookupchránené

Vykoná synchrónne vyhľadávanie typu čísla (NT). Tento endpoint je ideálny, ak je vašim primárnym cieľom zistiť v reálnom čase, či poskytnuté telefónne čísla patria do rozsahov pevnej linky, mobilných sietí, prémiových služieb, VoIP, pagerov alebo iných kategórií číselného plánu.

NT dotazy spoľahlivo detegujú typ telefónneho čísla, avšak neindikujú, či je cieľové číslo momentálne pripojené k sieti a dostupné. Pre získanie informácií o aktuálnej konektivite použite prosím endpoint POST /hlr-lookup.

Ak váš prípad použitia vyžaduje presné informácie o sieti a prenositeľnosti (MCCMNC), ale nie stav aktívnej konektivity, použite prosím endpoint POST /mnp-lookup pre dotazy na prenositeľnosť mobilných čísel.

Požiadavka Úspešná odpoveď Chybová odpoveď Referencia typov

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

Dáta požiadavky

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

Parametre požiadavky

Kľúč	Typ	Popis	Predvolené	Povinné
`number`	string	Telefónne číslo v medzinárodnom formáte (napr. +4989702626 alebo 004989702626).	null	mandatory
`route`	string(3)	Voliteľný trojznakový identifikátor určujúci trasu pre toto vyhľadávanie. Nastavte na `null` alebo vynechajte tento parameter pre použitie vašej vlastnej mapy smerovania alebo nechajte náš systém automaticky určiť najlepšie trasy pre túto požiadavku.	null	voliteľné
`storage`	string	Voliteľný identifikátor úložiska určujúci správu, do ktorej sa uložia výsledky na manuálne preskúmanie, analýzu a reporting. Systém automaticky pridáva časovú značku s aktuálnym mesiacom. Ak je vynechaný alebo nastavený na `null`, systém automaticky zoskupí výsledky podľa mesiaca na účely reportingu.	null	voliteľné

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

Atribúty úspešnej odpovede

Meno	Typ	Popis	Voliteľný
`id`	string(12)	Jedinečný identifikátor priradený k tejto vyhľadávacej požiadavke.	false
`number`	string	Telefónne číslo, ktoré bylo vyhodnotené počas tejto vyhľadávacej požiadavky.	false
`number_type`	string	Zistený typ čísla. Možné hodnoty zahŕňajú: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Označuje, či boli informácie o type čísla úspešne získané. Vracia `OK` v prípade úspechu alebo `FAILED`, ak vyhľadávanie zlyhalo.	false
`is_valid`	boolean	Označuje, či je telefónne číslo syntakticky platné.	true
`invalid_reason`	string	Textová správa v angličtine špecifikujúca dôvod, prečo je telefónne číslo považované za neplatné (napr. "too short" alebo "invalid prefix"), alebo `null`, ak je číslo platné.	true
`is_possibly_ported`	boolean	Označuje, či mohlo byť telefónne číslo prenesené z pôvodného operátora k inému poskytovateľovi. Pre definitívne informácie o prenositeľnosti použite MNP vyhľadávania.	true
`is_vanity_number`	boolean	Označuje, či je telefónne číslo vanity číslom, čo znamená, že obsahuje abecedné znaky.	true
`qualifies_for_hlr_lookup`	boolean	Označuje, či je telefónne číslo vhodné pre ďalšie dotazy prostredníctvom HLR vyhľadávaní.	true
`mccmnc`	string(5\|6)	Päť alebo šesť znakový reťazec reprezentujúci MCCMNC tuple (kód mobilnej krajiny a kód mobilnej siete), ktorý identifikuje pôvodnú sieť mobilného telefónneho čísla.	true
`mcc`	string(3)	Tri znakový reťazec reprezentujúci MCC (kód mobilnej krajiny), ktorý identifikuje krajinu spojenú s pôvodnou mobilnou sieťou telefónneho čísla.	true
`mnc`	string(2\|3)	Dva alebo tri znakový reťazec reprezentujúci MNC (kód mobilnej siete), ktorý identifikuje pôvodného operátora mobilnej siete telefónneho čísla.	true
`original_network_name`	string	Ľubovoľný textový reťazec v angličtine špecifikujúci názov pôvodného sieťového operátora kontrolovaného mobilného telefónneho čísla.	true
`original_country_name`	string	Ľubovoľný textový reťazec v angličtine špecifikujúci pôvodnú krajinu spojenú s kontrolovaným mobilným telefónnym číslom.	true
`original_country_code`	string(2)	Dva znakový ISO kód krajiny označujúci pôvodnú krajinu kontrolovaného mobilného telefónneho čísla.	true
`regions`	array	Zoznam čitateľných reťazcov v angličtine, ktoré špecifikujú geografický región (regióny) spojený s týmto telefónnym číslom.	true
`timezones`	array	Zoznam časových pásiem (vo formáte Olson) spojených s týmto telefónnym číslom.	true
`info_text`	string	Ľubovoľný reťazec, ktorý môže obsahovať dodatočné informácie o telefónnom čísle.	true
`cost`	string	Desatinná hodnota reprezentovaná ako reťazec, označujúca náklady (v EUR) na toto vyhľadávanie.	true
`timestamp`	string	Časová pečiatka vo formáte W3C (vrátane časového pásma) označujúca, kedy bolo vyhľadávanie dokončené.	true
`storage`	string	Špecifikuje názov úložiska, kam boli pripojené výsledky vyhľadávania. Toto zodpovedá názvu reportu použitému pre CSV sťahovanie a analytiku cez webové rozhranie.	true
`route`	string(3)	Trojznakový identifikátor špecifikujúci trasu použitú pre túto požiadavku na vyhľadávanie.	true

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

Parametre chybovej odpovede

Meno	Typ	Popis	Voliteľný
`errors[]`	string[]	Zoznam reťazcov vysvetľujúcich chybu.	false

Typ	Popis
LANDLINE	Číslo pevnej linky.
MOBILE	Číslo mobilného telefónu. Spĺňa podmienky pre HLR vyhľadávanie na získanie dodatočných informácií o stave pripojenia, sieti, prenositeľnosti a roamingu.
MOBILE_OR_LANDLINE	Číslo pevnej linky alebo mobilného telefónu. Môže spĺňať podmienky pre HLR vyhľadávanie.
TOLL_FREE	Bezplatné telefónne číslo.
PREMIUM_RATE	Telefónne číslo s prémiovou sadzbou a dodatočnými poplatkami.
SHARED_COST	Telefónne číslo so zdieľanými nákladmi. Zvyčajne menej nákladné ako čísla s prémiovou sadzbou.
VOIP	Voice over IP telefónne číslo. Zahŕňa TSoIP telefónne čísla (Telephony Service over IP).
PAGER	Číslo pagera. Zvyčajne bez hlasovej funkcionality.
UAN	Univerzálne prístupové číslo (firemné číslo). Môže byť presmerované na konkrétne pobočky, ale umožňuje používať jedno číslo pre celú spoločnosť.
VOICEMAIL	Číslo hlasovej schránky.
UNKNOWN	Typ čísla sa nepodarilo určiť.

Posunúť hore

POST/nt-lookups chránené

Tento endpoint spúšťa sériu asynchrónnych vyhľadávaní typu čísla s výsledkami odoslanými späť na váš server prostredníctvom webhooku. Je vhodný, ak je vaším primárnym cieľom zistiť, či dané telefónne čísla patria do rozsahov pevných liniek, mobilov, prémiových služieb, VoIP, pagerov alebo iných číselných plánov. Optimalizovaný pre rýchle spracovanie veľkých objemov čísel, tento endpoint je ideálny pre hromadné operácie (napr. sanitácia databázy). Pre živú prevádzku a časovo kritické prípady použitia prosím využite endpoint POST /nt-lookup.

Ako predpoklad pre vyvolanie tohto endpointu musíte špecifikovať webhook URL vo vašich API nastaveniach.

Požiadavka Úspešná odpoveď Chybová odpoveď Webhooky Referencia typov

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

Dáta požiadavky

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

Parametre požiadavky

Kľúč	Typ	Popis	Predvolené	Povinné
`numbers`	array	Pole telefónnych čísel v medzinárodnom formáte (napr. +14156226819 alebo 004989702626). Maximum 1000 čísel môže byť zahrnutých v jednej požiadavke.	null	povinné
`route`	string(3)	Voliteľný trojznakový identifikátor špecifikujúci trasu pre toto vyhľadávanie. Nastavte na `null` alebo vynechajte tento parameter pre použitie vašej vlastnej mapy smerovania alebo nechajte náš systém automaticky určiť najlepšiu trasu pre túto požiadavku.	null	voliteľné
`storage`	string	Voliteľný identifikátor úložiska určujúci správu, do ktorej sa uložia výsledky na manuálne preskúmanie, analýzu a reporting. Systém automaticky pridáva časovú značku s aktuálnym mesiacom. Ak je vynechaný alebo nastavený na `null`, systém automaticky zoskupí výsledky podľa mesiaca na účely reportingu.	null	voliteľné

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

Atribúty úspešnej odpovede

Meno	Typ	Popis	Voliteľný
`accepted`	array	Pole objektov, z ktorých každý obsahuje jedinečný identifikátor a telefónne číslo, ktoré bolo prijaté na zpracovanie.	false
`accepted_count`	integer	Celkový počet telefónnych čísel prijatých na spracovanie.	false
`rejected`	array	Pole objektov, z ktorých každý obsahuje jedinečný identifikátor a telefónne číslo, ktoré bolo odmietnuté na spracovanie. Zvyčajne sú tieto čísla neplatné a žiadny poplatok sa neúčtuje.	false
`rejected_count`	integer	Celkový počet telefónnych čísel, ktoré boli odmietnuté na spracovanie.	false
`total_count`	integer	Celkový počet prijatých a odmietnutých telefónnych čísel, ktoré boli odoslané na spracovanie.	false
`cost`	string	Reťazec reprezentujúci desatinnú hodnotu, ktorá udáva náklady v EUR za tieto vyhľadávania.	false
`storage`	string	Názov úložiska (reportu), do ktorého boli pripojené výsledky vyhľadávania. Tento názov sa používa pre CSV stiahnutia a analytiku cez webové rozhranie.	false
`route`	string(3)	Trojznakový identifikátor, ktorý špecifikuje trasu použitú pre túto požiadavku vyhľadávania.	false
`webhook_urls`	array	Webhook URL adresy nakonfigurované vo vašich nastaveniach API. Výsledky sa sem odosielajú späť.	false

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

Parametre chybovej odpovede

Meno	Typ	Popis	Voliteľný
`errors[]`	string[]	Zoznam reťazcov vysvetľujúcich chybu.	false

Spracovanie webhookov

Po odoslaní začne naša platforma spracovávať poskytnuté telefónne čísla a výsledky posiela na vami predtým zadanú webhook URL adresu na vašom serveri. Výsledky sú prenášané ako HTTP POST požiadavka s JSON objektom v tele požiadavky.

Autentifikácia

Overte webhook kontrolou HTTP hlavičky X-Signatures.

Hlavička X-Signatures obsahuje zoznam podpisov oddelených bodkočiarkou. Každý podpis v zozname je vygenerovaný pomocou jedného z API tajných kľúčov nakonfigurovaných vo vašom účte. Pre overenie webhooku vygenerujte SHA-256 hash pomocou vášho API kľúča, tajného kľúča a pôvodného HTTP tela - potom ho porovnajte s podpismi v zozname.

Zhoda potvrdzuje, že požiadavka je autentická a podpísaná tajným kľúčom, ktorý máte pod kontrolou.

Príklad kódu

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

Požiadavka je platná, ak sa ktorýkoľvek z podpisov uvedených v hlavičke zhoduje so SHA256 hashom vypočítaným zo spojeného reťazca vášho API kľúča, tajného kľúča a HTTP tela.

Potvrdenie prijatia

Váš server by mal odpovedať HTTP stavovým kódom 200 OK na potvrdenie úspešného prijatia. Ak je vrátený akýkoľvek iný kód odpovede, dôjde k vypršaniu časového limitu (10 sekúnd) alebo vznikne akýkoľvek iný problém s doručením, systém automaticky zopakuje webhook po jednej minúte. Ak požiadavka naďalej zlyhá, opakovania budú nasledovať stratégiu exponenciálneho spomalenia s ďalšími pokusmi po 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minútach.

Tento mechanizmus opakovania zabezpečuje maximálnu spoľahlivosť pri doručovaní výsledkov vyhľadávania do vašej infraštruktúry. Minimalizuje riziko straty dát v dôsledku dočasných problémov so sieťou alebo výpadku servera.

Obsah webhooku

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

Atribúty webhook payloadu

JSON objekt obsahuje atribút type => NT spolu s atribútom results, ktorý zahŕňa zoznam objektov vyhľadávania, ako je zdokumentované nižšie.

Meno	Typ	Popis	Voliteľný
`id`	string(12)	Jedinečný identifikátor priradený k tejto vyhľadávacej požiadavke.	false
`number`	string	Telefónne číslo, ktoré bylo vyhodnotené počas tejto vyhľadávacej požiadavky.	false
`number_type`	string	Zistený typ čísla. Možné hodnoty zahŕňajú: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Označuje, či boli informácie o type čísla úspešne získané. Vracia `OK` v prípade úspechu alebo `FAILED`, ak vyhľadávanie zlyhalo.	false
`is_valid`	boolean	Označuje, či je telefónne číslo syntakticky platné.	true
`invalid_reason`	string	Textová správa v angličtine špecifikujúca dôvod, prečo je telefónne číslo považované za neplatné (napr. "too short" alebo "invalid prefix"), alebo `null`, ak je číslo platné.	true
`is_possibly_ported`	boolean	Označuje, či mohlo byť telefónne číslo prenesené z pôvodného operátora k inému poskytovateľovi. Pre definitívne informácie o prenositeľnosti použite MNP vyhľadávania.	true
`is_vanity_number`	boolean	Označuje, či je telefónne číslo vanity číslom, čo znamená, že obsahuje abecedné znaky.	true
`qualifies_for_hlr_lookup`	boolean	Označuje, či je telefónne číslo vhodné pre ďalšie dotazy prostredníctvom HLR vyhľadávaní.	true
`mccmnc`	string(5\|6)	Päť alebo šesť znakový reťazec reprezentujúci MCCMNC tuple (kód mobilnej krajiny a kód mobilnej siete), ktorý identifikuje pôvodnú sieť mobilného telefónneho čísla.	true
`mcc`	string(3)	Tri znakový reťazec reprezentujúci MCC (kód mobilnej krajiny), ktorý identifikuje krajinu spojenú s pôvodnou mobilnou sieťou telefónneho čísla.	true
`mnc`	string(2\|3)	Dva alebo tri znakový reťazec reprezentujúci MNC (kód mobilnej siete), ktorý identifikuje pôvodného operátora mobilnej siete telefónneho čísla.	true
`original_network_name`	string	Ľubovoľný textový reťazec v angličtine špecifikujúci názov pôvodného sieťového operátora kontrolovaného mobilného telefónneho čísla.	true
`original_country_name`	string	Ľubovoľný textový reťazec v angličtine špecifikujúci pôvodnú krajinu spojenú s kontrolovaným mobilným telefónnym číslom.	true
`original_country_code`	string(2)	Dva znakový ISO kód krajiny označujúci pôvodnú krajinu kontrolovaného mobilného telefónneho čísla.	true
`regions`	array	Zoznam čitateľných reťazcov v angličtine, ktoré špecifikujú geografický región (regióny) spojený s týmto telefónnym číslom.	true
`timezones`	array	Zoznam časových pásiem (vo formáte Olson) spojených s týmto telefónnym číslom.	true
`info_text`	string	Ľubovoľný reťazec, ktorý môže obsahovať dodatočné informácie o telefónnom čísle.	true
`cost`	string	Desatinná hodnota reprezentovaná ako reťazec, označujúca náklady (v EUR) na toto vyhľadávanie.	true
`timestamp`	string	Časová pečiatka vo formáte W3C (vrátane časového pásma) označujúca, kedy bolo vyhľadávanie dokončené.	true
`storage`	string	Špecifikuje názov úložiska, kam boli pripojené výsledky vyhľadávania. Toto zodpovedá názvu reportu použitému pre CSV sťahovanie a analytiku cez webové rozhranie.	true
`route`	string(3)	Trojznakový identifikátor špecifikujúci trasu použitú pre túto požiadavku na vyhľadávanie.	true

Typ	Popis
LANDLINE	Číslo pevnej linky.
MOBILE	Číslo mobilného telefónu. Spĺňa podmienky pre HLR vyhľadávanie na získanie dodatočných informácií o stave pripojenia, sieti, prenositeľnosti a roamingu.
MOBILE_OR_LANDLINE	Číslo pevnej linky alebo mobilného telefónu. Môže spĺňať podmienky pre HLR vyhľadávanie.
TOLL_FREE	Bezplatné telefónne číslo.
PREMIUM_RATE	Telefónne číslo s prémiovou sadzbou a dodatočnými poplatkami.
SHARED_COST	Telefónne číslo so zdieľanými nákladmi. Zvyčajne menej nákladné ako čísla s prémiovou sadzbou.
VOIP	Voice over IP telefónne číslo. Zahŕňa TSoIP telefónne čísla (Telephony Service over IP).
PAGER	Číslo pagera. Zvyčajne bez hlasovej funkcionality.
UAN	Univerzálne prístupové číslo (firemné číslo). Môže byť presmerované na konkrétne pobočky, ale umožňuje používať jedno číslo pre celú spoločnosť.
VOICEMAIL	Číslo hlasovej schránky.
UNKNOWN	Typ čísla sa nepodarilo určiť.

Posunúť hore

GET/routechránené

Získava trasu, ktorá bude automaticky vybraná pri spustení HLR vyhľadávania bez zadania parametra route.

Automatický výber trasy je založený na smerovacej mape, ktorú možno získať pomocou endpointu GET /hlr-coverage, odvodený primárne z GET /routing-map. Svoju smerovaciu mapu môžete prispôsobiť a definovať vlastné pravidlá v nastaveniach účtu.

Požiadavka Úspešná odpoveď Chybová odpoveď

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

Parametre požiadavky

Kľúč	Typ	Popis	Predvolené	Povinné
`msisdn`	string	MSISDN, pre ktoré sa majú získať automaticky vybrané informácie o smerovaní.	null	povinné

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

Atribúty úspešnej odpovede

Meno	Typ	Popis	Voliteľný
`route`	string	Odporúčaná trasa.	false
`confidence_level`	string	Úroveň spoľahlivosti, s akou bola táto trasa vybraná, t.j. `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`.	false
`mccmnc`	string	MCCMNC založené na číslovacom pláne pre toto číslo.	false
`origin`	string	Pôvod, na ktorom je založené rozhodnutie o smerovaní, t.j. `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."
    ]
}

Parametre chybovej odpovede

Meno	Typ	Popis	Voliteľný
`errors[]`	string[]	Zoznam reťazcov vysvetľujúcich chybu.	false

Posunúť hore

GET/routeschránené

Tento endpoint vracia zoznam dostupných HLR, MNP a NT smerovaní. Každé smerovanie spolu s jeho funkciami a obmedzeniami je vysvetlené na stránke detaily smerovania.

Požiadavka Úspešná odpoveď Chybová odpoveď

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

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

Atribúty úspešnej odpovede

Meno	Typ	Popis	Voliteľný
`routes`	object	Objekt so smerovaniami zoskupenými podľa typu smerovania.	false
`HLR\|MNP\|NT`	string[]	Obsahuje zoznam identifikátorov smerovaní.	false

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

Parametre chybovej odpovede

Meno	Typ	Popis	Voliteľný
`errors[]`	string[]	Zoznam reťazcov vysvetľujúcich chybu.	false

Posunúť hore

GET/routing-mapchránené

Získava konfiguráciu automatického smerovania aktuálne aplikovanú na HLR vyhľadávania pre váš účet. Táto predvolená konfigurácia sa používa vždy, keď odošlete HLR vyhľadávania bez určenia parametra route. Svoju mapu smerovania môžete prispôsobiť a vytvoriť vlastné pravidlá v nastaveniach účtu.

Hierarchia konfigurácie prechádza od pravidiel na úrovni krajiny k pravidlám na úrovni MCCMNC a nakoniec k mapovaniu jednotlivých predvolieb telefónnych čísel. V praxi to znamená, že mapovanie jednotlivých predvolieb telefónnych čísel má prednosť pred konfliktným priradením MCCMNC, ktoré zase prepisuje pravidlá na úrovni krajiny. Upozorňujeme, že záložné MNP prepisuje akékoľvek konfliktné vlastné pravidlá, pokiaľ je zapnuté.

Požiadavka Úspešná odpoveď Chybová odpoveď

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

Atribúty úspešnej odpovede

Meno	Typ	Popis	Voliteľný
`default_route`	string	Predvolená trasa použitá, keď nie je možné určiť preferovanú možnosť smerovania pre MSISDN a neplatia žiadne vlastné pravidlá smerovania.	false
`mnp_fallback`	boolean	Označuje, či je zapnuté záložné MNP. Keď je zapnuté a HLR dotazy nie sú podporované sieťou (stav konektivity nie je dostupný), systém namiesto toho vykoná MNP vyhľadávanie.	false
`mccmncs`	array	Mapovanie kódov MCCMNC na ich automaticky vybrané trasy. Pri vykonávaní HLR vyhľadávania pre číslo v danom MCCMNC sa použije príslušná trasa.	false
`mccmnc`	string(5\|6)	Päť- alebo šesťznakový MCCMNC (kombinácia mobilného kódu krajiny a mobilného sieťového kódu) identifikujúci mobilného operátora.	false
`countrycode`	string(2)	Dvojznakový ISO kód krajiny identifikujúci krajinu siete.	false
`route`	string(3)	Vybraná trasa pre sieť.	false
`mno`	string	Spotrebiteľská značka, pod ktorou táto sieť pôsobí.	false
`confidence`	string	Úroveň spoľahlivosti, s ktorou bol výber vykonaný. Možné hodnoty sú: HIGH, NORMAL, LOW, MNP_REDIRECT. V prípade poslednej možnosti systém presmeruje prevádzku do tejto siete na MNP, ak je toto správanie povolené vo vašom účte. V opačnom prípade použije predvolenú trasu v účte.	false
`origin`	string	Pôvod, na ktorom je výber založený. Možné hodnoty 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	Zoznam vlastných pravidiel smerovania založených na predvoľbe nakonfigurovaných vo vašom účte, ak existujú.	false
`countrycode`	string(2)	Dvojznakový ISO kód krajiny identifikujúci krajinu predvoľby.	false
`cns`	string	Predvoľba, na ktorú sa pravidlo smerovania vzťahuje.	false
`route`	string(3)	Vybraná trasa pre predvoľbu.	false
`mccmnc`	string(5\|6)	Päť- alebo šesťznakový MCCMNC (kombinácia mobilného kódu krajiny a mobilného sieťového kódu) identifikujúci mobilného operátora.	true
`mno`	string	Spotrebiteľská značka, pod ktorou táto sieť pôsobí.	true
`countries`	array	Zoznam vlastných pravidiel založených na krajine nakonfigurovaných vo vašom účte, ak existujú.	false
`countrycode`	string(2)	Dvojznakový ISO kód krajiny identifikujúci krajinu.	false
`route`	string(3)	Vybraná trasa pre krajinu.	false

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

Parametre chybovej odpovede

Meno	Typ	Popis	Voliteľný
`errors[]`	string[]	Zoznam reťazcov vysvetľujúcich chybu.	false

Posunúť hore

GET/hlr-coverage chránené

Poskytuje prehľady HLR pokrytia na podporu rozhodovania založeného na dátach. Tento endpoint vám pomáha analyzovať možnosti smerovania HLR v reálnom čase naprieč mobilnými sieťami, identifikovať najefektívnejšie cesty pre vaše cieľové regióny a konfigurovať automatické smerovanie.

Odporúčané trasy z GET /route sú založené na údajoch o pokrytí získaných tu. Údaje o pokrytí sú dostupné aj na stránke pokrytie siete. Svoju mapu smerovania môžete ďalej prispôsobiť a definovať pravidlá v nastaveniach účtu.

Odporúčame oboznámiť sa s touto príručkou, ktorá vám pomôže interpretovať výsledky.

Požiadavka Úspešná odpoveď Chybová odpoveď Referencia stavov

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

Parametre požiadavky

Kľúč	Typ	Popis	Predvolené	Povinné
`countrycode`	string(2)	Povinný dvojpísmenový ISO kód krajiny používaný na filtrovanie výsledkov, ktorý vracia iba záznamy spojené so zadanou krajinou.	null	povinné
`sample_size`	string	Voliteľný parameter určujúci veľkosť vzorky. Možné hodnoty sú `LARGE`, `MEDIUM`, `SMALL`. Väčšie vzorky pokrývajú dlhšie časové obdobie, menšie vzorky pokrývajú veľmi nedávne časové obdobie.	LARGE	voliteľné

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

Atribúty úspešnej odpovede

Meno	Typ	Popis	Voliteľný
`name`	string	Názov vybranej krajiny v anglickom jazyku.	false
`countrycode`	string(2)	Dvojznakový ISO kód vybranej krajiny.	false
`prefix`	string	Medzinárodná predvoľba vybranej krajiny.	false
`mccs`	string[]	Zoznam MCC (kódov mobilných krajín) spojených s vybranou krajinou.	false
`carriers`	object[]	Zoznam objektov operátorov s metrikami konektivity špecifickými pre trasu.	false
`mno`	string	Názov mobilného operátora v anglickom jazyku.	false
`mccmnc`	string	MCCMNC mobilného operátora.	false
`mcc`	string	MCC (kód mobilnej krajiny) mobilného operátora.	false
`mnc`	string	MNC (kód mobilnej siete) mobilného operátora.	false
`routes`	object[]	Zoznam výsledkov konektivity špecifických pre trasu.	false
`route`	string	Trasa, na ktorú sa vzťahujú informácie o konektivite.	false
`selected`	bool	Označuje, či je toto vybraná trasa pre automatické smerovanie.	false
`selection_confidence`	string	Úroveň spoľahlivosti, s akou bola táto trasa vybraná, t.j. `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`. Obsahuje null, ak toto nie je vybraná trasa.	true
`n`	int	Celkový počet vyhľadávaní v tejto vzorke.	false
`CONNECTED`	int	Počet HLR vyhľadávaní, ktoré vrátili stav CONNECTED.	false
`CONNECTED_PCT`	float	Percento HLR vyhľadávaní, ktoré vrátili stav CONNECTED.	false
`ABSENT`	int	Počet HLR vyhľadávaní, ktoré vrátili stav ABSENT.	false
`ABSENT_PCT`	float	Percento HLR vyhľadávaní, ktoré vrátili stav ABSENT.	false
`INVALID_MSISDN`	int	Počet HLR vyhľadávaní, ktoré vrátili stav INVALID_MSISDN.	false
`INVALID_MSISDN_PCT`	float	Percento HLR vyhľadávaní, ktoré vrátili stav INVALID_MSISDN.	false
`UNDETERMINED`	int	Počet HLR vyhľadávaní, ktoré vrátili stav UNDETERMINED.	false
`UNDETERMINED_PCT`	float	Percento HLR vyhľadávaní, ktoré vrátili stav UNDETERMINED.	false

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

Parametre chybovej odpovede

Meno	Typ	Popis	Voliteľný
`errors[]`	string[]	Zoznam reťazcov vysvetľujúcich chybu.	false

Stav	Popis
CONNECTED	Číslo je platné a cieľové zariadenie je momentálne pripojené k mobilnej sieti. Hovory, SMS a ďalšie služby by mali príjemcu úspešne zastihnúť.
ABSENT	Číslo je platné, ale cieľové zariadenie je buď vypnuté alebo dočasne mimo dosahu siete. Správy alebo hovory nemusia byť doručené, kým sa zariadenie znovu nepripojí k sieti.
INVALID_MSISDN	Číslo je neplatné alebo momentálne nie je priradené žiadnemu účastníkovi v mobilnej sieti. Hovory a správy na toto číslo zlyhajú.
UNDETERMINED	Stav pripojenia čísla nebolo možné určiť. Môže to byť spôsobené neplatným číslom, chybovou odpoveďou SS7 alebo nedostatočným pripojením k cieľovému mobilnému operátorovi. Pre ďalšiu diagnostiku skontrolujte kód chyby a jeho popis.

Posunúť hore

GET/mnp-coveragechránené

Tento endpoint vracia zoznam mobilných operátorov spolu s ich príslušnými identifikátormi MCCMNC, ktorí sú momentálne podporovaní pre vyhľadávanie prenositeľnosti mobilných čísel.

Požiadavka Úspešná odpoveď Chybová odpoveď

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

Parametre požiadavky

Kľúč	Typ	Popis	Predvolené	Povinné
`countrycode`	string(2)	Voliteľný dvojpísmenový ISO kód krajiny použitý na filtrovanie výsledkov MCCMNC, vracajúci iba údaje relevantné pre zadanú krajinu.	null	voliteľné

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

Atribúty úspešnej odpovede

Meno	Typ	Popis	Voliteľný
`items[]`	array	Zoznam mobilných operátorov.	false
`country_name`	string	Názov krajiny v angličtine.	false
`country_code`	string(2)	Dvojpísmenový ISO kód krajiny.	false
`mccmnc`	string(5\|6)	Päť- alebo šesťznakový MCCMNC (kombinácia mobilného kódu krajiny a mobilného sieťového kódu) identifikujúci mobilného operátora.	false
`mcc`	string(3)	Trojznakový MCC (mobilný kód krajiny) reprezentujúci krajinu siete.	false
`mnc`	string(2\|3)	Dva- alebo trojznakový MNC (mobilný sieťový kód) reprezentujúci konkrétneho mobilného operátora.	false
`brand`	string	Spotrebiteľská značka, pod ktorou táto sieť pôsobí.	true
`operator`	string	Právny názov mobilného operátora.	true

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

Parametre chybovej odpovede

Meno	Typ	Popis	Voliteľný
`errors[]`	string[]	Zoznam reťazcov vysvetľujúcich chybu.	false

Posunúť hore

GET/price-listchránené

Tento endpoint vracia zoznam krajín, kde jsou podporované iba MNP vyhľadávania a HLR dotazy nie sú pre tieto destinácie dostupné.

Požiadavka Úspešná odpoveď Chybová odpoveď

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

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

Atribúty úspešnej odpovede

Meno	Typ	Popis	Voliteľný
`countries`	string[]	Zoznam dvojznakových ISO kódov krajín.	false

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

Parametre chybovej odpovede

Meno	Typ	Popis	Voliteľný
`errors[]`	string[]	Zoznam reťazcov vysvetľujúcich chybu.	false

Posunúť hore

GET/mccmncschránené

Tento endpoint vracia komplexný zoznam mobilných operátorov spolu s ich príslušnými identifikátormi MCCMNC a ďalšími kontextovými informáciami.

Požiadavka Úspešná odpoveď Chybová odpoveď

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

Parametre požiadavky

Kľúč	Typ	Popis	Predvolené	Povinné
`countrycode`	string(2)	Voliteľný dvojpísmenový ISO kód krajiny použitý na filtrovanie výsledkov MCCMNC, ktorý vracia len záznamy spojené so zadanou krajinou.	null	voliteľné

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

Atribúty úspešnej odpovede

Meno	Typ	Popis	Voliteľný
`items`	object[]	Zoznam mobilných operátorov.	false
`country_name`	string	Úplný názov krajiny v angličtine.	false
`country_code`	string(2)	Dvojpísmenový ISO kód krajiny reprezentujúci krajinu mobilného operátora.	false
`mccmnc`	string(5\|6)	Päť- alebo šesťznakový reťazec reprezentujúci MCCMNC, ktorý jednoznačne identifikuje mobilného operátora.	false
`mcc`	string(3)	Trojznakový kód krajiny mobilnej siete (MCC), ktorý identifikuje krajinu, v ktorej mobilná sieť pôsobí.	false
`mnc`	string(2\|3)	Dva- alebo trojznakový kód mobilnej siete (MNC), ktorý špecifikuje mobilnú sieť v rámci daného MCC.	false
`brand`	string	Komerčný názov značky, pod ktorým sieť pôsobí a je známa spotrebiteľom.	true
`operator`	string	Oficiálny názov mobilného operátora, typicky právna entita spravujúca sieť.	true
`parent_mccmnc`	string(5\|6)	Päť- alebo šesťznakový reťazec reprezentujúci MCCMNC nadradeného mobilného operátora, ak existuje.	true

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

Parametre chybovej odpovede

Meno	Typ	Popis	Voliteľný
`errors[]`	string[]	Zoznam reťazcov vysvetľujúcich chybu.	false

Posunúť hore

GET/pricechránené

Tento endpoint vracia cenu za HLR, MNP alebo NT vyhľadávanie.

Požiadavka Úspešná odpoveď Chybová odpoveď

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

Parametre požiadavky

Kľúč	Typ	Popis	Predvolené	Povinné
`msisdn`	string	Telefónne číslo, pre ktoré sa má získať cena. V medzinárodnom formáte.	null	povinné
`route_type`	string	Typ trasy, t.j. `HLR`, `MNP`, `NT`.	null	povinné
`route`	string(3)	Trasa, pre ktorú sa má vypočítať cena. Predvolená je trasa určená automatickým smerovaním.	null	voliteľné

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

Atribúty úspešnej odpovede

Meno	Typ	Popis	Voliteľný
`price`	object	Objekt s cenovými údajmi.	false
`amount`	string	Suma v EUR.	false
`msisdn`	string	MSISDN, pre ktoré platí táto cena.	false
`route_type`	string(2\|3)	Typ trasy, pre ktorý platí táto cena.	false
`route`	string(3)	Trasa, pre ktorú platí táto cena.	false

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

Parametre chybovej odpovede

Meno	Typ	Popis	Voliteľný
`errors[]`	string[]	Zoznam reťazcov vysvetľujúcich chybu.	false

Posunúť hore

GET/price-listchránené

Tento endpoint vracia cenník pre váš účet.

Požiadavka Úspešná odpoveď Chybová odpoveď

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

Atribúty úspešnej odpovede

Meno	Typ	Popis	Voliteľný
`pricing`	object[]	Zoznam objektov s cenovými informáciami.	false
`route`	string	Smerovanie, na ktoré sa toto ocenenie vzťahuje.	false
`countrycode`	string	Dvojznakový ISO kód krajiny, na ktorú sa toto ocenenie vzťahuje pre príslušné smerovanie, ak je k dispozícii.	true
`countryname`	string	Anglický názov krajiny zodpovedajúci kódu krajiny, ak je k dispozícii.	true
`mccmnc`	string	MCCMNC, na ktorý sa toto ocenenie vzťahuje pre príslušné smerovanie, ak je k dispozícii. Má prednosť pred ocenením na úrovni krajiny.	true
`cns`	string	Predvoľba volania, na ktorú sa toto ocenenie vzťahuje pre príslušné smerovanie, ak je k dispozícii. Má prednosť pred ocenením na úrovni krajiny a MCCMNC.	true
`route_type`	string	Príslušný typ smerovania, t.j. `HLR`, `MNP`, `NT`.	false
`route_type`	string	Príslušná cena v EUR.	false

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

Parametre chybovej odpovede

Meno	Typ	Popis	Voliteľný
`errors[]`	string[]	Zoznam reťazcov vysvetľujúcich chybu.	false

Posunúť hore

GET/balancechránené

Tento endpoint získava váš aktuálny zostatok na účte, čo vám umožňuje automatizovať procesy na základe stavu vášho kreditu. Bezproblémovo funguje s upozorneniami na nízky kredit, ktoré si môžete nakonfigurovať na stránke platieb.

Požiadavka Úspešná odpoveď Chybová odpoveď

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

{
    "balance":"1002.90"
}

Atribúty úspešnej odpovede

Meno	Typ	Popis	Voliteľný
`balance`	string	Váš aktuálny zostatok na účte v EUR. Desatinná hodnota typu string.	false

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

Parametre chybovej odpovede

Meno	Typ	Popis	Voliteľný
`errors[]`	string[]	Zoznam reťazcov vysvetľujúcich chybu.	false

Posunúť hore

GET/pingverejné

Tento endpoint odošle ping požiadavku do API a poskytuje jednoduchý spôsob testovania vášho pripojenia k HLR Lookups API.

Požiadavka Úspešná odpoveď Chybová odpoveď

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

{
    "success":true
}

Atribúty úspešnej odpovede

Meno	Typ	Popis	Voliteľný
`success`	boolean	Indikuje, že požiadavka bola úspešne spracovaná.	false

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

Parametre chybovej odpovede

Meno	Typ	Popis	Voliteľný
`errors[]`	string[]	Zoznam reťazcov vysvetľujúcich chybu.	false

Posunúť hore

GET/timeverejné

Tento endpoint vracia Unix timestamp reprezentujúci aktuálny čas na serveri HLR Lookups. Použite ho na synchronizáciu hodín vášho servera pri generovaní Digest-Auth podpisu pre autentifikáciu, čím zabezpečíte, že akékoľvek nezrovnalosti medzi časom vášho servera a časom servera HLR Lookups budú opravené.

Požiadavka Úspešná odpoveď Chybová odpoveď

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

{
    "time":1525898643
}

Atribúty úspešnej odpovede

Meno	Typ	Popis	Voliteľný
`time`	integer	Unix timestamp reprezentujúci aktuálny čas servera HLR Lookups.	false

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

Parametre chybovej odpovede

Meno	Typ	Popis	Voliteľný
`errors[]`	string[]	Zoznam reťazcov vysvetľujúcich chybu.	false

Posunúť hore

GET/auth-testchránené

Tento endpoint slúži ako úvodný test vašej Basic-Auth alebo, ideálne, Digest-Auth implementácie.

Basic Auth požiadavka Digest Auth požiadavka Úspešná odpoveď Chybová odpoveď

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

Hlavičky požiadavky

Kľúč	Typ	Popis
`X-Basic`	string	SHA256 hash `YOUR_API_KEY:YOUR_API_SECRET`. Zahrňte do hashu symbol dvojbodky (:).

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"

Hlavičky požiadavky

Kľúč	Typ	Popis
`X-Digest-Key`	string	Váš HLR Lookups API kľúč
`X-Digest-Signature`	string	Jedinečný Digest-Auth podpis (pozrite autentifikácia)
`X-Digest-Timestamp`	integer	Aktuálny Unix timestamp (pozrite tiež `GET /time`)

{
    "success":true
}

Atribúty úspešnej odpovede

Meno	Typ	Popis	Voliteľný
`success`	boolean	Indikuje, že požiadavka bola úspešne spracovaná.	false

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

Parametre chybovej odpovede

Meno	Typ	Popis	Voliteľný
`errors[]`	string[]	Zoznam reťazcov vysvetľujúcich chybu.	false

Posunúť hore

Dokumentácia staršieho API

Upozorňujeme, že staršie API je zastarané a v budúcnosti bude vyradené z prevádzky. Dôrazne odporúčame čo najskôr prejsť na najnovšiu verziu.

Ak ste implementovali naše HLR Lookups API medzi rokmi 2013 a začiatkom roku 2020, používate naše staršie API. V takom prípade si prosím pozrite našu dokumentáciu staršieho API.

Dokumentácia staršieho API

Dokumentácia API

Začíname

HLR vyhľadávania

MNP vyhľadávania

NT vyhľadávania

Smerovanie

Cenník

Nástroje

Začíname

Používanie HLR Lookups API

Príklad požiadavky

Príklad údajov

Úspešná odpoveď application/json

Doplnkové vyhľadávacie služby

Vyhľadávanie prenositeľnosti čísel (MNP)

Detekcia typu čísla (NT)

Vývojové súpravy (SDK)

Nástroje

Nie ste vývojár?

Autentifikácia

API kľúč a API tajný kód

HTTP Basic Auth

Odporúčané: X-Basic hlavička so SHA256

Basic Auth požiadavka

Hlavičky Basic Authentication

Príklad kódu

Príklad požiadavky

Hlavičky požiadavky

Vytvorenie podpisu

Komponenty Digest Signature

Príklady kódu

Koncepty

Synchrónne HLR Lookup API

Asynchrónne HLR Lookup API

SDK (Software Development Kits)

PHP SDK

NodeJS SDK

Ruby SDK

POST/hlr-lookupchránené

Dáta požiadavky

Parametre požiadavky

Atribúty úspešnej odpovede

Parametre chybovej odpovede

POST/hlr-lookupschránené

Dáta požiadavky

Parametre požiadavky

Atribúty úspešnej odpovede

Parametre chybovej odpovede

Spracovanie webhookov

Autentifikácia

Príklad kódu

Potvrdenie prijatia

Obsah webhooku

Atribúty webhook payloadu

POST/mnp-lookupchránené

Dáta požiadavky

Parametre požiadavky

Atribúty úspešnej odpovede

Parametre chybovej odpovede

POST/mnp-lookupschránené

Dáta požiadavky

Parametre požiadavky

Atribúty úspešnej odpovede

Parametre chybovej odpovede

Spracovanie webhookov

Autentifikácia

Príklad kódu

Potvrdenie prijatia

Obsah webhooku

Atribúty webhook payloadu

POST/nt-lookupchránené

Dáta požiadavky

Parametre požiadavky

Atribúty úspešnej odpovede

Parametre chybovej odpovede

POST/nt-lookups chránené

Dáta požiadavky

Parametre požiadavky

Atribúty úspešnej odpovede

Parametre chybovej odpovede