Konfiguracja API REST JTL-Wawi

JTL-Wawi ma własny interfejs programistyczny: API JTL-Wawi, często nazywane też „REST-API” lub „serwerem REST Wawi”. Dzięki niemu inny program – tutaj allverto – może odczytywać artykuły, klientów i dokumenty z Twojej Wawi bez bezpośredniego sięgania do bazy danych. Ta strona wyjaśnia, co musisz w tym celu skonfigurować w Wawi.

#Bezpośrednio z allverto (droga główna)

Jeśli Twoja JTL-Wawi działa na wynajętym serwerze, a serwer REST jest dostępny z internetu, allverto samo się z nim łączy. Nie potrzebujesz wtedy żadnego programu na serwerze.

Działa to, gdy:

• serwer REST jest dostępny pod publicznym adresem IP lub publiczną nazwą – nie pod localhost, adresem w sieci firmowej ani nazwą komputera.
• port to 80, 443 albo 1024 lub wyższy.

Jak to zrobić:

1. Otwórz Ustawienia → Migracja danych → Migracja z JTL-Wawi, krok Połącz źródło, i wybierz API JTL-Wawi.
2. W Dane połączenia wpisz Adres API Wawi, np. https://217.160.19.64:5885/api/eazybusiness, i kliknij Zapisz.
3. Kliknij Testuj połączenie. allverto odpytuje …/v2/info. Bez klucza API wynik brzmi „serwer REST dostępny ✓ – logowanie nastąpi przez rejestrację”. To normalne, że sam adres (…/api/eazybusiness) pokazuje w przeglądarce „404”.
4. Jeśli Twój serwer REST odpowiada tylko przez HTTPS, allverto proponuje adres z https://. Kliknij Zmień adres na https://.
5. Jeśli Twój serwer REST używa samodzielnie utworzonego certyfikatu, allverto pokazuje odcisk (SHA-256), wystawcę i ważność. Porównaj odcisk z certyfikatem na serwerze i kliknij Ufaj temu certyfikatowi.
6. Zarejestruj allverto w JTL-Wawi – w tej kolejności:
   1. W JTL-Wawi otwórz „Anwendungsregistrierungen“ → „Anwendung registrieren“ i przejdź do kroku „Registrierung beginnen”. Wawi czeka wtedy na żądanie.
   2. W allverto kliknij Wyślij rejestrację z allverto. allverto ponawia żądanie co 5 sekund przez maksymalnie 10 minut. Stan widzisz tuż poniżej, np. „Oczekiwanie na Wawi” lub „Przyjęte”. Przyciskiem Anuluj zatrzymujesz proces.
   3. W Wawi sprawdź „Anwendungsinformationen”, w „Benutzer” wybierz użytkownika Wawi, w „Zugriffsverwaltung” potwierdź uprawnienia (tylko odczyt, opcjonalnie drukowanie faktur) i kliknij „Einrichtung abschließen”. allverto pokaże wtedy „Klucz API zapisany.” i zapisze go w postaci zaszyfrowanej.
7. Kliknij Pobierz dane bezpośrednio teraz. allverto pobiera dane w tle. Ilości pojawią się potem w Znalezione dane.

Jeśli wpiszesz localhost lub adres z sieci firmowej, pole pokaże: „Ten adres jest dostępny tylko na Twoim serwerze. Wpisz publiczny adres IP serwera – albo użyj poniżej jtl-bridge.” Jeśli Twój serwer REST nie jest dostępny z internetu, skorzystaj z drogi przez jtl-bridge (kroki 2 i 3 poniżej).

#Czym jest API REST – w prostych słowach?

Wyobraź sobie serwer REST jako okienko recepcji Twojej Wawi. Programy, które chcą danych, pytają przy okienku („daj mi wszystkie faktury”). Okienko sprawdza, czy program ma ważną legitymację – klucz API – i wydaje dokładnie te dane, które zostały udostępnione.

• Serwer REST to program JTL, który działa na komputerze, na którym działa Twoja JTL-Wawi (zwykle serwer Windows).
• Na tym komputerze jest dostępny pod adresem takim jak http://localhost:5883/api/eazybusiness. localhost oznacza „ten komputer”, 5883 to przykład portu – chodzi o port ustawiony w Wawi dla serwera REST (często 5883, ale np. także 5885). eazybusiness to nazwa bazy danych Twojej Wawi.
• Każdy program musi się raz zarejestrować jako aplikacja. Rozpoczynasz rejestrację w Wawi, program wysyła swoje żądanie, Ty kończysz konfigurację – i dopiero wtedy program otrzymuje swój klucz API.
• allverto rejestruje się jako aplikacja „allverto – Umzug von JTL-Wawi” (migracja z JTL-Wawi) i prosi tylko o dostęp do odczytu (opcjonalnie dodatkowo o drukowanie PDF faktur). allverto niczego nie zmienia w Twojej Wawi.

#Od której wersji Wawi?

allverto korzysta z API w wersji, którą JTL opublikował dla Wawi 2.1 i 2.2 (ścieżki z /v2/…). Dla tych wersji droga przez API została zbudowana i przetestowana.

#Krok po kroku

#1. Włączenie serwera REST w Wawi

1. Zaloguj się do JTL-Wawi jako użytkownik z uprawnieniami administratora.
2. Skonfiguruj serwer REST tak, jak JTL opisuje to dla Twojej wersji, i uruchom go. Zanotuj przy tym port, na którym nasłuchuje.
3. Sprawdź, czy serwer działa – np. otwórz w przeglądarce na serwerze Wawi adres http://localhost:<port>/api/eazybusiness. Jeśli pojawi się jakakolwiek odpowiedź (nawet komunikat o błędzie w przeglądarce), serwer działa.

#2. Przez jtl-bridge: wybór źródła w allverto

Tej drogi potrzebujesz tylko wtedy, gdy Twój serwer REST nie jest dostępny z internetu.

1. Otwórz Ustawienia → Migracja danych → Migracja z JTL-Wawi, krok Połącz źródło.
2. Wybierz API JTL-Wawi. Wpisywać nic nie musisz – adres i klucz API przekazuje jtl-bridge sam.
3. Opcjonalnie: ustal dzień przejścia.

W Dane połączenia są też Klucz API (tylko jeśli masz już klucz), ID mandanta (opcjonalnie) (tylko jeśli Twoja Wawi go wymaga), Pobieraj PDF faktur przez API oraz przełącznik Uzupełnij brakujące dane z bazy danych (opcjonalnie) (zobacz niżej).

#3. Przez jtl-bridge: uruchomienie programu i rejestracja aplikacji w Wawi

Rozwiń na dole ramkę Serwer niedostępny z internetu? Prześlij dane przez jtl-bridge. Prowadzi Cię przez kroki (szczegółowo: Program pomocniczy jtl-bridge):

1. Pobierz jtl-bridge.
2. Skopiuj plik na serwer, na którym działa Twoja JTL-Wawi – np. przez Pulpit zdalny na pulpit.
3. Na serwerze uruchom plik dwukrotnym kliknięciem.
4. Kliknij tutaj „Wygeneruj kod konfiguracyjny”, skopiuj kod, wklej go w oknie prawym przyciskiem myszy i naciśnij Enter.
5. Odpowiedz na pytania w oknie – zwykle wystarczy Enter. Program szuka serwera REST na tym komputerze (porty od 5883 do 5890) i proponuje znaleziony adres, np. „Znaleziono: http://localhost:5885/api/eazybusiness – naciśnij Enter, aby użyć”.
6. Zarejestruj aplikację w JTL-Wawi (zobacz niżej).
7. Poczekaj, aż pojawi się „Gotowe” – allverto odhaczy wtedy ten krok.

Do kroku 6 – kolejność jest ważna, bo Wawi przyjmuje żądanie tylko wtedy, gdy jej kreator czeka:

1. Otwórz w JTL-Wawi Anwendungsregistrierungen → Anwendung registrieren (rejestracja aplikacji). Kreator ma kroki Einführung, Registrierung beginnen, Anwendungsinformationen, Benutzer, Zugriffsverwaltung i Einrichtung abschließen.
2. Przejdź do Registrierung beginnen (rozpocznij rejestrację). Pojawi się tam: „Eine Sitzung zur Entgegennahme von Registrierungsanfragen wurde gestartet …” (rozpoczęto sesję przyjmowania żądań rejestracji) oraz „Es wird auf die Übermittlung einer Registrierungsanfrage durch die zu registrierende Anwendung gewartet …” (oczekiwanie na żądanie rejestracji od aplikacji).
3. Teraz naciśnij Enter w oknie jtl-bridge. Program wyśle żądanie allverto – Umzug von JTL-Wawi. Jeśli Wawi jeszcze go nie przyjmuje, program ponawia próbę co 5 sekund przez 10 minut.
4. Sprawdź w Wawi Anwendungsinformationen, w Benutzer wybierz użytkownika Wawi i w Zugriffsverwaltung potwierdź żądane uprawnienia (tylko odczyt, opcjonalnie drukowanie faktur).
5. Kliknij Einrichtung abschließen. Potem jtl-bridge przekazuje klucz API w postaci zaszyfrowanej do allverto – nie widzisz go i nie musisz niczego przepisywać. allverto przechowuje go w postaci zaszyfrowanej i używa go tylko do tej migracji.

Jeśli nie ukończysz konfiguracji w ciągu 10 minut, jtl-bridge przerywa – wtedy po prostu uruchom go ponownie.

#Skąd się bierze klucz API?

JTL-Wawi nie pokazuje klucza API i nie tworzy go na życzenie. Wydaje go tylko aplikacji, która właśnie o niego prosi – gdy jej kreator czeka w kroku Registrierung beginnen. To żądanie wysyła samo allverto (Wyślij rejestrację z allverto). Jeśli Twój serwer REST nie jest dostępny z internetu, wysyła je jtl-bridge.

Następnie allverto pobiera dane albo jtl-bridge je przesyła. Dalej w kreatorze przechodzisz do Znalezione dane i Przypisania – zobacz Migracja z JTL-Wawi: jak to przebiega.

#Co API dostarcza – a czego nie?

#Jak jtl-bridge uzupełnia luki

Jeśli włączysz w kreatorze w sekcji Dane przełącznik Uzupełnij brakujące dane z bazy danych (opcjonalnie) i wpiszesz dostęp do SQL Server, jtl-bridge odczyta bezpośrednio z bazy danych wszystko, czego API nie dostarcza lub dostarcza tylko częściowo: subskrypcje, faktury zakupowe, pozycje korekt faktur, zestawienia materiałowe, nazwy atrybutów, mandaty SEPA. W polu Użytkownik (sa) wpisz użytkownika SQL Server (zwykle sa), a nie swojego użytkownika JTL-Wawi; wystarczy też osobny użytkownik tylko z prawem odczytu. Bez bazy danych tych danych brakuje – wszystko inne i tak zostanie przejęte.

#Bezpieczeństwo i sieć

• Bezpośrednio z allverto serwer REST musi być dostępny z internetu. Otwórz port w zaporze tylko dla serwerów allverto: 2.31.70.120, 2.31.74.112, 2.31.72.228 – nigdy dla wszystkich.
• Używaj https://. Przy http:// klucz API i dane idą przez internet bez szyfrowania. Samodzielnie utworzony certyfikat potwierdzasz raz przyciskiem Ufaj temu certyfikatowi. Potem allverto łączy się tylko z dokładnie tym certyfikatem.
• Przez jtl-bridge nic nie musi być dostępne z internetu. jtl-bridge działa na serwerze Wawi i przesyła dane tylko przez HTTPS. Dane są dodatkowo szyfrowane kluczem z tokenu importu.
• Klucz API i kod konfiguracji są jak hasła: nie wysyłaj ich e-mailem i nie kopiuj do zgłoszeń. allverto zapisuje klucz API w postaci zaszyfrowanej i nigdy go nie pokazuje. Kod konfiguracji jest ważny każdorazowo 30 dni (można przedłużyć), najdłużej do zakończenia migracji.
• Przez Testuj połączenie allverto samo sprawdza adres tylko wtedy, gdy jest dostępny z internetu. Przy localhost lub adresie w sieci firmowej test wykonuje jtl-bridge i przekazuje wynik.
• Po migracji możesz usunąć aplikację „allverto – Umzug von JTL-Wawi” w Wawi w „Anwendungsregistrierungen“.

#Rozwiązywanie problemów

Więcej przypadków: Rozwiązywanie problemów przy migracji z JTL.