HTTPS API v2 / HLR - sprawdzanie dostępności numeru

 

Informujemy, że obecnie nie działa opcja sprawdzania statusu aktywności numeru dla poniższych sieci:

26002 - T-mobile (PL)

Wynik zwracany w usłudze HLR będzie zawierał jedynie informacje na temat przynależności numeru do sieci oraz czy numer był przenoszony.

 

Zasada działania

Aby przy pomocy Zdalnej obsługi sprawdzić dostępność numeru należy wywołać określony adres URL metodą POST.

phones/check

Dostępne parametry

Parametr	Typ	Przykładowa wartość lub format	Opis
username	String	login	Login użytkownika API.
password	String	hasło	Hasło użytkownika API.
phone	String|Array	500600700 lub +42565478965	Numer w formacie 9-cio cyfrowym. Numery mogą być rozdzielone przecinkami lub w formie tablicy. Dla numerów zagranicznych niezbędne jest podanie plusa i prefiksu kraju. Maksymalna liczba obsługiwanych jednorazowo numerów to 50 000.
id	String	numer zgłoszenia	Parametr służący do odczytu wyniku, jeśli czas oczekiwania na odpowiedź przekroczy 60 sekund lub przesłano więcej niż jeden numer.
url	String	http://www.adres.com/index.php?id=#ID#&stan=#STAN#	W przypadku wysyłki więcej niż jednego numeru, po zakończeniu sprawdzania system wywoła podany URL informujący o możliwości pobrania wyników.

Parametry oznaczone pogrubieniem są obowiązkowe. Pozostałe są opcjonalne.

Zwrot wygenerowany po przesłaniu przykładowego pojedynczego zapytania.

{
   "phone":"+48500600700",
   "status":"OK",
   "imsi":26006,
   "network":"Orange (PTK Centertel Sp. z o.o.)",
   "ported":false,
   "network_ported":null,
   "description":null
}

Zwrot wygenerowany w przypadku sprawdzania więcej niż jednego numeru.

{
   "status":"done",
   "process": 100,
   "items":[
   {
       "phone":"+48500600700",
       "status":"ERR",
       "imsi":26003,
       "network":"Orange (PTK Centertel Sp. z o.o.)",
       "ported":false,
       "network_ported":null,
       "description":"ABSENT_SUBSCRIBER_SM"
   },
   {
       "phone":"+48600700800",
       "status":"OK",
       "imsi":260011234567890,
       "network":"Plus (Polkomtel S.A.)",
       "ported":true,
       "network_ported":"Plus (Polkomtel S.A.)",
       "description":null
   }]
}

Objaśnienie poszczególnych parametrów zwrotnych

Parametr	Opis
phone	Sprawdzany numer telefonu
status	Status zapytania HLR, jeśli jest poprawny, system zwróci „OK”, jeśli nie ma możliwości aby sprawdzić numer lub numer nie jest poprawny, system zwróci „ERR”. UWAGA! Taryfikowane są wszystkie zapytania HLR, zarówno poprawne jak i niepoprawne.
imsi	Unikatowy numer przypisany do każdej karty SIM w sieci GSM lub UMTS. W niektórych sytuacjach może zawierać jedynie numer kraju i numer sieci (np. „26003”).
network	Nazwa alfanumeryczna sieci z której numer pochodzi.
ported	Informacja o tym czy numer jest przenoszony „true” czy też nie „false”.
network_ported	Nazwa alfanumeryczna sieci do której numer jest obecnie przypisany.
description	Kod ew. błędu podczas sprawdzania numeru

Kody błędów

Kod	Opis
UNKNOWN_SUBSCRIBER	Numer nie istnieje lub nie jest przypisany do żadnego abonenta
CALL_BARRED	Abonent ustawił usługę "Nie przeszkadzać" (DND)
ABSENT_SUBSCRIBER_SM	Abonent tymczasowo niedostępny - znajduje się poza zasięgiem sieci lub jego aparat jest wyłączony
TELE_SERVICE_NOT_PROVISIONED	Usługa telefoniczna została zawieszona przez operatora
HLR_REJECT	Zapytanie zostało odrzucone przez operatora
HLR_ABORT	HLR (lub inna jednostka) przerwało zapytanie. Brak odpowiedzi
HLR_LOCAL_CANCEL	Brak odpowiedzi na zapytanie HLR
TIMEOUT	Brak odpowiedzi w określonym czasie
IMSI_LOOKUP_BLOCKED	Usługa zablokowana dla wybranego numeru
SYSTEM_FAILURE	Awaria systemu HLR po stronie operatora

Jeśli czas oczekiwania na odpowiedź przekroczy 60 sekund, zwrócony zostanie identyfikator, który należy podstawić do zapytania w późniejszym czasie w celu odczytu statusu po jego aktualizacji. Odpowiedź zwrotna będzie miała wówczas postać:

{
   "phone":"+48500600700",
   "id":"6970aa5525"
}

Zalecane ustawienia

Nie należy sprawdzać wielokrotnie pod rząd tego samego numeru gdyż każde wywołanie sprawdzające przynależność do sieci jest taryfikowane. Warto więc zapisywać wyniki lokalnie i posługiwać się nimi przez określony czas np. kilka dni. 

Należy ustawić większy timeout dla zapytań, gdyż oczekiwanie na odpowiedź systemu może trwać od kilku do nawet kilkudziesięciu sekund.