VSS.net i systemy ERP
Integracja VSS.net z SAP, Comarch i Microsoft Dynamics przez REST API - scenariusze i zakres wymienianych danych.
W skrócie: REST API Studio VSS.net w standardzie JSON z autoryzacją Bearer Token. Endpointy dla tworzenia awizacji, pobierania harmonogramu, rejestracji zdarzeń i webhooks dla powiadomień w czasie rzeczywistym. Dokumentacja OpenAPI/Swagger dostępna dla integratorów.
REST API Studio VSS.net - architektura i możliwości integracji
Studio VSS.net udostępnia REST API w standardzie JSON, które pozwala dowolnemu systemowi zewnętrznemu na programowy dostęp do funkcji platformy awizacyjnej. Przez API system zewnętrzny może tworzyć awizacje, pobierać harmonogram dostaw, aktualizować statusy wizyt i odbierać powiadomienia o zdarzeniach przez mechanizm webhooks. API jest zaprojektowane zgodnie ze standardem RESTful - każdy zasób ma unikalny URL, operacje odczytu używają metody GET, tworzenia POST, aktualizacji PUT/PATCH, a usuwania DELETE. Odpowiedzi są zwracane w formacie JSON z kodem HTTP odpowiadającym wyniku operacji.
Dostępne grupy endpointów API
REST API Studio VSS.net jest podzielone na cztery grupy endpointów. Pierwsza grupa obsługuje zarządzanie awizacjami - tworzenie, odczyt, aktualizację i anulowanie rekordów awizacji z pełnym zestawem pól: identyfikator dostawcy, numer pojazdu i naczepy, planowana data i godzina, deklarowana ilość palet, typ towaru, wymagana rampa i dane kontaktowe kierowcy. Druga grupa obsługuje harmonogram - pobieranie listy awizacji w zakresie dat z filtrowaniem po dostawcy, rampie i statusie oraz sprawdzanie dostępności wolnych slotów dla planowanej daty.
Trzecia grupa obsługuje zdarzenia operacyjne - rejestrację wjazdu pojazdu (z numerem rejestracyjnym i godziną), zmianę przydzielonej rampy, rozpoczęcie obsługi, zakończenie rozładunku i wyjazd pojazdu z placu. Te zdarzenia odpowiadają kolejnym etapom cyklu obsługi wizyty w systemie YMS i pozwalają systemom zewnętrznym (WMS, ERP, TMS) śledzić postęp każdej dostawy w czasie rzeczywistym. Czwarta grupa obsługuje słowniki systemowe - listę ramp z parametrami, listę dostawców, typy pojazdów i grupy towarów.
Autoryzacja i bezpieczeństwo API
REST API Studio VSS.net używa autoryzacji Bearer Token przekazywanego w nagłówku HTTP Authorization. Token jest generowany przez dedykowany endpoint autoryzacyjny na podstawie poświadczeń konta technicznego lub klucza API przypisanego do aplikacji integrującej. Dla integracji system-system (ERP lub WMS odpytujący API VSS.net bez udziału użytkownika) rekomendowane jest używanie kluczy API z ograniczonym zakresem uprawnień - klucz API dla integracji WMS ma dostęp wyłącznie do endpointów awizacji i harmonogramu, bez dostępu do konfiguracji systemu.
Komunikacja z API odbywa się wyłącznie przez HTTPS z certyfikatem SSL/TLS. Żądania bez nagłówka Authorization lub z nieważnym tokenem są odrzucane z kodem HTTP 401. Żądania przekraczające limit częstotliwości (rate limiting) są odrzucane z kodem HTTP 429 z informacją o czasie do odnowienia limitu. Każde żądanie API jest logowane z datą, godziną, identyfikatorem aplikacji i kodem odpowiedzi do celów audytowych.
Webhooks - zdarzenia w czasie rzeczywistym
Zamiast cyklicznego odpytywania API (polling) o statusy awizacji, Studio VSS.net obsługuje mechanizm webhooks, który automatycznie wysyła powiadomienie do systemu zewnętrznego w momencie wystąpienia zdarzenia. System zewnętrzny subskrybuje typy zdarzeń, które chce obserwować, i definiuje URL endpointu, na który mają być wysyłane powiadomienia. Każde zdarzenie generuje HTTP POST z danymi zdarzenia w formacie JSON zawierającym identyfikator awizacji, typ zdarzenia, datę i godzinę oraz dane powiązanego pojazdu lub dostawcy.
- POST /api/awizacje - tworzenie nowej awizacji z pełnym zestawem danych przez system ERP lub TMS.
- GET /api/harmonogram - pobieranie listy awizacji w zakresie dat z filtrowaniem po dostawcy i statusie.
- GET /api/rampy/dostepnosc - sprawdzanie wolnych slotów dla planowanej daty przed zaproponowaniem okna dostawcy.
- POST /api/zdarzenia/wjazd - rejestracja wjazdu pojazdu przez system ANPR lub aplikację mobilną ochrony.
- Webhooks - automatyczne powiadomienie systemu zewnętrznego o zdarzeniach: potwierdzenie awizacji, wjazd, wyjazd, anulowanie.
Pełna dokumentacja REST API Studio VSS.net jest dostępna w formacie OpenAPI 3.0 (Swagger) pod adresem środowiska deweloperskiego producenta. Integratorzy i programiści działów IT klientów mogą przetestować endpointy przez interfejs Swagger UI przed rozpoczęciem prac wdrożeniowych. SoftwareStudio udostępnia też przykładowe implementacje konektorów w językach Python, C# i PHP dla przyspieszenia prac integracyjnych.
Typowe scenariusze integracji przez REST API
Najczęściej realizowanym scenariuszem integracji przez API jest automatyczne tworzenie awizacji w VSS.net na podstawie zleceń transportowych z systemu ERP lub TMS. ERP po zatwierdzeniu zamówienia zakupowego generuje żądanie POST /api/awizacje z danymi dostawcy, planowaną datą dostawy i numerem zamówienia. VSS.net tworzy awizację i odsyła do ERP identyfikator awizacji, który jest zapisywany w zamówieniu jako referencja. Dostawca otrzymuje powiadomienie SMS z linkiem do portalu i może potwierdzić awizację lub wybrać inne okno w ramach zdefiniowanego zakresu. Po zamknięciu wizyty VSS.net wysyła webhook do ERP z rzeczywistym czasem obsługi, który jest zapisywany jako data i godzina realizacji dostawy w dokumencie zamówienia. Cały proces odbywa się bez ręcznej interwencji pracowników biura logistyki.
Sprawdź Studio VSS.net w działaniu
Bezpłatne demo, wycena i kalkulator ROI - bez zobowiązań.
Najczęstsze pytania o REST API systemu VSS.net
Jakie endpointy REST API udostępnia Studio VSS.net?
Studio VSS.net udostępnia REST API z endpointami pogrupowanymi w cztery kategorie. Zarządzanie awizacjami: POST /api/awizacje (tworzenie nowej awizacji), GET /api/awizacje/{id} (pobieranie szczegółów), PUT /api/awizacje/{id} (aktualizacja), DELETE /api/awizacje/{id}/anuluj (anulowanie). Harmonogram: GET /api/harmonogram (lista awizacji w zakresie dat), GET /api/rampy/dostepnosc (wolne sloty). Statusy i zdarzenia: POST /api/zdarzenia/wjazd (rejestracja wjazdu pojazdu), POST /api/zdarzenia/wyjazd (zamknięcie wizyty). Słowniki: GET /api/rampy, GET /api/dostawcy, GET /api/typy-pojazdow. Pełna dokumentacja API jest dostępna w formacie OpenAPI/Swagger w środowisku deweloperskim.
Jak wygląda autoryzacja w REST API systemu VSS.net?
REST API Studio VSS.net używa autoryzacji Bearer Token w nagłówku HTTP Authorization. Token jest generowany przez endpoint POST /api/auth/token na podstawie poświadczeń konta technicznego (login i hasło) lub klucza API przypisanego do aplikacji integrującej. Token jest ważny przez konfigurowalny czas (domyślnie 8 godzin) i musi być dołączany do każdego żądania API w nagłówku Authorization: Bearer {token}. Po wygaśnięciu tokenu aplikacja musi pobrać nowy token przez endpoint autoryzacyjny. Dla integracji system-system rekomendowane jest używanie kluczy API zamiast poświadczeń użytkownika.
Czy Studio VSS.net obsługuje webhooks do powiadamiania o zdarzeniach?
Studio VSS.net obsługuje mechanizm webhooks, który pozwala systemom zewnętrznym subskrybować zdarzenia w systemie awizacyjnym bez konieczności odpytywania API (polling). Dostępne typy zdarzeń to: awizacja.potwierdzona (dostawca potwierdził rezerwację), pojazd.wjechal (zarejestrowany wjazd przez ANPR lub kiosk), pojazd.wyjechał (zamknięcie wizyty), awizacja.anulowana i rampa.zmieniona. Przy każdym zdarzeniu system wysyła HTTP POST do skonfigurowanego URL endpointu z danymi zdarzenia w formacie JSON. Endpoint zewnętrzny musi odpowiedzieć kodem HTTP 200 w ciągu 5 sekund - w przeciwnym razie webhook jest ponawiany do 3 razy w odstępach 30-minutowych.