API Studio VSS.net - wymiana danych awizacji z systemami zewnętrznymi
Interfejs API pozwala systemowi zewnętrznemu zapisywać i odczytywać dane Studio VSS.net bez ręcznego przepisywania. Program udostępnia jedną metodę uniwersalną, która uruchamia siedem predefiniowanych akcji na awizacjach i kartotekach. Ta strona opisuje możliwości na poziomie funkcji. Adresów usług, nazw pól i danych konta technicznego nie publikujemy - przekazuje je wdrożenie.
Formularz dzieli dane awizacji na sekcje: wybór lokalizacji (obiekt, magazyn, brama), Awizo i ładunek, Termin, Transport i Podsumowanie awizacji. W sekcji Awizo i ładunek widać pola Rodzaj awizacji, Kontrahent, Rodzaj transportu, Nr zamówienia SAP, znacznik Agencja celna i Asortyment. Gwiazdka oznacza pole wymagane, a dolny pasek pokazuje licznik pól wymaganych. Interfejs API obsługuje podobne grupy danych, lecz nazwy pól wywołania należą do materiałów technicznych wdrożenia i nie występują w instrukcji.
Na tej stronie
Do czego służy interfejs
Interfejs przyjmuje wywołania z systemów zewnętrznych, na przykład z ERP, z platformy B2B kontrahenta albo z systemu przewoźnika. Studio VSS.net nie wysyła danych o awizacjach do tych systemów. Zmiany etapów wizyty odbiera system zewnętrzny, odpytując program o awizacje według statusu.
| Scenariusz | Akcja | Efekt w Studio VSS.net |
|---|---|---|
| System zamówień zapisuje awizację po zatwierdzeniu zamówienia zakupu | Dopisanie awizacji | Awizacja trafia do programu z danymi z tabeli poniżej. Numer zamówienia wpisuje się w pole Nr zamówienia SAP. |
| System przewoźnika uzupełnia kierowcę i numery rejestracyjne | Aktualizacja awizacji | Dane istniejącej awizacji zmieniają się bez logowania pracownika do programu. |
| Platforma kontrahenta sprawdza, na którym etapie jest dostawa | Odczyt awizacji według statusu | Program zwraca listę awizacji o wskazanym statusie wraz z tekstem statusu. |
| ERP synchronizuje listę dostawców i przewoźników | Dopisanie i aktualizacja kontrahenta lub przewoźnika | Rekord kartoteki powstaje albo zmienia się. Kluczem jest numer SAP. |
| ERP synchronizuje towary | Dopisanie i aktualizacja asortymentu | Pozycja kartoteki asortymentu powstaje albo zmienia się. Kluczem jest indeks. |
Zasady wywołania
| Cecha | Wartość |
|---|---|
| Rodzaj wywołania | Żądanie HTTP POST z treścią w formacie JSON. Jedna metoda uniwersalna wykonuje wskazaną akcję. |
| Odpowiedź | JSON. Formatu XML interfejs nie obsługuje. |
| Uwierzytelnienie | Login i hasło konta technicznego. Dla każdej integracji zalecamy osobne konto. |
| Kierunek | Wywołania przychodzące do programu: zapis i odczyt. Program nie wysyła zdarzeń do systemów zewnętrznych. |
| Kody odpowiedzi | 200 - akcja wykonana, 400 - błędne dane w żądaniu, 401 - brak autoryzacji. |
| Dostępność akcji | Zależy od konfiguracji instalacji, więc każdą akcję potwierdza się przy wdrożeniu. |
Kto wywołuje interfejs. 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.
Siedem akcji
Akcje dotyczą awizacji oraz kartotek (kontrahenci, przewoźnicy, asortyment). Klucz rekordu wynika z pola, które w kartotece jednoznacznie wskazuje pozycję.
| Akcja | Co robi | Uwagi |
|---|---|---|
| Dopisanie awizacji | Tworzy nową awizację z danymi z następnej tabeli. | Zachowanie przy zajętym oknie sprawdź na instalacji testowej. |
| Aktualizacja awizacji | Zmienia dane istniejącej awizacji. | Dotyczy awizacji już zapisanej w programie. |
| Odczyt awizacji według statusu | Zwraca listę awizacji o wskazanym statusie z tekstem statusu. | Tak system zewnętrzny wykrywa zmiany etapów wizyty. |
| Dopisanie kontrahenta lub przewoźnika | Tworzy rekord w kartotece kontrahentów albo przewoźników. | Klucz: numer SAP. Rodzaj rekordu: kontrahent albo przewoźnik. |
| Aktualizacja kontrahenta lub przewoźnika | Zmienia rekord w tej samej kartotece. | Klucz jak przy dopisaniu. |
| Dopisanie asortymentu | Tworzy pozycję w kartotece asortymentu. | Klucz: indeks. |
| Aktualizacja asortymentu | Zmienia pozycję kartoteki asortymentu. | Klucz: indeks. |
Dane awizacji obsługiwane przez interfejs
Poniższe grupy 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.
| Grupa danych | Zakres | Odpowiednik na ekranie |
|---|---|---|
| Lokalizacja | Obiekt, magazyn, brama | Sekcje wyboru lokalizacji w kreatorze |
| Strony | Kontrahent, przewoźnik | Pola Kontrahent i Przewoźnik |
| Rodzaje | Rodzaj awizacji, rodzaj transportu, rodzaj palet | Listy ze skorowidzów |
| Numery | Numer zamówienia, numer awizacji (własny numer dostawcy) | Nr zamówienia SAP, Nr awizacji (numer własny) |
| Termin | Dzień i godzina awizacji | Sekcja Termin i okno czasowe |
| Kierowca | Imię i nazwisko, telefon, dokument tożsamości | Sekcja Transport |
| Pojazd | Numery rejestracyjne ciągnika i naczepy, numer kontenera | Pola Nr rejestracyjny i Nr kontenera |
| Ładunek | Asortyment, ilość | Pole Asortyment i liczba palet |
| Flagi | Odprawa celna, piętrowanie, transport po stronie dostawcy, naczepa zostaje, kontener zostaje | Przełączniki formularza |
| Uwagi | Tekst dla magazynu | Uwagi w podsumowaniu |
Dane osobowe kierowcy. Imię i nazwisko, telefon, numer dokumentu tożsamości to dane osobowe. Przekazuj do programu tylko te dane, których ochrona potrzebuje przy bramie, i ustal podstawę ich przetwarzania zgodnie z tekstem RODO na EUR-Lex.
Inne kanały wymiany danych
Nie każda wymiana wymaga programisty. Część danych przenosi się plikami, a program potrafi sprawdzić plik przed zapisem.
| Kanał | Kierunek | Zakres |
|---|---|---|
| Import z Excela | Do programu | Awizacje, asortyment, kontrahenci, przewoźnicy, okna czasowe, rampy, parkingi. Przed zapisem można uruchomić audyt, który sprawdza plik bez zapisu danych. |
| Eksport gotowych zestawów | Z programu | Cztery zestawy: oczekujące; w trakcie realizacji; zrealizowane; anulowane. Każdy do 10 000 wierszy w pliku .xlsx. |
| Eksport rejestrów | Z programu | Excel do 50 000 wierszy i CSV do 10 000 wierszy z bieżącym filtrem i sortowaniem rejestru. |
| Wydruki PDF | Z programu | Wydruki: podgląd awizacji, przepustka, wydruk CMR - generowane na serwerze raportów. |
Pozycje importu i eksportu opisuje strona o imporcie i eksporcie Excel w sekcji Informacje. Audyt pliku nie sprawdza istnienia kontrahentów ani ramp w bazie i nie wykrywa konfliktów okien, więc kartoteki wgraj przed awizacjami.
Górny blok zawiera cztery gotowe zestawy eksportu bez parametrów. Dolny blok ma siedem kafli importu, od awizacji po parkingi. Każdy kafel otwiera okno wyboru pliku z podglądem wymaganych kolumn i wzorcem do pobrania.
Granice interfejsu awizacji
- Zmiana etapu wizyty. Siedem akcji nie obejmuje potwierdzenia przybycia, zezwolenia na wjazd, zwolnienia rampy, wyjazdu ani anulowania. Te kroki wykonuje obsługa w programie.
- Wysyłka zdarzeń. Program nie powiadamia systemów zewnętrznych o zmianach. System zewnętrzny musi sam odpytywać o awizacje według statusu.
- Format danych. Żądania i odpowiedzi mają wyłącznie format JSON.
- Magazyn. Operacje na zleceniach i dokumentach magazynowych oraz na stanach zapasów należą do interfejsu Studio WMS.net, a nie do interfejsu awizacji.
Sprawdź zapis w praktyce. Zachowanie zapisu z systemu zewnętrznego, w tym kontrolę zajętości okna, nadanie numeru Load Plan i etap awizacji po zapisie, potwierdź na instalacji testowej, zanim podłączysz środowisko produkcyjne.
Przygotowanie integracji
- Wskaż akcje potrzebne w Twoim procesie oraz kierunek każdej wymiany: zapis albo odczyt.
- Uzgodnij ze SoftwareStudio konto techniczne i materiały techniczne w ramach wdrożenia systemu logistycznego. Zakres i koszt integracji ustala wycena Studio VSS.net.
- Zsynchronizuj kartoteki (kontrahenci, przewoźnicy, asortyment), zanim zaczniesz zapisywać awizacje. Awizacja wskazuje rekordy tych kartotek.
- Przetestuj każdą akcję na instalacji testowej: sprawdź numer Load Plan, etap po zapisie i zachowanie przy zajętym oknie.
- Ustal częstotliwość odpytywania o statusy. Program nie wysyła zdarzeń, więc zbyt częste zapytania niepotrzebnie obciążają serwer.
- Zabezpiecz dane konta technicznego po stronie systemu wywołującego i monitoruj odpowiedzi 400 i 401.
Ograniczenia standardowej instalacji, w tym brak wbudowanego konektora do SAP, opisuje strona o programie Studio VSS.net. Ekrany, na których pojawiają się dane zapisane przez interfejs, sprawdzisz w bezpłatnym demo Studio VSS.net.
Najczęstsze pytania
Czy Studio VSS.net wysyła zmiany statusów do mojego ERP?
Nie samo z siebie. Program przyjmuje wywołania i odpowiada na nie. O zmianach etapów system zewnętrzny dowiaduje się, odpytując o awizacje według statusu.
Czy interfejs obsługuje format XML?
Nie. Żądania i odpowiedzi mają wyłącznie format JSON, a wywołanie to żądanie HTTP POST.
Czy przez API można potwierdzić przybycie albo anulować awizację?
Nie. Zestaw siedmiu akcji obejmuje dopisanie i aktualizację awizacji, odczyt według statusu oraz zapis kartotek. Zmianę etapu wizyty i anulowanie wykonuje obsługa w programie.
Czy przez to samo API pobiorę stany magazynowe i dokumenty PZ lub WZ?
Nie z interfejsu awizacji. Zlecenia i dokumenty magazynowe oraz stany zapasów udostępnia interfejs Studio WMS.net, który jest osobnym systemem.
Gdzie znajdę adres usługi i strukturę żądania?
Nie publikujemy ich w instrukcji ze względów bezpieczeństwa. Materiały techniczne otrzymuje zespół integrujący po uzgodnieniu zakresu we wdrożeniu.
Słownik pojęć
- API
- Application Programming Interface - interfejs, przez który jeden program wywołuje funkcje drugiego bez udziału użytkownika.
- Metoda uniwersalna
- Pojedyncza usługa Studio VSS.net, która wykonuje jedną z predefiniowanych akcji wskazanych w wywołaniu.
- Konto techniczne
- Konto używane wyłącznie przez integrację. Jego login i hasło uwierzytelniają każde wywołanie.
- JSON
- Tekstowy format danych, w którym żądanie i odpowiedź zapisuje się jako pary nazwa-wartość.
- Odpytywanie
- Cykliczne wywoływanie interfejsu przez system zewnętrzny w celu sprawdzenia, czy stan awizacji się zmienił.
- Klucz rekordu
- Pole jednoznacznie wskazujące rekord kartoteki w akcji API: numer SAP dla firm, indeks dla asortymentu.