Połączenia alarmowe
Są 2 metody przekazywania danych na potrzeby lokalizacji E112 do Centrów Powiadamiania Ratunkowego.
- Metoda wsadowa - polegająca na umieszczeniu na serwerze ftps danych abonentów raz w miesiącu wszystkich, następnie przyrostowo. System PLICBD odpytuje serwer ftps co godzinę w poszukiwaniu plików z danymi abonentów. Jest to metoda, której nie polecamy używać.
- Metoda PUSH - polegająca na wysyłce danych abonenta inicjującego połączenie pod numer alarmowy w momencie jego inicjowania.
W każdym z powyższych przypadków musisz odpowiednio zbudować NKA (Numer Kierowania Alarmowego) przed samym zestawieniem połączenia pod numer alarmowy. Dopiero w momencie otrzymania NKA (lub zbudowania, jeśli robisz to samodzielnie) możesz zestawić połączenie z wybranym numerem alarmowym. Pamiętaj, że NKA nie musi istnieć np. BOLESŁAWIEC w woj. DOLNOŚLĄSKIE nie posiada NKA dla numerów 985, 986, 987. W takim przypadku możesz zestawić połączenie ze standardowym numerem alarmowym 112. Przykłady zapytań w celu budowania prawidłowego NKA znajdziesz poniżej.
Mając aktywne API dla innych naszych usług PLICBD API pamiętaj, że żądne zapytanie nie wlicza się w usługi Lokalizacji E112, czyli oferty PLICBD 1. W każdym miesiącu możesz wykorzystać (mając aktywne PLICBD 1) niezliczoną ilość zapytań do lokalizacji PLICBD1 E112, nawet mając (lub nie mając) aktywne API naszego PLICBD.
Do obsługi PLICBD 1 w wersji FTP's w celu dodania lub modyfikacji/usunięcia danych przez API (i tylko przez API) należy zakupić pakiet API, lub skorzystać z możliwości ręcznego wprowadzania danych po kolei w panelu po zalogowaniu. W Panelu Operatora masz możliwość wrzucenia danych w formacie txt, sql, csv, xml, a nawet gotowych danych otrzymanych od poprzedniego providera w formacie zip bez żadnych limitów. Jeżeli potrzebujesz wrzucić dane z innego typu plików, to skontaktuj się z nami. Udostępnimy format dla Ciebie dogodny.
Metoda wsadowa a procesy NP
Korzystając z metody wsadowej do wysyłania danych w lokalizacji E112 i jednocześnie mając aktywny dowolny plan NP - przy odbiorze komunikatu E13 dane lokalizacyjne uzupełnią się automatycznie bez wykonywania dodatkowych czynności. Te dane wyślemy przyrostowo w najbliższej pełnej godzinie. Podczas wypełniania wniosku E03 o przeniesienie numeru poprosimy o podanie adresu klienta. Dane przyrostowe wysyłane są na serwer FTP w godzinach od 7 do 22 każdego dnia.
Metoda PUSH (online)
Metoda PUSH polega na wysyłaniu metodą POST pod wskazany adres URL informacji o Abonencie (szczegóły w dokumentcji poniżej) w momencie gdy wybiera on numer alarmowy. Pamiętaj o dodaniu adresu IP, z ktorego będziesz wysyłał komunikaty (może być ich wiele):
- Z lewego menu wybierz: Lokalizacja E112 rozwiń Numery Alarmowe. Wybierz Autoryzacja i historia.
- Po prawej stronie będzie przycisk Dodaj adres IP (kliknij).
- Wprowadź adres IP swojej centrali, z której będziesz wykonywał żądania na potrzeby E112.
- Do północy tego samego dnia wyślij i zautoryzuj swój adres IP poprzez wykonanie żądania post z wprowadzonego IP pod adres https://plicbd.arkanavoip.pl/api/emergency/confirm, bez żadnych form-data.
- Po wysłaniu POST z pkt poprzedniego wprowadzony adres IP zostanie uwierzytelniony i jest gotowy do wysyłania danych lokalizacyjnych.
Historię wysyłki trzymamy przez 60 dni i masz do niej wgląd w panelu.
Metoda wsadowa FTPS
Metoda wsadowa polega na umieszczaniu plików z danymi abonentów (osobowych i lokalizacyjnych) na przygotowanym przez nas serwerze FTPS. Każda zmiana danych Abonenta np. Nowy klient, zmiana danych osobowych/numeru powoduje konieczność wysłania danych przyrostowych co godzinę. Raz w miesiącu UKE pobierane dane wszystkich Abonentów.
Od momentu wejścia w życie ustawy PKE - ta metoda stała się obowiązkowa dla wszystkich przedsiębiorców telekomunikacyjnych.
Wykorzystując tą metodę nie ma potrzeby wykonywania specjalnych działań w momencie, gdy Abonent wybierze numer alarmowy, ponieważ dane Abonentów są dostępne na serwerze FTPS. Zadbaj o właściwy numer NKA (do pobrania z API, jeśli korzystasz z jakiejkolwiek metody PLICBD1, czyli komunikatów lokalizacyjnych są one dla Ciebie bezpłatne).
Opłata za korzystanie z metody FTPS to 299.99 zł miesięcznie.
Adres: https://plicbd.arkanavoip.pl/api/emergency/getEmeCall
Metoda: POST
| Parametr | Typ Danych | Wyjaśnienie |
|---|---|---|
| from_number | string|required | MSISDN dzwoniącego (format: Kod kraju+Numer telefonu np. 48601123456) + jako pierwszy znak jest dopuszczalny. Niezbędny do określenia, czy abonent dzwoniący to fix czy mobile (NKA różni się w tym zakresie) |
| to_number | string|required | Numer alarmowy, pod który dzwoni klient np. 986, 991, 987, 999, 997, 112 itd bez spacji i myślników |
| city | string|required | Miasto, z którego dzwoni klient*. |
| county | string|required_without:province | Powiat, z którego dzwoni klient*. Wymagane, gdy brak province. |
| province | string|required_without:county | Województwo, z którego dzwoni klient*. Warto podać, jednak w przypadku jednoznacznego dopasowania city i county nie jest ono wymagane. Gdy city nie znalazło county, szuka city po province, więc warto podać, choćby w celu eliminacji błedów. |
Miasta, powiaty i województwa jakie są używane znajdują się w ostatniej zakładce tej strony.
Oczekiwane kody odpowiedzi
200 W zwrocie otrzymasz NKA (czyli końcowy numer, z którym masz zestawić połączenie alarmowe) np. 71C700112
403 Nieautoryzowany dostęp. Dodaj adres IP centrali, z której wychodzi żądanie.
422 Walidacja danych zakończona niepomyślnie. W messages znajdziesz szczegóły. Zazwyczaj problem oznacza błędnie podane województwo, lub powiat
500 Błędne zapytanie. Zapoznaj się z dokumentacją.
Adres: https://plicbd.arkanavoip.pl/api/emergency/push
Metoda: POST
Odpowiedź umożliwiająca kontynuowanie połączenia: HTTP STATUS 201
| Parametr | Typ Danych | Wyjaśnienie |
|---|---|---|
| msisdn | string|required | MSISDN dzwoniącego (format: Kod kraju+Numer telefonu np. 48601123456) + jako pierwszzy znak jest dopuszczalny. |
| eme_call | string|required | Numer Kierowania Alarmowego (NKA). ABCSPQMnumer_wybierany np. 12C100112 (dla numeru 112 z msisdn fix, z lokalizacji Krakowa miasta). Jeśli nie wiesz jak zbudować NKA, lub Twoje systemy nie są do tego przygotowane, zapoznaj się z metodą getEmeCall. |
| customer_name | string|required | Osoba fizyczna: Imię Drugie Imię (jeśli dostępne)|Nazwisko|Ulica Numer Budynku/Numer Mieszkania|Telefon Kontaktowy (inny niż ten, z którego zostało wykonane połączenie), lub adres email|1:Pesel Firma: Nazwa Firmy Sp z o o|Spółka z ograniczoną odpowiedzialnością NIP: 1234567890|Ulica Firmy i numer, kod-pocztowy miasto np. Jan Kowalski i Spółka Sp z o o|Spółka z ograniczoną odpowiedzialnością NIP: 1234567890|Al. Jerozolimskie 1C, 02-222 Warszawa lub dla JDG: Jan Kowalski|jednoosobowa działaność gospodarcza NIP: 1234567890|Al. Jerozolimskie 1C, 02-222 Warszawa |
| lev_conf | string|required | Prawdopodobieństwo % zakończenia sieci pod danym adresem - stacjonarne zawsze 100 |
| x | string|required if mobile* | Szer. geogr. w stopniach dziesiętnych poprzedzona literą N |
| y | string|required if mobile* | Dł. geogr. w stopniach dziesiętnych poprzedzona literą E |
| angle | string|required if mobile* | Kąt w stopniach obrotu elipsy zgodnie z wskazówkami zegara z północy |
| semiMajor | string|required if mobile* | Długość wielkiej półosi w metrach |
| semiMinor | string|required if mobile* | Długość małej półosi w metrach |
| angularUnit | string|required if mobile* | Opcjonalny tag jednostki kątów |
| distanceUnit | string|required if mobile* | Opcjonalny tag jednostki odległości |
Oczekiwane kody odpowiedzi
201 Dane zostały prawidłowo wysłane do PLICBD oraz zapisane na serwerze.
403 Nieautoryzowany dostęp. Dodaj adres IP centrali, z której wychodzi żądanie.
422 Walidacja danych zakończona niepomyślnie. W messages znajdziesz szczegóły.
500 Błędne zapytanie. Zapoznaj się z dokumentacją.
Adres: https://plicbd.arkanavoip.pl/api/e112/ftps
Metoda: GET
| Parametr | Typ Danych | Wyjaśnienie |
|---|---|---|
| search[value] | sometimes|string | Jakiekolwiek dane, które chcemy wyszukać np. numer, nazwisko Abonenta, ulica, numer dokumentu tożsamości, pesel itd. |
| start | sometimes|digits | Strona. |
| length | sometimes|digits | Ilość rekordów na stronie. |
Oczekiwane kody odpowiedzi
200 Otrzymasz dane w formacie json.
Adres: https://plicbd.arkanavoip.pl/api/e112/ftps/store
Metoda: POST
| Parametr | Typ Danych | Wyjaśnienie |
|---|---|---|
| dirnum[] | required|array|numeric:9 | Początek zakresu numerów bez +, bez +48, bez 48, bez 00. Dokładnie 9 cyfr. |
| dirnum_end[] | required|array|numeric:9 | Koniec zakresu numeru bez +, bez +48, bez 48, bez 00. Dokładnie 9 cyfr. Zakres to dowolny zakres, gdzie dirnum_end[] > dirnum[]. Nie jest wymagane min. 10 numerów, jak w innych fukcjach. Mogą to być 2,4,7,1000 lub więcej numerów. Jeśli jeden numer to dirnum[i] musi być identyczny jak dirnum_end[i]. |
| type | required|in:PES,DOC,REG,NIP | PES jako pesel, NIP jako NIP, DOC jako dokument obcokrajowca. |
| full_name | string|required|max:80 | Pełne imie i nazwisko, lub prawidłowa nazwa firmy. |
| street | string|required|mx:120 | Ulica wraz z numerem demu i mieszkania np. Pierwsza 1/23. |
| post_code | required|string|regex:/^\d{2}-\d{3}$/ | Polski kod pocztowy format xx-xxx, gdzie x to cyfra od 0 do 9. Żadne inne dane nie będą przyjmowane. |
| city | required|string|max:32 | Polskie miasto, które może być wyszkukiwane poprzez TERYT. Za błędy nie odpowiadamy - Do Ciebie należy weryfikacja. My w komunikacji z PLICBD podamy dokładnie takie dane, jakie Ty nam podałeś. |
| county | sometimes|nullable|string|min:4|max:70 | Powiat abonenta. Jeśli korzystasz z PLICBD1 w formie FTPS powinieneś podać. County powinno być zgodne z TERYT (my tego nie weryfikujemy - Ty za to odpowiadasz. My w plikach INCR oraz FULL podamy dokładnie to co Ty nam podałeś). |
| province | sometimes|nullable|string|min:4|max:90 | Województwo abonenta. Jeśli korzystasz z PLICBD1 w formie FTPS powinieneś podać. Province powinno być zgodne z TERYT (my tego nie weryfikujemy - Ty za to odpowiadasz. My w plikach INCR oraz FULL podamy dokładnie to co Ty nam podałeś). |
| correspondence_address | sometimes|nullable|string|max:255 | Pełen adres korespondencyjny Abonenta. |
| document_value | required|string|min:7|max:20 | Jeśli obywatel polski numer pesel. Jeśli obcokrajowiec seria i numer dokumentu stwierdzającego tożsamość. |
Oczekiwane kody odpowiedzi
201 Dane zostały prawidłowo zapisane.
403 Nieautoryzowany dostęp. Dodaj adres IP centrali, z której wychodzi żądanie.
422 Walidacja danych zakończona niepomyślnie. W messages znajdziesz szczegóły.
500 Błędne zapytanie. Zapoznaj się z dokumentacją.
Adres: https://plicbd.arkanavoip.pl/api/e112/ftps/delete/{ftp}
Metoda: DELETE
| Parametr | Typ Danych | Wyjaśnienie |
|---|---|---|
| ftp | required|int | id rekordu. |
Oczekiwane kody odpowiedzi
200 Dane zostały prawidłowo usunięte, zmiana zostanie wysłana do PLICBD.
Przykład żądania getEmeCall
$client = new \GuzzleHttp\Client();
$client->request( 'POST', 'https://plicbd.arkanavoip.pl/api/emergency/getEmeCall',[
'form_params' => [
'from_number' => '48601234567',
'to_number' => '112',
'city' => 'WARSZAWA',
'county' => 'WARSZAWA',
'province' => 'MAZOWIECKIE',
]
]);
Przykład żądania PUSH dla stacjonarnych
$client = new \GuzzleHttp\Client();
$client->request( 'POST', 'https://plicbd.arkanavoip.pl/api/emergency/push',[
'form_params' => [
'msisdn' => '48601234567',
'eme_call' => '22C701112',
'customer_name' => 'Adam|Kowalski|ul. Jasna 72/40, 00-112 Warszawa|adam.kowalski@o2.pl|1:68112002345',
]
]);
Przykład żądania PUSH dla komórkowych
$client = new \GuzzleHttp\Client();
$client->request( 'POST', 'https://plicbd.arkanavoip.pl/api/emergency/push',[
'form_params' => [
'msisdn' => '48601234567',
'eme_call' => '22C701112',
'customer_name' => 'Adam|Kowalski|ul. Jasna 72/40, 00-112 Warszawa|adam.kowalski@o2.pl|1:68112002345',
'x' => 'N51.459',
'y' => 'E21.448',
'angle' => '90.00',
'semiMajor' => '500',
'semiMinor' => '250',
'angularUnit' => 'Degrees',
'distanceUnit' => 'meter',
'lev_conf' => '70',
]
]);
Przykład wykonania żądania w Asterisk
[emergency]
exten => 112, 1, Set(POST_DATA='msisdn=48601234567&eme_call=22C701112&customer_name=Adam|Kowalski|ul. Jasna 72/40, 00-112 Warszawa|adam.kowalski@o2.pl|1:68112002345&lev_conf=100')
same => n, Set(POST_URL='https://plicbd.arkanavoip.pl/api/emergency/push')
same => n, Set(CURL_RESULT=${CURL(${POST_URL},${POST_DATA},-H "Content-Type: application/x-www-form-urlencoded",-X POST)})
same => n, Dial(PJSIP/${EXTEN}@trunk)
Lub przekazannie do pliku php:
[emergency]
exten => 112, 1, System(php /path/to/post_request.php)
Używane dane, ze względu na ich ilość, zostały podzielone na przyciski wyboru z opcją dopasowania po rozpoczęciu wprowadzania danych. Po wybraniu i zaznaczeniu miasta, automatycznie uzupełni się powiat i województwo. Jednak powiat i województwo nie zmienią się po dokonaniu kolejnych zmian w powiecie i województwie.