Interfejs API Studio VSS.net - siedem akcji wymiany danych awizacji z ERP

Kierunek wymiany - kto kogo wywołuje

Interfejs działa w jedną stronę. Serwer systemu zewnętrznego wysyła żądanie, a Studio VSS.net je wykonuje i odpowiada. Tak zapisuje się nową awizację z ERP, poprawia numer auta podany przez przewoźnika albo dopisuje dostawcę do kartoteki. W drugą stronę nic nie płynie samo: program nie wywołuje adresów po stronie ERP i nie ma mechanizmu webhooków. Gdy system zamówień ma się dowiedzieć, że pojazd wjechał albo opuścił teren, musi sam zapytać o awizacje w danym statusie.

Ta asymetria wpływa na projekt integracji bardziej niż wybór języka programowania. Po stronie ERP potrzebne jest zadanie cykliczne, które co ustalony czas pobiera listę awizacji o wskazanym statusie i porównuje ją z poprzednim odczytem. Zbyt częste odpytywanie obciąża serwer bez korzyści, bo etapy wizyty zmienia obsługa bramy i magazynu ręcznie, przyciskami na ekranie Status. Częstotliwość warto więc dobrać do tempa pracy placu, a nie do możliwości łącza.

Zasady wywołania

Wszystkie akcje przechodzą przez jedną metodę uniwersalną. Żądanie ma postać HTTP POST z treścią w formacie JSON i wskazuje, którą akcję wykonać. Odpowiedź również jest w JSON, a formatu XML interfejs nie obsługuje. Kod 200 oznacza wykonaną akcję, 400 błędne dane w żądaniu, a 401 brak autoryzacji. Uwierzytelnienie opiera się na loginie i haśle konta technicznego, przy czym dla każdej integracji zalecamy osobne konto, żeby wyłączenie jednego połączenia nie zatrzymywało pozostałych.

Wywołanie wykonuje serwer systemu zewnętrznego, nie przeglądarka użytkownika. Dane konta technicznego trzymaj po stronie serwera i nie umieszczaj ich w skrypcie strony ani w aplikacji mobilnej, bo każdy, kto je pozna, może zapisywać awizacje. Adresów usług, nazw pól ani danych konta nie publikujemy na tej stronie ani w opisie API w instrukcji Studio VSS.net. Materiały techniczne otrzymuje zespół integrujący po uzgodnieniu zakresu we wdrożeniu, a dostępność każdej akcji zależy od konfiguracji instalacji.

Siedem akcji i klucze rekordów

Akcje dotyczą awizacji oraz trzech kartotek: kontrahentów, przewoźników i asortymentu. Każda akcja na kartotece rozpoznaje rekord po polu, które jednoznacznie go wskazuje. Dla firm jest to numer SAP, dla pozycji towarowych indeks.

Z tabeli wynika kolejność prac. Awizacja wskazuje rekordy kartotek, więc najpierw synchronizuje się kontrahentów i przewoźników, potem asortyment, a dopiero na końcu uruchamia zapis awizacji. Lokalizacji, czyli obiektów, magazynów i bram, interfejs nie obsługuje. Wprowadza się je ręcznie w kartotekach podczas konfiguracji, bo od nich zależy siatka okien czasowych. Kartoteka kontrahentów ma też pola wpływające na długość okna, co opisuje strona o kartotece kontrahentów w roli logistyki.

Dane awizacji, które przyjmuje interfejs

Grupy danych odpowiadają sekcjom formularza nowej awizacji. Wymagania formularza, na przykład obowiązkowy kontrahent, wynikają z ekranu i nie muszą pokrywać się z regułami wywołania API, dlatego listę pól obowiązkowych ustala się na instalacji testowej, a nie na podstawie formularza.

• Lokalizacja i termin - obiekt, magazyn i brama oraz dzień i godzina awizacji, a do tego strony transakcji: kontrahent i przewoźnik.
• Rodzaje i numery - rodzaj awizacji, rodzaj transportu, rodzaj palet, numer zamówienia i własny numer awizacji dostawcy.
• Pojazd i kierowca - numery rejestracyjne ciągnika i naczepy, numer kontenera, imię i nazwisko kierowcy, telefon oraz dokument tożsamości.
• Ładunek i znaczniki - asortyment z ilością, flagi odprawy celnej, piętrowania i transportu po stronie dostawcy, pozostawienia naczepy albo kontenera oraz uwagi dla magazynu.

Dane kierowcy są danymi osobowymi. Przekazuj do programu tylko te, których ochrona potrzebuje przy bramie. Przy potwierdzeniu przybycia brama i tak wymaga kierowcy oraz numeru auta, więc pola, których ERP nie zna w chwili zamówienia, można zostawić puste i uzupełnić później akcją aktualizacji albo w portalu przewoźnika.

Numery, po których systemy rozpoznają awizację

Awizacja ma cztery numery i tylko dwa z nich nadaje program. Numer Load Plan powstaje z licznika przy zapisie awizacji, a numer referencyjny jest technicznym identyfikatorem rekordu. Numer zamówienia SAP to pole tekstowe do 100 znaków, którego program nie waliduje i nie łączy z żadnym systemem SAP. Własny numer awizacji dostawcy ma do 50 znaków i nie podlega kontroli unikalności. Zasady liczników opisuje strona o numeracji dokumentów w panelu Administratora.

Dla integracji wynika z tego prosta reguła: do wiązania rekordów nie używaj numeru zamówienia ani numeru dostawcy, bo mogą się powtarzać. Jeśli ERP ma odnaleźć awizację przy kolejnym odczycie, potrzebuje identyfikatora nadanego przez Studio VSS.net. To, który numer wraca w odpowiedzi na zapis i w jakim etapie powstaje awizacja zapisana z zewnątrz, sprawdza się na instalacji testowej przed podłączeniem środowiska produkcyjnego.

Wymiana plikami, gdy programista nie jest potrzebny

Nie każda wymiana wymaga interfejsu. Import z Excela przyjmuje awizacje, asortyment, kontrahentów, przewoźników, okna czasowe, rampy i parkingi. Przed zapisem można uruchomić audyt pliku, który sprawdza go bez zapisu danych. Audyt nie sprawdza jednak, czy kontrahenci i rampy istnieją w bazie, i nie wykrywa konfliktów okien, więc kartoteki wgrywa się przed awizacjami. W drugą stronę program oferuje cztery gotowe zestawy eksportu do pliku .xlsx, do 10 000 wierszy każdy, a każdy rejestr eksportuje widok z bieżącym filtrem do Excela albo CSV. Zakres obu kierunków opisuje strona o imporcie i eksporcie Excel w sekcji Informacje.

W praktyce pliki dobrze sprawdzają się przy pierwszym zasileniu kartotek i przy wymianie raz na dzień. Interfejs ma przewagę wtedy, gdy awizacja ma powstać w chwili zatwierdzenia zamówienia, a przewoźnik ma uzupełniać kierowcę bez logowania do programu.

Granice interfejsu awizacji

Siedem akcji nie obejmuje potwierdzenia przybycia, zezwolenia na wjazd, zwolnienia rampy, wyjazdu ani anulowania. Te kroki wykonuje obsługa w programie, a każdy z nich dopisuje wpis do historii awizacji z loginem operatora. Operacje na zleceniach i dokumentach magazynowych oraz na stanach zapasów należą do interfejsu Studio WMS.net, nie do interfejsu awizacji. Standardowa instalacja nie ma też gotowego konektora do SAP ani do innego ERP: połączenie z konkretnym systemem powstaje w projekcie.

Moduł powiadomień, opisany w instrukcji jako dodatek włączany przez administratora, wysyła wiadomości SMS i e-mail do ludzi: kierowcy, kontrahenta, przewoźnika i dyspozytorni. Nie jest to kanał do systemów zewnętrznych, więc nie zastępuje odpytywania o statusy.

Koszt integracji zależy od wariantu licencji. Cennik wiąże integrację z ERP co najmniej z wariantem Standard, a interfejs API z wariantem Procesor, co opisuje cennik Studio VSS.net. Zakres prac integracyjnych wycenia się osobno w formularzu wyceny. Pełny opis modułów zawiera strona system awizacji dostaw Studio VSS.net.