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.

Zarządzanie danymi transportowymi przez REST API systemu Studio VSS.net - integracja z ERP, TMS i systemami celnymi.

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.

Infografika SoftwareStudio pokazująca 7 etapów optymalizacji YMS - wdrożenie i REST API — 7 etapów integracji przez REST API systemu Studio VSS.net z zewnętrznymi systemami ERP, TMS i WMS.

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.

Jak wybrać odpowiedni model chmura vs on-premise dla systemu YMS VSS.net - 4 cechy — Scenariusze integracji przez REST API Studio VSS.net z systemami ERP, TMS i celnym - webhooks i polling.

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

Schemat procesu awizacji kierowcy w Studio VSS.net - wdrożenie krok po kroku i REST API — Schemat procesu awizacji kierowcy i dane przekazywane przez REST API systemu Studio VSS.net do zewnętrznych systemów.

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.

Jak zaplanować integrację REST API systemu VSS.net z ERP lub WMS krok po kroku

Integracja przez REST API pozwala na automatyczną wymianę danych między Studio VSS.net a systemami ERP, WMS lub TMS bez ręcznego przepisywania danych. Poniższe kroki opisują, jak zaplanować i uruchomić integrację. Planowanie zajmuje 1-2 godziny robocze z udziałem działu IT.

~2 godziny wymagana dokumentacja API dostęp do środowiska testowego VSS.net

Pobierz i przejrzyj dokumentację API Studio VSS.net

Skontaktuj się z SoftwareStudio w celu otrzymania dokumentacji REST API systemu. Dokumentacja zawiera opis endpointów, format żądań i odpowiedzi, przykłady wywołań i kody błędów. Zapoznaj się z endpointami dotyczącymi tworzenia awizacji, aktualizacji statusów i pobierania danych o rampach.
Zidentyfikuj dane wymagane do synchronizacji

Ustal, jakie dane muszą przepływać między systemami i w jakim kierunku: ERP tworzy zamówienie zakupu i VSS.net ma automatycznie wygenerować awizację (push z ERP), lub VSS.net informuje WMS o potwierdzeniu awizacji (push z VSS.net). Precyzyjne określenie zakresu danych skraca czas implementacji.
Przetestuj wywołania API w środowisku testowym

Używając narzędzia Postman lub equivalent, przetestuj wywołania API w środowisku UAT VSS.net przed wdrożeniem na produkcji. Sprawdź, jak system reaguje na brakujące pola, błędne formaty dat i duplikaty. Testy w środowisku testowym nie wpływają na dane produkcyjne.
Wdróż integrację i monitoruj błędy przez pierwsze 2 tygodnie

Po uruchomieniu integracji na produkcji monitoruj logi błędów API przez pierwsze dwa tygodnie. Najczęstsze problemy po uruchomieniu to różnice w formatach dat między systemami, brakujące kody słownikowe i limity żądań API. Ustal z działem IT procedurę reagowania na błędy integracyjne.

Najczęstsze pytania

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.

Słownik pojęć integracji API systemu awizacyjnego

REST API (Representational State Transfer): Architektura interfejsu programistycznego opartego na protokole HTTP. Pozwala na wymianę danych między systemami przez żądania GET, POST, PUT i DELETE. Studio VSS.net udostępnia REST API umożliwiające integrację z ERP, WMS, TMS i systemami zewnętrznymi.
Endpoint API: Adres URL reprezentujący konkretny zasób lub operację w API systemu. Przykładowy endpoint VSS.net do tworzenia awizacji to /api/appointments (POST). Każdy endpoint obsługuje określone metody HTTP i wymaga autoryzacji przez token JWT lub klucz API.
Token JWT (JSON Web Token): Kompaktowy, podpisany cyfrowo token autoryzacyjny używany do uwierzytelniania żądań API. Każde wywołanie API VSS.net wymaga dołączenia ważnego tokenu JWT w nagłówku Authorization. Token ma określony czas ważności i wymaga odświeżenia po jego upływie.
Webhook: Mechanizm powiadamiania systemu zewnętrznego o zdarzeniu w VSS.net przez wysłanie żądania HTTP na wskazany adres URL (callback URL). Pozwala ERP lub WMS na natychmiastowe otrzymywanie informacji o zmianie statusu awizacji bez konieczności cyklicznego odpytywania API.
Środowisko UAT dla integracji: Izolowana instancja VSS.net przeznaczona do testowania integracji API przed wdrożeniem na produkcji. Pozwala testować wywołania API i obsługę błędów bez ryzyka uszkodzenia danych produkcyjnych lub zakłócenia bieżącej operacji magazynowej.

Tematy: awizacja dostaw YMS okna czasowe Studio VSS.net

REST API systemu awizacyjnego Studio VSS.net - integracja z ERP, TMS i systemami zewnętrznymi