Instrukcja rejestracji usługi ZSL, urządzeń GPS i wypełniania zgłoszeń przewozu w zakresie modułu SENT-GEO

Operator musi posiadać ZAAWANSOWANY poziom dostępu do Platformy PUESC.
Operator rejestruje usługę ZSL (SENT460).
Operator otrzymuje numer usługi ZSL, hasło operatora i hasło startowe przewoźnika (SENT461).
Operator może aktualizować swoje dane (SENT462 >>> Zarządzanie usługą >>> Edytuj - SENT 463).
Operator przekazuje numer usługi ZSL i hasło startowe przewoźnikowi.
Przewoźnik loguje się do platformy PUESC, a następnie przy pomocy numeru usługi ZSL i hasła startowego rejestruje swoje dane oraz dodaje identyfikatory techniczne urządzeń GPS (SENT470).
Przewoźnik otrzymuje nowe hasło oraz numery urządzeń powiązanych z usługą ZSL (SENT471).
Przewoźnik może aktualizować swoje dane oraz dodawać kolejne lub usuwać istniejące identyfikatory techniczne urządzeń GPS powiązanych z usługą ZSL (SENT472 >>> Zarządzanie urządzeniami >>> Edytuj - SENT473).
Przewoźnik wypełniając zgłoszenie przewozu, wprowadza dany numer urządzenia oraz współrzędne miejsca załadunku towaru i/lub współrzędne miejsca dostarczenia towaru. Urządzenie aktywuje się w systemie po wysłaniu pierwszego zgłoszenia przewozu.

Przesyłanie danych lokalizacyjnych przez operatorów ZSL do modułu SENT GEO winno mieć miejsce każdorazowo w przypadku zaistnienia jednego z poniższych kryteriów:

maksymalnie po przejechaniu 1 km albo po upływie 1 minuty w zależności, które zdarzenie wystąpi później, ale nie rzadziej niż co 5 minut;
przy zmianie azymutu kierunku jazdy środka transportu o wartość równą lub większą niż 40 stopni;
przy postoju środka transportu, przy włączonym sliniku, co 5 minut;
przed wyłączeniem slinika, wskazując gdzie pojazd się zatrzymał na dłuższą przerwą wynikająca z przepisów związanych z czasem pracy kierowcy oraz po włączeniu slinika, tym samym wskazując zakończenie przerwy.

Dane lokalizacyjne spełniające powyższe warunki powinny być przekazywane z urządzenia lokalizacyjnego do modułu SENT GEO z opóźnieniem nie większym niż 1 minuta. Dane lokalizacyjne zebrane przez urządzenie lokalizacyjne mogą być buforowane przez operatorów ZSL, a następnie w cyklu nie dłuższym niż 1 minuta wysyłane w pakietach do modułu SENT GEO, z zachowaniem ograniczenia na wielkość, która wynosi 500 KB oraz na liczbę pozycji minimalną 1, a maksymalną 500. Dane, których wielkość przekracza 500 KB lub/i 500 pozycji powinny zostać podzielone na odpowiednią liczbę pakietów. Dane w ramach pakietu mogą pochodzić z różnych urządzeń i spełniać różne powyżej zdefiniowane kryteria.

Przykłady do kryterium nr 1:

30 km/h – później występuje kryterium 1 km - przejechany 1 km, próbka wysłana po 2 min,
60 km/h – kryterium 1 km i 1 min występuje w tym samym momencie - przejechany 1 km, próbka wysłana po 1 min,
90 km/h – później występuje kryterium 1 min – przejechane 1,5 km, próbka wysłana po 1 min,
120 km/h – później występuje kryterium 1 min – przejechane 2 km, próbka wysłana po 1 min.

Do 31 grudnia 2018 r. obowiązuje: schemat JSON sgdi_rest_request_schema_v_0_5.json. Natomiast od 1 stycznia 2019 r. obowiązuje schemat: JSON sgdi_rest_request_schema_v_0_6.json. Niezastosowanie się do powyższych reguł spowoduje niedopełnienie po stronie przewoźników obowiązków wynikających z art. 10a ustawy o systemie monitorowania drogowego i kolejowego przewozu towarów.

Przekazywane dane będą weryfikowane pod kątem spełnienia powyższych kryteriów. W przypadku stwierdzenia ich przekroczenia Operatorzy ZSL będą cyklicznie informowani o stwierdzonych nieprawidłowościach celem ich usunięcia.

Przypominamy, że od 1 stycznia 2019 r. obowiązuje nowa schema (sgdi_rest_request_schema_v_0_6.json) do walidacji danych przekazywanych za pośrednictwem ZSL. W schemie tej jako pola obowiązkowe zostały oznaczone pola:

lat (szerokość geograficzna)
lon (długość geograficzna)
tsp (data i czas próbki)
dev (identyfikator techniczny urządzenia)
brg (azymut w stopniach)
acc (dokładność w metrach)
spd (prędkość w metrach na sekundę)

Przesyłanie danych niezgodnych ze schemą sgdi_rest_request_schema_v_0_6.json po 31 stycznia 2019 roku będzie skutkowało odrzucaniem przesyłanych na interfejs danych.
Prosimy o jak najszybsze dostosowanie się do wprowadzonych zmian.

Pragniemy także zwrócić uwagę na często występujące błędy w przesłanych danych:

Pole dev - przesyłanie numeru lokalizatora GPS (Znn-xxnnxx-n) w miejscu identyfikatora technicznego urządzenia.
Pole dev - Przesyłanie numeru lokalizatora w postaci innej niż została zarejestrowana w SENT_47x (np. zmiana wielkości liter, dodanie prefiksu lub sufiksu).
Pola lat - przesyłanie danych spoza granic kraju. Dane, które nie mieszczą się w przedziale 49.0 - 54.835778 nie powinny być przesyłane.
Pola lon - przesyłanie danych spoza granic kraju. Dane, które nie mieszczą się w przedziale 14.116667 - 24.15 nie powinny być przesyłane.
Pole tsp - przesyłanie danych z przyszłości, spowodowane nieprawidłowa implementację stref czasowych (timestamp wyznacza się dla czasu UTC).
Pola lat i lon - zbyt duża dokładność. Dozwolone jest maksymalnie 10 cyfr po kropce dziesiętnej.
Pole spd - dane w tym polu muszą być przesyłane w metrach na sekundę.
Pole id - przesyłanie stałej wartości w polu ID. Pole to jest identyfikatorem rekordu, w związku z czym, każdy przesłany przez Państwa rekord danych powinien mieć w tym polu inną wartość. Może to być np. klucz tabeli z danymi gps po państwa stronie. Pole to jest nieobowiązkowe.

W przypadku 1) i 2) przesłanie błędnych danych nie skutkuje zwróceniem błędu, gdyż zgodnie z ustaleniami ZSL może wysyłać dane wszystkich pojazdów, nawet tych niezarejestrowanych. Od 1 lutego 2019 r. wysłanie takich danych będzie skutkowało dodaniem ostrzeżenia w odpowiedzi.
W przypadku 2) w celu minimalizacji ilości błędów w przesyłanych danych od 1 lutego 2019 r. wielkość liter w identyfikatorze nie będzie brana pod uwagę.
W przypadku 3), 4), 6) i 7) przesłanie takich danych skutkuje błędem 400. Jeżeli paczka danych zawiera więcej niż jeden rekord, to wystąpienie tych błędów (a także innych błędów niezgodności ze schemą) w przynajmniej jednym rekordzie spowoduje odrzucenie całej paczki i konieczność ponownego przesłania danych z pominięciem błędnych rekordów.
W przypadku 5) dane zostaną przyjęte. Od 1 lutego 2019 r. takie dane będą powodowały zwrócenie w odpowiedzi ostrzeżenia. W przyszłości takie dane mogą być odrzucane.
W przypadku 8) dane zostaną przyjęte.

W celu weryfikacji poprawności przesyłania danych prosimy o korzystanie z interfejsów testowych. Interfejsy testowe można rejestrować za pośrednictwem https://test.puesc.gov.pl/. Obecnie interfejsy testowe działają zgodnie ze schemą sgdi_rest_request_schema_v_0_6.json i są wzbogacone o dodatkowe ostrzeżenia w odpowiedzi.

Od 1 kwietnia 2019 roku obowiązuje wydanie 0.61 schematu JSON (sgdi_rest_request_schema_v_0_6_1.json). Wprowadzone zmiany dotyczą odrzucania danych, których współrzędne są spoza obszaru Polski. Szczegóły znajdują się w załączonej poniżej instrukcji.

Szczegółowa instrukcja użytkownika

Podłączenie urządzeń ZSL do SENT GEO - wersja polska (wersja z dnia 2.10.2019)
Connection of ZSL devices to SENT GEO - english version (version of 2.10.2019)
sgdi_rest_request_schema_v_0_4.json (version of 2.10.2018)
sgdi_rest_request_schema_v_0_5.json (wersja z 21.12.2018)
sgdi_rest_request_schema_v_0_6.json (wersja z 21.12.2018)
sgdi_rest_request_schema_v_0_6_1.json (obowiązuje od 1.04.2019)

Specyfikację techniczną usługi SENT-GEO

Specyfikacja techniczna usługi SENT-GEO.zip (wersja z dnia 31.12.2018)

	NAZWA FORMULARZA	WYPEŁNIAJĄCY	OPIS
	SENT460 - REJESTRACJA USŁUGI ZSL	OPERATOR USŁUG ZSL	Rejestracja usługi zewnętrznych systemów lokalizacyjnych (ZSL) przez operatorów
	SENT462 - AKTUALIZACJA DANYCH REJESTRACYJNYCH USŁUGI ZSL	OPERATOR USŁUG ZSL	Podgląd i edycja danych rejestracyjnych usługi ZSL, zmiana hasła operatora, wyświetlenie listy usług ZSL świadczonych przez operatora
	SENT470 - REJESTRACJA URZĄDZEŃ GPS W RAMACH USŁUGI ZSL	PRZEWOŹNIK - UŻYTKOWNIK URZĄDZEŃ GPS	Rejestracja przez przewoźników urządzeń GPS w ramach usługi zewnętrznych systemów lokalizacyjnych ZSL
	SENT472 - AKTUALIZACJA DANYCH REJESTRACYJNYCH PRZEWOŹNIKA ORAZ DODAWANIE/USUWANIE URZĄDZEŃ GPS W RAMACH USŁUGI ZSL	PRZEWOŹNIK - UŻYTKOWNIK URZĄDZEŃ GPS	Podgląd i edycja danych rejestracyjnych przewoźnika oraz urządzeń GPS, zmianą hasła przewoźnika, wyświetlenie listy zarejestrowanych urządzeń GPS w ramach usługi ZSL
* ustawa z dnia 9 marca 2017 r. o systemie monitorowania drogowego i kolejowego przewozu towarów (Dz. U. poz. 708, z późn. zm.) ** rozporządzenie Ministra Finansów z dnia 19 września 2018 r. w sprawie zgłoszeń przewozu towarów (Dz. U. poz. 1849)