Dobre praktyki integracyjne
1. Cykl życia operacji – aktualny model referencyjny
Status początkowy: DRAFT
Każde przesłane zlecenie wydania otrzymuje status: DRAFT
Oznacza to, że:
dokument został zapisany w WMS,
przeszedł walidację techniczną,
nie został jeszcze zatwierdzony biznesowo.
Na tym etapie:
możliwa jest edycja danych,
możliwe jest usunięcie dokumentu,
operacja nie istnieje jeszcze operacyjnie w magazynie.
Status ACCEPTED
Zmiana statusu na: ACCEPTED
jest świadomą decyzją biznesową systemu nadrzędnego o przekazaniu operacji do weryfikacji WMS.
Kluczowa reguła
Po przejściu do ACCEPTED:
jedyną dostępną operacją dla integratora jest anulowanie,
nie wolno:
modyfikować pozycji,
zmieniać ilości,
ponownie edytować danych dokumentu.
Zapewnia to:
stabilność algorytmów WMS,
przewidywalność przebiegu procesu,
brak konfliktów między systemami.
Decyzja operacyjna WMS
Po statusie ACCEPTED WMS wykonuje asynchroniczną weryfikację i podejmuje decyzję:
NEW → operacja przyjęta do realizacji magazynowej
CANCELED → operacja odrzucona
Decyzja ta należy wyłącznie do WMS i nie jest sterowana przez system nadrzędny.
2. Numer operacji magazynowej
Kluczowa zasada projektowa:
Numer operacyjny nadawany jest wyłącznie operacjom w statusie NEW.
Oznacza to:
operacje NEW otrzymują:
numer magazynowy,
pełną reprezentację operacyjną,
obecność w dokumentach i raportach,
operacje CANCELED:
nie otrzymują numeru użytkowego,
posiadają jedynie techniczne ID systemowe.
Znaczenie biznesowe
Takie podejście:
eliminuje „puste” numery operacyjne,
zachowuje spójność ewidencji magazynowej,
upraszcza analizę historii operacji.
3. Dozwolone przejścia statusów
Ścieżka podstawowa
DRAFT → ACCEPTED → NEW
lub
DRAFT → ACCEPTED → CANCELED
Anulowanie przez integratora
Możliwe wyłącznie w statusie:
ACCEPTED
Po przejściu do NEW:
anulowanie nie jest już operacją integracyjną,
obowiązują procesy magazynowe (np. wstrzymanie, cofnięcie, korekta).
4. Komunikacja zwrotna o zmianach statusów
Model rekomendowany – webhook
Po zmianie statusu WMS przekazuje:
ID operacji,
numer magazynowy (dla NEW),
status końcowy,
znaczniki czasu.
Zapewnia to:
natychmiastową synchronizację,
brak potrzeby odpytywania API,
wysoką skalowalność.
Model alternatywny – lista zmian od ostatniego odczytu
System nadrzędny może:
zapamiętać moment ostatniej synchronizacji,
pobierać listę operacji zmienionych od tego czasu,
przetwarzać zmiany idempotentnie.
Model ten jest przeznaczony dla:
systemów bez możliwości obsługi webhooków,
środowisk o ograniczeniach sieciowych,
integracji legacy.
5. Kluczowe zasady projektowe dla integratorów
1. Nie edytuj po ACCEPTED
Po zatwierdzeniu możliwe jest wyłącznie anulowanie.
2. Traktuj WMS jako źródło prawdy operacyjnej
System nadrzędny nie steruje przejściem do NEW.
3. Projektuj komunikację jako asynchroniczną
Natychmiastowa odpowiedź nie jest gwarantowana.
4. Zapewnij idempotencję
Każde żądanie i każde zdarzenie musi być bezpieczne do powtórzenia.
5. Monitoruj przebieg procesu
Rekomendowane metryki:
czas DRAFT → NEW,
udział CANCELED,
brakujące aktualizacje statusów,
ponowienia komunikacji.