Przejdź do treści

Integracja z Apollo i SMS

Strona opisuje wszystkie wywołania, które kiosk wysyła do Apollo i do mikroserwisu SMS. Jest dla programistów i administratorów, którzy podłączają kiosk do nowego środowiska albo diagnozują błędy komunikacji.

Wywołania wysyła ApolloService oraz SmsService, a samo połączenie HTTP obsługuje HttpService z biblioteką OkHttp. Adresy i sposób autoryzacji pochodzą z konfiguracji opisanej na stronie Konfiguracja.

Wywołania

Wywołanie Metoda Adres z konfiguracji Autoryzacja
wyszukanie transportów APOLLO_GET_TRANSPORT_API_METHOD APOLLO_GET_TRANSPORT_URL APOLLO_GET_TRANSPORT_AUTHORIZE
wyszukanie transportów przerzutowych jak wyżej APOLLO_GET_TRANSPORT_URL_ALT jak wyżej
potwierdzenie statusu POST APOLLO_CONFIRM_CHECKPOINT_URL APOLLO_CONFIRM_CHECKPOINT_AUTHORIZE
potwierdzenie warunków BHP POST APOLLO_CONFIRM_CONDITIONS_URL zawsze
odświeżenie tokenu POST ACCESS_TOKEN_REFRESH_URL zawsze
wysyłka SMS POST MS_SMS_SEND_SMS_URL brak

Każde wywołanie niesie nagłówki content-type: application/json i ApiVersion. Wersja API pochodzi z konfiguracji, a dla wywołań bez własnej zmiennej wynosi v1. Czas oczekiwania na odpowiedź ustawia KIOSK_HTTP_REQUEST_TIMEOUT_SECONDS, zob. sekcja "Znane ograniczenia".

Zmienne w adresach

Adres wyszukiwania transportów może zawierać zmienne, które kiosk zamienia przed wysłaniem.

Zmienna Wartość
@CAR_REGISTRATION_NUMBER numer wpisany przez kierowcę, wielkie litery, bez spacji
@WAREHOUSE_IDS APOLLO_WAREHOUSE_IDS rozdzielone przecinkami
@CHECKPOINT_ALIAS APOLLO_CHECKPOINT_ALIAS
@TRANSFER_TRANSPORT_TYPE_ID APOLLO_TRANSFER_TRANSPORT_TYPE_ID, tylko w adresie alternatywnym

Przykładowy adres API v2:

http://localhost:8080/apollo/api/transports?archived=false&deleted=false&completed=false&in:warehouseId=@WAREHOUSE_IDS&in:checkpointAlias=@CHECKPOINT_ALIAS&carRegistrationNumber=@CAR_REGISTRATION_NUMBER&inn:internalIndex&limit=100

Filtry zapytania opisuje dokumentacja API w repozytorium apollo/backend.

Dwie wersje API wyszukiwania

Kiosk obsługuje dwie wersje odpowiedzi z Apollo i rozpoznaje je po treści. Odpowiedź zawierająca fragment "metaData" jest traktowana jako API v2, a pozostałe jako API v1.

Cecha API v1 API v2
metoda POST z ciałem FindTransportDTO GET
adres /api/infokiosk/getTransport /api/transports?...
autoryzacja niepotrzebna token Bearer
odpowiedź lista transportów obiekt z polami data i metaData
filtrowanie okien czasowych po stronie Apollo po stronie kiosku

Zmienne APOLLO_GET_TRANSPORT_API_METHOD, APOLLO_GET_TRANSPORT_API_VERSION i APOLLO_GET_TRANSPORT_AUTHORIZE ustawiamy zgodnie z wybraną wersją.

Filtrowanie transportów

Dla odpowiedzi API v2 kiosk sam wybiera transporty, które pasują do kierowcy. Transport zostaje na liście, gdy spełnia oba warunki.

  1. Ma krok w jednym z magazynów kiosku, a typ kroku zgadza się z wybranym typem albo wybrano UNDEFINED.
  2. Najwcześniejsze okno czasowe w tych magazynach zaczyna się nie wcześniej niż KIOSK_TIME_WINDOW_INTERVAL godzin temu i kończy nie później niż za tyle godzin.

Gdy żaden transport nie przejdzie filtra, kiosk sprawdza pierwszego kandydata, najpierw z zapytania standardowego. Na tej podstawie zgłasza DRIVER_TOO_EARLY albo DRIVER_TOO_LATE z datą okna czasowego.

Pusta odpowiedź kończy się błędem TRANSPORT_NOT_FOUND.

Dwa zapytania i wybór transportu

Gdy ustawiono APOLLO_GET_TRANSPORT_URL_ALT, kiosk wysyła oba zapytania, standardowe i alternatywne. Alternatywny adres służy do wahadeł i przerzutów, np. z filtrem eq:transportTypeId=@TRANSFER_TRANSPORT_TYPE_ID. Kiosk łączy wyniki bez duplikatów i dopiero wtedy stosuje filtr z poprzedniej sekcji [INF-34].

Transporty, które przeszły filtr, kiosk sortuje po początku najwcześniejszego okna czasowego w swoich magazynach. Dzięki temu wahadło z wcześniejszym oknem wygrywa z załadunkiem z późniejszym, niezależnie od tego, które zapytanie je zwróciło.

Dalszy przebieg zależy od zmiennej KIOSK_AUTO_SELECT_EARLIEST.

Wartość Zachowanie przy kilku pasujących transportach
false kierowca wybiera transport z listy na ekranie /selectTransport
true kiosk obsługuje pierwszy transport, czyli ten z najwcześniejszym oknem, i nie pokazuje listy

Obsługa błędów zapytań wygląda tak:

Sytuacja Reakcja
zapytanie standardowe zwróciło brak wyników albo kod inny niż 200, 302, 401 kiosk sprawdza zapytanie alternatywne
zapytanie alternatywne zwróciło kod inny niż 200, 302, 401 błąd trafia do logu, kiosk używa wyniku zapytania standardowego
którekolwiek zapytanie zwróciło 401 albo 302 obsługa kończy się błędem, jak w tabeli "Kody odpowiedzi"

Kiosk loguje kandydatów z oknami czasowymi i listę transportów po filtrze, co ułatwia diagnozę zgłoszeń kierowców.

Kody odpowiedzi

Kod odpowiedzi Apollo Reakcja kiosku
200 dalsze przetwarzanie
401 UnauthorizedException, w logu podpowiedź o zmiennej ACCESS_TOKEN
302 TRANSPORT_OUTSIDE_OF_INTERVAL z opisem błędu z pola error
inny TRANSPORT_NOT_FOUND

Potwierdzenie statusu i warunków

Do potwierdzenia statusu kiosk wysyła POST na adres /api/infokiosk/confirmCheckpoint. Body zawiera trzy pola.

{
  "transportId": 123,
  "transportInternalIndex": 4567,
  "driverPhoneNumber": "+48123456789"
}

Odpowiedź inna niż 200 kończy obsługę błędem. Potwierdzenie warunków BHP wysyła to samo body na /api/infokiosk/confirm-conditions i zawsze z tokenem. Odpowiedź inna niż 200 jest tylko logowana.

Autoryzacja tokenem

API v2 Apollo wymaga autoryzacji, a kiosk nie ma logowania. Dlatego używa stałego tokenu ze zmiennej ACCESS_TOKEN, wysyłanego w nagłówku Authorization: Bearer.

Dla każdego kiosku warto założyć w Apollo osobnego użytkownika. Wtedy w historii widać, który kiosk potwierdził status. Token można dostarczyć na dwa sposoby.

Token z logowania

Token zwraca endpoint logowania Apollo.

POST https://apollo.logintegra.com/apollo/api/login
Content-Type: application/json

{
  "username": "<login>",
  "password": "<hasło>"
}

W odpowiedzi pole access_token zawiera wartość do wpisania w ACCESS_TOKEN.

Token dopisany do bazy

Na serwerach testowych baza często wraca z kopii produkcyjnej. Wtedy wygodniej dopisać token do bazy Apollo skryptem:

INSERT INTO authentication_token (id, date_created, refreshed, token_value, username)
VALUES (NEXTVAL('hibernate_sequence'), NOW(), NOW(), '<token-kiosku>', '<login-apollo>')
ON CONFLICT DO NOTHING;

Symbol <token-kiosku> to wartość ACCESS_TOKEN z konfiguracji kiosku. Symbol <login-apollo> to użytkownik, w imieniu którego kiosk potwierdza statusy.

Odświeżanie tokenu

Token nieużywany wygasa. Job RefreshAccessTokenJob wysyła więc POST na ACCESS_TOKEN_REFRESH_URL zgodnie z harmonogramem ACCESS_TOKEN_REFRESH_JOB_CRON. Błąd odświeżenia jest wypisywany na konsolę i nie zatrzymuje kiosku.

Wysyłka SMS

Kiosk wysyła SMS przez mikroserwis SMS, wołając POST na MS_SMS_SEND_SMS_URL.

{
  "message": "<MS_SMS_PRINCIPAL_NAME> | <treść w języku kierowcy> <kod>",
  "phoneNumber": "+48123456789",
  "clientName": "<MS_SMS_PRINCIPAL_NAME>",
  "connectedAppUrl": "<MS_SMS_CONNECTED_APP_URL>",
  "retryOnError": true
}

Numer telefonu pochodzi z awizacji transportu i składa się z prefiksu oraz numeru kierowcy. Pola clientName i connectedAppUrl muszą zgadzać się z wpisem w tabeli connected_app w bazie mikroserwisu SMS. Treść wiadomości pochodzi z klucza smsBody w pliku komunikatów dla języka sesji.

Ostatnia zmiana: 2026-10-08 · Dariusz Bakowski
Zbudowano: 2026-11-20 10:32 UTC · wersja 1.0.0 · rewizja: 19fcdc12e