API WMS - SPECYFIKACJA FUNKCJONALNO-TECHNICZNA
API WMS Inceptus to RESTful interfejs integracyjny umożliwiający wymianę danych pomiędzy systemem magazynowym a systemami zewnętrznymi, takimi jak ERP, e-commerce czy TMS. API zostało zaprojektowane jako stabilny kontrakt komunikacyjny, operujący na dokumentach i obiektach biznesowych (np. zleceniach, stanach magazynowych, kontrahentach).
Komunikacja realizowana jest w oparciu o protokół HTTPS oraz format JSON. Interfejs zapewnia jednoznacznie zdefiniowaną strukturę danych, walidację wejścia, kontrolę spójności komunikatów oraz obsługę kodów odpowiedzi HTTP zgodnych ze standardem REST. Architektura API została zaprojektowana z myślą o skalowalności, przewidywalności integracji oraz odporności na zmiany po stronie systemów zewnętrznych.
Architektura ogólna
Warstwa usług API WMS Inceptus realizowana jest w modelu REST API (stateless). Każde żądanie zawiera komplet informacji niezbędnych do jego przetworzenia, a serwer nie przechowuje stanu sesji pomiędzy wywołaniami. Takie podejście zapewnia wysoką skalowalność, możliwość równoległego przetwarzania oraz odporność na restart instancji aplikacji.
Architektura systemu oparta jest na wyraźnej separacji odpowiedzialności:
Warstwa HTTP → Warstwa Processing → Polityki → Baza danych
Warstwa HTTP
Odpowiada za:
obsługę żądań POST,
deserializację danych JSON,
walidację techniczną schematu,
autoryzację wstępną,
zwracanie odpowiedzi HTTP.
Warstwa ta nie zawiera logiki biznesowej.
Warstwa Processing
Stanowi centralny punkt realizacji operacji.
Odpowiada za:
orkiestrację procesu,
wywołanie odpowiednich polityk,
kontrolę spójności operacji,
przygotowanie modelu zapisu lub odpowiedzi.
Każda operacja realizowana jest jako odseparowana jednostka przetwarzania (use case / command).
Warstwa Polityk
Warstwa ta zawiera reguły kontrolne i decyzyjne, w tym:
RBAC (Role-Based Access Control),
reguły przejść statusów,
walidację biznesową,
kontrolę dopuszczalnych operacji.
Polityki są w pełni odseparowane od kontrolerów HTTP i logiki dostępu do danych, co umożliwia ich niezależne testowanie oraz rozwój.
Usługi kartotek towarowych
Zakres funkcjonalny
Usługa umożliwia:
tworzenie kartotek towarowych,
aktualizację poprzez identyfikator techniczny (ItemId),
kontrolę wersji (Revision++),
soft delete,
historię wersji (snapshot),
porównanie wersji (diff),
kontrolę pól poprzez politykę,
audyt zmian.
Krytyczne założenie identyfikacyjne
Aktualizacja kartoteki odbywa się wyłącznie poprzez ItemId.
W operacjach magazynowych integrator przekazuje Code, który jest mapowany na ItemId.
Zapewnia to:
stabilność referencyjną,
odporność na nadpisywanie SKU w systemach e-commerce,
brak utraty relacji historycznych.
Wersjonowanie
Każda zmiana:
zwiększa numer Revision,
zapisuje snapshot poprzedniego stanu,
podlega optimistic concurrency (HTTP 409 przy konflikcie).
Historia i audyt
System przechowuje:
pełny snapshot każdej wersji,
znacznik czasu obowiązywania,
użytkownika dokonującego zmiany,
różnice między wersjami (diff).
Usługi operacji magazynowych
Etapowa transmisja zleceń
Integrator przesyła nagłówek (status IMPORT).
Następnie przesyła pozycje.
Po zakończeniu zmienia status na ACCEPTED.
Dopiero po ACCEPTED system przeprowadza walidację biznesową.
Maszyna stanów
Operacje podlegają kontrolowanej maszynie stanów:
IMPORT → ACCEPTED → NEW → RELEASED → IN_PROGRESS → COMPLETED
Możliwe przejście do CANCELLED.
Zmiana statusu podlega polityce przejść.
Monitoring zmian statusów
System udostępnia usługę:
pobranie pierwszych 100 operacji ze zmianą statusu,
operacje pozostają w kolejce do momentu ACK,
mechanizm potwierdzenia usuwa wpis z kolejki.
Zapewnia to niezawodność integracji.
Dynamiczna kontrola dostępu (RBAC)
Model
System wykorzystuje konfigurowalny RBAC oparty o bazę danych:
Users → Roles → Permissions → FieldAccessRules
Polityka nie jest zakodowana w aplikacji, lecz konfigurowana.
Zakres kontroli
RBAC umożliwia kontrolę:
dostępu do operacji,
dostępu do wybranych pól,
dostępu do partii i dat ważności,
dostępu do danych workflow,
dostępu per tenant.
Cechy rozwiązania
brak konieczności redeploy przy zmianie roli,
możliwość panelu administracyjnego,
pełna audytowalność zmian uprawnień,
zgodność z zasadą minimalnego dostępu (least privilege).
Bezpieczeństwo
Warstwa usług wspiera:
JWT
role i uprawnienia,
kontrolę dostępu do pól,
audyt dostępu do danych,
szyfrowanie transmisji (HTTPS),
mechanizmy logowania zdarzeń.
Wymagania niefunkcjonalne
Integralność
optimistic concurrency,
kontrola przejść statusów,
brak możliwości nadpisania danych bez zgodnej wersji.
Skalowalność
architektura bezstanowa,
gotowość pod poziome skalowanie,
możliwość pracy w środowisku chmurowym.
Audytowalność
historia operacji,
historia kartotek,
historia zmian statusów,
log dostępu do danych.
Integracyjność
REST
JSON
OpenAPI 3.0
możliwość rozszerzenia o event-driven (message broker)
Podsumowanie
Warstwa usług API WMS zapewnia:
✔ kontrolę integralności danych referencyjnych
✔ kontrolowaną maszynę stanów operacji
✔ etapową transmisję zlecenia
✔ monitoring zmian statusów
✔ pełne wersjonowanie kartoteki towarowej
✔ konfigurowalny RBAC dla pobierania danych operacji magazynowej
✔ multi-tenant ready