JTL-Anbindung über die REST API - BISpicy POS | REST API Server, App-Registrierung & Einrichtung

Diese Seite beschreibt die REST-API-Anbindung. Eine Übersicht beider Anbindungsarten und alle gemeinsamen Themen (Sync-Konfiguration, Feld-Mapping, Kassenapp verbinden, Auto-Sync) finden Sie auf der JTL-Wawi Integration. BISpicy empfiehlt die SQL-Direkt-Anbindung — schneller Sync, volle Kontrolle, kein REST API Server nötig.

Überblick

BISConnect — der JTL-Wawi-Bridge-Desktop-Client — bietet zwei Verbindungsmodi. Bei der REST API kommuniziert BISConnect über die JTL REST API mit Ihrer JTL-Wawi. Dafür muss der JTL REST API Server laufen und in JTL-Wawi eine App-Registrierung für BISpicy angelegt sein.

In BISConnect wird dieser Modus über einen Umschalter im Tab „Einstellungen" ausgewählt — die Option trägt das Label „REST API" mit dem Untertitel „Über die JTL REST API. Erfordert REST API Server."

Empfehlung: Für die meisten Betriebe ist die SQL-Direkt-Anbindung die einfachere und schnellere Wahl — dort entfallen der REST API Server und die JTL-App-Registrierung. Wählen Sie die REST API, wenn Sie die JTL REST API ohnehin einsetzen.

Voraussetzungen

Bevor Sie die REST-API-Anbindung einrichten, stellen Sie sicher, dass folgende Voraussetzungen erfüllt sind:

#	Voraussetzung	Details
1	JTL-Wawi 1.9+	Die REST API ist erst ab Version 1.9 verfügbar. Prüfen Sie Ihre Version unter Hilfe → Über JTL-Wawi.
2	REST API aktiviert	Die JTL REST API muss in den Einstellungen aktiviert und eine App-Registrierung angelegt sein.
3	BISpicy POS Account	Ein aktives BISpicy-Konto mit WaWi-Verbindung (BIS ERP oder Kundencenter).
4	Netzwerkzugang	Der BISpicy-Server muss die JTL-Wawi REST API erreichen können (Port freigegeben, ggf. VPN/Port-Forwarding bei OnPremise).

Hinweis: Die JTL REST API befindet sich derzeit noch im Beta-Stadium. Einige Endpunkte können sich in zukünftigen JTL-Versionen ändern. BISpicy passt die Integration laufend an neue JTL-API-Versionen an.

Kostenlos: Die JTL-Wawi Integration ist für alle BISpicy-Nutzer kostenlos verfügbar. Es ist kein Premium-Feature oder Zusatz-Abo erforderlich.

Einrichtung

Die Einrichtung erfolgt in 9 Schritten — alle der Reihe nach, ohne hin und her zu springen.

1JTL-Wawi REST API Server starten

Bevor Sie die Integration einrichten können, muss der REST API Server auf Ihrem JTL-Wawi-Rechner laufen. Sie haben zwei Möglichkeiten:

Option A: Manueller Start über Kommandozeile (CMD)

Öffnen Sie die Eingabeaufforderung (CMD) als Administrator
Navigieren Sie zum JTL-Installationsverzeichnis:
CMDcd "C:\Program Files (x86)\JTL-Software"
Starten Sie den REST API Server:
CMDJTL.Wawi.Rest.exe -w "Standard" -l 0.0.0.0 --port 5883 -d eazybusiness

Parameter	Beschreibung	Standard
`-w`	JTL-Wawi Profilname	`Standard`
`-l`	IP-Adresse, auf der der Server lauscht	`0.0.0.0` (alle Schnittstellen)
`--port`	Port für die REST API	`5883`
`-d`	Name der JTL-Datenbank	`eazybusiness`

IP-Adresse: 127.0.0.1 = nur lokaler Zugriff, 192.168.x.x = Zugriff im lokalen Netzwerk, 0.0.0.0 = alle Schnittstellen (lokal + Netzwerk + extern). Für die BISpicy-Anbindung muss der Server von außen erreichbar sein — verwenden Sie 0.0.0.0.

Option B: Automatischer Start als Windows-Dienst (empfohlen)

Ab JTL-Wawi 1.9 können Sie den REST API Server als Windows-Dienst installieren, sodass er automatisch mit Windows startet:

CMD (als Administrator)JTL.Wawi.Rest.exe install --instancename "JTL-Wawi API" -w "Standard" -l 0.0.0.0 --port 5883 -d eazybusiness

Der Dienst lässt sich über die Windows-Dienstverwaltung (services.msc) starten, stoppen und auf "Automatisch" setzen.

Wichtig: Falls der Server unerwartet stoppt, prüfen Sie ob der Editiermodus in JTL-Wawi aktiv ist — dieser kann den API-Server blockieren. Schließen Sie ggf. den Editiermodus.

CMD-Fenster nicht hochscrollen! Wenn Sie im CMD-Fenster nach oben scrollen, wird der Server pausiert und ist nicht mehr erreichbar. Stellen Sie sicher, dass Sie nach dem Scrollen mit der Enter-Taste wieder ganz nach unten scrollen. Andernfalls kommt es zu Fehlermeldungen, dass der Server nicht erreichbar ist.

JTL-Dokumentation: Die vollständige Anleitung finden Sie auch direkt bei JTL: JTL-Wawi API über Kommandozeile starten

2BISConnect einrichten (On-Premise)

Bei einer lokal installierten JTL-Wawi benötigen Sie BISConnect als Brücke zwischen dem BISpicy-Cloud-Server und Ihrem lokalen JTL-Server:

BISConnect für Windows herunterladen aktuell v1.0.4

Windows blockiert die Installation? Beim Öffnen der heruntergeladenen Datei meldet Windows unter Umständen: "Diese Datei stammt von einem anderen Computer. Der Zugriff wurde aus Sicherheitsgründen eventuell blockiert." Das ist bei heruntergeladenen Programmen normal und kein Hinweis auf Schadsoftware. So heben Sie die Blockierung auf:

Rechtsklick auf die Datei BISConnect-Setup.exe → Eigenschaften
Im Reiter Allgemein ganz unten im Bereich Sicherheit das Kästchen "Zulassen" anhaken
Mit OK bestätigen — danach lässt sich BISConnect normal installieren

Windows-Dateieigenschaften: Kästchen Zulassen anhaken

Datei-Eigenschaften — unten rechts das Kästchen "Zulassen" anhaken

BISConnect auf dem JTL-Server installieren und starten
In BISConnect im Tab Einstellungen über den Umschalter den Modus „REST API" wählen (Untertitel: „Über die JTL REST API. Erfordert REST API Server.")
In BISpicy unter JTL-Integration den BISConnect-Token generieren
Token und JTL-Wawi lokale URL (z.B. http://127.0.0.1:5883) in BISConnect eintragen
BISConnect verbinden, dann in BISpicy "Status aktualisieren" klicken

BISConnect Client - Einstellungen mit aktiviertem Modus REST API

BISConnect — Tab Einstellungen mit dem Modus „REST API" und der lokalen JTL-Wawi-URL

JTL Cloud: Bei JTL Cloud ist kein BISConnect erforderlich — überspringen Sie diesen Schritt und verwenden Sie die von JTL bereitgestellte Cloud-URL.

3BISpicy Kundencenter → Verbindungsdaten eingeben

Navigieren Sie in BISpicy zur JTL-Integration:

BIS ERP: Menü → Integrationen → JTL-Wawi
Kundencenter: Menü → JTL-Wawi Integration

Klicken Sie auf "Mit JTL verbinden" und füllen Sie den Dialog aus:

BISpicy Verbindungsdialog — Server-URL, Datenbankname und Registrierung

Feld	Beschreibung	Beispiel
Verbindungsname	Frei wählbarer Name für diese Verbindung	`JTL-Wawi`
JTL-Wawi Server-URL	IP-Adresse Ihres JTL-Servers (Port wird automatisch ergänzt, Standard: `5883`)	`192.168.1.61`
JTL-Wawi On-Premise	Aktivieren, wenn JTL lokal installiert ist (nicht Cloud)	Ein / Aus
Datenbankname	Name der JTL-Datenbank (der gleiche wie beim Start des API-Servers, Parameter `-d`)	`eazybusiness`

Noch nicht auf "Registrierung starten" klicken! Zuerst muss in JTL-Wawi die Registrierung vorbereitet werden (nächster Schritt).

4JTL-Wawi → Registrierung beginnen

Wechseln Sie zur JTL-Wawi Desktop-Anwendung und öffnen Sie den Registrierungsdialog:

Öffnen Sie in JTL-Wawi: JTL-Wawi API → Anwendung registrieren
Klicken Sie auf "Registrierung beginnen"
JTL-Wawi zeigt: "Es wird auf die Übermittlung einer Registrierungsanfrage durch die zu registrierende Anwendung gewartet..."

JTL-Wawi API - Registrierungsanfrage entgegennehmen

JTL-Wawi wartet auf die Registrierungsanfrage von BISpicy

Lassen Sie dieses Fenster geöffnet und wechseln Sie zurück zu BISpicy (nächster Schritt).

5BISpicy → Registrierung starten

Klicken Sie jetzt in BISpicy auf "Registrierung starten". BISpicy sendet die Anfrage an Ihre JTL-Wawi.

Kein manuelles Kopieren nötig: Der API-Key wird automatisch zwischen JTL-Wawi und BISpicy ausgetauscht.

6JTL-Wawi → App bestätigen

In JTL-Wawi erscheint jetzt die erkannte Anwendung. Gehen Sie alle Schritte vollständig durch:

JTL-Wawi API - BISpicy POS & ERP erkannt

JTL-Wawi hat die BISpicy-App erkannt — klicken Sie auf "Weiter"

a) Anwendungsinformationen — prüfen und auf "Weiter" klicken.

b) Benutzer zuordnen — vergeben Sie einen Benutzernamen (z.B. BISpicy):

Benutzername für die BISpicy-App vergeben

c) Zugriffsverwaltung — alle fünf API-Scopes müssen erteilt sein:

all.read — Lesezugriff auf alle Daten (Artikel, Kunden, Bestand)
stock.stockadjustment — Bestandsänderungen durchführen
salesorder.createsalesorder — Kassenverkäufe als Aufträge anlegen
customer.createcustomer — POS-Barkauf-Kunden automatisch erstellen
customers.write — Kundendaten schreiben

Alle API-Scopes müssen als "Erteilen" angehakt sein

d) Einrichtung abschließen — Zusammenfassung prüfen und auf "Fertigstellen" klicken:

Zusammenfassung prüfen und auf "Fertigstellen" klicken

7BISpicy → Registrierung abschließen

Zurück in BISpicy: Aktivieren Sie die Checkbox "Einrichtung in JTL-Wawi abgeschlossen" und klicken Sie auf "Registrierung abschließen".

Erst aktivieren, wenn JTL-Wawi fertig ist! Die Checkbox darf erst angehakt werden, wenn alle Schritte in JTL-Wawi komplett abgeschlossen sind (inkl. Benutzer- und Rechtevergabe). Andernfalls kann der API-Key nicht abgerufen werden.

BISpicy - Einrichtung in JTL-Wawi abschließen

Checkbox aktivieren und "Registrierung abschließen" klicken

Nach dem Klick wird der API-Key automatisch abgerufen:

Verbindung erfolgreich — der API-Key wurde automatisch gespeichert

In der JTL-Wawi Übersicht erscheint die Checkbox "Registrierung abgeschlossen" automatisch als angehakt:

JTL-Wawi Übersicht — Registrierung abgeschlossen

8Sync-Richtung konfigurieren

Legen Sie für jeden Datentyp fest, in welche Richtung synchronisiert werden soll. Details dazu finden Sie auf der Einstiegsseite im Abschnitt Sync-Konfiguration.

9Verbindung testen

Klicken Sie auf "Testen", um die Erreichbarkeit und Authentifizierung zu prüfen.

Status	Bedeutung
Verbunden	Verbindung erfolgreich. Sie können den ersten Sync auslösen.
Fehlgeschlagen	Prüfen Sie URL, API-Key und Netzwerk (siehe Fehlerbehebung).

Wie geht es weiter?

Sobald die Verbindung steht, erfolgt die weitere Konfiguration unabhängig vom gewählten Anbindungsmodus. Die folgenden Themen sind auf der Einstiegsseite JTL-Wawi Integration beschrieben:

Sync-Konfiguration — Sync-Richtung pro Datentyp festlegen
Feld-Mapping — wie BISpicy-Felder auf JTL-Felder abgebildet werden
Kassenapp verbinden — die POS-App mit demselben Konto anmelden
Auto-Sync — Intervall und Sync-Protokoll
Rechnungskauf an der Kasse — Rechnungsdruck über einen JTL-Workflow

BISpicy empfiehlt für die meisten Betriebe die SQL-Direkt-Anbindung. Der Anbindungsmodus lässt sich in BISConnect jederzeit über den Umschalter im Tab „Einstellungen" wechseln.

Fehlerbehebung (REST API)

Nachfolgend finden Sie Lösungen für die häufigsten Probleme der REST-API-Anbindung. Allgemeine Sync-Probleme (Produkte, Bestand) sind in der Fehlerbehebung der Einstiegsseite beschrieben.

"HttpListenerException: Format des Netzwerknamens ungültig"

Problem: Der REST API Server startet nicht und meldet System.Net.HttpListenerException: Das Format des angegebenen Netzwerknamens ist unzulässig.

Ursache: Windows kann den Server nicht auf die angegebene IP-Adresse binden — häufig nach einem Neustart, wenn Netzwerkadapter (WLAN, VPN) deaktiviert sind.

Lösung (der Reihe nach versuchen):

Stellen Sie sicher, dass die CMD als Administrator geöffnet ist
URL-Reservierung in Windows anlegen:
CMD (Admin)netsh http add urlacl url=http://+:5883/ user=Everyone
Falls die Reservierung bereits existiert — erst löschen, dann neu anlegen:
CMD (Admin)netsh http delete urlacl url=http://+:5883/ netsh http add urlacl url=http://+:5883/ user=Everyone
Falls weiterhin fehlschlägt: Starten Sie zunächst mit localhost zum Testen:
CMD (Admin)JTL.Wawi.Rest.exe -w "Standard" -l 127.0.0.1 --port 5883 -d eazybusiness

Hinweis: Mit 127.0.0.1 ist der Server nur lokal erreichbar. Für die BISpicy-Anbindung muss der Server von außen erreichbar sein. Prüfen Sie in diesem Fall, ob deaktivierte Netzwerkadapter (WLAN, VPN) das Binden auf 0.0.0.0 verhindern, und aktivieren Sie diese ggf. wieder.

"Verbindung fehlgeschlagen"

Problem: Der Verbindungstest schlägt fehl, die JTL-Wawi ist nicht erreichbar.

Lösung:

Prüfen Sie, ob die IP-Adresse und der Port korrekt eingegeben sind (Standard-Port: 5883)
Stellen Sie sicher, dass die Windows-Firewall auf dem JTL-Server den Port freigibt
Bei OnPremise: Prüfen Sie, ob der JTL-Server von außen erreichbar ist (Port-Forwarding, VPN)
Prüfen Sie, ob der JTL REST API Server auf dem Server läuft (siehe Schritt 1: REST API Server starten)

"401 Unauthorized"

Problem: Die Authentifizierung schlägt fehl.

Lösung:

Prüfen Sie, ob der API-Key korrekt kopiert wurde (keine Leerzeichen am Anfang/Ende)
Prüfen Sie, ob die App-Registrierung in JTL noch aktiv ist
Erstellen Sie ggf. eine neue App-Registrierung in JTL und verwenden Sie den neuen Key

"Timeout"

Problem: Die Verbindung wird hergestellt, aber die Anfrage läuft in ein Timeout.

Lösung:

Prüfen Sie die Netzwerkverbindung zwischen BISpicy-Server und JTL-Server
Bei großen Datenmengen: Reduzieren Sie ggf. die Batch-Größe beim initialen Sync
Prüfen Sie die Server-Auslastung des JTL-Servers (CPU, RAM)

Weitere Hilfe

Wenn Sie ein Problem nicht lösen können, kontaktieren Sie unseren Support:

In-App Support

Öffnen Sie ein Support-Ticket direkt in der BISpicy POS App unter Einstellungen → Support.

E-Mail

Schreiben Sie uns an [email protected] mit einer Beschreibung des Problems.

Zurück zur JTL-Wawi Integration