Začínáme

Globální infrastruktura mobilních sítí funguje na systému známém jako signalizační síť SS7. Tato síť umožňuje výměnu dat o účastnících, směrování hovorů, přenos SMS a aktualizace stavu mobilního připojení v reálném čase mezi operátory. Každá mobilní síť provozuje Home Location Register (HLR) - klíčovou databázi, která uchovává základní údaje o svých účastnících.

Technologie HLR Lookup umožňuje firmám dotazovat se do těchto registrů a získávat aktuální údaje o připojení a síti pro jakékoli mobilní telefonní číslo. To zahrnuje informace, zda je telefon zapnutý, ke které síti je aktuálně přiřazen, zda bylo číslo přeneseno, zda je číslo platné nebo deaktivované a zda se nachází v roamingu.

HLR Lookups API poskytuje bezproblémový přístup k těmto datům v reálném čase a umožňuje firmám ověřovat mobilní čísla, optimalizovat směrování a zlepšovat komunikaci se zákazníky. Tato dokumentace vás provede integrací HLR Lookups do vašeho softwaru a umožní automatizované získávání mobilních dat v reálném čase.

Použití HLR Lookups API

Provádění HLR Lookup dotazů je rychlé, bezpečné a jednoduché. Jakmile se zaregistrujete a získáte svůj API klíč, můžete se autentizovat a zahájit okamžité vyhledávání pomocí jednoduchých HTTP POST požadavků prostřednictvím POST /hlr-lookup. Alternativně můžete zpracovávat velké objemy dat pomocí rychlých asynchronních API požadavků s výsledky zasílanými zpět na váš server prostřednictvím webhooku, jak je vysvětleno v sekci koncepty.

Příklad požadavku

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"

Autentizace se provádí prostřednictvím HTTP hlaviček a payload.json by měl (minimálně) obsahovat následující JSON objekt:

Příklad datové části

{
   "msisdn": "+14156226819"
}

Po úspěšném provedení obdržíte odpověď obsahující aktuální údaje o připojení pro zadané mobilní číslo.

Úspěšná odpověď 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"
}

Pro kompletní přehled atributů požadavku a odpovědi a stavů připojení viz POST /hlr-lookup.

Další vyhledávací služby

Vyhledávání přenositelnosti čísel (MNP)

Použijte MNP vyhledávání k určení vlastnictví sítě a údajů o přenositelnosti bez dotazování na připojení v reálném čase. Pokud potřebujete pouze MCCMNC čísla, viz POST /mnp-lookup.

Detekce typu čísla (NT)

Určete, zda telefonní číslo patří k pevné lince, mobilnímu telefonu, prémiové lince, VoIP, pageru nebo jiným rozsahům číselného plánu pomocí POST /nt-lookup.

Vývojové sady (SDK)

HLR Lookups API funguje s jakýmkoli REST klientem v jakémkoli programovacím jazyce a publikovali jsme SDK pro PHP, Ruby a NodeJS na našem GitHubu, abychom vám pomohli rychle začít.

Nástroje

Pro zajištění bezproblémového vývojového prostředí nabízíme komplexní sadu nástrojů, včetně monitorování API požadavků a webhooků v prohlížeči, whitelistingu IP adres, robustních autentizačních možností a autentizačního testovacího endpointu.

Nejste vývojář?

HLR Lookups a dotazy na přenositelnost čísel lze provádět bez jakéhokoli programování. Zjistěte více o našem podnikovém webovém klientovi a reportovacích funkcích v prohlížeči.

Autentizace

Pro zajištění bezpečnosti a správné kontroly přístupu vyžaduje většina požadavků na HLR Lookups API autentizaci. Endpointy jsou kategorizovány jako veřejné nebo chráněné. Při přístupu k chráněnému endpointu musí být váš požadavek autentizován pomocí API klíče a tajného klíče prostřednictvím metody Digest-Auth nebo Basic-Auth. Digest-Auth je bezpečnější možnost a je silně doporučována. Použijte endpoint GET /auth-test k ověření nastavení autentizace.

API klíč a API tajný klíč

Získejte svůj API klíč a tajný klíč na stránce Nastavení API. Můžete také nakonfigurovat preferovanou metodu autentizace a povolit whitelist IP adres pro zvýšenou bezpečnost. Pokud máte podezření, že byl váš API tajný klíč kompromitován, můžete kdykoli vygenerovat nový.

Basic Auth Digest Auth Whitelist IP adres

Standardní Basic Authentication je snadno implementovatelná a široce podporovaná. Můžete se autentizovat předáním API klíče a tajného klíče jako dvojice user:pass v HTTP požadavku.

HTTP Basic Auth

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

Tímto se odešle hlavička Authorization:

Authorization: Basic BASE64(YOUR_API_KEY:YOUR_API_SECRET)

Doporučeno: X-Basic hlavička s SHA256

Pro zvýšenou bezpečnost můžete odeslat SHA256 hash vašich přihlašovacích údajů místo jejich přímého přenosu v base64. Pro použití této metody vypočítejte hash dvojice YOUR_API_KEY:YOUR_API_SECRET a odešlete jej prostřednictvím hlavičky X-Basic:

Basic Auth požadavek

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

Basic Authentication hlavičky

Klíč	Typ	Popis
`X-Basic`	string	SHA256 hash `YOUR_API_KEY:YOUR_API_SECRET`. Zahrňte do hashe symbol dvojtečky (:).	povinné

Příklad kódu

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

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

Digest-Auth je doporučená metoda pro zabezpečení přístupu k chráněným endpointům HLR Lookup API. Každý požadavek musí obsahovat následující hlavičky: X-Digest-Key, X-Digest-Signature a X-Digest-Timestamp, které jsou vysvětleny níže.

Příklad požadavku

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žadavku

Klíč	Typ	Popis
`X-Digest-Key`	string	Váš unikátní HLR Lookups API klíč.	povinné
`X-Digest-Signature`	string	Unikátní autentizační podpis (viz níže).	povinné
`X-Digest-Timestamp`	integer	Aktuální Unix timestamp (viz také `GET /time`).	povinné

Vytvoření podpisu

X-Digest-Signature je vytvořen pomocí SHA256 HMAC hashe, s vaším API tajným klíčem jako sdíleným klíčem.

Řetězec pro hashování je strukturován následovně:

ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY

Symbol . představuje zřetězení řetězců.

Komponenty Digest Signature

Komponenta	Typ	Popis
`ENDPOINT_PATH`	string	Požadovaný API endpoint, např. `/auth-test` malými písmeny.
`UNIX_TIMESTAMP`	integer	Aktuální Unix timestamp (musí být v rozmezí 30 sekund). Viz `GET /time`.
`REQUEST_METHOD`	string	Použitá HTTP metoda, např. `POST` nebo `GET`.
`REQUEST_BODY`	string	Data těla požadavku. Nastavte na `null` pro `GET` požadavky.

Pří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)

Posunout nahoru

Koncepty

Implementace HLR Lookup v jakémkoli programovacím jazyce nebo systému prostřednictvím našeho HTTP REST API je přímočará a efektivní. Díky jednoduchému integračnímu procesu můžete začít dotazovat mobilní sítě v reálném čase a získat okamžité informace o platnosti telefonního čísla, stavu připojení a směrovacích údajích.

Výběr vhodného API závisí na vašem konkrétním případu použití. Pokud potřebujete výsledky vyhledávání v reálném čase pro aplikace jako VoIP telefonie, detekce podvodů nebo směrování SMS, je nejlepší volbou synchronní API. Pokud však váš případ použití zahrnuje zpracování velkých objemů dat, hromadná vyhledávání nebo ověřování dat ve velkém měřítku, nabízí asynchronní API optimalizovaný výkon s efektivním využitím šířky pásma a možností dávkového vyhledávání.

Nakonfigurujte API tak, aby používalo jednu z našich vlastních možností směrování pro optimalizaci rychlosti, přesnosti a nákladové efektivity. Výsledky vyhledávání můžete také ukládat do úložišť pro snadné stahování sestav ve formátu CSV a JSON, stejně jako pro pokročilou analytiku prostřednictvím webového rozhraní.

Synchronní HLR Lookup API

Endpoint POST /hlr-lookup zpracovává jedno mobilní telefonní číslo (MSISDN) na požadavek a vrací výsledky okamžitě v těle HTTP odpovědi. Výsledky jsou formátovány jako JSON a jsou ideální pro aplikace v reálném čase, včetně validace mobilních čísel, směrování hovorů a doručování SMS zpráv.

Synchronní volání API se skládá z přímého HTTP požadavku a odpovědi. Váš systém odešle jedno MSISDN (mobilní číslo) na požadavek a obdrží okamžitou odpověď obsahující výsledky HLR vyhledávání v reálném čase ve formátu JSON. Toto API je optimalizováno pro případy použití, které vyžadují okamžité ověření a kontrolu připojení, jako je detekce podvodů, směrování VoIP hovorů a optimalizace SMS brány.

Asynchronní HLR Lookup API

Endpoint POST /hlr-lookups je navržen pro hromadné zpracování a zpracování velkých objemů, což vám umožňuje odeslat až 1,000 MSISDN na požadavek. Namísto okamžitého vrácení výsledků toto API používá automatizované webhooky k postupnému odesílání výsledků na váš server. Výsledky vyhledávání jsou vráceny jako JSON objekty prostřednictvím HTTP POST callbacků.

Asynchronní API je optimalizováno pro rychlost, efektivitu a škálovatelnost. Eliminuje problémy se síťovou latencí spojené se synchronními voláními, což je ideální pro firmy potřebující vyhledávání s vysokou propustností. Váš systém odešle až 1,000 MSISDN na požadavek a naše platforma je zpracuje paralelně, přičemž vrátí výsledky na váš server prostřednictvím HTTP webhooků v dávkách až 1,000 výsledků na callback.

SDK (Software Development Kits)

Naše Software Development Kits (SDK) pro PHP, NodeJS a Ruby zjednodušují proces integrace a umožňují vám efektivně se připojit k HLR Lookups API s minimálním úsilím.

Tyto SDK poskytují předpřipravené funkce, správu autentizace a strukturované šablony API požadavků, čímž zkracují dobu vývoje a zajišťují dodržování osvědčených postupů.

Prozkoumejte kompletní seznam dostupných SDK na GitHubu a začněte integrovat ještě 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);

Zobrazit na GitHubu 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   }

Zobrazit na GitHubu 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)

Zobrazit na GitHubu README.md

Posunout nahoru

POST/hlr-lookupchráněno

Provádí synchronní HLR dotaz, který poskytuje údaje o dostupnosti a přenositelnosti mobilního čísla v reálném čase přímo od síťových operátorů. Tento endpoint je ideální pro živý provoz, kdy časově kritické aplikace vyžadují okamžité ověření, zda je telefonní číslo aktuálně dostupné (připojeno) nebo nedostupné (vypnuto). Navíc pomáhá rozlišit aktivní čísla od neplatných, neznámých nebo falešných.

Pro hromadné zpracování velkých datových sad, které nevyžadují okamžité výsledky, zvažte použití asynchronního endpointu POST /hlr-lookups, který je optimalizován pro vysokorychlostní dávkové zpracování.

Pokud se primárně zaměřujete na získání údajů o přenositelnosti mobilních čísel (MCCMNC) a nepotřebujete živý stav připojení, endpoint POST /mnp-lookup nabízí nákladově efektivní alternativu pro dotazy na přenositelnost mobilních čísel.

Požadavek Úspěšná odpověď Chybová odpověď Referenční stavy

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

Datová část

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

Parametry požadavku

Klíč	Typ	Popis	Výchozí	Povinné
`msisdn`	string	Mobilní telefonní číslo (MSISDN), které má být dotazováno, uvedené v mezinárodním formátu (např. +14156226819 nebo 0014156226819). Předvolby zemí musí být zahrnuty.	null	povinné
`route`	string(3)	Volitelný tříznakový identifikátor určující trasu pro tento dotaz. Nastavte na `null` nebo tento parametr vynechte pro použití vaší vlastní mapy směrování nebo nechte náš systém automaticky určit nejlepší trasu pro tento dotaz.	null	volitelné
`storage`	string	Volitelný identifikátor úložiště určující report, kde budou výsledky uloženy pro manuální kontrolu, analýzu a reporting. Systém automaticky připojuje časové razítko s aktuálním měsícem. Pokud je vynecháno nebo nastaveno na `null`, systém automaticky seskupí výsledky podle měsíce pro účely reportingu.	null	volitelné

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

Atributy úspěšné odpovědi

Jméno	Typ	Popis	Nullable
`id`	string(12)	Jedinečný identifikátor přiřazený k tomuto vyhledávacímu požadavku.	false
`msisdn`	string	Mobilní telefonní číslo, které je dotazováno, formátované v mezinárodním formátu (např. +14156226819 nebo 0014156226819).	false
`connectivity_status`	string	Udává, zda byl stav připojení čísla úspěšně zjištěn. Možné hodnoty: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` nebo `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Pěti- nebo šestimístný Mobile Country Code (MCC) a Mobile Network Code (MNC) identifikující síť aktuálně přiřazenou k telefonnímu číslu.	true
`mcc`	string(3)	Třímístný Mobile Country Code (MCC) identifikující zemi, kde je telefonní číslo registrováno.	true
`mnc`	string(2\|3)	Dvou- nebo třímístný Mobile Network Code (MNC) identifikující konkrétní síť, do které telefonní číslo patří.	true
`imsi`	string	International Mobile Subscriber Identity (IMSI), jedinečný identifikátor SIM karty přiřazené k tomuto číslu. Dostupnost závisí na konfiguraci sítě.	true
`msin`	string(10)	Mobile Subscription Identification Number (MSIN) v databázi mobilního operátora. Dostupnost závisí na konfiguraci sítě.	true
`msc`	string(12)	Mobile Switching Center (MSC) aktuálně obsluhující komunikaci tohoto účastníka. Dostupnost závisí na konfiguraci sítě.	true
`original_network_name`	string	Název původního (domácího) síťového operátora přiřazeného k tomuto číslu.	true
`original_country_name`	string	Celý název země, kde bylo mobilní telefonní číslo původně registrováno, uvedený v angličtině.	true
`original_country_code`	string(2)	Dvoumístný ISO kód země reprezentující zemi, kde bylo telefonní číslo poprvé přiděleno.	true
`original_country_prefix`	string	Mezinárodní předvolba (kód země) odpovídající původní zemi mobilního telefonního čísla.	true
`is_ported`	boolean	Udává, zda bylo mobilní číslo přeneseno z původní sítě k jinému operátorovi.	true
`ported_network_name`	string	Název síťového operátora, ke kterému bylo mobilní číslo přeneseno, pokud je to relevantní.	true
`ported_country_name`	string	Název země, do které bylo mobilní číslo přeneseno, pokud je to relevantní.	true
`ported_country_code`	string(2)	Dvoumístný ISO kód země reprezentující zemi, do které bylo mobilní číslo přeneseno, pokud je to relevantní.	true
`ported_country_prefix`	string	Mezinárodní předvolba (kód země) pro zemi, do které bylo mobilní číslo přeneseno, pokud je to relevantní.	true
`is_roaming`	boolean	Udává, zda mobilní číslo aktuálně roamuje v zahraniční síti. Dostupnost informace o roamingu závisí na mobilním síťovém operátorovi.	true
`roaming_network_name`	string	Název sítě, ve které mobilní číslo aktuálně roamuje, pokud je to relevantní.	true
`roaming_country_name`	string	Název země, kde mobilní číslo aktuálně roamuje, pokud je to relevantní.	true
`roaming_country_code`	string(2)	Dvoumístný ISO kód země, kde mobilní číslo aktuálně roamuje, pokud je to relevantní.	true
`roaming_country_prefix`	string	Mezinárodní předvolba (kód země) země, kde mobilní číslo aktuálně roamuje, pokud je to relevantní.	true
`cost`	string	Desetinná hodnota reprezentovaná jako řetězec, udávající cenu vyhledávání v EUR.	true
`timestamp`	string	Časové razítko ve formátu W3C včetně časového pásma, specifikující, kdy bylo vyhledávání dokončeno.	true
`storage`	string	Název úložiště, kde byly uloženy výsledky vyhledávání. To odpovídá názvům reportů a CSV souborům ke stažení dostupným ve webovém rozhraní.	true
`route`	string(3)	Třímístný identifikátor udávající metodu směrování použitou pro tento vyhledávací požadavek.	true
`processing_status`	string	Výsledek zpracování vyhledávání. Možné hodnoty: `COMPLETED` (úspěšné), `REJECTED` (síť nedostupná, nebyl účtován poplatek) nebo `FAILED` (během zpracování došlo k chybě).	false
`error_code`	integer	Volitelný interní kód chyby poskytující další diagnostické informace pro zákaznickou podporu.	true
`error_description`	string	Stručné vysvětlení daného kódu chyby (pokud existuje) v prostém anglickém textu.	true
`data_source`	string	Zdroj dat použitý pro tento požadavek. Možné hodnoty: `LIVE_HLR` (dotaz HLR v reálném čase) nebo `MNP_DB` (statická databáze přenositelnosti mobilních čísel). Podrobnosti naleznete v možnostech směrování.	false
`routing_instruction`	string	Řetězec oddělený dvojtečkami popisující instrukci směrování použitou v požadavku. První složka je `STATIC`, pokud jste specifikovali trasu, nebo `AUTO` pro automatické směrování; druhá složka je identifikátor trasy a u požadavků s automatickým směrováním třetí složka ukazuje původ, na kterém je rozhodnutí o směrování založeno (tj. `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."
    ]
}

Parametry chybové odpovědi

Jméno	Typ	Popis	Nullable
`errors[]`	string[]	Seznam řetězců vysvětlujících chybu.	false

Stav	Popis
CONNECTED	Číslo je platné a cílové zařízení je aktuálně připojeno k mobilní síti. Hovory, SMS a další služby by měly být úspěšně doručeny příjemci.
ABSENT	Číslo je platné, ale cílové zařízení je buď vypnuté, nebo se dočasně nachází mimo dosah sítě. Zprávy nebo hovory nemusí být doručeny, dokud se zařízení znovu nepřipojí k síti.
INVALID_MSISDN	Číslo je neplatné nebo není aktuálně přiřazeno žádnému účastníkovi v mobilní síti. Hovory a zprávy na toto číslo selžou.
UNDETERMINED	Stav připojení čísla nelze určit. Může to být způsobeno neplatným číslem, chybovou odpovědí SS7 nebo nedostatečným připojením k cílové síti operátora. Pro další diagnostiku zkontrolujte kód chyby a jeho popis.

Posunout nahoru

POST/hlr-lookupschráněno

Zahajuje dávku asynchronních HLR dotazů, které získávají živá data o konektivitě a přenositelnosti mobilních telefonů od síťových operátorů. Výsledky jsou doručovány prostřednictvím webhooků na váš server. Tato metoda je optimalizována pro zpracování velkých objemů čísel, která nevyžadují okamžité odpovědi, jako je čištění a ověřování databází. Pro aplikace v reálném čase, jako je směrování hovorů nebo doručování SMS, zvažte místo toho použití endpointu POST /hlr-lookup.

Tento endpoint je ideální pro hromadné zpracování, kdy je cílem identifikovat telefonní čísla, která jsou aktuálně dostupná (připojená) nebo nedostupná (telefon vypnutý), a zároveň odfiltrovat neplatná, nepřidělená nebo falešná čísla. Poskytuje navíc živý stav přenositelnosti (MCCMNC) spolu s detaily o konektivitě.

Před použitím tohoto endpointu se ujistěte, že je nakonfigurována URL webhooku pro asynchronní příjem výsledků dotazů. Můžete to nastavit v nastavení API.

Požadavek Úspěšná odpověď Chybová odpověď Webhooky Referenční stavy

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

Datová část

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

Parametry požadavku

Klíč	Typ	Popis	Výchozí	Povinné
`msisdns`	array	Pole mobilních telefonních čísel (MSISDN) v mezinárodním formátu (např. +14156226819 nebo 0014156226819). V jednom požadavku můžete zahrnout až 1000 čísel.	null	povinné
`route`	string(3)	Volitelný tříznakový identifikátor určující trasu pro tento dotaz. Nastavte na `null` nebo tento parametr vynechte pro použití vaší vlastní mapy směrování nebo nechte náš systém automaticky určit nejlepší trasu pro tento dotaz.	null	volitelné
`storage`	string	Volitelný identifikátor úložiště určující report, kde budou výsledky uloženy pro manuální kontrolu, analýzu a reporting. Systém automaticky připojuje časové razítko s aktuálním měsícem. Pokud je vynecháno nebo nastaveno na `null`, systém automaticky seskupí výsledky podle měsíce pro účely reportingu.	null	volitelné

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

Atributy úspěšné odpovědi

Jméno	Typ	Popis	Nullable
`accepted`	array	Seznam objektů obsahujících jedinečné identifikátory a MSISDN, které byly přijaty ke zpracování.	false
`accepted_count`	integer	Celkový počet MSISDN úspěšně přijatých ke zpracování.	false
`rejected`	array	Seznam objektů obsahujících jedinečné identifikátory a MSISDN, které byly odmítnuty ke zpracování, typicky z důvodu neplatných čísel. Za odmítnuté položky se neúčtuje poplatek.	false
`rejected_count`	integer	Celkový počet MSISDN odmítnutých z důvodu chyb validace.	false
`total_count`	integer	Celkový počet přijatých a odmítnutých MSISDN, které byly odeslány ke zpracování.	false
`cost`	string	Desetinná hodnota reprezentovaná jako řetězec, která udává celkové náklady v EUR za přijaté dotazy.	false
`storage`	string	Název úložiště, kam jsou připojovány výsledky dotazů, používané pro reporty a stahování CSV přes webové rozhraní.	false
`route`	string(3\|4)	Tří nebo čtyřznakový identifikátor určující trasu použitou pro tento dotaz. Obsahuje AUTO, pokud bylo požadováno automatické směrování podle čísla.	false
`webhook_urls`	array	URL webhooků nakonfigurované v nastavení API. Výsledky jsou sem odesílány zpět.	false

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

Parametry chybové odpovědi

Jméno	Typ	Popis	Nullable
`errors[]`	string[]	Seznam řetězců vysvětlujících chybu.	false

Zpracování webhooků

Po odeslání začne naše platforma zpracovávat poskytnutá telefonní čísla a odesílá výsledky na předem zadanou URL adresu webhooku na vašem serveru. Výsledky jsou přenášeny jako HTTP POST požadavek s JSON objektem v těle požadavku.

Autentizace

Ověřte webhook kontrolou HTTP hlavičky X-Signatures.

Hlavička X-Signatures obsahuje seznam podpisů oddělených středníkem. Každý podpis v seznamu je generován pomocí jednoho z API tajných klíčů nakonfigurovaných ve vašem účtu. Pro ověření webhooku vygenerujte SHA-256 hash pomocí vašeho API klíče, tajného klíče a původního HTTP těla - poté jej porovnejte s podpisy v seznamu.

Shoda potvrzuje, že požadavek je autentický a podepsaný tajným klíčem, který kontrolujete.

Pří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žadavek je platný, pokud se kterýkoli z podpisů uvedených v hlavičce rovná SHA256 hashi vypočítanému ze zřetězeného řetězce vašeho API klíče, tajného klíče a HTTP těla.

Potvrzení přijetí

Váš server by měl odpovědět stavovým kódem HTTP 200 OK pro potvrzení úspěšného přijetí. Pokud je vrácen jakýkoli jiný stavový kód, dojde k vypršení časového limitu (10 sekund) nebo nastane jiný problém s doručením, systém automaticky zopakuje webhook po jedné minutě. Pokud požadavek nadále selhává, opakování budou následovat strategii exponenciálního zpoždění s dalšími pokusy po 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minutách.

Tento mechanismus opakování zajišťuje maximální spolehlivost při doručování výsledků vyhledávání do vaší infrastruktury. Minimalizuje riziko ztráty dat v důsledku dočasných problémů se sítí nebo výpadku serveru.

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

Atributy payloadu webhooku

JSON objekt obsahuje atribut type => HLR spolu s atributem results, který zahrnuje seznam objektů dotazů, jak je uvedeno níže.

Jméno	Typ	Popis	Nullable
`id`	string(12)	Jedinečný identifikátor přiřazený k tomuto vyhledávacímu požadavku.	false
`msisdn`	string	Mobilní telefonní číslo, které je dotazováno, formátované v mezinárodním formátu (např. +14156226819 nebo 0014156226819).	false
`connectivity_status`	string	Udává, zda byl stav připojení čísla úspěšně zjištěn. Možné hodnoty: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` nebo `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Pěti- nebo šestimístný Mobile Country Code (MCC) a Mobile Network Code (MNC) identifikující síť aktuálně přiřazenou k telefonnímu číslu.	true
`mcc`	string(3)	Třímístný Mobile Country Code (MCC) identifikující zemi, kde je telefonní číslo registrováno.	true
`mnc`	string(2\|3)	Dvou- nebo třímístný Mobile Network Code (MNC) identifikující konkrétní síť, do které telefonní číslo patří.	true
`imsi`	string	International Mobile Subscriber Identity (IMSI), jedinečný identifikátor SIM karty přiřazené k tomuto číslu. Dostupnost závisí na konfiguraci sítě.	true
`msin`	string(10)	Mobile Subscription Identification Number (MSIN) v databázi mobilního operátora. Dostupnost závisí na konfiguraci sítě.	true
`msc`	string(12)	Mobile Switching Center (MSC) aktuálně obsluhující komunikaci tohoto účastníka. Dostupnost závisí na konfiguraci sítě.	true
`original_network_name`	string	Název původního (domácího) síťového operátora přiřazeného k tomuto číslu.	true
`original_country_name`	string	Celý název země, kde bylo mobilní telefonní číslo původně registrováno, uvedený v angličtině.	true
`original_country_code`	string(2)	Dvoumístný ISO kód země reprezentující zemi, kde bylo telefonní číslo poprvé přiděleno.	true
`original_country_prefix`	string	Mezinárodní předvolba (kód země) odpovídající původní zemi mobilního telefonního čísla.	true
`is_ported`	boolean	Udává, zda bylo mobilní číslo přeneseno z původní sítě k jinému operátorovi.	true
`ported_network_name`	string	Název síťového operátora, ke kterému bylo mobilní číslo přeneseno, pokud je to relevantní.	true
`ported_country_name`	string	Název země, do které bylo mobilní číslo přeneseno, pokud je to relevantní.	true
`ported_country_code`	string(2)	Dvoumístný ISO kód země reprezentující zemi, do které bylo mobilní číslo přeneseno, pokud je to relevantní.	true
`ported_country_prefix`	string	Mezinárodní předvolba (kód země) pro zemi, do které bylo mobilní číslo přeneseno, pokud je to relevantní.	true
`is_roaming`	boolean	Udává, zda mobilní číslo aktuálně roamuje v zahraniční síti. Dostupnost informace o roamingu závisí na mobilním síťovém operátorovi.	true
`roaming_network_name`	string	Název sítě, ve které mobilní číslo aktuálně roamuje, pokud je to relevantní.	true
`roaming_country_name`	string	Název země, kde mobilní číslo aktuálně roamuje, pokud je to relevantní.	true
`roaming_country_code`	string(2)	Dvoumístný ISO kód země, kde mobilní číslo aktuálně roamuje, pokud je to relevantní.	true
`roaming_country_prefix`	string	Mezinárodní předvolba (kód země) země, kde mobilní číslo aktuálně roamuje, pokud je to relevantní.	true
`cost`	string	Desetinná hodnota reprezentovaná jako řetězec, udávající cenu vyhledávání v EUR.	true
`timestamp`	string	Časové razítko ve formátu W3C včetně časového pásma, specifikující, kdy bylo vyhledávání dokončeno.	true
`storage`	string	Název úložiště, kde byly uloženy výsledky vyhledávání. To odpovídá názvům reportů a CSV souborům ke stažení dostupným ve webovém rozhraní.	true
`route`	string(3)	Třímístný identifikátor udávající metodu směrování použitou pro tento vyhledávací požadavek.	true
`processing_status`	string	Výsledek zpracování vyhledávání. Možné hodnoty: `COMPLETED` (úspěšné), `REJECTED` (síť nedostupná, nebyl účtován poplatek) nebo `FAILED` (během zpracování došlo k chybě).	false
`error_code`	integer	Volitelný interní kód chyby poskytující další diagnostické informace pro zákaznickou podporu.	true
`error_description`	string	Stručné vysvětlení daného kódu chyby (pokud existuje) v prostém anglickém textu.	true
`data_source`	string	Zdroj dat použitý pro tento požadavek. Možné hodnoty: `LIVE_HLR` (dotaz HLR v reálném čase) nebo `MNP_DB` (statická databáze přenositelnosti mobilních čísel). Podrobnosti naleznete v možnostech směrování.	false
`routing_instruction`	string	Řetězec oddělený dvojtečkami popisující instrukci směrování použitou v požadavku. První složka je `STATIC`, pokud jste specifikovali trasu, nebo `AUTO` pro automatické směrování; druhá složka je identifikátor trasy a u požadavků s automatickým směrováním třetí složka ukazuje původ, na kterém je rozhodnutí o směrování založeno (tj. `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 cílové zařízení je aktuálně připojeno k mobilní síti. Hovory, SMS a další služby by měly být úspěšně doručeny příjemci.
ABSENT	Číslo je platné, ale cílové zařízení je buď vypnuté, nebo se dočasně nachází mimo dosah sítě. Zprávy nebo hovory nemusí být doručeny, dokud se zařízení znovu nepřipojí k síti.
INVALID_MSISDN	Číslo je neplatné nebo není aktuálně přiřazeno žádnému účastníkovi v mobilní síti. Hovory a zprávy na toto číslo selžou.
UNDETERMINED	Stav připojení čísla nelze určit. Může to být způsobeno neplatným číslem, chybovou odpovědí SS7 nebo nedostatečným připojením k cílové síti operátora. Pro další diagnostiku zkontrolujte kód chyby a jeho popis.

Posunout nahoru

POST/mnp-lookupchráněno

Provádí synchronní MNP vyhledávání a poskytuje informace o přenositelnosti mobilních čísel a síťové informace. Tento endpoint je vhodný, pokud je vaším primárním cílem zjistit aktuální MCCMNC daného mobilního telefonního čísla a určit původní a aktuální síť v reálném čase.

Pro hromadné zpracování velkých datových sad, které nevyžadují okamžité výsledky, zvažte použití asynchronního endpointu POST /mnp-lookups, který je optimalizován pro vysokorychlostní dávkové zpracování.

MNP dotazy spolehlivě určují přenositelnost a síťové informace, ale neindikují, zda je cílový mobilní telefon aktuálně připojen k síti a dostupný. Pro zjištění aktuálních informací o připojení použijte prosím endpoint POST /hlr-lookup.

Požadavek Úspěšná odpověď Chybová odpověď

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

Datová část

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

Parametry požadavku

Klíč	Typ	Popis	Výchozí	Povinné
`msisdn`	string	Mobilní telefonní číslo (MSISDN), které má být dotazováno, uvedené v mezinárodním formátu (např. +14156226819 nebo 0014156226819). Předvolby zemí musí být zahrnuty.	null	povinné
`route`	string(3)	Volitelný tříznakový identifikátor určující trasu pro tento dotaz. Nastavte na `null` nebo tento parametr vynechte pro použití vaší vlastní mapy směrování nebo nechte náš systém automaticky určit nejlepší trasu pro tento dotaz.	null	volitelné
`storage`	string	Volitelný identifikátor úložiště určující report, kde budou výsledky uloženy pro manuální kontrolu, analýzu a reporting. Systém automaticky připojuje časové razítko s aktuálním měsícem. Pokud je vynecháno nebo nastaveno na `null`, systém automaticky seskupí výsledky podle měsíce pro účely reportingu.	null	volitelné

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

Atributy úspěšné odpovědi

Jméno	Typ	Popis	Nullable
`id`	string(12)	Jedinečný 12znakový identifikátor pro toto vyhledávání.	false
`msisdn`	string	Mobilní telefonní číslo vyhodnocené v tomto požadavku na vyhledávání.	false
`query_status`	string	Indikuje, zda získání informací o přenositelnosti a síti proběhlo úspěšně. Možné hodnoty jsou `OK` nebo `FAILED`.	false
`mccmnc`	string(5\|6)	Pěti- nebo šestimístný MCCMNC (kombinace kódu mobilní země a kódu mobilní sítě), který identifikuje síť, do které mobilní telefonní číslo aktuálně patří.	true
`mcc`	string(3)	Třímístný MCC (kód mobilní země) reprezentující zemi spojenou s aktuální sítí mobilního telefonního čísla.	true
`mnc`	string(2\|3)	Dvou- nebo třímístný MNC (kód mobilní sítě), který identifikuje aktuálního síťového operátora pro mobilní telefonní číslo.	true
`is_ported`	boolean	Indikuje, zda bylo telefonní číslo přeneseno z původní sítě k novému operátorovi.	true
`original_network_name`	string	Libovolný řetězec (v angličtině) specifikující název původního síťového operátora zkoumaného mobilního telefonního čísla.	true
`original_country_name`	string	Libovolný řetězec (v angličtině) indikující původní zemi zkoumaného mobilního telefonního čísla.	true
`original_country_code`	string(2)	Dvoumístný ISO kód země reprezentující původní zemi zkoumaného mobilního telefonního čísla.	true
`original_country_prefix`	string	Předvolba původní země spojené se zkoumaným mobilním telefonním číslem.	true
`ported_network_name`	string	Specifikuje síťového operátora, ke kterému bylo zkoumaný mobilní telefonní číslo přeneseno, pokud je to relevantní.	true
`ported_country_name`	string	Specifikuje zemi, do které bylo zkoumaný mobilní telefonní číslo přeneseno, pokud je to relevantní.	true
`ported_country_code`	string(2)	Dvoumístný ISO kód země reprezentující zemi, do které bylo zkoumaný mobilní telefonní číslo přeneseno, pokud je to relevantní.	true
`ported_country_prefix`	string	Předvolba země, do které bylo zkoumaný mobilní telefonní číslo přeneseno, pokud je to relevantní.	true
`extra`	string	Libovolný řetězec poskytující volitelné doplňující podrobnosti o telefonním čísle.	true
`cost`	string	Desetinná hodnota reprezentovaná jako řetězec, indikující náklady v EUR za toto vyhledávání.	true
`timestamp`	string	Časové razítko ve formátu W3C včetně informace o časovém pásmu, indikující, kdy bylo vyhledávání dokončeno.	true
`storage`	string	Název úložiště (nebo název reportu), do kterého byly připojeny výsledky vyhledávání. Používá se pro stahování CSV a reportování prostřednictvím webového rozhraní.	true
`route`	string(3)	Třímístný identifikátor specifikující trasu použitou pro tento požadavek na vyhledávání.	true
`error_code`	integer	Volitelný interní kód chyby poskytující dodatečný kontext pro diagnostiku zákaznické podpory.	true

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

Parametry chybové odpovědi

Jméno	Typ	Popis	Nullable
`errors[]`	string[]	Seznam řetězců vysvětlujících chybu.	false

Posunout nahoru

POST/mnp-lookupschráněno

Zahajuje dávku asynchronních MNP (přenositelnost mobilních čísel) dotazů, které v reálném čase získávají aktuální MCCMNC a přesně určují původní i současnou síť. Výsledky jsou doručovány prostřednictvím webhooků na váš server. Tato metoda je optimalizována pro zpracování velkých objemů čísel, která nevyžadují okamžité odpovědi, jako je čištění a ověřování databází. Pro aplikace v reálném čase, jako je směrování hovorů nebo doručování SMS, zvažte místo toho použití endpointu POST /mnp-lookup.

MNP dotazy spolehlivě určují přenositelnost a síťové informace, ale neindikují, zda je cílový mobilní telefon aktuálně připojen k síti a dostupný. Pro zjištění aktuálních informací o připojení použijte prosím endpoint POST /hlr-lookups.

Před použitím tohoto endpointu se ujistěte, že je nakonfigurována URL webhooku pro asynchronní příjem výsledků dotazů. Můžete to nastavit v nastavení API.

Požadavek Úspěšná odpověď Chybová odpověď Webhooky

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

Datová část

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

Parametry požadavku

Klíč	Typ	Popis	Výchozí	Povinné
`msisdns`	array	Pole mobilních telefonních čísel (MSISDN) v mezinárodním formátu (např. +14156226819 nebo 0014156226819). V jednom požadavku můžete zahrnout až 1000 čísel.	null	povinné
`route`	string(3)	Volitelný tříznakový identifikátor specifikující trasu pro tento dotaz. Nastavte na `null` nebo tento parametr vynechte, aby se použilo vaše vlastní mapování tras nebo aby systém automaticky určil nejlepší trasy pro tento požadavek.	null	volitelné
`storage`	string	Volitelný identifikátor úložiště určující report, kde budou výsledky uloženy pro manuální kontrolu, analýzu a reporting. Systém automaticky připojuje časové razítko s aktuálním měsícem. Pokud je vynecháno nebo nastaveno na `null`, systém automaticky seskupí výsledky podle měsíce pro účely reportingu.	null	volitelné

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

Atributy úspěšné odpovědi

Jméno	Typ	Popis	Nullable
`accepted`	array	Seznam objektů obsahujících jedinečné identifikátory a MSISDN, které byly přijaty ke zpracování.	false
`accepted_count`	integer	Celkový počet MSISDN úspěšně přijatých ke zpracování.	false
`rejected`	array	Seznam objektů obsahujících jedinečné identifikátory a MSISDN, které byly odmítnuty ke zpracování, typicky z důvodu neplatných čísel. Za odmítnuté položky se neúčtuje poplatek.	false
`rejected_count`	integer	Celkový počet MSISDN odmítnutých z důvodu chyb validace.	false
`total_count`	integer	Celkový počet přijatých a odmítnutých MSISDN, které byly odeslány ke zpracování.	false
`cost`	string	Desetinná hodnota reprezentovaná jako řetězec, která udává celkové náklady v EUR za přijaté dotazy.	false
`storage`	string	Název úložiště, kam jsou připojovány výsledky dotazů, používané pro reporty a stahování CSV přes webové rozhraní.	false
`route`	string(3)	Třímístný identifikátor specifikující trasu použitou pro tento požadavek na vyhledávání.	false
`webhook_urls`	array	URL webhooků nakonfigurované v nastavení API. Výsledky jsou sem odesílány zpět.	false

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

Parametry chybové odpovědi

Jméno	Typ	Popis	Nullable
`errors[]`	string[]	Seznam řetězců vysvětlujících chybu.	false

Zpracování webhooků

Po odeslání začne naše platforma zpracovávat poskytnutá telefonní čísla a odesílá výsledky na předem zadanou URL adresu webhooku na vašem serveru. Výsledky jsou přenášeny jako HTTP POST požadavek s JSON objektem v těle požadavku.

Autentizace

Ověřte webhook kontrolou HTTP hlavičky X-Signatures.

Hlavička X-Signatures obsahuje seznam podpisů oddělených středníkem. Každý podpis v seznamu je generován pomocí jednoho z API tajných klíčů nakonfigurovaných ve vašem účtu. Pro ověření webhooku vygenerujte SHA-256 hash pomocí vašeho API klíče, tajného klíče a původního HTTP těla - poté jej porovnejte s podpisy v seznamu.

Shoda potvrzuje, že požadavek je autentický a podepsaný tajným klíčem, který kontrolujete.

Pří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žadavek je platný, pokud se kterýkoli z podpisů uvedených v hlavičce rovná SHA256 hashi vypočítanému ze zřetězeného řetězce vašeho API klíče, tajného klíče a HTTP těla.

Potvrzení přijetí

Váš server by měl odpovědět stavovým kódem HTTP 200 OK pro potvrzení úspěšného přijetí. Pokud je vrácen jakýkoli jiný stavový kód, dojde k vypršení časového limitu (10 sekund) nebo nastane jiný problém s doručením, systém automaticky zopakuje webhook po jedné minutě. Pokud požadavek nadále selhává, opakování budou následovat strategii exponenciálního zpoždění s dalšími pokusy po 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minutách.

Tento mechanismus opakování zajišťuje maximální spolehlivost při doručování výsledků vyhledávání do vaší infrastruktury. Minimalizuje riziko ztráty dat v důsledku dočasných problémů se sítí nebo výpadku serveru.

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

Atributy payloadu webhooku

JSON objekt obsahuje atribut type => MNP spolu s atributem results, který zahrnuje seznam objektů dotazů, jak je uvedeno níže.

Jméno	Typ	Popis	Nullable
`id`	string(12)	Jedinečný 12znakový identifikátor pro toto vyhledávání.	false
`msisdn`	string	Mobilní telefonní číslo vyhodnocené v tomto požadavku na vyhledávání.	false
`query_status`	string	Indikuje, zda získání informací o přenositelnosti a síti proběhlo úspěšně. Možné hodnoty jsou `OK` nebo `FAILED`.	false
`mccmnc`	string(5\|6)	Pěti- nebo šestimístný MCCMNC (kombinace kódu mobilní země a kódu mobilní sítě), který identifikuje síť, do které mobilní telefonní číslo aktuálně patří.	true
`mcc`	string(3)	Třímístný MCC (kód mobilní země) reprezentující zemi spojenou s aktuální sítí mobilního telefonního čísla.	true
`mnc`	string(2\|3)	Dvou- nebo třímístný MNC (kód mobilní sítě), který identifikuje aktuálního síťového operátora pro mobilní telefonní číslo.	true
`is_ported`	boolean	Indikuje, zda bylo telefonní číslo přeneseno z původní sítě k novému operátorovi.	true
`original_network_name`	string	Libovolný řetězec (v angličtině) specifikující název původního síťového operátora zkoumaného mobilního telefonního čísla.	true
`original_country_name`	string	Libovolný řetězec (v angličtině) indikující původní zemi zkoumaného mobilního telefonního čísla.	true
`original_country_code`	string(2)	Dvoumístný ISO kód země reprezentující původní zemi zkoumaného mobilního telefonního čísla.	true
`original_country_prefix`	string	Předvolba původní země spojené se zkoumaným mobilním telefonním číslem.	true
`ported_network_name`	string	Specifikuje síťového operátora, ke kterému bylo zkoumaný mobilní telefonní číslo přeneseno, pokud je to relevantní.	true
`ported_country_name`	string	Specifikuje zemi, do které bylo zkoumaný mobilní telefonní číslo přeneseno, pokud je to relevantní.	true
`ported_country_code`	string(2)	Dvoumístný ISO kód země reprezentující zemi, do které bylo zkoumaný mobilní telefonní číslo přeneseno, pokud je to relevantní.	true
`ported_country_prefix`	string	Předvolba země, do které bylo zkoumaný mobilní telefonní číslo přeneseno, pokud je to relevantní.	true
`extra`	string	Libovolný řetězec poskytující volitelné doplňující podrobnosti o telefonním čísle.	true
`cost`	string	Desetinná hodnota reprezentovaná jako řetězec, indikující náklady v EUR za toto vyhledávání.	true
`timestamp`	string	Časové razítko ve formátu W3C včetně informace o časovém pásmu, indikující, kdy bylo vyhledávání dokončeno.	true
`storage`	string	Název úložiště (nebo název reportu), do kterého byly připojeny výsledky vyhledávání. Používá se pro stahování CSV a reportování prostřednictvím webového rozhraní.	true
`route`	string(3)	Třímístný identifikátor specifikující trasu použitou pro tento požadavek na vyhledávání.	true
`error_code`	integer	Volitelný interní kód chyby poskytující dodatečný kontext pro diagnostiku zákaznické podpory.	true

Posunout nahoru

POST/nt-lookupchráněno

Provádí synchronní vyhledávání typu čísla (NT). Tento endpoint je ideální, pokud je vaším hlavním cílem zjistit v reálném čase, zda poskytnutá telefonní čísla patří do rozsahů pevných linek, mobilních sítí, prémiových tarifů, VoIP, pagerů nebo jiných číselných plánů.

NT dotazy spolehlivě detekují typ telefonního čísla, nicméně neindikují, zda je cílové číslo aktuálně připojeno k síti a dostupné. Pro získání informací o aktuální dostupnosti použijte prosím endpoint POST /hlr-lookup.

Pokud váš případ vyžaduje přesné informace o síti a přenositelnosti (MCCMNC), ale ne stav aktuální dostupnosti, použijte prosím endpoint POST /mnp-lookup pro dotazy na přenositelnost mobilních čísel.

Požadavek Úspěšná odpověď Chybová odpověď Referenční příručka typů

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

Datová část

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

Parametry požadavku

Klíč	Typ	Popis	Výchozí	Povinné
`number`	string	Telefonní číslo v mezinárodním formátu (např. +4989702626 nebo 004989702626).	null	mandatory
`route`	string(3)	Volitelný tříznakový identifikátor určující trasu pro toto vyhledávání. Nastavte na `null` nebo tento parametr vynechte pro použití vaší vlastní mapy směrování nebo nechte náš systém automaticky určit nejlepší trasy pro tento požadavek.	null	volitelné
`storage`	string	Volitelný identifikátor úložiště určující report, kde budou výsledky uloženy pro manuální kontrolu, analýzu a reporting. Systém automaticky připojuje časové razítko s aktuálním měsícem. Pokud je vynecháno nebo nastaveno na `null`, systém automaticky seskupí výsledky podle měsíce pro účely reportingu.	null	volitelné

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

Atributy úspěšné odpovědi

Jméno	Typ	Popis	Nullable
`id`	string(12)	Jedinečný identifikátor přiřazený k tomuto vyhledávacímu požadavku.	false
`number`	string	Telefonní číslo, které bylo vyhodnoceno během tohoto vyhledávacího požadavku.	false
`number_type`	string	Zjištěný typ čísla. Možné hodnoty zahrnují: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Označuje, zda byla informace o typu čísla úspěšně získána. Vrací `OK` v případě úspěchu nebo `FAILED`, pokud vyhledávání selhalo.	false
`is_valid`	boolean	Označuje, zda je telefonní číslo syntakticky platné.	true
`invalid_reason`	string	Textová zpráva v angličtině specifikující, proč je telefonní číslo považováno za neplatné (např. "too short" nebo "invalid prefix"), nebo `null`, pokud je číslo platné.	true
`is_possibly_ported`	boolean	Označuje, zda mohlo být telefonní číslo přeneseno od původního operátora k jinému poskytovateli. Pro definitivní informace o přenositelnosti použijte MNP vyhledávání.	true
`is_vanity_number`	boolean	Označuje, zda je telefonní číslo vanity číslem, což znamená, že obsahuje abecední znaky.	true
`qualifies_for_hlr_lookup`	boolean	Označuje, zda je telefonní číslo způsobilé pro další dotazy prostřednictvím HLR vyhledávání.	true
`mccmnc`	string(5\|6)	Pět nebo šestimístný řetězec reprezentující MCCMNC tuple (kód mobilní země a kód mobilní sítě), který identifikuje původní síť mobilního telefonního čísla.	true
`mcc`	string(3)	Třímístný řetězec reprezentující MCC (kód mobilní země), který identifikuje zemi spojenou s původní mobilní sítí telefonního čísla.	true
`mnc`	string(2\|3)	Dvou nebo třímístný řetězec reprezentující MNC (kód mobilní sítě), který identifikuje původního operátora mobilní sítě telefonního čísla.	true
`original_network_name`	string	Libovolný textový řetězec v angličtině specifikující název původního síťového operátora kontrolovaného mobilního telefonního čísla.	true
`original_country_name`	string	Libovolný textový řetězec v angličtině specifikující původní zemi spojenou s kontrolovaným mobilním telefonním číslem.	true
`original_country_code`	string(2)	Dvoumístný ISO kód země označující původní zemi kontrolovaného mobilního telefonního čísla.	true
`regions`	array	Seznam čitelných řetězců v angličtině, které specifikují geografickou oblast (oblasti) spojenou s tímto telefonním číslem.	true
`timezones`	array	Seznam časových pásem (ve formátu Olson) spojených s tímto telefonním číslem.	true
`info_text`	string	Libovolný řetězec, který může obsahovat další informace o telefonním čísle.	true
`cost`	string	Desetinná hodnota reprezentovaná jako řetězec, označující náklady (v EUR) tohoto vyhledávání.	true
`timestamp`	string	Časové razítko ve formátu W3C (včetně časového pásma) označující, kdy bylo vyhledávání dokončeno.	true
`storage`	string	Určuje název úložiště, kam byly připojeny výsledky vyhledávání. To odpovídá názvu reportu používanému pro stahování CSV a analytiku prostřednictvím webového rozhraní.	true
`route`	string(3)	Třímístný identifikátor specifikující trasu použitou pro tento požadavek na vyhledávání.	true

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

Parametry chybové odpovědi

Jméno	Typ	Popis	Nullable
`errors[]`	string[]	Seznam řetězců vysvětlujících chybu.	false

Typ	Popis
LANDLINE	Číslo pevné linky.
MOBILE	Číslo mobilního telefonu. Vhodné pro HLR vyhledávání za účelem získání dodatečných informací o stavu připojení, síti, přenositelnosti a roamingu.
MOBILE_OR_LANDLINE	Číslo pevné linky nebo mobilního telefonu. Může být vhodné pro HLR vyhledávání.
TOLL_FREE	Bezplatné telefonní číslo.
PREMIUM_RATE	Telefonní číslo se zvýšeným tarifem s dodatečnými poplatky.
SHARED_COST	Telefonní číslo se sdílenými náklady. Obvykle levnější než čísla se zvýšeným tarifem.
VOIP	VoIP telefonní číslo. Zahrnuje TSoIP čísla (Telephony Service over IP).
PAGER	Číslo pageru. Obvykle bez hlasové funkcionality.
UAN	Univerzální přístupové číslo (firemní číslo). Může být směrováno na konkrétní pobočky, ale umožňuje používat jedno číslo pro celou společnost.
VOICEMAIL	Číslo hlasové schránky.
UNKNOWN	Typ čísla nelze určit.

Posunout nahoru

POST/nt-lookups chráněno

Tento endpoint spouští sérii asynchronních vyhledávání typu čísla s výsledky odeslanými zpět na váš server prostřednictvím webhooku. Je vhodný, pokud je vaším primárním cílem zjistit, zda daná telefonní čísla patří do rozsahů pevné linky, mobilní sítě, prémiových služeb, VoIP, pageru nebo jiných číselných plánů. Optimalizovaný pro rychlé zpracování velkých objemů čísel, tento endpoint je ideální pro hromadné operace (např. sanitizace databáze). Pro živý provoz a časově kritické případy použití prosím použijte místo toho endpoint POST /nt-lookup.

Pro vyvolání tohoto endpointu musíte jako předpoklad specifikovat webhook URL ve vašem nastavení API.

Požadavek Úspěšná odpověď Chybová odpověď Webhooky Referenční příručka typů

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

Datová část

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

Parametry požadavku

Klíč	Typ	Popis	Výchozí	Povinné
`numbers`	array	Pole telefonních čísel v mezinárodním formátu (např. +14156226819 nebo 004989702626). Na jeden požadavek lze zahrnout maximálně 1000 čísel.	null	povinné
`route`	string(3)	Volitelný tříznakový identifikátor specifikující trasu pro toto vyhledávání. Nastavte na `null` nebo tento parametr vynechte pro aplikaci vaší vlastní mapy směrování nebo nechte náš systém automaticky určit nejlepší trasu pro tento požadavek.	null	volitelné
`storage`	string	Volitelný identifikátor úložiště určující report, kde budou výsledky uloženy pro manuální kontrolu, analýzu a reporting. Systém automaticky připojuje časové razítko s aktuálním měsícem. Pokud je vynecháno nebo nastaveno na `null`, systém automaticky seskupí výsledky podle měsíce pro účely reportingu.	null	volitelné

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

Atributy úspěšné odpovědi

Jméno	Typ	Popis	Nullable
`accepted`	array	Pole objektů, z nichž každý obsahuje jedinečný identifikátor a telefonní číslo, které bylo přijato ke zpracování.	false
`accepted_count`	integer	Celkový počet telefonních čísel přijatých ke zpracování.	false
`rejected`	array	Pole objektů, z nichž každý obsahuje jedinečný identifikátor a telefonní číslo, které bylo odmítnuto ke zpracování. Typicky jsou tato čísla neplatná a není účtován žádný poplatek.	false
`rejected_count`	integer	Celkový počet telefonních čísel, která byla odmítnuta ke zpracování.	false
`total_count`	integer	Celkový počet přijatých a odmítnutých telefonních čísel, která byla odeslána ke zpracování.	false
`cost`	string	Řetězec představující desetinnou hodnotu, která udává náklady v EUR za tato vyhledávání.	false
`storage`	string	Název úložiště (reportu), do kterého byly připojeny výsledky vyhledávání. Tento název se používá pro stahování CSV a analytiku prostřednictvím webového rozhraní.	false
`route`	string(3)	Tříznakový identifikátor, který specifikuje trasu použitou pro tento požadavek na vyhledávání.	false
`webhook_urls`	array	URL webhooků nakonfigurované v nastavení API. Výsledky jsou sem odesílány zpět.	false

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

Parametry chybové odpovědi

Jméno	Typ	Popis	Nullable
`errors[]`	string[]	Seznam řetězců vysvětlujících chybu.	false

Zpracování webhooků

Po odeslání začne naše platforma zpracovávat poskytnutá telefonní čísla a odesílá výsledky na předem zadanou URL adresu webhooku na vašem serveru. Výsledky jsou přenášeny jako HTTP POST požadavek s JSON objektem v těle požadavku.

Autentizace

Ověřte webhook kontrolou HTTP hlavičky X-Signatures.

Hlavička X-Signatures obsahuje seznam podpisů oddělených středníkem. Každý podpis v seznamu je generován pomocí jednoho z API tajných klíčů nakonfigurovaných ve vašem účtu. Pro ověření webhooku vygenerujte SHA-256 hash pomocí vašeho API klíče, tajného klíče a původního HTTP těla - poté jej porovnejte s podpisy v seznamu.

Shoda potvrzuje, že požadavek je autentický a podepsaný tajným klíčem, který kontrolujete.

Pří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žadavek je platný, pokud se kterýkoli z podpisů uvedených v hlavičce rovná SHA256 hashi vypočítanému ze zřetězeného řetězce vašeho API klíče, tajného klíče a HTTP těla.

Potvrzení přijetí

Váš server by měl odpovědět stavovým kódem HTTP 200 OK pro potvrzení úspěšného přijetí. Pokud je vrácen jakýkoli jiný stavový kód, dojde k vypršení časového limitu (10 sekund) nebo nastane jiný problém s doručením, systém automaticky zopakuje webhook po jedné minutě. Pokud požadavek nadále selhává, opakování budou následovat strategii exponenciálního zpoždění s dalšími pokusy po 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minutách.

Tento mechanismus opakování zajišťuje maximální spolehlivost při doručování výsledků vyhledávání do vaší infrastruktury. Minimalizuje riziko ztráty dat v důsledku dočasných problémů se sítí nebo výpadku serveru.

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

Atributy payloadu webhooku

JSON objekt obsahuje atribut type => NT spolu s atributem results, který zahrnuje seznam objektů dotazů, jak je uvedeno níže.

Jméno	Typ	Popis	Nullable
`id`	string(12)	Jedinečný identifikátor přiřazený k tomuto vyhledávacímu požadavku.	false
`number`	string	Telefonní číslo, které bylo vyhodnoceno během tohoto vyhledávacího požadavku.	false
`number_type`	string	Zjištěný typ čísla. Možné hodnoty zahrnují: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Označuje, zda byla informace o typu čísla úspěšně získána. Vrací `OK` v případě úspěchu nebo `FAILED`, pokud vyhledávání selhalo.	false
`is_valid`	boolean	Označuje, zda je telefonní číslo syntakticky platné.	true
`invalid_reason`	string	Textová zpráva v angličtině specifikující, proč je telefonní číslo považováno za neplatné (např. "too short" nebo "invalid prefix"), nebo `null`, pokud je číslo platné.	true
`is_possibly_ported`	boolean	Označuje, zda mohlo být telefonní číslo přeneseno od původního operátora k jinému poskytovateli. Pro definitivní informace o přenositelnosti použijte MNP vyhledávání.	true
`is_vanity_number`	boolean	Označuje, zda je telefonní číslo vanity číslem, což znamená, že obsahuje abecední znaky.	true
`qualifies_for_hlr_lookup`	boolean	Označuje, zda je telefonní číslo způsobilé pro další dotazy prostřednictvím HLR vyhledávání.	true
`mccmnc`	string(5\|6)	Pět nebo šestimístný řetězec reprezentující MCCMNC tuple (kód mobilní země a kód mobilní sítě), který identifikuje původní síť mobilního telefonního čísla.	true
`mcc`	string(3)	Třímístný řetězec reprezentující MCC (kód mobilní země), který identifikuje zemi spojenou s původní mobilní sítí telefonního čísla.	true
`mnc`	string(2\|3)	Dvou nebo třímístný řetězec reprezentující MNC (kód mobilní sítě), který identifikuje původního operátora mobilní sítě telefonního čísla.	true
`original_network_name`	string	Libovolný textový řetězec v angličtině specifikující název původního síťového operátora kontrolovaného mobilního telefonního čísla.	true
`original_country_name`	string	Libovolný textový řetězec v angličtině specifikující původní zemi spojenou s kontrolovaným mobilním telefonním číslem.	true
`original_country_code`	string(2)	Dvoumístný ISO kód země označující původní zemi kontrolovaného mobilního telefonního čísla.	true
`regions`	array	Seznam čitelných řetězců v angličtině, které specifikují geografickou oblast (oblasti) spojenou s tímto telefonním číslem.	true
`timezones`	array	Seznam časových pásem (ve formátu Olson) spojených s tímto telefonním číslem.	true
`info_text`	string	Libovolný řetězec, který může obsahovat další informace o telefonním čísle.	true
`cost`	string	Desetinná hodnota reprezentovaná jako řetězec, označující náklady (v EUR) tohoto vyhledávání.	true
`timestamp`	string	Časové razítko ve formátu W3C (včetně časového pásma) označující, kdy bylo vyhledávání dokončeno.	true
`storage`	string	Určuje název úložiště, kam byly připojeny výsledky vyhledávání. To odpovídá názvu reportu používanému pro stahování CSV a analytiku prostřednictvím webového rozhraní.	true
`route`	string(3)	Třímístný identifikátor specifikující trasu použitou pro tento požadavek na vyhledávání.	true

Typ	Popis
LANDLINE	Číslo pevné linky.
MOBILE	Číslo mobilního telefonu. Vhodné pro HLR vyhledávání za účelem získání dodatečných informací o stavu připojení, síti, přenositelnosti a roamingu.
MOBILE_OR_LANDLINE	Číslo pevné linky nebo mobilního telefonu. Může být vhodné pro HLR vyhledávání.
TOLL_FREE	Bezplatné telefonní číslo.
PREMIUM_RATE	Telefonní číslo se zvýšeným tarifem s dodatečnými poplatky.
SHARED_COST	Telefonní číslo se sdílenými náklady. Obvykle levnější než čísla se zvýšeným tarifem.
VOIP	VoIP telefonní číslo. Zahrnuje TSoIP čísla (Telephony Service over IP).
PAGER	Číslo pageru. Obvykle bez hlasové funkcionality.
UAN	Univerzální přístupové číslo (firemní číslo). Může být směrováno na konkrétní pobočky, ale umožňuje používat jedno číslo pro celou společnost.
VOICEMAIL	Číslo hlasové schránky.
UNKNOWN	Typ čísla nelze určit.

Posunout nahoru

GET/routechráněno

Načte trasu, která bude automaticky vybrána při spuštění HLR vyhledávání bez zadání parametru route.

Automatický výběr trasy je založen na mapě směrování, kterou lze získat pomocí endpointu GET /hlr-coverage, jenž je primárně odvozen z GET /routing-map. Mapu směrování můžete přizpůsobit a definovat vlastní pravidla v nastavení účtu.

Požadavek Úspěšná odpověď Chybová odpověď

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

Parametry požadavku

Klíč	Typ	Popis	Výchozí	Povinné
`msisdn`	string	MSISDN, pro které se mají načíst automaticky vybrané informace o směrování.	null	povinné

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

Atributy úspěšné odpovědi

Jméno	Typ	Popis	Nullable
`route`	string	Doporučená trasa.	false
`confidence_level`	string	Úroveň spolehlivosti, s jakou byla tato trasa vybrána, tj. `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`.	false
`mccmnc`	string	MCCMNC založené na číslovacím plánu pro toto číslo.	false
`origin`	string	Původ, na kterém je založeno rozhodnutí o směrování, tj. `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."
    ]
}

Parametry chybové odpovědi

Jméno	Typ	Popis	Nullable
`errors[]`	string[]	Seznam řetězců vysvětlujících chybu.	false

Posunout nahoru

GET/routeschráněno

Tento endpoint vrací seznam dostupných HLR, MNP a NT tras. Každá trasa, včetně jejích funkcí a omezení, je vysvětlena na stránce podrobnosti směrování.

Požadavek Úspěšná odpověď Chybová odpověď

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

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

Atributy úspěšné odpovědi

Jméno	Typ	Popis	Nullable
`routes`	object	Objekt s trasami seskupenými podle typu trasy.	false
`HLR\|MNP\|NT`	string[]	Obsahuje seznam identifikátorů tras.	false

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

Parametry chybové odpovědi

Jméno	Typ	Popis	Nullable
`errors[]`	string[]	Seznam řetězců vysvětlujících chybu.	false

Posunout nahoru

GET/routing-mapchráněno

Načítá aktuální konfiguraci automatického směrování aplikovanou na HLR vyhledávání pro váš účet. Tato výchozí konfigurace se používá vždy, když odešlete HLR vyhledávání bez uvedení parametru route. Mapu směrování můžete přizpůsobit a vytvořit vlastní pravidla v nastavení účtu.

Hierarchie konfigurace kaskáduje od pravidel na úrovni země k pravidlům na úrovni MCCMNC a nakonec k mapování jednotlivých předvoleb telefonních čísel. V praxi to znamená, že mapování jednotlivých předvoleb telefonních čísel má přednost před konfliktními přiřazeními MCCMNC, která zase přepisují pravidla na úrovni země. Upozorňujeme, že záložní MNP přepisuje jakákoli konfliktní vlastní pravidla, pokud je aktivováno.

Požadavek Úspěšná odpověď Chybová odpověď

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

Atributy úspěšné odpovědi

Jméno	Typ	Popis	Nullable
`default_route`	string	Výchozí trasa používaná v případě, že nelze pro MSISDN určit preferovanou možnost směrování a neplatí žádná vlastní pravidla směrování.	false
`mnp_fallback`	boolean	Indikuje, zda je aktivováno záložní MNP. Pokud je aktivováno a HLR dotazy nejsou sítí podporovány (stav konektivity není dostupný), systém místo toho provede MNP vyhledávání.	false
`mccmncs`	array	Mapování kódů MCCMNC na jejich automaticky vybrané trasy. Při provádění HLR vyhledávání pro číslo v daném MCCMNC se použije odpovídající trasa.	false
`mccmnc`	string(5\|6)	Pěti- nebo šestimístný MCCMNC (kombinace kódu mobilní země a kódu mobilní sítě) identifikující operátora mobilní sítě.	false
`countrycode`	string(2)	Dvoumístný ISO kód země identifikující zemi sítě.	false
`route`	string(3)	Vybraná trasa pro síť.	false
`mno`	string	Spotřebitelská značka, pod kterou tato síť funguje.	false
`confidence`	string	Úroveň spolehlivosti, s jakou byl výběr proveden. Možné hodnoty jsou: HIGH, NORMAL, LOW, MNP_REDIRECT. V případě posledně uvedené hodnoty systém přesměruje provoz do této sítě na MNP, pokud je toto chování povoleno ve vašem účtu. Jinak použije výchozí trasu v účtu.	false
`origin`	string	Původ, na kterém je výběr založen. Možné hodnoty jsou: `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	Seznam vlastních pravidel směrování založených na předvolbách nakonfigurovaných ve vašem účtu, pokud existují.	false
`countrycode`	string(2)	Dvoumístný ISO kód země identifikující zemi předvolby.	false
`cns`	string	Předvolba, na kterou se pravidlo směrování vztahuje.	false
`route`	string(3)	Vybraná trasa pro předvolbu.	false
`mccmnc`	string(5\|6)	Pěti- nebo šestimístný MCCMNC (kombinace kódu mobilní země a kódu mobilní sítě) identifikující operátora mobilní sítě.	true
`mno`	string	Spotřebitelská značka, pod kterou tato síť funguje.	true
`countries`	array	Seznam vlastních pravidel založených na zemích nakonfigurovaných ve vašem účtu, pokud existují.	false
`countrycode`	string(2)	Dvoumístný ISO kód země identifikující zemi.	false
`route`	string(3)	Vybraná trasa pro zemi.	false

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

Parametry chybové odpovědi

Jméno	Typ	Popis	Nullable
`errors[]`	string[]	Seznam řetězců vysvětlujících chybu.	false

Posunout nahoru

GET/hlr-coverage chráněno

Vrací přehledy HLR pokrytí pro podporu rozhodování založeného na datech. Tento endpoint vám pomůže analyzovat možnosti HLR směrování v reálném čase napříč mobilními sítěmi, identifikovat nejefektivnější cesty pro vaše cílové regiony a konfigurovat automatické směrování.

Doporučené trasy z GET /route jsou založeny na datech o pokrytí získaných zde. Data o pokrytí jsou také k dispozici na stránce pokrytí sítí. Můžete dále přizpůsobit svou mapu směrování a definovat pravidla v nastavení účtu.

Doporučujeme se seznámit s tímto průvodcem, který vám pomůže interpretovat výsledky.

Požadavek Úspěšná odpověď Chybová odpověď Referenční stavy

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

Parametry požadavku

Klíč	Typ	Popis	Výchozí	Povinné
`countrycode`	string(2)	Povinný dvoupísmenný ISO kód země použitý k filtrování výsledků, vrací pouze záznamy spojené se specifikovanou zemí.	null	povinné
`sample_size`	string	Volitelný parametr specifikující velikost vzorku. Možné hodnoty jsou `LARGE`, `MEDIUM`, `SMALL`. Větší vzorky pokrývají delší časové období, menší vzorky pokrývají velmi nedávné časové období.	LARGE	volitelné

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

Atributy úspěšné odpovědi

Jméno	Typ	Popis	Nullable
`name`	string	Název vybrané země v anglickém prostém textu.	false
`countrycode`	string(2)	Dvoumístný ISO kód vybrané země.	false
`prefix`	string	Mezinárodní předvolba vybrané země.	false
`mccs`	string[]	Seznam MCC (mobilních kódů zemí) spojených s vybranou zemí.	false
`carriers`	object[]	Seznam objektů operátorů s metrikami konektivity specifickými pro trasu.	false
`mno`	string	Název mobilního síťového operátora v anglickém prostém textu.	false
`mccmnc`	string	MCCMNC mobilního síťového operátora.	false
`mcc`	string	MCC (mobilní kód země) mobilního síťového operátora.	false
`mnc`	string	MNC (mobilní síťový kód) mobilního síťového operátora.	false
`routes`	object[]	Seznam výsledků konektivity specifických pro trasu.	false
`route`	string	Trasa, na kterou se vztahují informace o konektivitě.	false
`selected`	bool	Označuje, zda se jedná o vybranou trasu pro automatické směrování.	false
`selection_confidence`	string	Úroveň spolehlivosti, s jakou byla tato trasa vybrána, tj. `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`. Obsahuje null, pokud se nejedná o vybranou trasu.	true
`n`	int	Celkový počet dotazů v tomto vzorku.	false
`CONNECTED`	int	Počet HLR dotazů, které vrátily stav CONNECTED.	false
`CONNECTED_PCT`	float	Procento HLR dotazů, které vrátily stav CONNECTED.	false
`ABSENT`	int	Počet HLR dotazů, které vrátily stav ABSENT.	false
`ABSENT_PCT`	float	Procento HLR dotazů, které vrátily stav ABSENT.	false
`INVALID_MSISDN`	int	Počet HLR dotazů, které vrátily stav INVALID_MSISDN.	false
`INVALID_MSISDN_PCT`	float	Procento HLR dotazů, které vrátily stav INVALID_MSISDN.	false
`UNDETERMINED`	int	Počet HLR dotazů, které vrátily stav UNDETERMINED.	false
`UNDETERMINED_PCT`	float	Procento HLR dotazů, které vrátily stav UNDETERMINED.	false

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

Parametry chybové odpovědi

Jméno	Typ	Popis	Nullable
`errors[]`	string[]	Seznam řetězců vysvětlujících chybu.	false

Stav	Popis
CONNECTED	Číslo je platné a cílové zařízení je aktuálně připojeno k mobilní síti. Hovory, SMS a další služby by měly být úspěšně doručeny příjemci.
ABSENT	Číslo je platné, ale cílové zařízení je buď vypnuté, nebo se dočasně nachází mimo dosah sítě. Zprávy nebo hovory nemusí být doručeny, dokud se zařízení znovu nepřipojí k síti.
INVALID_MSISDN	Číslo je neplatné nebo není aktuálně přiřazeno žádnému účastníkovi v mobilní síti. Hovory a zprávy na toto číslo selžou.
UNDETERMINED	Stav připojení čísla nelze určit. Může to být způsobeno neplatným číslem, chybovou odpovědí SS7 nebo nedostatečným připojením k cílové síti operátora. Pro další diagnostiku zkontrolujte kód chyby a jeho popis.

Posunout nahoru

GET/mnp-coveragechráněno

Tento endpoint vrací seznam operátorů mobilních sítí spolu s jejich odpovídajícími identifikátory MCCMNC, které jsou aktuálně podporovány pro vyhledávání přenositelnosti mobilních čísel.

Požadavek Úspěšná odpověď Chybová odpověď

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

Parametry požadavku

Klíč	Typ	Popis	Výchozí	Povinné
`countrycode`	string(2)	Volitelný dvoumístný ISO kód země použitý k filtrování výsledků MCCMNC, který vrací pouze data relevantní pro zadanou zemi.	null	volitelné

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

Atributy úspěšné odpovědi

Jméno	Typ	Popis	Nullable
`items[]`	array	Seznam operátorů mobilních sítí.	false
`country_name`	string	Název země v angličtině.	false
`country_code`	string(2)	Dvoumístný ISO kód země.	false
`mccmnc`	string(5\|6)	Pěti- nebo šestimístný MCCMNC (kombinace kódu mobilní země a kódu mobilní sítě) identifikující operátora mobilní sítě.	false
`mcc`	string(3)	Třímístný MCC (kód mobilní země) představující zemi sítě.	false
`mnc`	string(2\|3)	Dvou- nebo třímístný MNC (kód mobilní sítě) představující konkrétního operátora mobilní sítě.	false
`brand`	string	Spotřebitelská značka, pod kterou tato síť funguje.	true
`operator`	string	Právní název operátora mobilní sítě.	true

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

Parametry chybové odpovědi

Jméno	Typ	Popis	Nullable
`errors[]`	string[]	Seznam řetězců vysvětlujících chybu.	false

Posunout nahoru

GET/price-listchráněno

Tento endpoint vrací seznam zemí, kde jsou podporovány pouze MNP dotazy a HLR dotazy nejsou pro tyto destinace dostupné.

Požadavek Úspěšná odpověď Chybová odpověď

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

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

Atributy úspěšné odpovědi

Jméno	Typ	Popis	Nullable
`countries`	string[]	Seznam dvouznakových ISO kódů zemí.	false

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

Parametry chybové odpovědi

Jméno	Typ	Popis	Nullable
`errors[]`	string[]	Seznam řetězců vysvětlujících chybu.	false

Posunout nahoru

GET/mccmncschráněno

Tento endpoint vrací kompletní seznam operátorů mobilních sítí spolu s jejich odpovídajícími identifikátory MCCMNC a dalšími kontextovými informacemi.

Požadavek Úspěšná odpověď Chybová odpověď

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

Parametry požadavku

Klíč	Typ	Popis	Výchozí	Povinné
`countrycode`	string(2)	Volitelný dvoupísmenný ISO kód země použitý k filtrování výsledků MCCMNC, vrací pouze záznamy spojené se zadanou zemí.	null	volitelné

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

Atributy úspěšné odpovědi

Jméno	Typ	Popis	Nullable
`items`	object[]	Seznam operátorů mobilních sítí.	false
`country_name`	string	Úplný název země v angličtině.	false
`country_code`	string(2)	Dvoupísmenný ISO kód země reprezentující zemi mobilního operátora.	false
`mccmnc`	string(5\|6)	Pěti- nebo šestimístný řetězec reprezentující MCCMNC, který jednoznačně identifikuje operátora mobilní sítě.	false
`mcc`	string(3)	Třímístný kód země mobilní sítě (MCC), který identifikuje zemi, kde mobilní síť působí.	false
`mnc`	string(2\|3)	Dvou- nebo třímístný kód mobilní sítě (MNC), který specifikuje mobilní síť v rámci daného MCC.	false
`brand`	string	Obchodní značka, pod kterou síť působí a je spotřebiteli známá.	true
`operator`	string	Oficiální název operátora mobilní sítě, obvykle právní subjekt spravující síť.	true
`parent_mccmnc`	string(5\|6)	Pěti- nebo šestimístný řetězec reprezentující MCCMNC mateřského operátora mobilní sítě, pokud existuje.	true

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

Parametry chybové odpovědi

Jméno	Typ	Popis	Nullable
`errors[]`	string[]	Seznam řetězců vysvětlujících chybu.	false

Posunout nahoru

GET/pricechráněno

Tento endpoint vrací cenu pro HLR, MNP nebo NT dotaz.

Požadavek Úspěšná odpověď Chybová odpověď

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

Parametry požadavku

Klíč	Typ	Popis	Výchozí	Povinné
`msisdn`	string	Telefonní číslo, pro které se má zjistit cena. V mezinárodním formátu.	null	povinné
`route_type`	string	Typ trasy, tj. `HLR`, `MNP`, `NT`.	null	povinné
`route`	string(3)	Trasa, pro kterou má být vypočítána cena. Výchozí je trasa určená automatickým směrováním.	null	volitelné

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

Atributy úspěšné odpovědi

Jméno	Typ	Popis	Nullable
`price`	object	Objekt s podrobnostmi o cenách.	false
`amount`	string	Částka v EUR.	false
`msisdn`	string	MSISDN, pro které platí tato cena.	false
`route_type`	string(2\|3)	Typ trasy, pro který platí tato cena.	false
`route`	string(3)	Trasa, pro kterou platí tato cena.	false

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

Parametry chybové odpovědi

Jméno	Typ	Popis	Nullable
`errors[]`	string[]	Seznam řetězců vysvětlujících chybu.	false

Posunout nahoru

GET/price-listchráněno

Tento endpoint vrací ceník ve vašem účtu.

Požadavek Úspěšná odpověď Chybová odpověď

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

Atributy úspěšné odpovědi

Jméno	Typ	Popis	Nullable
`pricing`	object[]	Seznam objektů s informacemi o cenách.	false
`route`	string	Směrování, pro které platí tento ceník.	false
`countrycode`	string	Dvoumístný ISO kód země, pro který platí tento ceník pro odpovídající směrování, pokud existuje.	true
`countryname`	string	Anglický název země odpovídající kódu země, pokud existuje.	true
`mccmnc`	string	MCCMNC, pro které platí tento ceník pro odpovídající směrování, pokud existuje. Přepisuje ceník na úrovni země.	true
`cns`	string	Volací předčíslí, pro které platí tento ceník pro odpovídající směrování, pokud existuje. Přepisuje ceník na úrovni země i MCCMNC.	true
`route_type`	string	Odpovídající typ směrování, tj. `HLR`, `MNP`, `NT`.	false
`route_type`	string	Odpovídající cena v EUR.	false

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

Parametry chybové odpovědi

Jméno	Typ	Popis	Nullable
`errors[]`	string[]	Seznam řetězců vysvětlujících chybu.	false

Posunout nahoru

GET/balancechráněno

Tento endpoint načte aktuální zůstatek vašeho účtu a umožňuje automatizovat procesy na základě stavu vašeho kreditu. Bezproblémově funguje s notifikačními e-maily o nízkém kreditu, které si můžete nastavit na stránce plateb.

Požadavek Úspěšná odpověď Chybová odpověď

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

{
    "balance":"1002.90"
}

Atributy úspěšné odpovědi

Jméno	Typ	Popis	Nullable
`balance`	string	Váš aktuální zůstatek účtu v EUR. Desítkové číslo typu string.	false

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

Parametry chybové odpovědi

Jméno	Typ	Popis	Nullable
`errors[]`	string[]	Seznam řetězců vysvětlujících chybu.	false

Posunout nahoru

GET/pingveřejné

Tento endpoint odesílá ping požadavek do API a poskytuje jednoduchý způsob, jak otestovat připojení k HLR Lookups API.

Požadavek Úspěšná odpověď Chybová odpověď

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

{
    "success":true
}

Atributy úspěšné odpovědi

Jméno	Typ	Popis	Nullable
`success`	boolean	Indikuje, že požadavek byl úspěšně zpracován.	false

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

Parametry chybové odpovědi

Jméno	Typ	Popis	Nullable
`errors[]`	string[]	Seznam řetězců vysvětlujících chybu.	false

Posunout nahoru

GET/timeveřejné

Tento endpoint vrací Unix timestamp reprezentující aktuální čas na serveru HLR Lookups. Použijte jej k synchronizaci hodin vašeho serveru při generování Digest-Auth podpisu pro autentizaci, čímž zajistíte opravu případných nesrovnalostí mezi časem vašeho serveru a časem serveru HLR Lookups.

Požadavek Úspěšná odpověď Chybová odpověď

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

{
    "time":1525898643
}

Atributy úspěšné odpovědi

Jméno	Typ	Popis	Nullable
`time`	integer	Unix timestamp reprezentující aktuální čas serveru HLR Lookups.	false

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

Parametry chybové odpovědi

Jméno	Typ	Popis	Nullable
`errors[]`	string[]	Seznam řetězců vysvětlujících chybu.	false

Posunout nahoru

GET/auth-testchráněno

Tento endpoint slouží jako počáteční test vaší implementace Basic-Auth nebo, lépe, Digest-Auth.

Basic Auth požadavek Požadavek s Digest Auth Úspěšná odpověď Chybová odpověď

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

Hlavičky požadavku

Klíč	Typ	Popis
`X-Basic`	string	SHA256 hash `YOUR_API_KEY:YOUR_API_SECRET`. Zahrňte do hashe symbol dvojtečky (:).

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žadavku

Klíč	Typ	Popis
`X-Digest-Key`	string	Váš API klíč HLR Lookups
`X-Digest-Signature`	string	Unikátní Digest-Auth podpis (viz autentizace)
`X-Digest-Timestamp`	integer	Aktuální Unix timestamp (viz také `GET /time`)

{
    "success":true
}

Atributy úspěšné odpovědi

Jméno	Typ	Popis	Nullable
`success`	boolean	Indikuje, že požadavek byl úspěšně zpracován.	false

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

Parametry chybové odpovědi

Jméno	Typ	Popis	Nullable
`errors[]`	string[]	Seznam řetězců vysvětlujících chybu.	false

Posunout nahoru

Dokumentace starší verze API

Upozorňujeme, že starší verze API je zastaralá a v budoucnu bude vyřazena z provozu. Důrazně doporučujeme co nejdříve přejít na nejnovější verzi.

Pokud jste implementovali naše HLR Lookups API mezi roky 2013 a začátkem roku 2020, používáte naši starší verzi API. V takovém případě prosím použijte naši dokumentaci starší verze API.

Dokumentace starší verze API

Dokumentace API

Začínáme

HLR vyhledávání

MNP vyhledávání

NT vyhledávání

Směrování

Ceník

Nástroje

Začínáme

Použití HLR Lookups API

Příklad požadavku

Příklad datové části

Úspěšná odpověď application/json

Další vyhledávací služby

Vyhledávání přenositelnosti čísel (MNP)

Detekce typu čísla (NT)

Vývojové sady (SDK)

Nástroje

Nejste vývojář?

Autentizace

API klíč a API tajný klíč

HTTP Basic Auth

Doporučeno: X-Basic hlavička s SHA256

Basic Auth požadavek

Basic Authentication hlavičky

Příklad kódu

Příklad požadavku

Hlavičky požadavku

Vytvoření podpisu

Komponenty Digest Signature

Příklady kódu

Koncepty

Synchronní HLR Lookup API

Asynchronní HLR Lookup API

SDK (Software Development Kits)

SDK pro PHP

SDK pro NodeJS

SDK pro Ruby

POST/hlr-lookupchráněno

Datová část

Parametry požadavku

Atributy úspěšné odpovědi

Parametry chybové odpovědi

POST/hlr-lookupschráněno

Datová část

Parametry požadavku

Atributy úspěšné odpovědi

Parametry chybové odpovědi

Zpracování webhooků

Autentizace

Příklad kódu

Potvrzení přijetí

Obsah webhooku

Atributy payloadu webhooku

POST/mnp-lookupchráněno

Datová část

Parametry požadavku

Atributy úspěšné odpovědi

Parametry chybové odpovědi

POST/mnp-lookupschráněno

Datová část

Parametry požadavku

Atributy úspěšné odpovědi

Parametry chybové odpovědi

Zpracování webhooků

Autentizace

Příklad kódu

Potvrzení přijetí

Obsah webhooku

Atributy payloadu webhooku

POST/nt-lookupchráněno

Datová část

Parametry požadavku

Atributy úspěšné odpovědi

Parametry chybové odpovědi

POST/nt-lookups chráněno

Datová část

Parametry požadavku

Atributy úspěšné odpovědi

Parametry chybové odpovědi