API integracyjne Studio WMS.net - jak system ERP przekazuje zlecenia i odczytuje stany magazynu

API integracyjne Studio WMS.net pozwala systemowi handlowemu przekazywać do magazynu zlecenia przyjęcia i wydania, a w drugą stronę odczytywać stany magazynowe i realizację zleceń. Z interfejsu korzysta program, nie człowiek - najczęściej system ERP albo platforma e-commerce. Strona opisuje zakres operacji, reguły walidacji zlecenia, kody błędów i pozostałe kanały wymiany danych. Adresy metod i nazwy pól zawiera dokumentacja techniczna przekazywana przy wdrożeniu.

Kolumny tabeli podają numer ZWZ i datę zlecenia, symbol magazynu, osobę odpowiedzialną oraz kontrahenta z odbiorcą; w bazie demonstracyjnej kolejka liczy 41 zleceń. Zlecenie przekazane przez API jest zwykłym zleceniem wydania ZWZ albo przyjęcia ZPZ. Kierownik obsługuje je w tych samych rejestrach modułów Wydania i Przyjęcia co zlecenia wpisane w formularzu, złożone w koszyku panelu klienta albo wczytane z pliku.

Jak działa wymiana danych przez API

Komunikacja odbywa się po protokole HTTP. System zewnętrzny wysyła żądanie POST, którego treścią jest dokument JSON, i dostaje odpowiedź w formacie JSON. Ten sam schemat dotyczy zapisów, np. utworzenia zlecenia, i odczytów, np. pobrania stanów. Gdy żądania nie da się wykonać, odpowiedź ma kod błędu HTTP i komunikat, więc program po drugiej stronie może zareagować bez udziału człowieka.

Z API korzysta osobne konto techniczne integracji, a nie konto pracownika magazynu. Konto jest przypisane do jednego klienta magazynu, czyli deponenta - firmy, której towar magazyn przechowuje. Operator logistyczny, który łączy z magazynem systemy kilku klientów, konfiguruje osobne konto dla każdego z nich.

Reguła inicjatywy. Operacje API uruchamia system zewnętrzny, wysyłając żądanie. O tym, że magazyn wydał towar, system handlowy dowiaduje się, odczytując zlecenie z realizacją pozycji albo dokumenty magazynowe. Częstotliwość takich odczytów trzeba więc zaplanować w projekcie integracji.

Operacje dostępne w API

Operacje dotyczą zleceń, kartotek, stanów magazynowych i dokumentów. Każda ma w programie ekran, na którym kierownik widzi te same dane.

Stan na wskazaną datę pozwala uzgodnić ewidencję magazynu z systemem księgowym na koniec miesiąca bez ręcznego eksportu. Duże zbiory, np. stan szczegółowy magazynu, API zwraca stronami. Numer awizo zapisany w zleceniu i w dokumencie wskazuje z kolei wszystko, co magazyn przyjął albo wydał w ramach jednej awizacji.

Reguły walidacji zlecenia

Zanim zlecenie trafi do magazynu, Studio WMS.net sprawdza je według czterech reguł. Zlecenie, które nie spełnia którejkolwiek z nich, nie zostaje zapisane, a odpowiedź zawiera kod błędu i komunikat.

• Liczba pozycji - od 1 do 999 w jednym zleceniu. Zamówienie bez pozycji nie przejdzie kontroli, a większe trzeba podzielić na kilka zleceń.
• Termin realizacji - nie wcześniejszy niż chwila wysłania żądania. Formularz ZWZ w przeglądarce przyjmuje datę od wczoraj, API - nie, dlatego zlecenie wysyłane ponownie po awarii połączenia potrzebuje aktualnego terminu.
• Klient - kontrahent, którego towar ma zostać przyjęty albo wydany, musi istnieć w kartotece kontrahentów magazynu przed pierwszym zleceniem.
• SKU - każda pozycja musi wskazywać towar z kartoteką asortymentu. Nowy towar system handlowy zakłada najpierw operacją założenia kartoteki, a dopiero potem wysyła zlecenie.

Kolejność synchronizacji. Zlecenie z towarem, którego magazyn jeszcze nie zna, zostanie odrzucone. Integracja wysyła więc najpierw kartoteki - asortyment i odbiorców - a dopiero potem zlecenia. Kartoteka asortymentu jest zakładana dla magazynu i oddziału, dlatego towar obsługiwany w dwóch magazynach potrzebuje kartoteki w każdym z nich.

Przykład przepływu - zamówienie z systemu handlowego do wydania

Tabela pokazuje drogę zamówienia od systemu handlowego do potwierdzenia wydania. Kroki systemu handlowego wykonuje program przez API, kroki magazynu - kierownik i magazynier.

Zlecenie ZWZ, także przekazane przez API, nie rezerwuje towaru. Stan dostępny zmniejszają dopiero pozycje WZ zapisane w buforze, co opisuje strona wydania WZ w buforze.

Wiersz zamówienia podaje liczbę pozycji i termin, a pasek realizacji porównuje ilość zrealizowaną z zamówioną. W bazie demonstracyjnej zlecenie zatwierdzone ma 1056 sztuk z realizacją równą zeru. Realizacja rośnie dopiero wtedy, gdy magazyn zatwierdza wydania WZ do zlecenia.

Kody odpowiedzi i obsługa błędów

Każda odpowiedź API ma kod HTTP. Kod mówi programowi po stronie systemu handlowego, czy żądanie wykonano, a komunikat w JSON - dlaczego nie.

Jedna baza dla wszystkich kanałów. Zlecenie zapisane przez API trafia do tej samej bazy SQL Server, z której korzystają interfejs przeglądarkowy i urządzenia mobilne. Tabela rejestru w przeglądarce nie odświeża się sama: nowe zlecenie kierownik zobaczy po poleceniu Odśwież albo po zmianie filtra. Aplikacja wymaga bazy SQL Server 2016 SP1 lub nowszej z poziomem zgodności co najmniej 130, bo korzysta z funkcji OPENJSON i STRING_SPLIT.

Dokumentacja OpenAPI dla zespołu integracji

Opis API w formacie Swagger/OpenAPI jest częścią dokumentacji technicznej wdrożenia. Zawiera to, czego publiczna instrukcja celowo nie podaje: adresy operacji, strukturę żądań i odpowiedzi, nazwy pól oraz sposób uwierzytelnienia konta integracji. Dokumentację dostaje zespół, który buduje połączenie po stronie systemu handlowego - programiści Twojej firmy albo dostawca systemu ERP.

Format pliku opisuje specyfikacja OpenAPI. Narzędzia programistyczne generują z takiego opisu kod klienta i pozwalają wysłać próbne żądanie, więc reguły walidacji sprawdza się na danych testowych, a nie na pierwszym prawdziwym zamówieniu.

Inne kanały wymiany danych

API nie jest jedyną drogą. Część systemów handlowych nie ma modułu, który wyśle żądanie HTTP, a część wymienia dane wsadowo, kilka razy na dobę. Studio WMS.net obsługuje wtedy wymianę przez bazę danych albo przez pliki.

Tabele pośrednie oddzielają system handlowy od tabel operacyjnych magazynu. Zapis zlecenia nie konkuruje wtedy o blokady z transakcjami magazynierów, a procedury składowane przenoszą zlecenia do magazynu w jego własnym cyklu. Mechanizm opisuje dokumentacja procedur składowanych SQL Server w Microsoft Learn.

Import z FTP i eksporty o stałej porze uruchamia zewnętrzna usługa harmonogramu, działająca poza aplikacją WWW. Eksport CSV z tabel programu używa średnika i kodowania UTF-8 ze znacznikiem BOM - inaczej niż przecinek z opisu formatu w RFC 4180, co musi uwzględnić program czytający plik.

Menu dzieli import na dokumenty otwarcia, czyli stany początkowe magazynu, oraz kartoteki dostawców, odbiorców, towarów i lokalizacji. Schemat importu mapuje kolumny pliku na pola i może dopisać wartości stałe albo wyliczane. Tryb kontroli sprawdza plik bez zapisu do bazy, a pusty wzorzec do pobrania ma arkusz Instrukcja. Zlecenia z pliku wczytuje osobna pozycja w bloku Inne działania modułów Przyjęcia i Wydania. Szczegóły zawiera strona import danych kartotek, a przygotowanie arkusza opisuje artykuł import Excel do systemu WMS.

Integracje realizowane we wdrożeniu

Kod Studio WMS.net zawiera połączenia z kilkoma zewnętrznymi systemami i usługami. Nie są to przyciski gotowe do użycia zaraz po instalacji: każde połączenie wymaga konfiguracji i danych dostępowych po stronie dostawcy usługi, dlatego jego zakres ustala się we wdrożeniu.

Połączenie z innym systemem ERP buduje się we wdrożeniu z elementów opisanych wyżej: API, tabel pośrednich albo plików. Zakres prac ustala analiza przed uruchomieniem systemu; przebieg projektu opisuje strona wdrożenie systemu WMS w SoftwareStudio, a zapytanie o integrację z konkretnym systemem przyjmuje formularz wyceny Studio WMS.net.