Die JTL-Wawi-REST-API einrichten

Die JTL-Wawi hat eine eigene Programmierschnittstelle: die JTL-Wawi-API, oft auch „REST-API“ oder „REST-Server der Wawi“ genannt. Über sie kann ein anderes Programm – hier allverto – Artikel, Kunden und Belege aus deiner Wawi lesen, ohne direkt in die Datenbank zu greifen. Diese Seite erklärt, was du dafür in der Wawi einrichten musst.

#Was ist die REST-API – in einfachen Worten?

Stell dir den REST-Server als Empfangsschalter deiner Wawi vor. Programme, die Daten wollen, fragen am Schalter an („gib mir alle Rechnungen“). Der Schalter prüft, ob das Programm einen gültigen Ausweis hat – den API-Schlüssel – und gibt dann genau die freigegebenen Daten heraus.

• Der REST-Server ist ein Programm von JTL, das in deinem Firmennetz läuft, meist auf demselben Rechner wie die Wawi oder ihr SQL Server.
• Er ist über eine Adresse wie http://wawi-server:5883/api/eazybusiness erreichbar. wawi-server ist der Name oder die IP deines Rechners, 5883 der Port (bei dir kann es ein anderer sein), eazybusiness der Name deiner Wawi-Datenbank.
• Jedes Programm muss sich einmal als App registrieren. Du bestätigst die Registrierung in der Wawi, danach bekommt das Programm seinen API-Schlüssel.
• allverto meldet sich als App „allverto – Umzug von JTL-Wawi“ an und fragt nur Lesezugriff an (dazu optional das Drucken von Rechnungs-PDFs). allverto ändert in deiner Wawi nichts.

#Ab welcher Wawi-Version?

allverto nutzt die API in der Fassung, die JTL für die Wawi 2.1 und 2.2 veröffentlicht hat (Pfade mit /v2/…). Mit diesen Versionen ist der API-Weg gebaut und getestet.

#Schritt für Schritt

#1. REST-Server in der Wawi aktivieren

1. Melde dich an der JTL-Wawi als Benutzer mit Administrationsrechten an.
2. Richte den REST-Server so ein, wie JTL es für deine Version beschreibt, und starte ihn. Notiere dir dabei den Port, auf dem er lauscht.
3. Prüfe, dass der Server läuft: Ein Rechner im Firmennetz muss die Adresse http://<wawi-server>:<port>/api/eazybusiness erreichen können (Firewall des Wawi-Rechners für diesen Port im internen Netz freigeben).

#2. allverto als App registrieren

Die Registrierung startest du mit dem Hilfsprogramm jtl-bridge auf einem Rechner im Firmennetz:

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

1. jtl-bridge schickt die Registrierungsanfrage an deinen REST-Server und meldet: „Registrierung gesendet … Bitte jetzt in der JTL-Wawi unter Admin → App-Registrierung bestätigen“.
2. Öffne in der Wawi die App-Registrierung. So heißt der Punkt laut unseren Unterlagen in Wawi 2.2: Admin → App-Registrierung. Dort steht die Anfrage von allverto – Umzug von JTL-Wawi mit den angefragten Rechten.
3. Prüfe die Rechte (nur Lesen, optional Rechnungen drucken) und bestätige die Anfrage.
4. jtl-bridge fragt alle 5 Sekunden nach. Nach der Bestätigung zeigt es den API-Schlüssel an – nur dieses eine Mal. Kopiere ihn sofort.
5. Bestätigst du nicht innerhalb von 10 Minuten, bricht jtl-bridge ab – starte die Registrierung dann einfach neu.

#3. In allverto eintragen

1. Öffne Einstellungen → Datenübernahme → Umzug von JTL-Wawi, Schritt Quelle verbinden.
2. Wähle JTL-Wawi-API.
3. Trage bei Adresse der Wawi-API die Adresse aus Schritt 1 ein, z. B. http://wawi-server:5883/api/eazybusiness.
4. Füge den API-Schlüssel ein. allverto speichert ihn verschlüsselt; beim nächsten Öffnen steht dort „Hinterlegt – leer lassen, um ihn zu behalten“.
5. Mandanten-ID (optional): nur ausfüllen, wenn deine Wawi eine verlangt. Bei einer Wawi im eigenen Haus bleibt das Feld meist leer.
6. Lass Rechnungs-PDFs über die API holen an, wenn deine Rechnungen als PDF mitkommen sollen (die Wawi erzeugt sie dafür neu).
7. Optional: Trage den SQL Server ein – dann ergänzt jtl-bridge, was die API nicht liefert (siehe unten).
8. Klicke auf Quelle speichern.

#4. Daten hochladen

Weil der REST-Server nur im Firmennetz erreichbar ist (und das auch so bleiben soll), lädt jtl-bridge die Daten hoch: Import-Token erzeugen, dann den angezeigten Befehl im Firmennetz ausführen, z. B.

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

Weiter geht es im Assistenten mit Gefundene Daten und Zuordnungen – siehe Umzug von JTL-Wawi: so läuft es ab.

#Was liefert die API – und was nicht?

#Wie jtl-bridge die Lücken schließt

Startest du jtl-bridge mit --fill-from-db und hast in allverto zusätzlich den SQL Server hinterlegt, liest es alles, was die API nicht oder nur teilweise liefert, direkt aus der Datenbank: Abos, Eingangsrechnungen, Positionen von Rechnungskorrekturen, Stücklisten, Attributnamen, SEPA-Mandate. Dafür reicht ein Datenbank-Benutzer nur mit Leserecht. Ohne Datenbank fehlen diese Daten – alles andere wird trotzdem übernommen.

#Sicherheit und Netzwerk

• Der REST-Server bleibt im Firmennetz. Gib den Port nicht ins Internet frei. jtl-bridge läuft innen, liest den REST-Server und lädt die Daten nach außen hoch – eingehende Verbindungen braucht es nicht.
• jtl-bridge lädt nur über HTTPS hoch. Die Daten sind zusätzlich mit einem Schlüssel aus dem Import-Token verschlüsselt.
• Der API-Schlüssel und das Import-Token sind wie Passwörter: nicht per E-Mail verschicken, nicht in Tickets kopieren. Das Import-Token gilt bis zum Abschluss des Umzugs; danach ist es ungültig.
• Daten direkt abholen funktioniert nur, wenn die Wawi-API aus dem Internet erreichbar ist. Das empfehlen wir nur mit abgesichertem Zugang (z. B. HTTPS über einen Reverse-Proxy mit Zugriffsbeschränkung). Im Normalfall nimm jtl-bridge.
• Nach dem Umzug kannst du die App-Registrierung von allverto in der Wawi wieder entfernen.

#Fehlerbehebung

Mehr Fälle: Fehlerbehebung beim JTL-Umzug.