API WMS - kartoteka towarowa
API WMS – kartoteka towarowa to kluczowy element nowoczesnej integracji ERP z magazynem. Dzięki API WMS możliwa jest pełna synchronizacja danych produktów, kodów kreskowych (EAN/GTIN), jednostek logistycznych, wymiarów i wag w systemie WMS. Moduł API WMS kartoteka towarowa umożliwia automatyczne przekazywanie danych referencyjnych z ERP do magazynu, zapewniając spójność informacji i jednoznaczną identyfikację towarów w procesach skanerowych. REST API WMS wspiera integrację produktów, opakowań zbiorczych oraz parametrów operacyjnych, co pozwala na automatyzację przyjęć, kompletacji, pakowania i wysyłki. Wdrożenie API WMS w obszarze kartoteki towarowej minimalizuje błędy integracyjne, przyspiesza start operacyjny magazynu i zwiększa skalowalność procesów logistycznych.
Zakres funkcjonalny
API zapewnia:
Tworzenie kartoteki towarowej
Aktualizację kartoteki z kontrolą wersji (optimistic concurrency)
Oznaczenie kartoteki jako usuniętej (soft delete)
Pobieranie historii wersji
Porównanie dowolnych dwóch wersji (diff)
Kontrolę możliwości edycji wybranych pól
Monitoring zmian
Model danych – kartoteka towarowa
Identyfikacja
Zestawienie
| Pole | Charakter | Opis |
|---|---|---|
| ItemId | Techniczne ID | Jedyny identyfikator kartoteki |
| Code | Identyfikator biznesowy | Może podlegać zmianie wg polityki |
| Revision | Wersja | Numer wersji obiektu |
ItemId jest niezmienny i stanowi klucz referencyjny w systemie.
Wersjonowanie
System realizuje:
mechanizm optimistic concurrency
przy każdej zmianie: Revision++
konflikt wersji skutkuje HTTP 409
Zapobiega to nadpisaniu równoległych zmian.
Historia zmian (Versioning)
System utrzymuje:
snapshot każdej wersji
znacznik czasu obowiązywania (ValidFrom, ValidTo)
użytkownika dokonującego zmiany
pełny stan obiektu
Umożliwia to:
odtworzenie stanu w dowolnym momencie
audyt zmian
analizę regresji
przywrócenie wcześniejszej wersji
Mechanizm różnic (Diff)
System udostępnia mechanizm porównania dwóch wersji kartoteki.
Cechy:
automatyczny (reflection-based)
obsługuje pola zagnieżdżone
obsługuje kolekcje
ignoruje pola techniczne (np. Revision)
prezentuje nazwy biznesowe (np. „Kod towaru”)
Poniższa tabela prezentuje przykładowe wartości loga.
Kolumny są przesuwalne w poziomie
| Pole | Poprzednia wartość | Nowa wartość |
|---|---|---|
| Kod towaru | BUT-42 | BUT-42-2026 |
| Waga netto | 1.20 | 1.30 |
Soft Delete
Usunięcie kartoteki realizowane jest w modelu soft delete, poprzez:
ustawienie flagi
IsDeleted,zwiększenie numeru wersji (
Revision),zapis historii zmian w mechanizmie audytu.
Kartoteka nie jest fizycznie usuwana z bazy danych w momencie operacji integracyjnej.
Pozostaje w systemie dla celów referencyjnych, zachowania integralności danych oraz pełnej ścieżki audytowej.
Trwałe usunięcie (physical delete) może zostać wykonane wyłącznie po stronie systemu WMS i dotyczy wyłącznie kartotek, które nie posiadają żadnych powiązanych operacji magazynowych (np. przyjęć, wydań, rezerwacji, stanów historycznych).
W przypadku kartotek, dla których zarejestrowano operacje magazynowe, fizyczne usunięcie nie jest możliwe ze względu na konieczność zachowania spójności referencyjnej oraz historii operacyjnej.
Operacja trwałego usunięcia nie stanowi elementu interfejsu API integracyjnego.
Kontrola możliwości edycji pól
System umożliwia:
zdefiniowanie polityki zmian per pole
zablokowanie zmiany wybranych pól
rozszerzenie polityki per tenant / per rola
Przykładowo:
ItemId – niezmienny
Code – opcjonalnie zmienny
Revision – kontrolowany przez system
Struktury danych kartoteki
Oznaczenia określają wymagania dla komunikatu wejściowego API.
✔ – wymagane przy zapisie
✖ – opcjonalne
🔒 – tylko do odczytu (zwracane przez API)
Wymagalność odnosi się do struktury komunikatu wejściowego (request).
Pola oznaczone symbolem 🔒 są generowane lub utrzymywane przez system i
występują wyłącznie w odpowiedzi API (response).
Karta towarowa/produktowa (Item)
Reprezentuje podstawową kartotekę towarową.
Zawiera dane identyfikacyjne oraz referencję do parametrów operacyjnych.
Wymiary i objętość odnoszą się do jednostki podstawowej (uom).
Specyfikacja pól jest przesuwalna w poziomie
| Pole | Typ danych | Wymagalność | Opis |
|---|---|---|---|
| itemId | long | 🔒 | Techniczny identyfikator towaru (PK). |
| code | varchar(50) | ✔ | Wewnętrzny kod towaru (unikalny). |
| name | varchar(255) | ✔ | Nazwa towaru. |
| uom | varchar(20) | ✔ | Jednostka podstawowa ewidencji. |
| net_weight | decimal(12,3) | ✖ | Waga netto jednostki podstawowej. |
| gross_weight | decimal(12,3) | ✖ | Waga brutto jednostki podstawowej. |
| weight_uom | varchar(10) | ✖ | Jednostka miary wagi (np. KG). |
| length | decimal(12,3) | ✖ | Długość jednostki podstawowej. |
| width | decimal(12,3) | ✖ | Szerokość jednostki podstawowej. |
| height | decimal(12,3) | ✖ | Wysokość jednostki podstawowej. |
| dimension_uom | varchar(10) | ✖ | Jednostka miary wymiarów (MM, CM, M). |
| volume | decimal(16,6) | ✖ | Objętość jednostki podstawowej (np. m³). |
| volume_uom | varchar(10) | ✖ | Jednostka miary objętości (np. M3, CM3). |
| status | enum(ACTIVE, BLOCKED, ARCHIVED) | ✔ | Status operacyjny. |
| logistic_group | varchar(10) | ✖ | Kod grupy logistycznej. |
| note | text | ✖ | Informacje dodatkowe. |
| created_at | datetime | 🔒 | Data utworzenia. |
| updated_at | datetime | 🔒 | Data modyfikacji. |
Kody EAN (ItemBarcode)
Reprezentuje wszystkie kody kreskowe przypisane do towaru:
kod jednostki podstawowej,
kody opakowań zbiorczych,
aliasy handlowe,
jednostki logistyczne (np. karton, paleta).
Jedno źródło prawdy dla identyfikacji towaru. Wymiary i objętość odnoszą się do całego opakowania reprezentowanego przez barcode.
Specyfikacja pól jest przesuwalna w poziomie
| Pole | Typ danych | Wymagalność | Opis |
|---|---|---|---|
| itemId | long | ✔ | Id towaru (FK → Item.itemId). |
| barcode | varchar(20) | ✔ | Kod jednostki logistycznej. |
| barcode_type | varchar(20) | ✖ | Typ kodu. |
| is_primary | boolean | ✔ | Czy kod jednostki podstawowej. |
| quantity | decimal(12,3) | ✖ | Ilość jednostek podstawowych w opakowaniu. |
| uom | varchar(20) | ✖ | Jednostka logistyczna (BOX, PAL). |
| net_weight | decimal(12,3) | ✖ | Waga netto całego opakowania. |
| gross_weight | decimal(12,3) | ✖ | Waga brutto opakowania. |
| weight_uom | varchar(10) | ✖ | Jednostka miary wagi. |
| length | decimal(12,3) | ✖ | Długość opakowania. |
| width | decimal(12,3) | ✖ | Szerokość opakowania. |
| height | decimal(12,3) | ✖ | Wysokość opakowania. |
| dimension_uom | varchar(10) | ✖ | Jednostka miary wymiarów. |
| volume | decimal(16,6) | ✖ | Objętość całego opakowania. |
| volume_uom | varchar(10) | ✖ | Jednostka miary objętości. |
| created_at | datetime | 🔒 | Data utworzenia. |
| updated_at | datetime | 🔒 | Data modyfikacji. |
Przykładowa struktura danych
Poniższy przykład przedstawia strukturę danych przekazywaną do Inceptus WMS w celu synchronizacji kartoteki towarowej.
Model zakłada:
Itemjako agregat główny,zagnieżdżoną strukturę
barcodesreprezentującą wszystkie kody kreskowe przypisane do towaru,przekazywanie wyłącznie kodu grupy logistycznej (
logistic_group_code), przy założeniu, że grupa jest wcześniej skonfigurowana w systemie WMS,pełne dane wymiarowe i wagowe zarówno dla jednostki podstawowej, jak i dla opakowań logistycznych.
W przykładzie zaprezentowano:
dwa towary (
Item),różne grupy logistyczne przekazywane referencyjnie,
jednostkę podstawową (
is_primary = true),opakowanie zbiorcze (
quantity_in_barcode > 1),komplet parametrów wagowych i objętościowych,
status operacyjny towaru i kodów kreskowych.
Struktura odzwierciedla podejście, w którym:
ERP dostarcza dane referencyjne,
WMS jako warstwa sterowania operacjami magazynowymi interpretuje parametry logistyczne na podstawie
logistic_group,kody kreskowe stanowią jedyne źródło identyfikacji w procesach skanerowych.
Przykład ma charakter poglądowy i może zostać wykorzystany jako wzorzec dla implementacji endpointu typu upsert Item.
{
„items”: [
{
„code”: „FOOD-100”,
„name”: „Kawa ziarnista 1kg”,
„uom”: „PCS”,
„net_weight”: 1.000,
„gross_weight”: 1.050,
„weight_uom”: „KG”,
„length”: 250,
„width”: 120,
„height”: 80,
„dimension_uom”: „MM”,
„volume”: 0.0024,
„volume_uom”: „M3”,
„status”: „ACTIVE”,
„logistic_group”: „FOOD”,
„note”: „Przechowywać w suchym miejscu”,
„created_at”: „2026-02-10T08:00:00Z”,
„updated_at”: „2026-02-10T08:00:00Z”,
„barcodes”: [
{
„barcode”: „5909876543210”,
„barcode_type”: „EAN13”,
„is_primary”: true,
„quantity_in_barcode”: 1,
„uom”: „PCS”,
„net_weight”: 1.000,
„gross_weight”: 1.050,
„weight_uom”: „KG”,
„length”: 250,
„width”: 120,
„height”: 80,
„dimension_uom”: „MM”,
„volume”: 0.0024,
„volume_uom”: „M3”,
„status”: „ACTIVE”,
„created_at”: „2026-02-10T08:00:00Z”,
„updated_at”: „2026-02-10T08:00:00Z”
}
]
},
{
„code”: „PROD-001”,
„name”: „Kubek ceramiczny 300ml”,
„uom”: „PCS”,
„net_weight”: 0.320,
„gross_weight”: 0.350,
„weight_uom”: „KG”,
„length”: 90,
„width”: 90,
„height”: 100,
„dimension_uom”: „MM”,
„volume”: 0.00081,
„volume_uom”: „M3”,
„status”: „ACTIVE”,
„logistic_group”: „STD”,
„note”: „Produkt kruchy – wymaga ostrożnego pakowania”,
„created_at”: „2026-02-10T08:00:00Z”,
„updated_at”: „2026-02-10T08:00:00Z”,
„barcodes”: [
{
„barcode”: „5901234123457”,
„barcode_type”: „EAN13”,
„is_primary”: true,
„quantity_in_barcode”: 1,
„uom”: „PCS”,
„net_weight”: 0.320,
„gross_weight”: 0.350,
„weight_uom”: „KG”,
„length”: 90,
„width”: 90,
„height”: 100,
„dimension_uom”: „MM”,
„volume”: 0.00081,
„volume_uom”: „M3”,
„status”: „ACTIVE”,
„created_at”: „2026-02-10T08:00:00Z”,
„updated_at”: „2026-02-10T08:00:00Z”
},
{
„barcode”: „5901234123464”,
„barcode_type”: „ITF14”,
„is_primary”: false,
„quantity_in_barcode”: 12,
„uom”: „BOX”,
„net_weight”: 3.840,
„gross_weight”: 4.200,
„weight_uom”: „KG”,
„length”: 400,
„width”: 300,
„height”: 250,
„dimension_uom”: „MM”,
„volume”: 0.03,
„volume_uom”: „M3”,
„status”: „ACTIVE”,
„created_at”: „2026-02-10T08:00:00Z”,
„updated_at”: „2026-02-10T08:00:00Z”
} ] } ] }
FAQ - najczęściej zadawane pytania
1️⃣ Czy grupa logistyczna jest przesyłana w payloadzie?
Nie. Integrator przekazuje wyłącznie logistic_group. Grupy logistyczne są konfigurowane bezpośrednio w systemie WMS i tam następuje walidacja kodu.
2️⃣ Czy kod kreskowy musi być globalnie unikalny?
Tak. Ten sam EAN nie może być przypisany do dwóch różnych towarów. System wymusza unikalność na poziomie bazy danych.
3️⃣ Czy może istnieć więcej niż jeden is_primary = true?
Nie. Dla jednego itemId może istnieć maksymalnie jeden kod główny. Naruszenie tej reguły skutkuje błędem walidacji.
4️⃣ Czy objętość musi być przesyłana, jeśli podano wymiary?
Nie jest to obowiązkowe. Objętość może być wyliczana na podstawie zależności:
V=length×width×height
W praktyce rekomenduje się jej zapis w systemie dla zwiększenia wydajności operacyjnej.