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.
- Ma krok w jednym z magazynów kiosku, a typ kroku zgadza się z wybranym typem albo wybrano
UNDEFINED. - Najwcześniejsze okno czasowe w tych magazynach zaczyna się nie wcześniej niż
KIOSK_TIME_WINDOW_INTERVALgodzin 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.
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