# 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](<https://docs.logintegra.com/infokiosk/konfiguracja/index.md>).

## 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](<https://youtrack.logintegra.com/issue/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.
