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.

#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 w Twojej sieci firmowej, zwykle na tym samym komputerze co Wawi lub jej SQL Server.
• Jest dostępny pod adresem takim jak http://wawi-server:5883/api/eazybusiness. wawi-server to nazwa lub IP Twojego komputera, 5883 to port (u Ciebie może być inny), eazybusiness to nazwa bazy danych Twojej Wawi.
• Każdy program musi się raz zarejestrować jako aplikacja. Potwierdzasz rejestrację w Wawi, a następnie 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: komputer w sieci firmowej musi mieć dostęp do adresu http://<wawi-server>:<port>/api/eazybusiness (odblokuj ten port w zaporze komputera z Wawi w sieci wewnętrznej).

#2. Rejestracja allverto jako aplikacji

Rejestrację uruchamiasz programem pomocniczym jtl-bridge na komputerze w sieci firmowej:

jtl-bridge register --api-url http://wawi-server:5883/api/eazybusiness

1. jtl-bridge wysyła żądanie rejestracji do Twojego serwera REST i zgłasza: „Registrierung gesendet … Bitte jetzt in der JTL-Wawi unter Admin → App-Registrierung bestätigen” (rejestracja wysłana – potwierdź ją teraz w JTL-Wawi w Admin → App-Registrierung).
2. Otwórz w Wawi App-Registrierung (rejestracja aplikacji). Według naszych informacji w Wawi 2.2 ta pozycja nazywa się: Admin → App-Registrierung. Znajduje się tam żądanie od allverto – Umzug von JTL-Wawi z wnioskowanymi uprawnieniami.
3. Sprawdź uprawnienia (tylko odczyt, opcjonalnie drukowanie faktur) i potwierdź żądanie.
4. jtl-bridge odpytuje co 5 sekund. Po potwierdzeniu wyświetla klucz API – tylko ten jeden raz. Skopiuj go od razu.
5. Jeśli nie potwierdzisz w ciągu 10 minut, jtl-bridge przerywa – wtedy po prostu uruchom rejestrację ponownie.

#3. Wpisanie danych w allverto

1. Otwórz Ustawienia → Migracja danych → Migracja z JTL-Wawi, krok Połącz źródło.
2. Wybierz API JTL-Wawi.
3. W polu Adres API Wawi wpisz adres z kroku 1, np. http://wawi-server:5883/api/eazybusiness.
4. Wklej Klucz API. allverto zapisuje go w postaci zaszyfrowanej; przy następnym otwarciu widnieje tam „Zapisany – pozostaw puste, aby go zachować”.
5. ID mandanta (opcjonalnie): wypełnij tylko wtedy, gdy Twoja Wawi go wymaga. Przy Wawi we własnej firmie pole zwykle pozostaje puste.
6. Pozostaw włączone Pobieraj PDF faktur przez API, jeśli Twoje faktury mają zostać przejęte jako PDF (Wawi generuje je w tym celu ponownie).
7. Opcjonalnie: wpisz SQL Server – wtedy jtl-bridge uzupełni to, czego API nie dostarcza (zobacz niżej).
8. Kliknij Zapisz źródło.

#4. Przesyłanie danych

Ponieważ serwer REST jest dostępny tylko w sieci firmowej (i tak powinno zostać), dane przesyła jtl-bridge: Wygeneruj token importu, a następnie uruchom w sieci firmowej wyświetlone polecenie, np.

jtl-bridge upload --url https://erp.allverto.cloud --token avjtl_… --fill-from-db

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 uruchomisz jtl-bridge z --fill-from-db i dodatkowo zapiszesz w allverto SQL Server, odczyta on 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. Wystarczy do tego użytkownik bazy danych tylko z prawem odczytu. Bez bazy danych tych danych brakuje – wszystko inne i tak zostanie przejęte.

#Bezpieczeństwo i sieć

• Serwer REST pozostaje w sieci firmowej. Nie udostępniaj portu w internecie. jtl-bridge działa wewnątrz, odczytuje serwer REST i przesyła dane na zewnątrz – połączenia przychodzące nie są potrzebne.
• jtl-bridge przesyła dane tylko przez HTTPS. Dane są dodatkowo szyfrowane kluczem wyprowadzonym z tokenu importu.
• Klucz API i token importu traktuj jak hasła: nie wysyłaj ich e-mailem, nie kopiuj do zgłoszeń. Token importu obowiązuje do zakończenia migracji; potem traci ważność.
• Pobierz dane bezpośrednio działa tylko wtedy, gdy API Wawi jest dostępne z internetu. Zalecamy to tylko przy zabezpieczonym dostępie (np. HTTPS przez reverse proxy z ograniczeniem dostępu). W normalnym przypadku użyj jtl-bridge.
• Po migracji możesz ponownie usunąć rejestrację aplikacji allverto w Wawi.

#Rozwiązywanie problemów

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