WebAPI to interfejs programistyczny platformy StudioSystem. Wywołania realizowane są w stylu REST, z wynikiem w formacie JSON lub XML, a metody pogrupowano w foldery odpowiadające rolom licencyjnym: WMS, VSS, TCS i RMA. Każde wywołanie wymaga uwierzytelnienia sekcją authData z polami login i password.
Czym jest WebAPI
System magazynowy rzadko pracuje w izolacji. Zamówienia przychodzą z systemu ERP, dane kontrahentów utrzymywane są w innym miejscu, a terminale w magazynie potrzebują dostępu do tych samych stanów magazynowych co przeglądarka. WebAPI jest warstwą, przez którą ten ruch danych się odbywa.
W realizacji API webowych najczęściej spotykanym stylem architektury jest REST, w którym wywołanie usługi wraz z parametrami zakodowane jest w formie adresu URI, a wynik działania zwracany z użyciem formatu JSON lub XML. Platforma StudioSystem korzysta z tego podejścia, udostępniając metody wywoływane żądaniem POST z nagłówkiem content-type: application/json.
Praktyczne konsekwencje istnienia takiego interfejsu są dla wdrożenia dość konkretne:
- Brak plików pośrednich - dane nie muszą wędrować przez katalogi wymiany i pliki CSV odkładane nocą.
- Jedno źródło stanów - operacja z terminala i operacja z przeglądarki trafiają do tej samej tabeli.
- Integracja bez dostępu do bazy - system zewnętrzny nie potrzebuje poświadczeń do serwera SQL.
- Kontrola uprawnień - każde wywołanie jest uwierzytelniane i sprawdzane pod kątem nadanych praw.
- Wspólny kanał dla aplikacji mobilnych - terminale magazynowe korzystają z tego samego interfejsu co ERP.
REST i SOAP
Na platformie współistnieją dwa style komunikacji. Obok metod w stylu REST dostępne są usługi oparte na plikach asmx, czyli ASP.NET Web Service File, wymieniające komunikaty w protokole SOAP. Protokół ten jest niezależny od platformy i języka programowania - odbiorca usługi nie musi wiedzieć nic o modelu obiektów ani technologii, w której usługę zaimplementowano, wystarczy, że potrafi wysyłać i odbierać komunikaty SOAP.
| Cecha | REST | SOAP (pliki asmx) |
|---|---|---|
| Sposób wywołania | Żądanie POST, parametry w adresie i treści | Komunikat SOAP w kopercie XML |
| Format danych | JSON lub XML | XML |
| Typowe zastosowanie | Nowe integracje, aplikacje mobilne | Systemy oczekujące usług sieciowych SOAP |
| Próg wejścia | Niski - wystarczy klient HTTP | Wyższy - wymaga obsługi kopert SOAP |
Przy nowych wdrożeniach naturalnym wyborem jest REST, głównie ze względu na niższy próg wejścia po stronie integratora. Usługi SOAP pozostają jednak istotne wszędzie tam, gdzie po drugiej stronie stoi starszy system, dla którego usługa sieciowa w tym protokole jest formatem natywnym i najtańszym w obsłudze.
Foldery ról licencyjnych
Metody nie są udostępniane jako jeden wspólny zbiór. Podzielono je na wydzielone foldery odpowiadające roli licencji, którą obsługują - podobnie jak transakcje aspx pogrupowane są w katalogi ról użytkowników.
| Folder | Obszar | Powiązany moduł |
|---|---|---|
| WMS | Program magazynowy - stany, przyjęcia, wydania | Transakcje WMS |
| VSS | System awizacyjny wraz z YMS i asystentem bramy | Transakcje YMS |
| TCS | Zarządzanie narzędziownią oraz CMMS | Transakcje TCS |
| RMA | System reklamacyjny | Transakcje RMA |
Taki podział ma praktyczne znaczenie przy ustalaniu zakresu integracji. Firma integrująca otrzymuje dostęp do obszaru, na który klient posiada licencję, a nie do całości interfejsu. Szczegółowy wykaz metod dla obszaru magazynowego zebrano na osobnej stronie opisującej WebAPI dla roli WMS.
Warto zwrócić uwagę na nazewnictwo folderu VSS: obejmuje on zarówno klasyczne awizacje, jak i zarządzanie placem oraz obsługę bramy. To ten sam obszar, który w warstwie transakcji odpowiada katalogowi \role_maw\, a w materiałach produktowych występuje pod nazwą YMS.
Uwierzytelnianie wywołań
Każde wywołanie metody związane jest z przekazaniem danych użytkownika i hasła. System na podstawie przekazanych danych sprawdza, czy taki użytkownik istnieje i czy ma nadane uprawnienia do wykonywania metod WebService. Nie ma więc metod anonimowych - również odczyt stanów magazynowych wymaga poprawnego konta.
Logowanie polega na przesłaniu w treści żądania sekcji authData zawierającej dwa pola:
{
"authData": {
"login": "nazwa_uzytkownika",
"password": "haslo"
}
}Dane logowania przekazywane są firmie integrującej, natomiast hasłem oraz dostępem konta zarządza administrator platformy z poziomu swojego panelu. Rozwiązanie to ma istotną zaletę organizacyjną: zakończenie współpracy z integratorem albo podejrzenie wycieku poświadczeń oznacza jedną zmianę w module administratora, bez ingerencji w kod po którejkolwiek ze stron.
Konto wykorzystywane do integracji warto traktować jak każde inne konto systemowe - przypisać mu wyłącznie te uprawnienia, które są niezbędne do realizacji uzgodnionego zakresu wymiany danych.
Konto techniczne jak każde inne
Integrator nie dostaje osobnego, wyłączonego spod kontroli dostępu. Korzysta z konta zakładanego w tym samym miejscu co konta pracowników, z własnym zestawem uprawnień.
Dobrą praktyką jest zakładanie odrębnego konta dla każdej integracji, nawet jeśli obsługuje je ten sam dostawca. Gdy w systemie działa równolegle wymiana z ERP i osobna synchronizacja ze sklepem internetowym, oddzielne konta pozwalają jednoznacznie ustalić, która integracja wykonała daną operację, oraz odciąć jedną z nich bez wpływu na drugą.
Dokumentacja w Swaggerze
Dokumentacja metod przygotowywana jest w Swaggerze, w formacie YAML lub JSON, zgodnie ze specyfikacją OpenAPI. Dla zespołu po stronie klienta oznacza to możliwość zapoznania się ze strukturą żądań i odpowiedzi przed napisaniem pierwszej linii kodu, a często także przetestowania wywołań bezpośrednio z poziomu przeglądarki.
Z perspektywy prowadzenia projektu jest to również wygodny punkt odniesienia przy uzgodnieniach. Zamiast opisywać w korespondencji, jakie pola zawiera odpowiedź, obie strony pracują na jednym dokumencie opisującym rzeczywisty kształt interfejsu. Skraca to etap analizy i ogranicza liczbę nieporozumień, które zwykle wychodzą dopiero przy pierwszych testach.
Typowe scenariusze integracji
W praktyce wdrożeniowej WebAPI obsługuje kilka powtarzalnych przypadków. Warto rozpoznać je na etapie analizy, bo determinują kierunek przepływu danych i częstotliwość wywołań:
- Przekazanie zamówień z ERP - system nadrzędny tworzy w platformie dokumenty zlecenia wydania lub przyjęcia.
- Zwrot potwierdzeń realizacji - po skompletowaniu wysyłki dane o faktycznie wydanych ilościach wracają do ERP.
- Synchronizacja kartotek - indeksy towarowe i dane kontrahentów utrzymywane są w jednym systemie i replikowane do drugiego.
- Odczyt stanów magazynowych - sklep internetowy lub system sprzedaży pyta o dostępność towaru.
- Obsługa aplikacji mobilnych - terminale z systemem Android korzystają z tego samego interfejsu, co opisuje materiał o aplikacji Android WMS.
We wszystkich tych przypadkach dane ostatecznie trafiają do tej samej bazy SQL Server, z której korzystają transakcje uruchamiane w przeglądarce. To założenie odróżnia integrację przez WebAPI od wymiany plikowej, gdzie zwykle powstaje pośredni bufor wymagający osobnego pilnowania.
Zanim zaczniesz integrację
Uruchomienie wymiany danych przebiega sprawniej, gdy przed pierwszym wywołaniem uzgodnione są cztery rzeczy. Po pierwsze - zakres, czyli które metody i z którego folderu roli będą wykorzystywane. Po drugie - konto techniczne wraz z zestawem uprawnień odpowiadającym temu zakresowi. Po trzecie - kierunek i częstotliwość wymiany, ponieważ synchronizacja wyzwalana zdarzeniem i odpytywanie cykliczne prowadzą do zupełnie innego obciążenia. Po czwarte - sposób obsługi błędów po stronie systemu wywołującego.
Ostatni punkt bywa pomijany, a decyduje o tym, jak integracja zachowa się w sytuacji nietypowej: przy chwilowej niedostępności usługi, odrzuceniu żądania z powodu uprawnień albo przekazaniu danych niezgodnych z oczekiwaną strukturą. Ustalenie, czy system nadrzędny ponawia próbę, kolejkuje żądanie czy zgłasza błąd operatorowi, warto mieć za sobą przed startem produkcyjnym, a nie po pierwszym incydencie.
Podsumowanie
WebAPI stanowi kanał wymiany danych między platformą StudioSystem a systemami zewnętrznymi i aplikacjami mobilnymi. Metody wywoływane są w stylu REST żądaniem POST z treścią w formacie JSON, a obok nich dostępne są usługi SOAP oparte na plikach asmx. Podział na foldery ról - WMS, VSS, TCS i RMA - odzwierciedla zakres licencji klienta.
Uwierzytelnienie realizuje sekcja authData z loginem i hasłem, a kontami integracyjnymi zarządza administrator platformy. Dokumentacja w Swaggerze zgodna ze specyfikacją OpenAPI pozwala poznać strukturę interfejsu przed rozpoczęciem prac programistycznych.