Przejdź do treści

MOWI OTM – wysyłka statusów transportu

Ta strona jest dla programistów backendu i testerów. Opisuje, kiedy Apollo wysyła mapę transportu do MOWI OTM (POST /status2otm), co jest wysyłane i gdzie szukać śladów wysyłki. Autoryzację OAuth 2.0 i konfigurację klienta opisuje Klient OAuth 2.0 Client Credentials.

Kiedy wysyłamy komunikat

Komunikat jest wysyłany po potwierdzeniu i po wycofaniu statusu, gdy spełnione są wszystkie warunki:

  1. Integracja jest włączona: mowi.otm.oauth.enabled = true.
  2. Transport należy do pryncypała MOWI (alias firmy mowi, Company.MOWI_ALIAS).
  3. Task statusu ma włączoną flagę „Wysyłanie komunikatu API” (Task.sendApiMessage).

Sprawdzenie pryncypała (MowiOtmStatusService#isMowi) jest tymczasowe. Docelowo integracja powinna być konfigurowana per pryncypał.

Zdarzenie Co wysyłamy Kolejność
potwierdzenie statusu osobny komunikat dla każdego potwierdzonego statusu z flagą, także dla statusów potwierdzonych automatycznie w tej samej operacji rosnący idx
wycofanie statusu osobny komunikat dla każdego wycofanego statusu z flagą (wycofanie cofa też wszystkie późniejsze statusy) malejący idx

Źródło potwierdzenia nie ma znaczenia: UI, Public API, automat, SMS, infokiosk itd. Wszystkie ścieżki przechodzą przez WorkflowService.

Na transportach MOWI flaga uruchamia wyłącznie wysyłkę do MOWI OTM. Standardowa wysyłka na adres z ustawienia API_MESSAGE_URL jest dla nich pomijana, niezależnie od mowi.otm.oauth.enabled.

Na transportach innych pryncypałów flaga działa jak dotąd: po potwierdzeniu wysyła komunikat na API_MESSAGE_URL. Wycofanie statusu nigdy nie wysyła komunikatu na API_MESSAGE_URL.

Co wysyłamy

Body to pełna mapa transportu w formacie Public API v1 (PublicApiDTO, PublicApiMapper). Ma ten sam kształt co odpowiedź GET /api/transports/{id} z nagłówkiem APIVersion: v1 i co komunikaty wysyłane na API_MESSAGE_URL. Daty są tekstem w UTC. Mapa jest budowana z bazy (z pominięciem cache) w stanie po potwierdzeniu albo po wycofaniu statusu.

Body nie zawiera osobnego pola ze statusem. MOWI odczytuje stan z listy checkpoints: potwierdzony status ma uzupełnione executionDate, wycofany ma je puste.

Przepływ

sequenceDiagram
    participant W as WorkflowService
    participant L as CheckpointConfirmationListenerService
    participant M as MowiOtmStatusService
    participant O as MOWI OTM
    W->>W: confirm / revoke, commit transakcji
    W-->>L: CheckpointConfirmedEvent / CheckpointsRevokedEvent (po commicie)
    L->>M: sendAfterConfirmation(ids) / sendAfterRevoke(snapshots)
    M->>M: filtr: enabled, MOWI, sendApiMessage
    loop każdy status
        M->>O: POST /status2otm (Bearer)
        O-->>M: odpowiedź
        M->>M: log aplikacji + PublicApiLog
    end
Klasa Zadanie
WorkflowService publikuje CheckpointConfirmedEvent z listą wszystkich statusów potwierdzonych w operacji oraz CheckpointsRevokedEvent po wycofaniu
CheckpointConfirmationListenerService odbiera oba eventy; dla transportów MOWI pomija wysyłkę na API_MESSAGE_URL, dla pozostałych działa ona jak dotąd
MowiOtmStatusService filtruje statusy, buduje body, wysyła, loguje i zapisuje wpis w „Integracji”
MowiOtmClientService klient HTTP z autoryzacją OAuth 2.0

Eventy są dostarczane asynchronicznie, po commicie transakcji potwierdzenia lub wycofania. Wysyłka nie wydłuża więc odpowiedzi dla użytkownika i widzi zapisany stan transportu.

Event wycofania niesie migawki (RevokedCheckpointSnapshot), a nie encje. Wycofanie może usunąć i odtworzyć statusy (recalculateCheckpointsIfTransactionDependent), więc identyfikatory checkpointów mogłyby już nie istnieć.

Obsługa błędów

Błąd wysyłki nie cofa i nie blokuje potwierdzenia ani wycofania statusu. Nie ma ponawiania: każda próba kończy się jednym wpisem w logach i w „Integracji”.

Sytuacja responseCode w „Integracji”
sukces kod HTTP, np. 200 OK
MOWI odpowiedziało błędem kod HTTP, np. 500 INTERNAL_SERVER_ERROR
nie udało się pobrać tokenu OAUTH_TOKEN_ERROR:<reason>, np. OAUTH_TOKEN_ERROR:INVALID_CREDENTIALS
timeout lub brak połączenia MOWI_UNREACHABLE
brak mowi.otm.baseUrl NOT_CONFIGURED
inny błąd UNKNOWN_ERROR

Gdzie szukać śladów wysyłki

Sekcja „Integracja” transportu (PublicApiLog):

Pole Wartość
event MOWI_OTM_STATUS_CONFIRMED albo MOWI_OTM_STATUS_REVOKED
url pełny adres /status2otm
httpMethod POST
request wysłane body
responseCode wynik, patrz tabela wyżej
actor potwierdzający albo wycofujący użytkownik
canBeResend false, ponowna wysyłka z „Integracji” nie jest obsługiwana

Logi aplikacji mają prefiks MOWI OTM:

MOWI OTM | transport 123 | status ARRIVAL_UPPER_BARRIER | MOWI_OTM_STATUS_CONFIRMED | SUCCESS | 200 OK | 87 ms | response: ...
MOWI OTM | transport 123 | status ARRIVAL_UPPER_BARRIER | MOWI_OTM_STATUS_REVOKED | FAILURE | 500 INTERNAL_SERVER_ERROR | 120 ms | details: ...

Treść odpowiedzi MOWI i alias statusu są tylko w logach aplikacji. Logi nie zawierają tokenu ani sekretu klienta.

Testowanie lokalnie

  1. Uruchom stack Dockera z mockiem mowi-otm-mock (WireMock) i ustaw MOWI_OTM_OAUTH_ENABLED=true (klucze w application-docker.yml).
  2. W workflow transportu MOWI włącz flagę „Wysyłanie komunikatu API” na wybranym tasku.
  3. Potwierdź status w UI albo przez Public API: PUT /api/transports/{identifier}/confirm/{taskAlias}.
  4. Sprawdź żądanie w WireMocku, wpis w „Integracji” (GET /api/transports/{id}/getIntegrationLogs) i logi: docker logs -f apollo_backend | grep "MOWI OTM".
  5. Wycofaj status i powtórz sprawdzenie.

Testy jednostkowe: MowiOtmStatusServiceSpec, MowiOtmStatusServiceRequestBodySpec i CheckpointConfirmationListenerServiceSpec.

Ograniczenia

Ograniczenie Skutek
łączenie transportów (TransportRelationService) nie publikuje eventu potwierdzenia statusy potwierdzone przy łączeniu nie są wysyłane
automatyczne potwierdzenie przy edycji transportu wysyłany jest tylko status potwierdzony wprost, bez wcześniejszych potwierdzonych razem z nim
brak ponawiania po błędzie trzeba ponownie potwierdzić status albo wycofać go i potwierdzić
pryncypał rozpoznawany po aliasie tymczasowe, do zastąpienia konfiguracją per pryncypał

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