Pierwsze kroki

Globalna infrastruktura sieci komórkowych działa w oparciu o system znany jako sieć sygnalizacyjna SS7. Sieć ta umożliwia wymianę danych abonentów, routing połączeń, transmisję SMS oraz aktualizacje statusu łączności mobilnej w czasie rzeczywistym pomiędzy operatorami. Każda sieć komórkowa utrzymuje rejestr Home Location Register (HLR) - centralną bazę danych przechowującą kluczowe informacje o swoich abonentach.

Technologia HLR Lookup umożliwia firmom odpytywanie tych rejestrów i pobieranie aktualnych informacji o łączności oraz danych sieciowych dla dowolnego numeru telefonu komórkowego. Obejmuje to informacje o tym, czy telefon jest włączony, do której sieci jest aktualnie przypisany, czy został przeniesiony, czy numer jest aktywny lub dezaktywowany oraz czy znajduje się w roamingu.

API HLR Lookups zapewnia bezproblemowy dostęp do tych danych w czasie rzeczywistym, umożliwiając firmom weryfikację numerów telefonów komórkowych, optymalizację routingu oraz usprawnienie komunikacji z klientami. Niniejsza dokumentacja poprowadzi Cię przez proces integracji HLR Lookups z Twoim oprogramowaniem, umożliwiając automatyczne pobieranie danych o łączności mobilnej w czasie rzeczywistym.

Korzystanie z API HLR Lookups

Wykonywanie zapytań HLR Lookup jest szybkie, bezpieczne i proste. Po zarejestrowaniu się i uzyskaniu klucza API, możesz przeprowadzić uwierzytelnienie i rozpocząć natychmiastowe wyszukiwania za pomocą prostych żądań HTTP POST, poprzez POST /hlr-lookup. Alternatywnie możesz przetwarzać duże zbiory danych, wybierając szybkie asynchroniczne żądania API z wynikami przesyłanymi z powrotem na Twój serwer przez webhook, jak wyjaśniono w sekcji koncepcje.

Przykładowe żądanie

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"

Uwierzytelnienie jest przekazywane przez nagłówki HTTP, a payload.json powinien (jako minimum) zawierać następujący obiekt JSON:

Przykładowy payload

{
   "msisdn": "+14156226819"
}

Po pomyślnym wykonaniu otrzymasz odpowiedź zawierającą szczegóły łączności w czasie rzeczywistym dla podanego numeru telefonu komórkowego.

Odpowiedź Sukcesu 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"
}

Pełny opis atrybutów żądania i odpowiedzi oraz statusów łączności znajdziesz w POST /hlr-lookup.

Dodatkowe usługi wyszukiwania

Zapytania o przenośność numerów (MNP)

Użyj zapytań MNP, aby określić przynależność do sieci i szczegóły przenośności bez odpytywania łączności w czasie rzeczywistym. Jeśli potrzebujesz tylko kodu MCCMNC numeru, skorzystaj z POST /mnp-lookup.

Wykrywanie typu numeru (NT)

Określ, czy numer telefonu należy do telefonu stacjonarnego, komórkowego, premium, VoIP, pagera lub innych zakresów planu numeracji za pomocą POST /nt-lookup.

Zestawy SDK

API HLR Lookups działa z dowolnym klientem REST w każdym języku programowania. Opublikowaliśmy zestawy SDK dla PHP, Ruby i NodeJS na naszym GitHubie, aby pomóc Ci szybko rozpocząć pracę.

Narzędzia

Aby zapewnić bezproblemowe środowisko programistyczne, oferujemy kompleksowy zestaw narzędzi, w tym monitorowanie żądań API i webhooków w przeglądarce, białą listę adresów IP, zaawansowane opcje uwierzytelniania oraz testowy endpoint uwierzytelniania.

Nie jesteś programistą?

Zapytania HLR Lookups i przenośności numerów mogą być wykonywane bez programowania. Dowiedz się więcej o naszym kliencie webowym dla przedsiębiorstw oraz funkcjach raportowania w przeglądarce.

Uwierzytelnianie

Aby zapewnić bezpieczeństwo i odpowiednią kontrolę dostępu, większość żądań do API HLR Lookups wymaga uwierzytelnienia. Endpointy są podzielone na publiczne i chronione. Podczas dostępu do chronionego endpointu, żądanie musi być uwierzytelnione przy użyciu klucza API i sekretu za pomocą metody Digest-Auth lub Basic-Auth. Digest-Auth jest bezpieczniejszą opcją i jest zdecydowanie zalecana. Użyj endpointu GET /auth-test, aby zweryfikować konfigurację uwierzytelniania.

Klucz API i sekret API

Pobierz swój klucz API i sekret ze strony Ustawienia API. Możesz również skonfigurować preferowaną metodę uwierzytelniania i włączyć białą listę adresów IP w celu zwiększenia bezpieczeństwa. Jeśli podejrzewasz, że Twój sekret API został skompromitowany, możesz w każdej chwili wygenerować nowy.

Basic Auth Digest Auth Whitelist IP

Standardowe uwierzytelnianie Basic jest łatwe do wdrożenia i szeroko wspierane. Możesz się uwierzytelnić, przekazując klucz API i sekret jako parę user:pass w żądaniu HTTP.

HTTP Basic Auth

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

Wysyła to nagłówek Authorization:

Authorization: Basic BASE64(YOUR_API_KEY:YOUR_API_SECRET)

Zalecane: nagłówek X-Basic z SHA256

Dla zwiększenia bezpieczeństwa możesz wysłać hash SHA256 swoich danych uwierzytelniających zamiast przesyłać je bezpośrednio jako base64. Aby użyć tej metody, oblicz hash pary YOUR_API_KEY:YOUR_API_SECRET i wyślij go przez nagłówek X-Basic:

Żądanie Basic Auth

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

Nagłówki uwierzytelniania Basic

Klucz	Typ	Opis
`X-Basic`	string	Hash SHA256 z `YOUR_API_KEY:YOUR_API_SECRET`. Uwzględnij dwukropek (:) w hashu.	obowiązkowy

Przykład kodu

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

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

Digest-Auth jest zalecaną metodą zabezpieczania dostępu do chronionych endpointów API HLR Lookup. Każde żądanie musi zawierać następujące nagłówki: X-Digest-Key, X-Digest-Signature i X-Digest-Timestamp, które są wyjaśnione poniżej.

Przykład żądania

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"

Nagłówki żądania

Klucz	Typ	Opis
`X-Digest-Key`	string	Twój unikalny klucz API HLR Lookups.	obowiązkowy
`X-Digest-Signature`	string	Unikalna sygnatura uwierzytelniania (patrz poniżej).	obowiązkowy
`X-Digest-Timestamp`	integer	Aktualny znacznik czasu Unix (patrz również `GET /time`).	obowiązkowy

Tworzenie sygnatury

X-Digest-Signature jest tworzony przy użyciu hashu HMAC SHA256, z Twoim sekretem API jako kluczem współdzielonym.

Ciąg znaków do zahashowania jest zbudowany w następujący sposób:

ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY

Symbol . oznacza konkatenację ciągów znaków.

Komponenty sygnatury Digest

Komponent	Typ	Opis
`ENDPOINT_PATH`	string	Żądany endpoint API, np. `/auth-test` małymi literami.
`UNIX_TIMESTAMP`	integer	Aktualny znacznik czasu Unix (musi być w ciągu 30 sekund). Patrz `GET /time`.
`REQUEST_METHOD`	string	Użyta metoda HTTP, np. `POST` lub `GET`.
`REQUEST_BODY`	string	Dane w treści żądania. Ustaw na `null` dla żądań `GET`.

Przykłady kodu

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)

Przewiń w górę

Koncepcje

Implementacja zapytań HLR w dowolnym języku programowania lub systemie za pomocą naszego HTTP REST API jest prosta i wydajna. Dzięki prostemu procesowi integracji możesz rozpocząć odpytywanie sieci komórkowych w czasie rzeczywistym, uzyskując natychmiastowe informacje o ważności numerów telefonów, statusie łączności i szczegółach routingu.

Wybór odpowiedniego API zależy od konkretnego przypadku użycia. Jeśli potrzebujesz wyników zapytań w czasie rzeczywistym dla aplikacji takich jak telefonia VoIP, wykrywanie oszustw lub routing SMS, najlepszym wyborem jest synchroniczne API. Jeśli jednak Twój przypadek użycia obejmuje przetwarzanie dużych wolumenów, zapytania masowe lub weryfikację danych na dużą skalę, asynchroniczne API oferuje zoptymalizowaną wydajność z efektywnym wykorzystaniem przepustowości i możliwością zapytań wsadowych.

Skonfiguruj API, aby korzystało z jednej z naszych niestandardowych opcji routingu w celu optymalizacji szybkości, dokładności i opłacalności. Możesz również przechowywać wyniki zapytań w magazynach, aby łatwo pobierać raporty CSV i JSON oraz korzystać z zaawansowanej analityki przez interfejs webowy.

Synchroniczne API zapytań HLR

Endpoint POST /hlr-lookup przetwarza jeden numer telefonu komórkowego (MSISDN) na żądanie i zwraca wyniki natychmiast w treści odpowiedzi HTTP. Wyniki są formatowane jako JSON i idealnie nadają się do aplikacji czasu rzeczywistego, w tym walidacji numerów komórkowych, routingu połączeń i dostarczania wiadomości SMS.

Synchroniczne wywołanie API składa się z bezpośredniego żądania i odpowiedzi HTTP. Twój system przesyła pojedynczy MSISDN (numer komórkowy) na żądanie i otrzymuje natychmiastową odpowiedź zawierającą wyniki zapytania HLR w czasie rzeczywistym w formacie JSON. To API jest zoptymalizowane pod kątem przypadków użycia wymagających natychmiastowej weryfikacji i sprawdzania łączności, takich jak wykrywanie oszustw, routing połączeń VoIP i optymalizacja bramek SMS.

Asynchroniczne API wyszukiwania HLR

Endpoint POST /hlr-lookups jest zaprojektowany do przetwarzania masowego i dużych wolumenów, umożliwiając przesłanie do 1,000 numerów MSISDN na żądanie. Zamiast zwracać wyniki natychmiast, to API wykorzystuje zautomatyzowane webhooki do stopniowego przesyłania wyników na Twój serwer. Wyniki zapytań są zwracane jako obiekty JSON poprzez wywołania zwrotne HTTP POST.

Asynchroniczne API jest zoptymalizowane pod kątem szybkości, wydajności i skalowalności. Eliminuje problemy z opóźnieniami sieciowymi związanymi z wywołaniami synchronicznymi, dzięki czemu idealnie nadaje się dla firm wymagających zapytań o wysokiej przepustowości. Twój system przesyła do 1,000 numerów MSISDN na żądanie, a nasza platforma przetwarza je równolegle, dostarczając wyniki z powrotem na Twój serwer poprzez webhooki HTTP w partiach do 1,000 wyników na wywołanie zwrotne.

SDK (zestawy narzędzi programistycznych)

Nasze zestawy narzędzi programistycznych (SDK) dla PHP, NodeJS i Ruby usprawniają proces integracji, umożliwiając efektywne połączenie z API HLR Lookups przy minimalnym wysiłku.

Te SDK zapewniają gotowe funkcje, obsługę uwierzytelniania oraz ustrukturyzowane szablony zapytań API, skracając czas rozwoju i gwarantując najlepsze praktyki.

Zapoznaj się z pełną listą dostępnych SDK na GitHub i rozpocznij integrację już dziś.

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

Zobacz na GitHub README.md

1   require('node-hlr-client');
2
3   let response = await client.post('/hlr-lookup', {msisdn: '+491788735000'});
4
5   if (response.status === 200) {
6      // lookup was successful
7      let data = response.data;
8   }

Zobacz na GitHub README.md

1   require 'ruby_hlr_client/client'
2
3   client = HlrLookupsSDK::Client.new(
4       'YOUR-API-KEY',
5       'YOUR-API-SECRET',
6       '/var/log/hlr-lookups.log'
7   )
8
9   params = { :msisdn => '+14156226819' }
10  response = client.get('/hlr-lookup', params)

Zobacz na GitHub README.md

Przewiń w górę

POST/hlr-lookupchroniony

Wykonuje synchroniczne zapytanie HLR, dostarczając w czasie rzeczywistym dane o łączności i przenośności numerów telefonów komórkowych bezpośrednio od operatorów sieci. Ten endpoint jest idealny dla scenariuszy ruchu na żywo, gdzie aplikacje wymagające natychmiastowej weryfikacji, czy numer telefonu jest obecnie osiągalny (podłączony) czy niedostępny (wyłączony). Dodatkowo pomaga odróżnić aktywne numery od nieważnych, nieznanych lub fałszywych.

Do przetwarzania zbiorczego dużych zestawów danych, które nie wymagają natychmiastowych wyników, rozważ użycie asynchronicznego POST /hlr-lookups, który jest zoptymalizowany pod kątem szybkiego przetwarzania wsadowego.

Jeśli Twoim głównym celem jest pobranie danych o przenośności numerów komórkowych (MCCMNC) i nie potrzebujesz statusu łączności na żywo, POST /mnp-lookup stanowi opłacalną alternatywę dla zapytań o przenośność numerów komórkowych.

Żądanie Odpowiedź Sukcesu Odpowiedź Błędu Informacje o statusach

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

Dane wejściowe

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

Parametry żądania

Klucz	Typ	Opis	Domyślnie	Wymagane
`msisdn`	string	Numer telefonu komórkowego (MSISDN) do sprawdzenia, podany w formacie międzynarodowym (np. +14156226819 lub 0014156226819). Kody krajów muszą być uwzględnione.	null	obowiązkowy
`route`	string(3)	Opcjonalny trzyliterowy identyfikator określający trasę dla tego zapytania. Ustaw na `null` lub pomiń ten parametr, aby zastosować swoją niestandardową mapę routingu lub pozwól naszemu systemowi automatycznie określić najlepszą trasę dla tego zapytania.	null	opcjonalnie
`storage`	string	Opcjonalny identyfikator przechowywania określający raport, w którym wyniki będą przechowywane do ręcznego przeglądu, analityki i raportowania. System automatycznie dodaje znacznik czasu z bieżącym miesiącem. Jeśli zostanie pominięty lub ustawiony na `null`, system automatycznie pogrupuje wyniki według miesięcy dla celów raportowania.	null	opcjonalnie

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

Atrybuty Odpowiedzi Sukcesu

Nazwa	Typ	Opis	Opcjonalny
`id`	string(12)	Unikalny identyfikator przypisany do tego zapytania.	false
`msisdn`	string	Numer telefonu komórkowego będący przedmiotem zapytania, w formacie międzynarodowym (np. +14156226819 lub 0014156226819).	false
`connectivity_status`	string	Wskazuje, czy status łączności numeru został pomyślnie pobrany. Możliwe wartości: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` lub `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Pięcio- lub sześciocyfrowy kod Mobile Country Code (MCC) i Mobile Network Code (MNC) identyfikujący sieć aktualnie przypisaną do numeru telefonu.	true
`mcc`	string(3)	Trzycyfrowy kod Mobile Country Code (MCC) identyfikujący kraj, w którym zarejestrowany jest numer telefonu.	true
`mnc`	string(2\|3)	Dwu- lub trzycyfrowy kod Mobile Network Code (MNC) identyfikujący konkretną sieć, do której należy numer telefonu.	true
`imsi`	string	International Mobile Subscriber Identity (IMSI), unikalny identyfikator karty SIM powiązanej z tym numerem. Dostępność zależy od konfiguracji sieci.	true
`msin`	string(10)	Mobile Subscription Identification Number (MSIN) w bazie danych operatora sieci komórkowej. Dostępność zależy od konfiguracji sieci.	true
`msc`	string(12)	Mobile Switching Center (MSC) aktualnie obsługujący komunikację tego abonenta. Dostępność zależy od konfiguracji sieci.	true
`original_network_name`	string	Nazwa pierwotnego (natywnego) operatora sieci przypisanego do tego numeru.	true
`original_country_name`	string	Pełna nazwa kraju, w którym pierwotnie zarejestrowany został numer telefonu komórkowego, podana w języku angielskim.	true
`original_country_code`	string(2)	Dwuznakowy kod kraju ISO reprezentujący kraj, w którym numer telefonu został pierwotnie przypisany.	true
`original_country_prefix`	string	Międzynarodowy kod kierunkowy (numer kierunkowy kraju) odpowiadający pierwotnemu krajowi numeru telefonu komórkowego.	true
`is_ported`	boolean	Wskazuje, czy numer komórkowy został przeniesiony z pierwotnej sieci do innego operatora.	true
`ported_network_name`	string	Nazwa operatora sieci, do którego przeniesiony został numer komórkowy, jeśli dotyczy.	true
`ported_country_name`	string	Nazwa kraju, do którego przeniesiony został numer komórkowy, jeśli dotyczy.	true
`ported_country_code`	string(2)	Dwuznakowy kod kraju ISO reprezentujący kraj, do którego przeniesiony został numer komórkowy, jeśli dotyczy.	true
`ported_country_prefix`	string	Międzynarodowy kod kierunkowy (numer kierunkowy kraju) dla kraju, do którego przeniesiony został numer komórkowy, jeśli dotyczy.	true
`is_roaming`	boolean	Wskazuje, czy numer komórkowy aktualnie korzysta z roamingu w sieci zagranicznej. Dostępność statusu roamingu zależy od operatora sieci komórkowej.	true
`roaming_network_name`	string	Nazwa sieci, w której numer komórkowy aktualnie korzysta z roamingu, jeśli dotyczy.	true
`roaming_country_name`	string	Nazwa kraju, w którym numer komórkowy aktualnie korzysta z roamingu, jeśli dotyczy.	true
`roaming_country_code`	string(2)	Dwuznakowy kod kraju ISO dla kraju, w którym numer komórkowy aktualnie korzysta z roamingu, jeśli dotyczy.	true
`roaming_country_prefix`	string	Międzynarodowy kod kierunkowy (numer kierunkowy kraju) dla kraju, w którym numer komórkowy aktualnie korzysta z roamingu, jeśli dotyczy.	true
`cost`	string	Wartość dziesiętna reprezentowana jako ciąg znaków, wskazująca koszt zapytania w EUR.	true
`timestamp`	string	Znacznik czasu w formacie W3C wraz ze strefą czasową, określający moment zakończenia zapytania.	true
`storage`	string	Nazwa magazynu, w którym zapisano wyniki zapytania. Odpowiada nazwom raportów i plików CSV dostępnych do pobrania przez interfejs webowy.	true
`route`	string(3)	Trzyliterowy identyfikator wskazujący metodę routingu użytą dla tego zapytania.	true
`processing_status`	string	Wynik przetwarzania zapytania. Możliwe wartości: `COMPLETED` (pomyślne), `REJECTED` (sieć nieosiągalna, bez obciążenia), lub `FAILED` (wystąpił błąd podczas przetwarzania).	false
`error_code`	integer	Opcjonalny wewnętrzny kod błędu dostarczający dodatkowych informacji diagnostycznych dla wsparcia klienta.	true
`error_description`	string	Krótkie wyjaśnienie podanego kodu błędu (jeśli występuje) w postaci tekstu w języku angielskim.	true
`data_source`	string	Źródło danych użyte dla tego zapytania. Możliwe wartości: `LIVE_HLR` (zapytanie HLR w czasie rzeczywistym) lub `MNP_DB` (statyczna baza danych przenoszenia numerów). Szczegóły w opcjach routingu.	false
`routing_instruction`	string	Ciąg znaków rozdzielony dwukropkiem opisujący instrukcję routingu użytą w zapytaniu. Pierwszy komponent to `STATIC`, gdy określono trasę, lub `AUTO` dla automatycznego routingu; drugi komponent to identyfikator trasy, a dla zapytań z automatycznym routingiem trzeci komponent pokazuje źródło, na podstawie którego podjęto decyzję o routingu (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 Odpowiedzi Błędu

Nazwa	Typ	Opis	Opcjonalny
`errors[]`	string[]	Lista ciągów tekstowych wyjaśniających błąd.	false

Status	Opis
CONNECTED	Numer jest prawidłowy, a docelowe urządzenie jest obecnie podłączone do sieci komórkowej. Połączenia, wiadomości SMS i inne usługi powinny dotrzeć do odbiorcy bez problemu.
ABSENT	Numer jest prawidłowy, ale docelowe urządzenie jest wyłączone lub tymczasowo poza zasięgiem sieci. Wiadomości lub połączenia mogą nie zostać dostarczone do momentu ponownego połączenia urządzenia z siecią.
INVALID_MSISDN	Numer jest nieprawidłowy lub nie jest obecnie przypisany do żadnego abonenta w sieci komórkowej. Połączenia i wiadomości do tego numeru zakończą się niepowodzeniem.
UNDETERMINED	Nie można ustalić statusu łączności numeru. Może to wynikać z nieprawidłowego numeru, błędu odpowiedzi SS7 lub braku połączenia z docelowym operatorem sieci. Sprawdź kod błędu i pole opisu w celu uzyskania dodatkowych informacji diagnostycznych.

Przewiń w górę

POST/hlr-lookupschroniony

Inicjuje partię asynchronicznych zapytań HLR, pobierając na żywo dane o łączności i przenośności numerów telefonów komórkowych od operatorów sieci. Wyniki są dostarczane przez webhooks na Twój serwer. Ta metoda jest zoptymalizowana do przetwarzania dużych wolumenów numerów, które nie wymagają natychmiastowych odpowiedzi, takich jak czyszczenie i weryfikacja bazy danych. W przypadku aplikacji działających w czasie rzeczywistym, takich jak routing połączeń lub dostarczanie SMS, rozważ użycie punktu końcowego POST /hlr-lookup.

Ten punkt końcowy jest idealny do masowego przetwarzania, gdy celem jest identyfikacja numerów telefonów, które są obecnie dostępne (podłączone) lub niedostępne (telefon wyłączony), przy jednoczesnym filtrowaniu nieprawidłowych, nieprzypisanych lub fałszywych numerów. Dodatkowo dostarcza na żywo status przenośności (MCCMNC) wraz ze szczegółami łączności.

Przed użyciem tego punktu końcowego upewnij się, że skonfigurowany jest adres URL webhooka do asynchronicznego odbierania wyników zapytań. Możesz to skonfigurować w ustawieniach API.

Żądanie Odpowiedź Sukcesu Odpowiedź Błędu Webhooki Informacje o statusach

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

Dane wejściowe

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

Parametry żądania

Klucz	Typ	Opis	Domyślnie	Wymagane
`msisdns`	array	Tablica numerów telefonów komórkowych (MSISDN) w formacie międzynarodowym (np. +14156226819 lub 0014156226819). Możesz uwzględnić do 1000 numerów na żądanie.	null	obowiązkowy
`route`	string(3)	Opcjonalny trzyliterowy identyfikator określający trasę dla tego zapytania. Ustaw na `null` lub pomiń ten parametr, aby zastosować swoją niestandardową mapę routingu lub pozwól naszemu systemowi automatycznie określić najlepszą trasę dla tego zapytania.	null	opcjonalnie
`storage`	string	Opcjonalny identyfikator przechowywania określający raport, w którym wyniki będą przechowywane do ręcznego przeglądu, analityki i raportowania. System automatycznie dodaje znacznik czasu z bieżącym miesiącem. Jeśli zostanie pominięty lub ustawiony na `null`, system automatycznie pogrupuje wyniki według miesięcy dla celów raportowania.	null	opcjonalnie

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

Atrybuty Odpowiedzi Sukcesu

Nazwa	Typ	Opis	Opcjonalny
`accepted`	array	Lista obiektów zawierających unikalne identyfikatory i numery MSISDN, które zostały zaakceptowane do przetwarzania.	false
`accepted_count`	integer	Całkowita liczba numerów MSISDN pomyślnie zaakceptowanych do przetwarzania.	false
`rejected`	array	Lista obiektów zawierających unikalne identyfikatory i numery MSISDN, które zostały odrzucone do przetwarzania, zazwyczaj z powodu nieprawidłowych numerów. Za odrzucone wpisy nie są naliczane opłaty.	false
`rejected_count`	integer	Całkowita liczba numerów MSISDN odrzuconych z powodu błędów walidacji.	false
`total_count`	integer	Całkowita liczba zaakceptowanych i odrzuconych numerów MSISDN, które zostały przesłane do przetwarzania.	false
`cost`	string	Wartość dziesiętna reprezentowana jako ciąg znaków, wskazująca całkowity koszt w EUR dla zaakceptowanych zapytań.	false
`storage`	string	Nazwa magazynu, w którym dodawane są wyniki zapytań, używana do raportowania i pobierania plików CSV przez interfejs webowy.	false
`route`	string(3\|4)	Trzyliterowy lub czteroliterowy identyfikator określający trasę użytą dla tego żądania zapytania. Zawiera AUTO, jeśli zażądano automatycznego routingu opartego na numerze.	false
`webhook_urls`	array	Adresy URL webhooków skonfigurowane w ustawieniach API. Wyniki są tutaj odsyłane.	false

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

Parametry Odpowiedzi Błędu

Nazwa	Typ	Opis	Opcjonalny
`errors[]`	string[]	Lista ciągów tekstowych wyjaśniających błąd.	false

Przetwarzanie webhooków

Po przesłaniu nasz system rozpoczyna przetwarzanie podanych numerów telefonów i wysyła wyniki na wcześniej określony adres URL webhooka na Państwa serwerze. Wyniki są przesyłane jako żądanie HTTP POST z obiektem JSON w treści żądania.

Uwierzytelnianie

Uwierzytelnij webhook sprawdzając nagłówek HTTP X-Signatures.

Nagłówek X-Signatures zawiera listę sygnatur oddzielonych średnikami. Każda sygnatura na liście jest generowana przy użyciu jednego z sekretów API skonfigurowanych na Państwa koncie. Aby zweryfikować webhook, wygeneruj hash SHA-256 używając swojego klucza API, sekretu i surowej treści HTTP - następnie porównaj go z sygnaturami na liście.

Zgodność potwierdza, że żądanie jest autentyczne i podpisane sekretem, który kontrolujesz.

Przykład kodu

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

Żądanie jest prawidłowe, jeśli którakolwiek z sygnatur podanych w nagłówku jest równa hashowi SHA256 obliczonemu na podstawie połączonego ciągu Państwa klucza API, sekretu i treści HTTP.

Potwierdzanie odbioru

Państwa serwer powinien odpowiedzieć kodem statusu HTTP 200 OK, aby potwierdzić pomyślny odbiór. Jeśli zostanie zwrócony inny kod odpowiedzi, wystąpi przekroczenie czasu (10 sekund) lub pojawi się jakikolwiek inny problem z dostarczeniem, system automatycznie ponowi próbę dostarczenia webhooka po jednej minucie. Jeśli żądanie nadal kończy się niepowodzeniem, kolejne próby będą realizowane zgodnie ze strategią wykładniczego wycofywania, z następnymi próbami po 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minutach.

Ten mechanizm ponawiania zapewnia maksymalną niezawodność w dostarczaniu wyników wyszukiwania do Państwa infrastruktury. Minimalizuje ryzyko utraty danych z powodu tymczasowych problemów sieciowych lub przestojów serwera.

Dane webhooka

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

Atrybuty ładunku webhooka

Obiekt JSON zawiera atrybut type => HLR oraz atrybut results, który zawiera listę obiektów zapytań, zgodnie z dokumentacją poniżej.

Nazwa	Typ	Opis	Opcjonalny
`id`	string(12)	Unikalny identyfikator przypisany do tego zapytania.	false
`msisdn`	string	Numer telefonu komórkowego będący przedmiotem zapytania, w formacie międzynarodowym (np. +14156226819 lub 0014156226819).	false
`connectivity_status`	string	Wskazuje, czy status łączności numeru został pomyślnie pobrany. Możliwe wartości: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` lub `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Pięcio- lub sześciocyfrowy kod Mobile Country Code (MCC) i Mobile Network Code (MNC) identyfikujący sieć aktualnie przypisaną do numeru telefonu.	true
`mcc`	string(3)	Trzycyfrowy kod Mobile Country Code (MCC) identyfikujący kraj, w którym zarejestrowany jest numer telefonu.	true
`mnc`	string(2\|3)	Dwu- lub trzycyfrowy kod Mobile Network Code (MNC) identyfikujący konkretną sieć, do której należy numer telefonu.	true
`imsi`	string	International Mobile Subscriber Identity (IMSI), unikalny identyfikator karty SIM powiązanej z tym numerem. Dostępność zależy od konfiguracji sieci.	true
`msin`	string(10)	Mobile Subscription Identification Number (MSIN) w bazie danych operatora sieci komórkowej. Dostępność zależy od konfiguracji sieci.	true
`msc`	string(12)	Mobile Switching Center (MSC) aktualnie obsługujący komunikację tego abonenta. Dostępność zależy od konfiguracji sieci.	true
`original_network_name`	string	Nazwa pierwotnego (natywnego) operatora sieci przypisanego do tego numeru.	true
`original_country_name`	string	Pełna nazwa kraju, w którym pierwotnie zarejestrowany został numer telefonu komórkowego, podana w języku angielskim.	true
`original_country_code`	string(2)	Dwuznakowy kod kraju ISO reprezentujący kraj, w którym numer telefonu został pierwotnie przypisany.	true
`original_country_prefix`	string	Międzynarodowy kod kierunkowy (numer kierunkowy kraju) odpowiadający pierwotnemu krajowi numeru telefonu komórkowego.	true
`is_ported`	boolean	Wskazuje, czy numer komórkowy został przeniesiony z pierwotnej sieci do innego operatora.	true
`ported_network_name`	string	Nazwa operatora sieci, do którego przeniesiony został numer komórkowy, jeśli dotyczy.	true
`ported_country_name`	string	Nazwa kraju, do którego przeniesiony został numer komórkowy, jeśli dotyczy.	true
`ported_country_code`	string(2)	Dwuznakowy kod kraju ISO reprezentujący kraj, do którego przeniesiony został numer komórkowy, jeśli dotyczy.	true
`ported_country_prefix`	string	Międzynarodowy kod kierunkowy (numer kierunkowy kraju) dla kraju, do którego przeniesiony został numer komórkowy, jeśli dotyczy.	true
`is_roaming`	boolean	Wskazuje, czy numer komórkowy aktualnie korzysta z roamingu w sieci zagranicznej. Dostępność statusu roamingu zależy od operatora sieci komórkowej.	true
`roaming_network_name`	string	Nazwa sieci, w której numer komórkowy aktualnie korzysta z roamingu, jeśli dotyczy.	true
`roaming_country_name`	string	Nazwa kraju, w którym numer komórkowy aktualnie korzysta z roamingu, jeśli dotyczy.	true
`roaming_country_code`	string(2)	Dwuznakowy kod kraju ISO dla kraju, w którym numer komórkowy aktualnie korzysta z roamingu, jeśli dotyczy.	true
`roaming_country_prefix`	string	Międzynarodowy kod kierunkowy (numer kierunkowy kraju) dla kraju, w którym numer komórkowy aktualnie korzysta z roamingu, jeśli dotyczy.	true
`cost`	string	Wartość dziesiętna reprezentowana jako ciąg znaków, wskazująca koszt zapytania w EUR.	true
`timestamp`	string	Znacznik czasu w formacie W3C wraz ze strefą czasową, określający moment zakończenia zapytania.	true
`storage`	string	Nazwa magazynu, w którym zapisano wyniki zapytania. Odpowiada nazwom raportów i plików CSV dostępnych do pobrania przez interfejs webowy.	true
`route`	string(3)	Trzyliterowy identyfikator wskazujący metodę routingu użytą dla tego zapytania.	true
`processing_status`	string	Wynik przetwarzania zapytania. Możliwe wartości: `COMPLETED` (pomyślne), `REJECTED` (sieć nieosiągalna, bez obciążenia), lub `FAILED` (wystąpił błąd podczas przetwarzania).	false
`error_code`	integer	Opcjonalny wewnętrzny kod błędu dostarczający dodatkowych informacji diagnostycznych dla wsparcia klienta.	true
`error_description`	string	Krótkie wyjaśnienie podanego kodu błędu (jeśli występuje) w postaci tekstu w języku angielskim.	true
`data_source`	string	Źródło danych użyte dla tego zapytania. Możliwe wartości: `LIVE_HLR` (zapytanie HLR w czasie rzeczywistym) lub `MNP_DB` (statyczna baza danych przenoszenia numerów). Szczegóły w opcjach routingu.	false
`routing_instruction`	string	Ciąg znaków rozdzielony dwukropkiem opisujący instrukcję routingu użytą w zapytaniu. Pierwszy komponent to `STATIC`, gdy określono trasę, lub `AUTO` dla automatycznego routingu; drugi komponent to identyfikator trasy, a dla zapytań z automatycznym routingiem trzeci komponent pokazuje źródło, na podstawie którego podjęto decyzję o routingu (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

Status	Opis
CONNECTED	Numer jest prawidłowy, a docelowe urządzenie jest obecnie podłączone do sieci komórkowej. Połączenia, wiadomości SMS i inne usługi powinny dotrzeć do odbiorcy bez problemu.
ABSENT	Numer jest prawidłowy, ale docelowe urządzenie jest wyłączone lub tymczasowo poza zasięgiem sieci. Wiadomości lub połączenia mogą nie zostać dostarczone do momentu ponownego połączenia urządzenia z siecią.
INVALID_MSISDN	Numer jest nieprawidłowy lub nie jest obecnie przypisany do żadnego abonenta w sieci komórkowej. Połączenia i wiadomości do tego numeru zakończą się niepowodzeniem.
UNDETERMINED	Nie można ustalić statusu łączności numeru. Może to wynikać z nieprawidłowego numeru, błędu odpowiedzi SS7 lub braku połączenia z docelowym operatorem sieci. Sprawdź kod błędu i pole opisu w celu uzyskania dodatkowych informacji diagnostycznych.

Przewiń w górę

POST/mnp-lookupchroniony

Wykonuje synchroniczne zapytanie MNP i dostarcza informacje o przenośności numerów oraz sieci komórkowej. Ten endpoint jest odpowiedni, jeśli Twoim głównym celem jest wyodrębnienie aktualnego MCCMNC danego numeru telefonu komórkowego oraz określenie oryginalnej i obecnej sieci w czasie rzeczywistym.

Do przetwarzania zbiorczego dużych zestawów danych, które nie wymagają natychmiastowych wyników, rozważ użycie asynchronicznego POST /mnp-lookups, który jest zoptymalizowany pod kątem szybkiego przetwarzania wsadowego.

Zapytania MNP w sposób niezawodny określają przenośność i informacje o sieci, ale nie wskazują, czy docelowy telefon komórkowy jest aktualnie podłączony do sieci i osiągalny. Aby uzyskać informacje o łączności na żywo, należy użyć endpointu POST /hlr-lookup.

Żądanie Odpowiedź Sukcesu Odpowiedź Błędu

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

Dane wejściowe

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

Parametry żądania

Klucz	Typ	Opis	Domyślnie	Wymagane
`msisdn`	string	Numer telefonu komórkowego (MSISDN) do sprawdzenia, podany w formacie międzynarodowym (np. +14156226819 lub 0014156226819). Kody krajów muszą być uwzględnione.	null	obowiązkowy
`route`	string(3)	Opcjonalny trzyliterowy identyfikator określający trasę dla tego zapytania. Ustaw na `null` lub pomiń ten parametr, aby zastosować swoją niestandardową mapę routingu lub pozwól naszemu systemowi automatycznie określić najlepszą trasę dla tego zapytania.	null	opcjonalnie
`storage`	string	Opcjonalny identyfikator przechowywania określający raport, w którym wyniki będą przechowywane do ręcznego przeglądu, analityki i raportowania. System automatycznie dodaje znacznik czasu z bieżącym miesiącem. Jeśli zostanie pominięty lub ustawiony na `null`, system automatycznie pogrupuje wyniki według miesięcy dla celów raportowania.	null	opcjonalnie

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

Atrybuty Odpowiedzi Sukcesu

Nazwa	Typ	Opis	Opcjonalny
`id`	string(12)	Unikalny 12-znakowy identyfikator dla tego zapytania.	false
`msisdn`	string	Numer telefonu komórkowego sprawdzony w tym zapytaniu.	false
`query_status`	string	Wskazuje, czy pobranie informacji o przenośności i sieci zakończyło się sukcesem. Możliwe wartości to `OK` lub `FAILED`.	false
`mccmnc`	string(5\|6)	Pięcio- lub sześcioznakowy kod MCCMNC (para kodu kraju mobilnego i kodu sieci mobilnej) identyfikujący sieć, do której aktualnie należy numer telefonu komórkowego.	true
`mcc`	string(3)	Trzycyfrowy kod MCC (kod kraju mobilnego) reprezentujący kraj powiązany z aktualną siecią numeru telefonu komórkowego.	true
`mnc`	string(2\|3)	Dwu- lub trzycyfrowy kod MNC (kod sieci mobilnej) identyfikujący aktualnego operatora sieci dla numeru telefonu komórkowego.	true
`is_ported`	boolean	Wskazuje, czy numer telefonu został przeniesiony z oryginalnej sieci do nowego operatora.	true
`original_network_name`	string	Dowolny ciąg znaków (w języku angielskim) określający nazwę oryginalnego operatora sieci sprawdzanego numeru telefonu komórkowego.	true
`original_country_name`	string	Dowolny ciąg znaków (w języku angielskim) wskazujący oryginalny kraj sprawdzanego numeru telefonu komórkowego.	true
`original_country_code`	string(2)	Dwuliterowy kod kraju ISO reprezentujący oryginalny kraj sprawdzanego numeru telefonu komórkowego.	true
`original_country_prefix`	string	Numer kierunkowy oryginalnego kraju powiązanego ze sprawdzanym numerem telefonu komórkowego.	true
`ported_network_name`	string	Określa operatora sieci, do którego sprawdzany numer telefonu komórkowego został przeniesiony, jeśli dotyczy.	true
`ported_country_name`	string	Określa kraj, do którego sprawdzany numer telefonu komórkowego został przeniesiony, jeśli dotyczy.	true
`ported_country_code`	string(2)	Dwuliterowy kod kraju ISO reprezentujący kraj, do którego sprawdzany numer telefonu komórkowego został przeniesiony, jeśli dotyczy.	true
`ported_country_prefix`	string	Numer kierunkowy kraju, do którego sprawdzany numer telefonu komórkowego został przeniesiony, jeśli dotyczy.	true
`extra`	string	Dowolny ciąg znaków zawierający opcjonalne dodatkowe informacje o numerze telefonu.	true
`cost`	string	Wartość dziesiętna, reprezentowana jako ciąg znaków, wskazująca koszt w EUR za to zapytanie.	true
`timestamp`	string	Znacznik czasu w formacie W3C, zawierający informację o strefie czasowej, wskazujący moment zakończenia zapytania.	true
`storage`	string	Nazwa magazynu (lub nazwa raportu), do której dołączono wyniki zapytania. Służy do pobierania plików CSV i raportowania przez interfejs webowy.	true
`route`	string(3)	Trzyliterowy identyfikator określający trasę użytą dla tego zapytania.	true
`error_code`	integer	Opcjonalny wewnętrzny kod błędu dostarczający dodatkowego kontekstu dla diagnostyki wsparcia klienta.	true

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

Parametry Odpowiedzi Błędu

Nazwa	Typ	Opis	Opcjonalny
`errors[]`	string[]	Lista ciągów tekstowych wyjaśniających błąd.	false

Przewiń w górę

POST/mnp-lookupschroniony

Inicjuje partię asynchronicznych zapytań MNP (przenoszenie numeru), pobierając aktualny MCCMNC i określając w czasie rzeczywistym pierwotną oraz obecną sieć operatora. Wyniki są dostarczane przez webhooks na Twój serwer. Ta metoda jest zoptymalizowana do przetwarzania dużych wolumenów numerów, które nie wymagają natychmiastowych odpowiedzi, takich jak czyszczenie i weryfikacja bazy danych. W przypadku aplikacji działających w czasie rzeczywistym, takich jak routing połączeń lub dostarczanie SMS, rozważ użycie punktu końcowego POST /mnp-lookup.

Zapytania MNP w sposób niezawodny określają przenośność i informacje o sieci, ale nie wskazują, czy docelowy telefon komórkowy jest aktualnie podłączony do sieci i osiągalny. Aby uzyskać informacje o łączności na żywo, należy użyć endpointu POST /hlr-lookups.

Przed użyciem tego punktu końcowego upewnij się, że skonfigurowany jest adres URL webhooka do asynchronicznego odbierania wyników zapytań. Możesz to skonfigurować w ustawieniach API.

Żądanie Odpowiedź Sukcesu Odpowiedź Błędu Webhooki

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

Dane wejściowe

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

Parametry żądania

Klucz	Typ	Opis	Domyślnie	Wymagane
`msisdns`	array	Tablica numerów telefonów komórkowych (MSISDN) w formacie międzynarodowym (np. +14156226819 lub 0014156226819). Możesz uwzględnić do 1000 numerów na żądanie.	null	obowiązkowy
`route`	string(3)	Opcjonalny trzyliterowy identyfikator określający trasę dla tego zapytania. Ustaw na `null` lub pomiń ten parametr, aby zastosować niestandardową mapę routingu lub pozwolić systemowi automatycznie określić najlepsze trasy dla tego żądania.	null	opcjonalnie
`storage`	string	Opcjonalny identyfikator przechowywania określający raport, w którym wyniki będą przechowywane do ręcznego przeglądu, analityki i raportowania. System automatycznie dodaje znacznik czasu z bieżącym miesiącem. Jeśli zostanie pominięty lub ustawiony na `null`, system automatycznie pogrupuje wyniki według miesięcy dla celów raportowania.	null	opcjonalnie

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

Atrybuty Odpowiedzi Sukcesu

Nazwa	Typ	Opis	Opcjonalny
`accepted`	array	Lista obiektów zawierających unikalne identyfikatory i numery MSISDN, które zostały zaakceptowane do przetwarzania.	false
`accepted_count`	integer	Całkowita liczba numerów MSISDN pomyślnie zaakceptowanych do przetwarzania.	false
`rejected`	array	Lista obiektów zawierających unikalne identyfikatory i numery MSISDN, które zostały odrzucone do przetwarzania, zazwyczaj z powodu nieprawidłowych numerów. Za odrzucone wpisy nie są naliczane opłaty.	false
`rejected_count`	integer	Całkowita liczba numerów MSISDN odrzuconych z powodu błędów walidacji.	false
`total_count`	integer	Całkowita liczba zaakceptowanych i odrzuconych numerów MSISDN, które zostały przesłane do przetwarzania.	false
`cost`	string	Wartość dziesiętna reprezentowana jako ciąg znaków, wskazująca całkowity koszt w EUR dla zaakceptowanych zapytań.	false
`storage`	string	Nazwa magazynu, w którym dodawane są wyniki zapytań, używana do raportowania i pobierania plików CSV przez interfejs webowy.	false
`route`	string(3)	Trzyliterowy identyfikator określający trasę użytą dla tego zapytania.	false
`webhook_urls`	array	Adresy URL webhooków skonfigurowane w ustawieniach API. Wyniki są tutaj odsyłane.	false

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

Parametry Odpowiedzi Błędu

Nazwa	Typ	Opis	Opcjonalny
`errors[]`	string[]	Lista ciągów tekstowych wyjaśniających błąd.	false

Przetwarzanie webhooków

Po przesłaniu nasz system rozpoczyna przetwarzanie podanych numerów telefonów i wysyła wyniki na wcześniej określony adres URL webhooka na Państwa serwerze. Wyniki są przesyłane jako żądanie HTTP POST z obiektem JSON w treści żądania.

Uwierzytelnianie

Uwierzytelnij webhook sprawdzając nagłówek HTTP X-Signatures.

Nagłówek X-Signatures zawiera listę sygnatur oddzielonych średnikami. Każda sygnatura na liście jest generowana przy użyciu jednego z sekretów API skonfigurowanych na Państwa koncie. Aby zweryfikować webhook, wygeneruj hash SHA-256 używając swojego klucza API, sekretu i surowej treści HTTP - następnie porównaj go z sygnaturami na liście.

Zgodność potwierdza, że żądanie jest autentyczne i podpisane sekretem, który kontrolujesz.

Przykład kodu

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

Żądanie jest prawidłowe, jeśli którakolwiek z sygnatur podanych w nagłówku jest równa hashowi SHA256 obliczonemu na podstawie połączonego ciągu Państwa klucza API, sekretu i treści HTTP.

Potwierdzanie odbioru

Państwa serwer powinien odpowiedzieć kodem statusu HTTP 200 OK, aby potwierdzić pomyślny odbiór. Jeśli zostanie zwrócony inny kod odpowiedzi, wystąpi przekroczenie czasu (10 sekund) lub pojawi się jakikolwiek inny problem z dostarczeniem, system automatycznie ponowi próbę dostarczenia webhooka po jednej minucie. Jeśli żądanie nadal kończy się niepowodzeniem, kolejne próby będą realizowane zgodnie ze strategią wykładniczego wycofywania, z następnymi próbami po 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minutach.

Ten mechanizm ponawiania zapewnia maksymalną niezawodność w dostarczaniu wyników wyszukiwania do Państwa infrastruktury. Minimalizuje ryzyko utraty danych z powodu tymczasowych problemów sieciowych lub przestojów serwera.

Dane webhooka

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

Atrybuty ładunku webhooka

Obiekt JSON zawiera atrybut type => MNP oraz atrybut results, który zawiera listę obiektów zapytań, zgodnie z dokumentacją poniżej.

Nazwa	Typ	Opis	Opcjonalny
`id`	string(12)	Unikalny 12-znakowy identyfikator dla tego zapytania.	false
`msisdn`	string	Numer telefonu komórkowego sprawdzony w tym zapytaniu.	false
`query_status`	string	Wskazuje, czy pobranie informacji o przenośności i sieci zakończyło się sukcesem. Możliwe wartości to `OK` lub `FAILED`.	false
`mccmnc`	string(5\|6)	Pięcio- lub sześcioznakowy kod MCCMNC (para kodu kraju mobilnego i kodu sieci mobilnej) identyfikujący sieć, do której aktualnie należy numer telefonu komórkowego.	true
`mcc`	string(3)	Trzycyfrowy kod MCC (kod kraju mobilnego) reprezentujący kraj powiązany z aktualną siecią numeru telefonu komórkowego.	true
`mnc`	string(2\|3)	Dwu- lub trzycyfrowy kod MNC (kod sieci mobilnej) identyfikujący aktualnego operatora sieci dla numeru telefonu komórkowego.	true
`is_ported`	boolean	Wskazuje, czy numer telefonu został przeniesiony z oryginalnej sieci do nowego operatora.	true
`original_network_name`	string	Dowolny ciąg znaków (w języku angielskim) określający nazwę oryginalnego operatora sieci sprawdzanego numeru telefonu komórkowego.	true
`original_country_name`	string	Dowolny ciąg znaków (w języku angielskim) wskazujący oryginalny kraj sprawdzanego numeru telefonu komórkowego.	true
`original_country_code`	string(2)	Dwuliterowy kod kraju ISO reprezentujący oryginalny kraj sprawdzanego numeru telefonu komórkowego.	true
`original_country_prefix`	string	Numer kierunkowy oryginalnego kraju powiązanego ze sprawdzanym numerem telefonu komórkowego.	true
`ported_network_name`	string	Określa operatora sieci, do którego sprawdzany numer telefonu komórkowego został przeniesiony, jeśli dotyczy.	true
`ported_country_name`	string	Określa kraj, do którego sprawdzany numer telefonu komórkowego został przeniesiony, jeśli dotyczy.	true
`ported_country_code`	string(2)	Dwuliterowy kod kraju ISO reprezentujący kraj, do którego sprawdzany numer telefonu komórkowego został przeniesiony, jeśli dotyczy.	true
`ported_country_prefix`	string	Numer kierunkowy kraju, do którego sprawdzany numer telefonu komórkowego został przeniesiony, jeśli dotyczy.	true
`extra`	string	Dowolny ciąg znaków zawierający opcjonalne dodatkowe informacje o numerze telefonu.	true
`cost`	string	Wartość dziesiętna, reprezentowana jako ciąg znaków, wskazująca koszt w EUR za to zapytanie.	true
`timestamp`	string	Znacznik czasu w formacie W3C, zawierający informację o strefie czasowej, wskazujący moment zakończenia zapytania.	true
`storage`	string	Nazwa magazynu (lub nazwa raportu), do której dołączono wyniki zapytania. Służy do pobierania plików CSV i raportowania przez interfejs webowy.	true
`route`	string(3)	Trzyliterowy identyfikator określający trasę użytą dla tego zapytania.	true
`error_code`	integer	Opcjonalny wewnętrzny kod błędu dostarczający dodatkowego kontekstu dla diagnostyki wsparcia klienta.	true

Przewiń w górę

POST/nt-lookupchroniony

Wykonuje synchroniczne zapytanie o typ numeru (NT). Ten endpoint jest idealny, jeśli Twoim głównym celem jest ustalenie w czasie rzeczywistym, czy podane numery telefonów należą do zakresów numeracji stacjonarnej, komórkowej, premium rate, VoIP, pagerów lub innych.

Zapytania NT wiarygodnie wykrywają typ numeru telefonu, jednak nie wskazują, czy docelowy numer jest aktualnie podłączony do sieci i osiągalny. Aby uzyskać informacje o aktualnej łączności, użyj endpointu POST /hlr-lookup.

Jeśli Twój przypadek użycia wymaga dokładnych informacji o sieci i przenośności (MCCMNC), ale nie wymaga statusu aktualnej łączności, użyj endpointu POST /mnp-lookup do zapytań o przenośność numerów komórkowych.

Żądanie Odpowiedź Sukcesu Odpowiedź Błędu Informacje o typach

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

Dane wejściowe

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

Parametry żądania

Klucz	Typ	Opis	Domyślnie	Wymagane
`number`	string	Numer telefonu w formacie międzynarodowym (np. +4989702626 lub 004989702626).	null	mandatory
`route`	string(3)	Opcjonalny trzyliterowy identyfikator określający trasę dla tego zapytania. Ustaw na `null` lub pomiń ten parametr, aby zastosować niestandardową mapę routingu lub pozwolić naszemu systemowi automatycznie określić najlepsze trasy dla tego żądania.	null	opcjonalnie
`storage`	string	Opcjonalny identyfikator przechowywania określający raport, w którym wyniki będą przechowywane do ręcznego przeglądu, analityki i raportowania. System automatycznie dodaje znacznik czasu z bieżącym miesiącem. Jeśli zostanie pominięty lub ustawiony na `null`, system automatycznie pogrupuje wyniki według miesięcy dla celów raportowania.	null	opcjonalnie

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

Atrybuty Odpowiedzi Sukcesu

Nazwa	Typ	Opis	Opcjonalny
`id`	string(12)	Unikalny identyfikator przypisany do tego zapytania.	false
`number`	string	Numer telefonu, który został oceniony podczas tego zapytania wyszukiwania.	false
`number_type`	string	Wykryty typ numeru. Możliwe wartości obejmują: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Wskazuje, czy informacja o typie numeru została pomyślnie uzyskana. Zwraca `OK` w przypadku sukcesu lub `FAILED`, jeśli wyszukiwanie nie powiodło się.	false
`is_valid`	boolean	Wskazuje, czy numer telefonu jest poprawny składniowo.	true
`invalid_reason`	string	Komunikat tekstowy w języku angielskim określający, dlaczego numer telefonu jest uznany za nieprawidłowy (np. "too short" lub "invalid prefix"), lub `null`, jeśli numer jest prawidłowy.	true
`is_possibly_ported`	boolean	Wskazuje, czy numer telefonu mógł zostać przeniesiony od pierwotnego operatora do innego dostawcy. Aby uzyskać ostateczne informacje o przenośności, użyj zapytań MNP.	true
`is_vanity_number`	boolean	Wskazuje, czy numer telefonu jest numerem mnemotechnicznym, czyli zawiera znaki alfabetyczne.	true
`qualifies_for_hlr_lookup`	boolean	Wskazuje, czy numer telefonu kwalifikuje się do dodatkowych zapytań za pomocą zapytań HLR.	true
`mccmnc`	string(5\|6)	Pięcio- lub sześcioznakowy ciąg reprezentujący krotkę MCCMNC (kod kraju mobilnego i kod sieci mobilnej), który identyfikuje pierwotną sieć numeru telefonu komórkowego.	true
`mcc`	string(3)	Trzyznakowy ciąg reprezentujący MCC (kod kraju mobilnego), który identyfikuje kraj powiązany z pierwotną siecią mobilną numeru telefonu.	true
`mnc`	string(2\|3)	Dwu- lub trzyznakowy ciąg reprezentujący MNC (kod sieci mobilnej), który identyfikuje pierwotnego operatora sieci mobilnej numeru telefonu.	true
`original_network_name`	string	Dowolny ciąg tekstowy w języku angielskim określający nazwę pierwotnego operatora sieci sprawdzanego numeru telefonu komórkowego.	true
`original_country_name`	string	Dowolny ciąg tekstowy w języku angielskim określający pierwotny kraj powiązany ze sprawdzanym numerem telefonu komórkowego.	true
`original_country_code`	string(2)	Dwuznakowy kod kraju ISO wskazujący pierwotny kraj sprawdzanego numeru telefonu komórkowego.	true
`regions`	array	Lista czytelnych dla człowieka ciągów w języku angielskim, które określają region(-y) geograficzny(-e) powiązany(-e) z tym numerem telefonu.	true
`timezones`	array	Lista stref czasowych (w formacie Olson) powiązanych z tym numerem telefonu.	true
`info_text`	string	Dowolny ciąg, który może zawierać dodatkowe informacje o numerze telefonu.	true
`cost`	string	Wartość dziesiętna reprezentowana jako ciąg, wskazująca koszt (w EUR) tego wyszukiwania.	true
`timestamp`	string	Znacznik czasu w formacie W3C (zawierający strefę czasową) wskazujący, kiedy wyszukiwanie zostało zakończone.	true
`storage`	string	Określa nazwę magazynu, do którego zostały dołączone wyniki wyszukiwania. Odpowiada to nazwie raportu używanej do pobierania plików CSV i analityki przez interfejs webowy.	true
`route`	string(3)	Trzyliterowy identyfikator określający trasę użytą dla tego zapytania.	true

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

Parametry Odpowiedzi Błędu

Nazwa	Typ	Opis	Opcjonalny
`errors[]`	string[]	Lista ciągów tekstowych wyjaśniających błąd.	false

Typ	Opis
LANDLINE	Numer telefonu stacjonarnego.
MOBILE	Numer telefonu komórkowego. Kwalifikuje się do zapytań HLR w celu uzyskania dodatkowych informacji o statusie połączenia, sieci, przenośności numeru i roamingu.
MOBILE_OR_LANDLINE	Numer telefonu stacjonarnego lub komórkowego. Może kwalifikować się do zapytania HLR.
TOLL_FREE	Numer infolinii bezpłatnej.
PREMIUM_RATE	Numer telefonu premium z dodatkowymi opłatami.
SHARED_COST	Numer telefonu o współdzielonych kosztach. Zazwyczaj tańszy niż numery premium.
VOIP	Numer telefonu Voice over IP. Obejmuje numery TSoIP (Telephony Service over IP).
PAGER	Numer pagera. Zazwyczaj bez funkcji głosowych.
UAN	Uniwersalny Numer Dostępu (Numer Firmowy). Może być kierowany do konkretnych biur, ale umożliwia używanie jednego numeru dla całej firmy.
VOICEMAIL	Numer poczty głosowej.
UNKNOWN	Nie udało się określić typu numeru.

Przewiń w górę

POST/nt-lookups chroniony

Ten endpoint uruchamia serię asynchronicznych zapytań o typ numeru z wynikami przesyłanymi z powrotem na Twój serwer przez webhook. Jest odpowiedni, jeśli Twoim głównym celem jest ustalenie, czy podane numery telefonów należą do zakresów numeracji stacjonarnej, komórkowej, premium rate, VoIP, pager lub innych. Zoptymalizowany pod kątem szybkiego przetwarzania dużych wolumenów numerów, ten endpoint jest idealny do operacji masowych (np. czyszczenia bazy danych). W przypadku ruchu na żywo i zastosowań krytycznych czasowo prosimy użyć endpointu POST /nt-lookup.

Musisz określić adres URL webhooka w swoich ustawieniach API jako warunek wstępny wywołania tego endpointu.

Żądanie Odpowiedź Sukcesu Odpowiedź Błędu Webhooki Informacje o typach

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

Dane wejściowe

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

Parametry żądania

Klucz	Typ	Opis	Domyślnie	Wymagane
`numbers`	array	Tablica numerów telefonów w formacie międzynarodowym (np. +14156226819 lub 004989702626). Maksymalnie 1000 numerów można uwzględnić w jednym żądaniu.	null	obowiązkowy
`route`	string(3)	Opcjonalny trzyliterowy identyfikator określający trasę dla tego zapytania. Ustaw na `null` lub pomiń ten parametr, aby zastosować swoją niestandardową mapę routingu lub pozwól naszemu systemowi automatycznie określić najlepszą trasę dla tego żądania.	null	opcjonalnie
`storage`	string	Opcjonalny identyfikator przechowywania określający raport, w którym wyniki będą przechowywane do ręcznego przeglądu, analityki i raportowania. System automatycznie dodaje znacznik czasu z bieżącym miesiącem. Jeśli zostanie pominięty lub ustawiony na `null`, system automatycznie pogrupuje wyniki według miesięcy dla celów raportowania.	null	opcjonalnie

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

Atrybuty Odpowiedzi Sukcesu

Nazwa	Typ	Opis	Opcjonalny
`accepted`	array	Tablica obiektów, z których każdy zawiera unikalny identyfikator i numer telefonu zaakceptowany do przetworzenia.	false
`accepted_count`	integer	Całkowita liczba numerów telefonów zaakceptowanych do przetworzenia.	false
`rejected`	array	Tablica obiektów, z których każdy zawiera unikalny identyfikator i numer telefonu odrzucony do przetworzenia. Zazwyczaj są to numery nieprawidłowe i nie są naliczane opłaty.	false
`rejected_count`	integer	Całkowita liczba numerów telefonów odrzuconych do przetworzenia.	false
`total_count`	integer	Całkowita liczba zaakceptowanych i odrzuconych numerów telefonów przesłanych do przetworzenia.	false
`cost`	string	Ciąg znaków reprezentujący wartość dziesiętną wskazującą koszt w EUR dla tych zapytań.	false
`storage`	string	Nazwa magazynu (raportu), do którego dołączono wyniki zapytań. Ta nazwa jest używana do pobierania plików CSV i analiz przez interfejs webowy.	false
`route`	string(3)	Trzyliterowy identyfikator określający trasę użytą dla tego żądania zapytania.	false
`webhook_urls`	array	Adresy URL webhooków skonfigurowane w ustawieniach API. Wyniki są tutaj odsyłane.	false

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

Parametry Odpowiedzi Błędu

Nazwa	Typ	Opis	Opcjonalny
`errors[]`	string[]	Lista ciągów tekstowych wyjaśniających błąd.	false

Przetwarzanie webhooków

Po przesłaniu nasz system rozpoczyna przetwarzanie podanych numerów telefonów i wysyła wyniki na wcześniej określony adres URL webhooka na Państwa serwerze. Wyniki są przesyłane jako żądanie HTTP POST z obiektem JSON w treści żądania.

Uwierzytelnianie

Uwierzytelnij webhook sprawdzając nagłówek HTTP X-Signatures.

Nagłówek X-Signatures zawiera listę sygnatur oddzielonych średnikami. Każda sygnatura na liście jest generowana przy użyciu jednego z sekretów API skonfigurowanych na Państwa koncie. Aby zweryfikować webhook, wygeneruj hash SHA-256 używając swojego klucza API, sekretu i surowej treści HTTP - następnie porównaj go z sygnaturami na liście.

Zgodność potwierdza, że żądanie jest autentyczne i podpisane sekretem, który kontrolujesz.

Przykład kodu

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

Żądanie jest prawidłowe, jeśli którakolwiek z sygnatur podanych w nagłówku jest równa hashowi SHA256 obliczonemu na podstawie połączonego ciągu Państwa klucza API, sekretu i treści HTTP.

Potwierdzanie odbioru

Państwa serwer powinien odpowiedzieć kodem statusu HTTP 200 OK, aby potwierdzić pomyślny odbiór. Jeśli zostanie zwrócony inny kod odpowiedzi, wystąpi przekroczenie czasu (10 sekund) lub pojawi się jakikolwiek inny problem z dostarczeniem, system automatycznie ponowi próbę dostarczenia webhooka po jednej minucie. Jeśli żądanie nadal kończy się niepowodzeniem, kolejne próby będą realizowane zgodnie ze strategią wykładniczego wycofywania, z następnymi próbami po 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minutach.

Ten mechanizm ponawiania zapewnia maksymalną niezawodność w dostarczaniu wyników wyszukiwania do Państwa infrastruktury. Minimalizuje ryzyko utraty danych z powodu tymczasowych problemów sieciowych lub przestojów serwera.

Dane webhooka

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

Atrybuty ładunku webhooka

Obiekt JSON zawiera atrybut type => NT oraz atrybut results, który zawiera listę obiektów zapytań, zgodnie z dokumentacją poniżej.

Nazwa	Typ	Opis	Opcjonalny
`id`	string(12)	Unikalny identyfikator przypisany do tego zapytania.	false
`number`	string	Numer telefonu, który został oceniony podczas tego zapytania wyszukiwania.	false
`number_type`	string	Wykryty typ numeru. Możliwe wartości obejmują: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Wskazuje, czy informacja o typie numeru została pomyślnie uzyskana. Zwraca `OK` w przypadku sukcesu lub `FAILED`, jeśli wyszukiwanie nie powiodło się.	false
`is_valid`	boolean	Wskazuje, czy numer telefonu jest poprawny składniowo.	true
`invalid_reason`	string	Komunikat tekstowy w języku angielskim określający, dlaczego numer telefonu jest uznany za nieprawidłowy (np. "too short" lub "invalid prefix"), lub `null`, jeśli numer jest prawidłowy.	true
`is_possibly_ported`	boolean	Wskazuje, czy numer telefonu mógł zostać przeniesiony od pierwotnego operatora do innego dostawcy. Aby uzyskać ostateczne informacje o przenośności, użyj zapytań MNP.	true
`is_vanity_number`	boolean	Wskazuje, czy numer telefonu jest numerem mnemotechnicznym, czyli zawiera znaki alfabetyczne.	true
`qualifies_for_hlr_lookup`	boolean	Wskazuje, czy numer telefonu kwalifikuje się do dodatkowych zapytań za pomocą zapytań HLR.	true
`mccmnc`	string(5\|6)	Pięcio- lub sześcioznakowy ciąg reprezentujący krotkę MCCMNC (kod kraju mobilnego i kod sieci mobilnej), który identyfikuje pierwotną sieć numeru telefonu komórkowego.	true
`mcc`	string(3)	Trzyznakowy ciąg reprezentujący MCC (kod kraju mobilnego), który identyfikuje kraj powiązany z pierwotną siecią mobilną numeru telefonu.	true
`mnc`	string(2\|3)	Dwu- lub trzyznakowy ciąg reprezentujący MNC (kod sieci mobilnej), który identyfikuje pierwotnego operatora sieci mobilnej numeru telefonu.	true
`original_network_name`	string	Dowolny ciąg tekstowy w języku angielskim określający nazwę pierwotnego operatora sieci sprawdzanego numeru telefonu komórkowego.	true
`original_country_name`	string	Dowolny ciąg tekstowy w języku angielskim określający pierwotny kraj powiązany ze sprawdzanym numerem telefonu komórkowego.	true
`original_country_code`	string(2)	Dwuznakowy kod kraju ISO wskazujący pierwotny kraj sprawdzanego numeru telefonu komórkowego.	true
`regions`	array	Lista czytelnych dla człowieka ciągów w języku angielskim, które określają region(-y) geograficzny(-e) powiązany(-e) z tym numerem telefonu.	true
`timezones`	array	Lista stref czasowych (w formacie Olson) powiązanych z tym numerem telefonu.	true
`info_text`	string	Dowolny ciąg, który może zawierać dodatkowe informacje o numerze telefonu.	true
`cost`	string	Wartość dziesiętna reprezentowana jako ciąg, wskazująca koszt (w EUR) tego wyszukiwania.	true
`timestamp`	string	Znacznik czasu w formacie W3C (zawierający strefę czasową) wskazujący, kiedy wyszukiwanie zostało zakończone.	true
`storage`	string	Określa nazwę magazynu, do którego zostały dołączone wyniki wyszukiwania. Odpowiada to nazwie raportu używanej do pobierania plików CSV i analityki przez interfejs webowy.	true
`route`	string(3)	Trzyliterowy identyfikator określający trasę użytą dla tego zapytania.	true

Typ	Opis
LANDLINE	Numer telefonu stacjonarnego.
MOBILE	Numer telefonu komórkowego. Kwalifikuje się do zapytań HLR w celu uzyskania dodatkowych informacji o statusie połączenia, sieci, przenośności numeru i roamingu.
MOBILE_OR_LANDLINE	Numer telefonu stacjonarnego lub komórkowego. Może kwalifikować się do zapytania HLR.
TOLL_FREE	Numer infolinii bezpłatnej.
PREMIUM_RATE	Numer telefonu premium z dodatkowymi opłatami.
SHARED_COST	Numer telefonu o współdzielonych kosztach. Zazwyczaj tańszy niż numery premium.
VOIP	Numer telefonu Voice over IP. Obejmuje numery TSoIP (Telephony Service over IP).
PAGER	Numer pagera. Zazwyczaj bez funkcji głosowych.
UAN	Uniwersalny Numer Dostępu (Numer Firmowy). Może być kierowany do konkretnych biur, ale umożliwia używanie jednego numeru dla całej firmy.
VOICEMAIL	Numer poczty głosowej.
UNKNOWN	Nie udało się określić typu numeru.

Przewiń w górę

GET/routechroniony

Pobiera trasę, która zostanie automatycznie wybrana podczas wykonywania zapytania HLR bez określania parametru route.

Automatyczny wybór trasy opiera się na mapie routingu dostępnej za pomocą endpointu GET /hlr-coverage, która jest głównie pochodną GET /routing-map. Możesz dostosować swoją mapę routingu i zdefiniować niestandardowe reguły w ustawieniach konta.

Żądanie Odpowiedź Sukcesu Odpowiedź Błędu

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

Parametry żądania

Klucz	Typ	Opis	Domyślnie	Wymagane
`msisdn`	string	Numer MSISDN, dla którego należy pobrać automatycznie wybrane informacje o routingu.	null	obowiązkowy

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

Atrybuty Odpowiedzi Sukcesu

Nazwa	Typ	Opis	Opcjonalny
`route`	string	Rekomendowana trasa.	false
`confidence_level`	string	Poziom pewności, z jakim wybrano tę trasę, tj. `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`.	false
`mccmnc`	string	MCCMNC oparte na planie numeracyjnym dla tego numeru.	false
`origin`	string	Źródło, na którym opiera się decyzja routingowa, 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 Odpowiedzi Błędu

Nazwa	Typ	Opis	Opcjonalny
`errors[]`	string[]	Lista ciągów tekstowych wyjaśniających błąd.	false

Przewiń w górę

GET/routeschroniony

Ten endpoint zwraca listę dostępnych tras HLR, MNP i NT. Każda trasa, wraz z jej funkcjami i ograniczeniami, jest wyjaśniona na stronie szczegóły routingu.

Żądanie Odpowiedź Sukcesu Odpowiedź Błędu

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

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

Atrybuty Odpowiedzi Sukcesu

Nazwa	Typ	Opis	Opcjonalny
`routes`	object	Obiekt z trasami pogrupowanymi według typu trasy.	false
`HLR\|MNP\|NT`	string[]	Zawiera listę identyfikatorów tras.	false

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

Parametry Odpowiedzi Błędu

Nazwa	Typ	Opis	Opcjonalny
`errors[]`	string[]	Lista ciągów tekstowych wyjaśniających błąd.	false

Przewiń w górę

GET/routing-mapchroniony

Pobiera aktualnie stosowaną konfigurację automatycznego routingu dla zapytań HLR w Twoim koncie. Ta domyślna konfiguracja jest używana za każdym razem, gdy wysyłasz zapytania HLR bez określenia parametru route. Możesz dostosować mapę routingu i utworzyć niestandardowe reguły w ustawieniach konta.

Hierarchia konfiguracji kaskadowo przechodzi od reguł na poziomie kraju do reguł na poziomie MCCMNC, a następnie do mapowań poszczególnych prefiksów numerów telefonów. W praktyce oznacza to, że mapowania poszczególnych prefiksów numerów telefonów mają pierwszeństwo przed sprzecznymi przypisaniami MCCMNC, które z kolei nadpisują reguły na poziomie kraju. Należy pamiętać, że zapasowy routing MNP nadpisuje wszelkie sprzeczne reguły niestandardowe, gdy jest włączony.

Żądanie Odpowiedź Sukcesu Odpowiedź Błędu

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

Atrybuty Odpowiedzi Sukcesu

Nazwa	Typ	Opis	Opcjonalny
`default_route`	string	Domyślna trasa używana, gdy nie można określić preferowanej opcji routingu dla numeru MSISDN i nie mają zastosowania żadne niestandardowe reguły routingu.	false
`mnp_fallback`	boolean	Wskazuje, czy zapasowy routing MNP jest włączony. Gdy jest włączony i zapytania HLR nie są obsługiwane przez sieć (status łączności niedostępny), system wykona zamiast tego zapytanie MNP.	false
`mccmncs`	array	Mapowanie kodów MCCMNC do automatycznie wybranych tras. Podczas wykonywania zapytania HLR dla numeru w danym MCCMNC używana jest odpowiadająca mu trasa.	false
`mccmnc`	string(5\|6)	Pięcio- lub sześcioznakowy MCCMNC (kombinacja kodu kraju mobilnego i kodu sieci mobilnej) identyfikujący operatora sieci komórkowej.	false
`countrycode`	string(2)	Dwuznakowy kod kraju ISO identyfikujący kraj sieci.	false
`route`	string(3)	Wybrana trasa dla sieci.	false
`mno`	string	Marka konsumencka, pod którą działa ta sieć.	false
`confidence`	string	Poziom pewności, z jakim dokonano wyboru. Możliwe wartości to: HIGH, NORMAL, LOW, MNP_REDIRECT. W przypadku tej ostatniej system przekierowuje ruch do tej sieci na MNP, jeśli to zachowanie jest włączone w Twoim koncie. W przeciwnym razie używa domyślnej trasy w koncie.	false
`origin`	string	Źródło, na podstawie którego dokonano wyboru. Możliwe wartości to: `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	Lista niestandardowych reguł routingu opartych na prefiksach skonfigurowanych w Twoim koncie, jeśli istnieją.	false
`countrycode`	string(2)	Dwuznakowy kod kraju ISO identyfikujący kraj prefiksu.	false
`cns`	string	Prefiks, do którego ma zastosowanie reguła routingu.	false
`route`	string(3)	Wybrana trasa dla prefiksu.	false
`mccmnc`	string(5\|6)	Pięcio- lub sześcioznakowy MCCMNC (kombinacja kodu kraju mobilnego i kodu sieci mobilnej) identyfikujący operatora sieci komórkowej.	true
`mno`	string	Marka konsumencka, pod którą działa ta sieć.	true
`countries`	array	Lista niestandardowych reguł opartych na krajach skonfigurowanych w Twoim koncie, jeśli istnieją.	false
`countrycode`	string(2)	Dwuznakowy kod kraju ISO identyfikujący kraj.	false
`route`	string(3)	Wybrana trasa dla kraju.	false

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

Parametry Odpowiedzi Błędu

Nazwa	Typ	Opis	Opcjonalny
`errors[]`	string[]	Lista ciągów tekstowych wyjaśniających błąd.	false

Przewiń w górę

GET/hlr-coverage chroniony

Zwraca szczegółowe informacje o zasięgu HLR, wspierając podejmowanie decyzji opartych na danych. Ten endpoint pomaga analizować opcje routingu HLR w czasie rzeczywistym w sieciach komórkowych, identyfikować najbardziej efektywne ścieżki dla docelowych regionów oraz konfigurować automatyczny routing.

Rekomendowane trasy z GET /route są oparte na danych o zasięgu pobieranych w tym miejscu. Dane o zasięgu są również dostępne na stronie zasięg sieci. Możesz dodatkowo dostosować mapę routingu i zdefiniować reguły w ustawieniach konta.

Zalecamy zapoznanie się z tym przewodnikiem, który pomoże w interpretacji wyników.

Żądanie Odpowiedź Sukcesu Odpowiedź Błędu Informacje o statusach

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

Parametry żądania

Klucz	Typ	Opis	Domyślnie	Wymagane
`countrycode`	string(2)	Wymagany dwuliterowy kod kraju ISO używany do filtrowania wyników, zwracający tylko rekordy powiązane z określonym krajem.	null	obowiązkowy
`sample_size`	string	Opcjonalny parametr określający wielkość próbki. Możliwe wartości to `LARGE`, `MEDIUM`, `SMALL`. Większe próbki obejmują dłuższy okres czasu, mniejsze próbki obejmują bardzo niedawny okres czasu.	LARGE	opcjonalnie

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

Atrybuty Odpowiedzi Sukcesu

Nazwa	Typ	Opis	Opcjonalny
`name`	string	Nazwa wybranego kraju w języku angielskim.	false
`countrycode`	string(2)	Dwuznakowy kod kraju ISO wybranego kraju.	false
`prefix`	string	Międzynarodowy prefiks wybranego kraju.	false
`mccs`	string[]	Lista kodów MCC (mobile country code) powiązanych z wybranym krajem.	false
`carriers`	object[]	Lista obiektów operatorów z metrykami łączności specyficznymi dla tras.	false
`mno`	string	Nazwa operatora sieci komórkowej w języku angielskim.	false
`mccmnc`	string	MCCMNC operatora sieci komórkowej.	false
`mcc`	string	MCC (mobile country code) operatora sieci komórkowej.	false
`mnc`	string	MNC (mobile network code) operatora sieci komórkowej.	false
`routes`	object[]	Lista wyników łączności specyficznych dla tras.	false
`route`	string	Trasa, do której odnoszą się informacje o łączności.	false
`selected`	bool	Wskazuje, czy jest to wybrana trasa dla automatycznego routingu.	false
`selection_confidence`	string	Poziom pewności, z jakim wybrano tę trasę, tj. `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`. Zawiera null, jeśli nie jest to wybrana trasa.	true
`n`	int	Całkowita liczba zapytań w tej próbce.	false
`CONNECTED`	int	Liczba zapytań HLR, które zwróciły status CONNECTED.	false
`CONNECTED_PCT`	float	Procent zapytań HLR, które zwróciły status CONNECTED.	false
`ABSENT`	int	Liczba zapytań HLR, które zwróciły status ABSENT.	false
`ABSENT_PCT`	float	Procent zapytań HLR, które zwróciły status ABSENT.	false
`INVALID_MSISDN`	int	Liczba zapytań HLR, które zwróciły status INVALID_MSISDN.	false
`INVALID_MSISDN_PCT`	float	Procent zapytań HLR, które zwróciły status INVALID_MSISDN.	false
`UNDETERMINED`	int	Liczba zapytań HLR, które zwróciły status UNDETERMINED.	false
`UNDETERMINED_PCT`	float	Procent zapytań HLR, które zwróciły status UNDETERMINED.	false

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

Parametry Odpowiedzi Błędu

Nazwa	Typ	Opis	Opcjonalny
`errors[]`	string[]	Lista ciągów tekstowych wyjaśniających błąd.	false

Status	Opis
CONNECTED	Numer jest prawidłowy, a docelowe urządzenie jest obecnie podłączone do sieci komórkowej. Połączenia, wiadomości SMS i inne usługi powinny dotrzeć do odbiorcy bez problemu.
ABSENT	Numer jest prawidłowy, ale docelowe urządzenie jest wyłączone lub tymczasowo poza zasięgiem sieci. Wiadomości lub połączenia mogą nie zostać dostarczone do momentu ponownego połączenia urządzenia z siecią.
INVALID_MSISDN	Numer jest nieprawidłowy lub nie jest obecnie przypisany do żadnego abonenta w sieci komórkowej. Połączenia i wiadomości do tego numeru zakończą się niepowodzeniem.
UNDETERMINED	Nie można ustalić statusu łączności numeru. Może to wynikać z nieprawidłowego numeru, błędu odpowiedzi SS7 lub braku połączenia z docelowym operatorem sieci. Sprawdź kod błędu i pole opisu w celu uzyskania dodatkowych informacji diagnostycznych.

Przewiń w górę

GET/mnp-coveragechroniony

Ten endpoint zwraca listę operatorów sieci komórkowych wraz z odpowiadającymi im identyfikatorami MCCMNC, które są obecnie obsługiwane w zakresie wyszukiwania przeniesienia numerów.

Żądanie Odpowiedź Sukcesu Odpowiedź Błędu

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

Parametry żądania

Klucz	Typ	Opis	Domyślnie	Wymagane
`countrycode`	string(2)	Opcjonalny dwuliterowy kod kraju ISO używany do filtrowania wyników MCCMNC, zwracający tylko dane dotyczące określonego kraju.	null	opcjonalnie

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

Atrybuty Odpowiedzi Sukcesu

Nazwa	Typ	Opis	Opcjonalny
`items[]`	array	Lista operatorów sieci komórkowych.	false
`country_name`	string	Nazwa kraju w języku angielskim.	false
`country_code`	string(2)	Dwuliterowy kod kraju ISO.	false
`mccmnc`	string(5\|6)	Pięcio- lub sześcioznakowy MCCMNC (kombinacja kodu kraju mobilnego i kodu sieci mobilnej) identyfikujący operatora sieci komórkowej.	false
`mcc`	string(3)	Trzycyfrowy MCC (kod kraju mobilnego) reprezentujący kraj sieci.	false
`mnc`	string(2\|3)	Dwu- lub trzycyfrowy MNC (kod sieci mobilnej) reprezentujący konkretnego operatora sieci komórkowej.	false
`brand`	string	Marka konsumencka, pod którą działa ta sieć.	true
`operator`	string	Pełna nazwa prawna operatora sieci komórkowej.	true

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

Parametry Odpowiedzi Błędu

Nazwa	Typ	Opis	Opcjonalny
`errors[]`	string[]	Lista ciągów tekstowych wyjaśniających błąd.	false

Przewiń w górę

GET/price-listchroniony

Ten endpoint zwraca listę krajów, w których obsługiwane są wyłącznie zapytania MNP, a zapytania HLR są niedostępne dla tych destynacji.

Żądanie Odpowiedź Sukcesu Odpowiedź Błędu

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

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

Atrybuty Odpowiedzi Sukcesu

Nazwa	Typ	Opis	Opcjonalny
`countries`	string[]	Lista dwuznakowych kodów krajów ISO.	false

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

Parametry Odpowiedzi Błędu

Nazwa	Typ	Opis	Opcjonalny
`errors[]`	string[]	Lista ciągów tekstowych wyjaśniających błąd.	false

Przewiń w górę

GET/mccmncschroniony

Ten endpoint zwraca kompleksową listę operatorów sieci komórkowych wraz z odpowiadającymi im identyfikatorami MCCMNC oraz dodatkowymi informacjami kontekstowymi.

Żądanie Odpowiedź Sukcesu Odpowiedź Błędu

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

Parametry żądania

Klucz	Typ	Opis	Domyślnie	Wymagane
`countrycode`	string(2)	Opcjonalny dwuliterowy kod kraju ISO używany do filtrowania wyników MCCMNC, zwracający tylko rekordy powiązane z określonym krajem.	null	opcjonalnie

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

Atrybuty Odpowiedzi Sukcesu

Nazwa	Typ	Opis	Opcjonalny
`items`	object[]	Lista operatorów sieci komórkowych.	false
`country_name`	string	Pełna nazwa kraju w języku angielskim.	false
`country_code`	string(2)	Dwuliterowy kod kraju ISO reprezentujący kraj operatora sieci komórkowej.	false
`mccmnc`	string(5\|6)	Pięcio- lub sześcioznakowy ciąg reprezentujący MCCMNC, który jednoznacznie identyfikuje operatora sieci komórkowej.	false
`mcc`	string(3)	Trzycyfrowy kod kraju mobilnego (MCC), który identyfikuje kraj, w którym działa sieć komórkowa.	false
`mnc`	string(2\|3)	Dwu- lub trzycyfrowy kod sieci komórkowej (MNC), który określa sieć komórkową w ramach danego MCC.	false
`brand`	string	Komercyjna nazwa marki, pod którą sieć działa i jest rozpoznawana przez konsumentów.	true
`operator`	string	Oficjalna nazwa operatora sieci komórkowej, zazwyczaj podmiotu prawnego zarządzającego siecią.	true
`parent_mccmnc`	string(5\|6)	Pięcio- lub sześcioznakowy ciąg reprezentujący MCCMNC nadrzędnego operatora sieci komórkowej, jeśli istnieje.	true

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

Parametry Odpowiedzi Błędu

Nazwa	Typ	Opis	Opcjonalny
`errors[]`	string[]	Lista ciągów tekstowych wyjaśniających błąd.	false

Przewiń w górę

GET/pricechroniony

Ten endpoint zwraca cenę za zapytanie HLR, MNP lub NT.

Żądanie Odpowiedź Sukcesu Odpowiedź Błędu

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

Parametry żądania

Klucz	Typ	Opis	Domyślnie	Wymagane
`msisdn`	string	Numer telefonu, dla którego ma zostać pobrana cena. W formacie międzynarodowym.	null	obowiązkowy
`route_type`	string	Typ trasy, tj. `HLR`, `MNP`, `NT`.	null	obowiązkowy
`route`	string(3)	Trasa, dla której powinna zostać obliczona cena. Domyślnie trasa określona przez automatyczny routing.	null	opcjonalnie

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

Atrybuty Odpowiedzi Sukcesu

Nazwa	Typ	Opis	Opcjonalny
`price`	object	Obiekt ze szczegółami cenowymi.	false
`amount`	string	Kwota w EUR.	false
`msisdn`	string	MSISDN, dla którego obowiązuje ta cena.	false
`route_type`	string(2\|3)	Typ trasy, dla którego obowiązuje ta cena.	false
`route`	string(3)	Trasa, dla której obowiązuje ta cena.	false

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

Parametry Odpowiedzi Błędu

Nazwa	Typ	Opis	Opcjonalny
`errors[]`	string[]	Lista ciągów tekstowych wyjaśniających błąd.	false

Przewiń w górę

GET/price-listchroniony

Ten endpoint zwraca cennik obowiązujący na Twoim koncie.

Żądanie Odpowiedź Sukcesu Odpowiedź Błędu

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

Atrybuty Odpowiedzi Sukcesu

Nazwa	Typ	Opis	Opcjonalny
`pricing`	object[]	Lista obiektów z informacjami o cenach.	false
`route`	string	Trasa, do której odnosi się ten cennik.	false
`countrycode`	string	Dwuznakowy kod kraju ISO, do którego odnosi się ten cennik dla odpowiedniej trasy, jeśli dotyczy.	true
`countryname`	string	Angielska nazwa kraju odpowiadająca kodowi kraju, jeśli dotyczy.	true
`mccmnc`	string	MCCMNC, do którego odnosi się ten cennik dla odpowiedniej trasy, jeśli dotyczy. Nadpisuje cennik na poziomie kraju.	true
`cns`	string	Prefiks wybierania, do którego odnosi się ten cennik dla odpowiedniej trasy, jeśli dotyczy. Nadpisuje cennik na poziomie kraju i MCCMNC.	true
`route_type`	string	Odpowiadający typ trasy, tj. `HLR`, `MNP`, `NT`.	false
`route_type`	string	Odpowiadająca cena w EUR.	false

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

Parametry Odpowiedzi Błędu

Nazwa	Typ	Opis	Opcjonalny
`errors[]`	string[]	Lista ciągów tekstowych wyjaśniających błąd.	false

Przewiń w górę

GET/balancechroniony

Ten endpoint pobiera aktualny stan konta, umożliwiając automatyzację procesów w oparciu o status kredytu. Działa bezproblemowo z powiadomieniami e-mail o niskim stanie konta, które można skonfigurować na stronie płatności.

Żądanie Odpowiedź Sukcesu Odpowiedź Błędu

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

{
    "balance":"1002.90"
}

Atrybuty Odpowiedzi Sukcesu

Nazwa	Typ	Opis	Opcjonalny
`balance`	string	Aktualny stan konta w EUR. Wartość dziesiętna typu string.	false

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

Parametry Odpowiedzi Błędu

Nazwa	Typ	Opis	Opcjonalny
`errors[]`	string[]	Lista ciągów tekstowych wyjaśniających błąd.	false

Przewiń w górę

GET/pingpubliczny

Ten endpoint wysyła żądanie ping do API, zapewniając prostą metodę testowania połączenia z API HLR Lookups.

Żądanie Odpowiedź Sukcesu Odpowiedź Błędu

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

{
    "success":true
}

Atrybuty Odpowiedzi Sukcesu

Nazwa	Typ	Opis	Opcjonalny
`success`	boolean	Wskazuje, że żądanie zostało przetworzone pomyślnie.	false

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

Parametry Odpowiedzi Błędu

Nazwa	Typ	Opis	Opcjonalny
`errors[]`	string[]	Lista ciągów tekstowych wyjaśniających błąd.	false

Przewiń w górę

GET/timepubliczny

Ten endpoint zwraca znacznik czasu Unix reprezentujący aktualny czas na serwerze HLR Lookups. Użyj go do synchronizacji zegara swojego serwera podczas generowania podpisu Digest-Auth do uwierzytelnienia, zapewniając skorygowanie wszelkich rozbieżności między czasem Twojego serwera a czasem serwera HLR Lookups.

Żądanie Odpowiedź Sukcesu Odpowiedź Błędu

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

{
    "time":1525898643
}

Atrybuty Odpowiedzi Sukcesu

Nazwa	Typ	Opis	Opcjonalny
`time`	integer	Znacznik czasu Unix reprezentujący aktualny czas serwera HLR Lookups.	false

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

Parametry Odpowiedzi Błędu

Nazwa	Typ	Opis	Opcjonalny
`errors[]`	string[]	Lista ciągów tekstowych wyjaśniających błąd.	false

Przewiń w górę

GET/auth-testchroniony

Ten endpoint służy jako wstępny test implementacji Basic-Auth lub, preferowane, Digest-Auth.

Żądanie Basic Auth Żądanie Digest Auth Odpowiedź Sukcesu Odpowiedź Błędu

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

Nagłówki żądania

Klucz	Typ	Opis
`X-Basic`	string	Hash SHA256 z `YOUR_API_KEY:YOUR_API_SECRET`. Uwzględnij dwukropek (:) w hashu.

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"

Nagłówki żądania

Klucz	Typ	Opis
`X-Digest-Key`	string	Twój klucz API HLR Lookups
`X-Digest-Signature`	string	Unikalna sygnatura Digest-Auth (zobacz uwierzytelnianie)
`X-Digest-Timestamp`	integer	Aktualny znacznik czasu Unix (zobacz także `GET /time`)

{
    "success":true
}

Atrybuty Odpowiedzi Sukcesu

Nazwa	Typ	Opis	Opcjonalny
`success`	boolean	Wskazuje, że żądanie zostało przetworzone pomyślnie.	false

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

Parametry Odpowiedzi Błędu

Nazwa	Typ	Opis	Opcjonalny
`errors[]`	string[]	Lista ciągów tekstowych wyjaśniających błąd.	false

Przewiń w górę

Dokumentacja starszego API

Należy pamiętać, że starsze API jest przestarzałe i zostanie wycofane w przyszłości. Zdecydowanie zalecamy aktualizację do najnowszej wersji przy najbliższej okazji.

Jeśli wdrożono nasze HLR Lookups API w latach 2013-2020, używasz starszego API. W takim przypadku zapoznaj się z naszą dokumentacją starszego API.

Dokumentacja starszego API

Dokumentacja API

Pierwsze kroki

Zapytania HLR

Zapytania MNP

Zapytania NT

Routing

Cennik

Narzędzia

Pierwsze kroki

Korzystanie z API HLR Lookups

Przykładowe żądanie

Przykładowy payload

Odpowiedź Sukcesu application/json

Dodatkowe usługi wyszukiwania

Zapytania o przenośność numerów (MNP)

Wykrywanie typu numeru (NT)

Zestawy SDK

Narzędzia

Nie jesteś programistą?

Uwierzytelnianie

Klucz API i sekret API

HTTP Basic Auth

Zalecane: nagłówek X-Basic z SHA256

Żądanie Basic Auth

Nagłówki uwierzytelniania Basic

Przykład kodu

Przykład żądania

Nagłówki żądania

Tworzenie sygnatury

Komponenty sygnatury Digest

Przykłady kodu

Koncepcje

Synchroniczne API zapytań HLR

Asynchroniczne API wyszukiwania HLR

SDK (zestawy narzędzi programistycznych)

SDK PHP

SDK NodeJS

SDK Ruby

POST/hlr-lookupchroniony

Dane wejściowe

Parametry żądania

Atrybuty Odpowiedzi Sukcesu

Parametry Odpowiedzi Błędu

POST/hlr-lookupschroniony

Dane wejściowe

Parametry żądania

Atrybuty Odpowiedzi Sukcesu

Parametry Odpowiedzi Błędu

Przetwarzanie webhooków

Uwierzytelnianie

Przykład kodu

Potwierdzanie odbioru

Dane webhooka

Atrybuty ładunku webhooka

POST/mnp-lookupchroniony

Dane wejściowe

Parametry żądania

Atrybuty Odpowiedzi Sukcesu

Parametry Odpowiedzi Błędu

POST/mnp-lookupschroniony

Dane wejściowe

Parametry żądania

Atrybuty Odpowiedzi Sukcesu

Parametry Odpowiedzi Błędu

Przetwarzanie webhooków

Uwierzytelnianie

Przykład kodu

Potwierdzanie odbioru

Dane webhooka

Atrybuty ładunku webhooka

POST/nt-lookupchroniony

Dane wejściowe

Parametry żądania

Atrybuty Odpowiedzi Sukcesu

Parametry Odpowiedzi Błędu

POST/nt-lookups chroniony

Dane wejściowe

Parametry żądania

Atrybuty Odpowiedzi Sukcesu

Parametry Odpowiedzi Błędu