API WMS - OPERACJE MAGAZYNOWE

Operacje magazynowe w API WMS umożliwiają przekazywanie do systemu magazynowego zleceń logistycznych generowanych w ERP, takich jak zlecenia wydań, awizacje przyjęć oraz przesunięcia międzymagazynowe. API WMS zapewnia ustandaryzowany model danych do obsługi dokumentów magazynowych, pozycji towarowych oraz stron operacji, gwarantując spójność informacji pomiędzy systemami. Dzięki integracji przez REST API WMS możliwe jest automatyczne uruchamianie procesów magazynowych – od przyjęcia i kompletacji po wydanie – przy zachowaniu pełnej kontroli, wersjonowania i audytowalności komunikacji.

Zakres funkcjonalny

System zapewnia:

  1. Tworzenie nagłówka operacji (status IMPORT)

  2. Dodawanie pozycji do operacji

  3. Zmianę statusu na ACCEPTED po zakończeniu przesyłania

  4. Walidację integralności operacji

  5. Kontrolę przejść statusów

  6. Monitoring zmian statusów (z mechanizmem ACK)

  7. Kontrolę zmian statusu przez system zewnętrzny

  8. Pełną historię zmian statusów

Architektura API WMS zlecania operacji

Model danych

Identyfikacja

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut elit tellus, luctus nec ullamcorper mattis, pulvinar dapibus leo.

Tabela przesuwna w poziomie

Pole Charakter Opis
OperationId Techniczne ID Jedyny identyfikator operacji
ReferenceNumber Identyfikator biznesowy Numer zewnętrzny (ERP / OMS)
OperationType Typ INBOUND / OUTBOUND / TRANSFER

OperationId jest kluczem technicznym i nie podlega zmianie.

Wersjonowanie (Revision++)

Zmiana danych nagłówka operacji:

  • zwiększa numer wersji (Revision++)

  • podlega kontroli optimistic concurrency

  • zapobiega nadpisaniu równoległych zmian

W przypadku niezgodności wersji system zwraca błąd 409 Conflict.

Walidacja wielopoziomowa

System realizuje trzystopniową walidację:

  1. Techniczna (IMPORT)

  2. Kompletność (ACCEPTED)

  3. Biznesowa (NEW)

Walidacja obejmuje m.in.:

  • istnienie pozycji

  • poprawność ilości

  • zgodność (batch/expiry)

  • wymagane strony operacji (SUPPLIER, SHIP_TO itd.)

Historia zmian

Zmiany statusów

System przechowuje historię:

  • poprzedni status

  • nowy status

  • data zmiany

  • użytkownik zmieniający

Zapewnia to pełną audytowalność procesu.

Zmiany danych operacji

W systemie WMS każda zmiana danych nagłówkowych operacji (np. OperationType, ReferenceNumber, kontrahent, daty, status) podlega pełnemu monitorowaniu i kontroli zgodności z obowiązującą polityką operacyjną.

Kontrola zgodności z polityką

Każda próba modyfikacji danych nagłówkowych jest weryfikowana pod kątem:

  • statusu operacji (np. brak możliwości zmiany po rozpoczęciu realizacji),

  • spójności procesowej (np. brak zmiany typu operacji po wygenerowaniu zadań),

  • reguł biznesowych (np. blokada zmiany kontrahenta po rezerwacji towaru),

  • uprawnień użytkownika (kontrola ról i zakresu odpowiedzialności).

Jeżeli zmiana narusza politykę systemową, operacja jest odrzucana, a użytkownik otrzymuje komunikat walidacyjny.

Rejestracja (logowanie) zmian

Każda zaakceptowana zmiana jest zapisywana w rejestrze audytowym (audit log), który obejmuje:

  • identyfikator operacji,

  • nazwę zmienionego pola,

  • wartość poprzednią i nową,

  • identyfikator użytkownika,

  • znacznik czasu,

  • źródło zmiany (UI / API / integracja).

Dzięki temu możliwe jest:

  • pełne odtworzenie historii operacji,

  • analiza przyczyn zmian,

  • wsparcie procesów kontrolnych i audytowych.

Transparentność i bezpieczeństwo

Mechanizm monitorowania zmian:

  • zwiększa bezpieczeństwo operacyjne magazynu,

  • ogranicza ryzyko nieautoryzowanych modyfikacji,

  • zapewnia zgodność z wymaganiami audytowymi i kontrolą wewnętrzną.

Takie podejście jest szczególnie istotne w środowiskach zintegrowanych z ERP/OMS, gdzie operacja magazynowa stanowi element szerszego łańcucha procesowego.

Specyfikacja struktury danych

Operation

Tabela przesuwna w poziomie

Pole Typ danych Wymagalność Opis
operationId long ✔ Techniczny identyfikator operacji w systemie nadrzędnym. Jednoznacznie identyfikuje dokument w WMS.
revision int ✔ Numer rewizji operacji. Pozwala kontrolować wersjonowanie dokumentu i wykrywać konflikty aktualizacji.
operationType enum ✔ Typ operacji: INBOUND, OUTBOUND, TRANSFER. Określa logikę biznesową przetwarzania.
warehouseCode string ✔ Identyfikator magazynu, którego dotyczy operacja.
referenceNumber string ✔ Główny numer referencyjny dokumentu (np. SO, PO).
externalReference string ✖ Dodatkowe odniesienie do systemu zewnętrznego.
priority enum ✖ Priorytet realizacji (np. LOW, STANDARD, HIGH, URGENT). Wpływa na kolejność przetwarzania.
plannedDate datetime ✖ Planowana data realizacji operacji.
currency string (ISO 4217) ✖ Kod waluty dokumentu (np. PLN, EUR).
totalWeight decimal(18,4) ✖ Łączna waga operacji (wyliczana lub przekazana referencyjnie).
totalVolume decimal(18,4) ✖ Łączna objętość operacji.
createdAt datetime ✔ Data utworzenia dokumentu w systemie źródłowym.
createdBy string ✔ Identyfikator użytkownika lub systemu tworzącego dokument.
attributes array<Attribute> ✖ Mechanizm rozszerzeń umożliwiający dodawanie pól niestandardowych.

Line

Tabela przesuwna w poziomie

Pole Typ danych Wymagalność Opis
lineId long ✔ Techniczny identyfikator linii operacji.
lineNumber int ✔ Numer porządkowy linii w dokumencie.
itemId long ✔ Identyfikator towaru (SKU) zgodny z kartoteką WMS.
quantity decimal(18,4) ✔ Ilość planowana do realizacji.
uom string ✔ Jednostka miary (np. PCS, KG).
batchNumber string ✖ Numer partii (zgodny z GS1 AI 10).
expiryDate date ✖ Data ważności (AI 17).
productionDate date ✖ Data produkcji (AI 11).
countryOfOrigin string ✖ Kraj pochodzenia towaru (ISO 3166-1).
fulfillmentType enum ✖ Sposób realizacji: FULL, PARTIAL, BACKORDER_ALLOWED.
attributes array<Attribute> ✖ Atrybuty rozszerzające poziomu linii.

Party

Tabela przesuwna w poziomie

Pole Typ danych Wymagalność Opis
partyId long ✔ Identyfikator strony operacji.
partyType enum ✔ Typ strony: SUPPLIER, CUSTOMER, SHIP_FROM, SHIP_TO, CARRIER, OWNER.
name string ✔ Nazwa podmiotu.
taxId string ✖ Numer identyfikacji podatkowej.
gln string ✖ Global Location Number (GS1).
externalCode string ✖ Kod zewnętrzny partnera.
address Address ✔ Struktura adresowa powiązana z podmiotem.
contactName string ✖ Osoba kontaktowa.
email string ✖ Adres e-mail kontaktowy.
phone string ✖ Numer telefonu.
attributes array<Attribute> ✖ Atrybuty rozszerzające poziomu partnera.

Address

Tabela przesuwna w poziomie

Pole Typ danych Wymagalność Opis
street string ✔ Ulica i numer budynku.
city string ✔ Miasto.
postalCode string ✔ Kod pocztowy.
region string ✖ Region / województwo.
country string (ISO 3166-1 alpha-2) ✔ Dwuliterowy kod kraju.
latitude decimal(9,6) ✖ Szerokość geograficzna.
longitude decimal(9,6) ✖ Długość geograficzna.
addressType enum ✖ Typ adresu: LEGAL, DELIVERY, BILLING.
note string ✖ Dodatkowe informacje logistyczne (np. godziny dostawy).

Reference

Tabela przesuwna w poziomie

Pole Typ danych Wymagalność Opis
referenceId long ✔ Techniczny identyfikator referencji.
referenceType enum ✔ Typ dokumentu: PO, SO, ASN, INVOICE, CONTRACT.
referenceNumber string ✔ Numer dokumentu referencyjnego.
referenceDate date ✖ Data dokumentu źródłowego.
sourceSystem string ✖ Nazwa systemu źródłowego.
relationType enum ✖ Relacja (PARENT, CHILD, RELATED).

Attribute (mechanizm rozszerzeń)

Tabela przesuwna w poziomie

Pole Typ danych Wymagalność Opis
code string ✔ Kod atrybutu.
value string ✔ Wartość atrybutu.
scope enum ✔ Zakres obowiązywania: HEADER, LINE, PARTY, ITEM.

Dane przykładowe

Poniższy przykład przedstawia model danych operacji magazynowej przekazywanej z systemu nadrzędnego (np. ERP) do systemu WMS w ramach integracji API. Struktura obejmuje wyłącznie dane referencyjne i planistyczne, nie zawiera natomiast informacji wykonawczych generowanych w trakcie realizacji operacji przez WMS.

Model operacji został zaprojektowany zgodnie z zasadą rozdzielenia warstw:

  • warstwa integracyjna (ERP → WMS) przekazuje dane dokumentu, strony operacji, referencje oraz planowane ilości,

  • warstwa wykonawcza (WMS) odpowiada za realizację operacji, alokacje, potwierdzenia ilości, obsługę partii, numerów seryjnych oraz rejestrowanie postępu.

W przykładzie zastosowano podejście kanoniczne (canonical contract), w którym:

  • operacja stanowi agregat główny (WarehouseOperation),

  • struktury takie jak parties, references oraz lines są zagnieżdżone bezpośrednio w operacji,

  • wykorzystywane są kody biznesowe (np. warehouseCode) zamiast identyfikatorów technicznych,

  • pozycje operacji (lines) znajdują się na końcu struktury, co zwiększa czytelność i jednoznaczność kontraktu.

Przedstawiony model może zostać wykorzystany jako wzorzec implementacyjny dla endpointów typu create / update operacji magazynowej w API WMS.

{
„operationId”: 3000456,
„revision”: 2,
„operationType”: „OUTBOUND”,
„status”: „RELEASED”,
„warehouseCode”: „PL-WAW-01”,
„referenceNumber”: „SO-2026-000350”,
„externalReference”: „ERP-998877”,
„priority”: „HIGH”,
„plannedDate”: „2026-04-15T07:00:00Z”,
„currency”: „PLN”,
„totalWeight”: 185.7500,
„totalVolume”: 2.4500,
„createdAt”: „2026-04-14T16:32:10Z”,
„createdBy”: „ERP”,

„attributes”: [
{
„code”: „SALES_CHANNEL”,
„value”: „B2B”,
„scope”: „HEADER”
}
],

„parties”: [
{
„partyType”: „CUSTOMER”,
„externalCode”: „CUST-001”,
„name”: „ABC Sp. z o.o.”,
„taxId”: „PL5250000000”,
„gln”: „5901234000005”,
„contactName”: „Jan Kowalski”,
„email”: „logistyka@abc.pl”,
„phone”: „+48 600 000 000”,
„address”: {
„street”: „ul. Logistyczna 15”,
„city”: „Warszawa”,
„postalCode”: „01-234”,
„region”: „Mazowieckie”,
„country”: „PL”,
„addressType”: „DELIVERY”
}
}
],

„references”: [
{
„referenceType”: „SO”,
„referenceNumber”: „SO-2026-000350”,
„referenceDate”: „2026-04-14”,
„sourceSystem”: „ERP”,
„relationType”: „PARENT”
}
],

„lines”: [
{
„lineNumber”: 1,
„itemId”: 5001,
„quantity”: 120.000000,
„uom”: „PCS”,
„batchNumber”: „BATCH-2026-04-A”,
„productionDate”: „2026-03-10”,
„expiryDate”: „2027-03-10”,
„countryOfOrigin”: „PL”,
„fulfillmentType”: „FULL”
},
{
„lineNumber”: 2,
„itemId”: 5002,
„quantity”: 25.000000,
„uom”: „PCS”,
„fulfillmentType”: „PARTIAL”
}
]
}

Transmisja danych - event envelope

Warstwa transportowa komunikatu

Event Envelope stanowi zewnętrzną warstwę komunikatu przesyłanego pomiędzy systemami (np. ERP → WMS, WMS → 3PL, WMS → ESB). Jego zadaniem nie jest przenoszenie danych biznesowych operacji, lecz zapewnienie kontroli transportowej, wersjonowania oraz bezpieczeństwa przetwarzania komunikatu.

W modelu integracyjnym rozróżniamy:

  • Payload biznesowy – dane operacji magazynowej (WarehouseOperation),

  • Event Envelope – metadane komunikatu odpowiedzialne za jego obsługę w warstwie integracyjnej.

Cel stosowania Event Envelope

Wprowadzenie warstwy eventowej pozwala:

  • zapewnić idempotentność przetwarzania komunikatów,

  • kontrolować wersjonowanie kontraktu,

  • śledzić komunikację między systemami,

  • wspierać architekturę event-driven,

  • separować dane operacyjne od mechanizmów transportowych.

Struktura danych

Tabela przesuwna w poziomie

Pole Typ danych Wymagalność Opis
eventId UUID ✔ Unikalny identyfikator komunikatu. Służy do śledzenia komunikacji, audytu oraz eliminowania duplikatów na poziomie transportowym.
eventType string ✔ Typ zdarzenia określający kontekst operacyjny, np. operation.created, operation.updated, operation.cancelled. Pozwala WMS interpretować charakter komunikatu.
eventTimestamp datetime (UTC) ✔ Data i czas wygenerowania komunikatu w strefie UTC. Wykorzystywany do sekwencjonowania zdarzeń i analizy czasowej.
correlationId string ✖ Identyfikator powiązania pomiędzy systemami (np. numer dokumentu ERP). Ułatwia śledzenie całego cyklu życia operacji.
tenantId string ✔ Identyfikator klienta w architekturze multi-tenant. Pozwala separować dane pomiędzy różnymi podmiotami.
schemaVersion string ✔ Wersja kontraktu integracyjnego (np. 2.1). Zapewnia kontrolę kompatybilności.
idempotencyKey string ✔ Klucz idempotencji zapobiegający wielokrotnemu przetworzeniu tego samego komunikatu. WMS musi gwarantować przetwarzanie dokładnie raz.
payload WarehouseOperation ✔ Właściwa treść operacji magazynowej.

FAQ – Event Envelope w API WMS

1️⃣ Czym jest Event Envelope w integracji WMS?

Event Envelope to zewnętrzna warstwa komunikatu, która otacza dane biznesowe operacji magazynowej (payload). Zawiera metadane transportowe takie jak identyfikator zdarzenia, wersja schematu czy klucz idempotencji. Nie przenosi logiki operacyjnej, lecz zapewnia kontrolę komunikacji między systemami.

2️⃣ Czy Event Envelope jest obowiązkowy?

Nie zawsze.
W prostych integracjach synchronicznych REST (request/response) może zostać pominięty. Jest natomiast rekomendowany w integracjach asynchronicznych, event-driven oraz w architekturach opartych o message broker (np. Kafka, RabbitMQ).

3️⃣ Jaką rolę pełni idempotencyKey?

idempotencyKey zabezpiecza system przed wielokrotnym przetworzeniem tego samego komunikatu. Jest szczególnie istotny w przypadku retransmisji zdarzeń lub chwilowych problemów sieciowych.

4️⃣ Czy Event Envelope zastępuje dane operacyjne?

Nie.
Event Envelope zawiera wyłącznie metadane transportowe. Dane operacyjne, takie jak operacja magazynowa, linie dokumentu czy strony operacji, znajdują się w sekcji payload.

5️⃣ Dlaczego warto stosować wersjonowanie schematu (schemaVersion)?

schemaVersion umożliwia równoległe wspieranie kilku wersji kontraktu integracyjnego. Dzięki temu możliwe jest bezpieczne rozwijanie API bez przerywania działania istniejących integracji.

6️⃣ Jak Event Envelope wspiera architekturę multi-tenant?

Pole tenantId pozwala jednoznacznie określić, do którego klienta lub środowiska należy komunikat. Jest to kluczowe w systemach WMS obsługujących wielu klientów w jednej instancji (model multi-tenant).

Get A Quote
Get A Quote