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:
- Integracja jest włączona:
mowi.otm.oauth.enabled = true. - Transport należy do pryncypała MOWI (alias firmy
mowi,Company.MOWI_ALIAS). - 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¶
- Uruchom stack Dockera z mockiem
mowi-otm-mock(WireMock) i ustawMOWI_OTM_OAUTH_ENABLED=true(klucze wapplication-docker.yml). - W workflow transportu MOWI włącz flagę „Wysyłanie komunikatu API” na wybranym tasku.
- Potwierdź status w UI albo przez Public API:
PUT /api/transports/{identifier}/confirm/{taskAlias}. - Sprawdź żądanie w WireMocku, wpis w „Integracji” (
GET /api/transports/{id}/getIntegrationLogs) i logi:docker logs -f apollo_backend | grep "MOWI OTM". - 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