Der JTL-Klar-Sync überträgt deine Bestellungen aus JTL-Wawi 1.x automatisch nach Klar. Du installierst ein Programm auf dem Rechner, auf dem JTL-Wawi läuft. Danach läuft die Übertragung im Hintergrund weiter, ohne dass du etwas tun musst.

⚠️ Beta-Test — Version 1.0.0-beta.10
Das Programm ist im Beta-Test. Es ist von Klar Insights GmbH signiert und meldet neue Versionen selbst. Der Abschnitt Updates erklärt, wie das abläuft. Melde Probleme an [email protected].

1. Was das Programm macht

Das Programm besteht aus drei Teilen:

Teil	Wo es läuft	Aufgabe
Windows-Dienst	Im Hintergrund, immer	Liest die Bestellungen und sendet sie an Klar
Taskleisten-Programm	In deiner Windows-Sitzung, neben der Uhr	Zeigt den Status. Startet Aufgaben. Meldet Updates.
Setup-Assistent	Einmalig, beim ersten Start	Fragt die Zugangsdaten und den Importzeitraum ab

Die Arbeit macht der Dienst. Das Taskleisten-Programm zeigt nur den Status an. Wenn du es schließt, läuft die Übertragung weiter.

Der Dienst führt in jedem Durchlauf diese Schritte aus:

Er sendet Bestellungen erneut, die in einem früheren Durchlauf fehlgeschlagen sind.
Er liest die neuen Bestellungen aus JTL-Wawi.
Er sucht nach Änderungen in den Bestellungen der letzten 90 Tage.
Er sucht nach Bestellungen, die du in JTL-Wawi gelöscht hast.
Er sendet das Ergebnis an Klar.

Der Standardabstand zwischen zwei Durchläufen ist 1 Stunde. Du kannst ihn im Einstellungsfenster ändern.

Warum ein Fehler alles anhält

Wenn Klar eine Gruppe von Bestellungen ablehnt, hält der Dienst an. Er liest keine neuen Bestellungen. Er sendet die fehlgeschlagene Gruppe erneut, mit steigender Wartezeit, bis Klar sie annimmt.

Das ist Absicht. So geht keine Bestellung verloren. Es bedeutet aber auch: Ein dauerhafter Fehler hält alle neuen Bestellungen an. Schau in das Taskleisten-Menü, wenn die Zeile Errors nicht mehr auf 0 steht.

Wie Änderungen erkannt werden

JTL-Wawi kann dem Programm nicht mitteilen, welche Bestellungen sich geändert haben. Das Programm vergleicht deshalb in jedem Durchlauf die Bestellungen der letzten 90 Tage mit dem letzten bekannten Stand.

Eine Art von Änderung erkennt das Programm erst verzögert: eine Änderung an einer Position, die den Gesamtbetrag der Bestellung nicht verändert. Ein Beispiel ist eine korrigierte SKU. Solche Änderungen findet das Programm mit einem langsamen Durchgang, der alle Bestellungen einmal in 24 Stunden prüft. Die maximale Verzögerung ist deshalb 24 Stunden.

Wie Löschungen erkannt werden

Wenn eine Bestellung nicht mehr in der Antwort von JTL-Wawi steht, fragt das Programm JTL-Wawi noch einmal gezielt nach dieser Bestellung. Antwortet JTL-Wawi, dass die Bestellung nicht existiert, gilt sie als gelöscht. Das Programm meldet sie dann als storniert an Klar. Es verwendet dafür den letzten bekannten Stand der Bestellung.

2. Welche Daten an Klar gehen

Es gehen nur Bestelldaten an Klar. Das Programm sendet keine Artikelstammdaten, keine Lagerbestände und keine Lieferantendaten.

Pro Bestellung sendet das Programm:

Bestell-ID, Bestellnummer und die Datumsangaben der Bestellung
Zahlungsstatus und Versandstatus
Währung, Gesamtbeträge, Steuern und Rabatte
Name der Zahlungsart und Name des Zahlungsanbieters
Die Positionen: SKU, Produktname, Menge, Beträge, Steuern und Rabatte
Produkt-Tags: die Kategoriepfade des Artikels, seine Warengruppe und freigegebene eigene Felder
Versandkosten und Versandsteuern
Rückerstattungen und Retouren, zugeordnet über die SKU
Die Kundennummer aus JTL-Wawi
Die E-Mail-Adresse des Kunden, oder einen Hash der E-Mail-Adresse (siehe unten)
Aus der Lieferadresse: Ort, Bundesland, Postleitzahl und Land
Die Google-Analytics-Transaktions-ID (siehe unten)

Das Programm sendet nicht den Namen des Kunden. Es sendet nicht die Straße.

Die E-Mail-Adresse

In der Standardeinstellung sendet das Programm die E-Mail-Adresse des Kunden an Klar.

Du kannst im Einstellungsfenster einen Hash salt hinterlegen. Das Programm sendet dann einen SHA1-Hash der E-Mail-Adresse statt der Adresse selbst. Die Adresse verlässt den Rechner dann nicht.

Achtung: Der Salt muss der Salt sein, den Klar ebenfalls verwendet. Sprich ihn mit uns ab. Wenn du den Salt später änderst, sieht Klar alle Kunden als neue Kunden.

Die Google-Analytics-Transaktions-ID

Klar verknüpft eine Bestellung über diese ID mit der passenden Transaktion in GA4. Dafür muss das Programm dasselbe Feld senden, das dein Shop an GA4 schickt.

Du wählst das Feld im Einstellungsfenster unter GA transaction id. Es gibt drei Möglichkeiten:

Auswahl	Was gesendet wird
externalNumber (falls back to number) — Standard	Die externe Bestellnummer aus JTL, zum Beispiel die Bestellnummer aus JTL-Shop oder vom Marktplatz. Fehlt sie, sendet das Programm die JTL-Bestellnummer.
number	Immer die JTL-Bestellnummer, ohne Rückfallebene
id	Die interne, numerische Bestell-ID aus JTL-Wawi

Der Standard passt für die meisten Shops. Prüfe im Zweifel in GA4, welcher Wert dort als Transaktions-ID steht, und wähle hier dasselbe Feld.

Achtung: Eine Änderung wirkt nur auf neue und auf geänderte Bestellungen. Bereits übertragene Bestellungen behalten die alte ID. Um sie nachzuziehen, brauchst du Re-export: full refresh from JTL (Abschnitt 9). Die anderen beiden Re-Export-Varianten senden den gespeicherten Stand erneut und ändern nichts.

Wo die Zugangsdaten liegen

Das Programm speichert den JTL-Wawi-API-Key und den Klar-Token in der Datei config.yaml. Beide Werte sind mit der Windows Data Protection API verschlüsselt und an den Rechner gebunden. Nur derselbe Rechner kann sie entschlüsseln.

3. Voraussetzungen

Punkt	Anforderung
Betriebssystem	Windows 10, Windows 11, oder Windows Server 2019 oder neuer
Architektur	64-Bit
JTL-Wawi	Version 1.x, auf demselben Rechner wie das Programm
JTL-Wawi-API	Die JTL-Wawi-API-Lizenz, gebucht im JTL-Kundencenter
JTL-API-Server	Gestartet und erreichbar unter `http://127.0.0.1:5883/api/eazybusiness/`
Klar	Ein Klar-Konto und ein Access Token (siehe Abschnitt 4)
Rechte	Administratorrechte, nur für die Installation und für Updates
Speicherplatz	100 MB für das Programm. Etwa 2 MB je 1.000 Bestellungen.
Netzwerk	Ausgehendes HTTPS zur Klar-API und zum Klar-Update-Server

Das Programm braucht keine eigene Datenbank und keinen eigenen Webserver.

Hinweis zu Terminalservern und Servern ohne Grafikkarte

Der Setup-Assistent und das Einstellungsfenster brauchen OpenGL 2.1 oder neuer. Das Taskleisten-Symbol und der Dienst brauchen kein OpenGL.

Achtung: Auf einem Server ohne Grafikadapter und in manchen Remotedesktop-Sitzungen kann OpenGL fehlen. Der Setup-Assistent öffnet sich dann möglicherweise nicht. Führe ihn in diesem Fall direkt an der Konsole des Rechners aus. Melde uns diesen Fall bitte — wir wollen wissen, ob er in der Praxis auftritt.

4. Vorbereitung

Lege diese fünf Dinge bereit, bevor du installierst:

Die Installationsdatei jtl-klar-sync-setup.exe herunterladen.
Administratorrechte auf dem JTL-Wawi-Rechner.
Die JTL-Wawi-API-Lizenz. Buche sie im JTL-Kundencenter.
Einen JTL-Wawi-Benutzer, der eine App-Registrierung annehmen darf.
Den Klar Access Token (siehe unten).

Gut zu wissen: Die JTL-Wawi-API ist während der JTL-Beta-Phase kostenlos. JTL berechnet sie nach dem offiziellen Release.

Ohne API-Lizenz beantwortet JTL-Wawi jede Anfrage mit HTTP 402. Der Setup-Assistent zeigt dann einen Hinweis auf die Lizenz. Solange die Lizenz fehlt, erreicht keine Bestellung Klar.

Den Klar Access Token erzeugen

Der Token berechtigt das Programm, deine Bestellungen in Klar zu schreiben. Du erzeugst ihn im Klar-Dashboard.

Gehe zu Einstellungen → Store-Konfigurator → dein Store → Datenquellen.
Klicke auf Connect Data Source.
Wähle im Dialog Klar API.
Gib der Datenquelle einen Namen, zum Beispiel JTL-Wawi, und speichere sie.
Öffne die neue Datenquelle.
Gehe zum Tab Access Token.
Klicke auf Copy Token.

Der Token ist eine lange Zeichenkette, die mit eyJ beginnt. Ausführliche Beschreibung: API-Authentifizierung.

Achtung: Lege für JTL-Wawi eine eigene Datenquelle an. Verwende nicht den Token einer bestehenden Datenquelle, die schon Bestellungen aus einer anderen Quelle liefert.

5. Installation

Kopiere jtl-klar-sync-setup.exe auf den JTL-Wawi-Rechner.
Doppelklicke die Datei.
Bestätige die Rückfrage der Benutzerkontensteuerung mit Ja. Als Herausgeber steht dort Klar Insights GmbH.
Bestätige den vorgeschlagenen Zielordner und klicke auf Install.
Warte, bis die Installation fertig ist.
Klicke auf Close.

Installer: Auswahl des Zielordners mit der Schaltfläche Install.

Gut zu wissen: Bei einer brandneuen Version kann Windows trotz gültiger Signatur einmalig einen SmartScreen-Hinweis zeigen, weil die Datei noch selten heruntergeladen wurde. Prüfe in diesem Fall, dass als Herausgeber Klar Insights GmbH steht, und fahre fort. Schalte keinen Virenscanner ab.

Die Installation macht Folgendes:

Sie kopiert das Programm nach C:\Program Files\JtlKlarSync\.
Sie legt den Datenordner C:\ProgramData\JtlKlarSync\ an.
Sie registriert den Windows-Dienst JtlKlarSync. Der Dienst läuft als NetworkService.
Sie legt vier Startmenü-Einträge an (siehe Abschnitt 11).
Sie legt einen Autostart-Eintrag an, damit das Taskleisten-Programm bei jeder Anmeldung startet.
Sie startet das Taskleisten-Programm.

Bei einer Erstinstallation startet der Installer den Dienst noch nicht. Das macht der Setup-Assistent.

Der Setup-Assistent öffnet sich nach der Installation automatisch, weil noch keine Konfiguration vorhanden ist.

6. Der Setup-Assistent

Der Assistent hat drei Schritte. Schließe das Fenster nicht, bevor Schritt 3 fertig ist. Die Oberfläche des Assistenten ist englisch, JTL-Wawi ist deutsch.

Schritt 1 von 3 — Connect to JTL WaWi

In diesem Schritt registriert sich das Programm als App in JTL-Wawi. JTL-Wawi gibt dem Programm dafür einen API-Key.

Wichtig: Öffne die App-Registrierung zuerst in JTL-Wawi. JTL-Wawi muss auf die Anfrage warten, bevor du sie im Assistenten abschickst. Sonst weist die API die Anfrage ab.

Öffne JTL-Wawi.
Melde dich an derselben Datenbank an, die die API bedient. Der Datenbankname steht in der API-URL im Assistenten, meist eazybusiness.
Öffne Admin und dann App-Registrierung.
Starte eine neue App-Registrierung.
Wechsle zum Setup-Assistenten.
Prüfe die API URL. Der Standardwert ist http://127.0.0.1:5883/api/eazybusiness/.
Ändere den Port, wenn der JTL-API-Server einen anderen Port benutzt.
Klicke auf Register with JTL-Wawi.
Wechsle zu JTL-Wawi.
Nimm die Anfrage Klar Sync an.
Weise den JTL-Wawi-Benutzer zu, unter dem das Programm arbeiten soll.
Erteile die angeforderte Berechtigung. Das Programm braucht nur Leserechte (all.read).
Klicke auf Fertigstellen.
Wechsle zum Assistenten. Er zeigt ✓ Registered — API key received. Click Continue.
Klicke auf Continue ▸.

Setup-Assistent, Schritt 1 von 3, mit API-URL-Feld und der Schaltfläche Register with JTL-Wawi.

JTL-Wawi: Admin ▸ App-Registrierung mit der offenen Anfrage Klar Sync.

JTL-Wawi: Benutzerzuweisung und Berechtigungsfreigabe, mit der Schaltfläche Fertigstellen.

Setup-Assistent mit der Erfolgsmeldung ✓ Registered — API key received.

Der Assistent fragt JTL-Wawi alle 3 Sekunden nach dem Ergebnis. Nach 10 Minuten bricht er ab. Starte den Vorgang dann neu.

Achtung: JTL-Wawi gibt den API-Key nur ein einziges Mal heraus, und zwar je App-ID. Es kann denselben Key nicht erneut ausgeben. Bewahre eine Kopie des Keys an einem sicheren Ort auf.

Wenn du schon einen API-Key hast — zum Beispiel nach einer Neuinstallation:

Klicke auf I already have an API key.
Trage den vorhandenen Key ein.
Klicke auf Continue ▸.

Gut zu wissen: Nach einem Factory Reset bietet der Assistent den alten Key von selbst an, sofern er noch funktioniert. Dann erscheint die Schaltfläche Use the preserved API key. Nutze sie — eine neue Registrierung mit derselben App-ID würde abgewiesen.

Schritt 2 von 3 — Connect to Klar

Lass die vorbelegte API URL unverändert, außer Klar hat dir eine andere URL genannt.
Füge den Klar-Token in das Feld Access token ein.
Klicke auf Continue ▸.

Gut zu wissen: Der Assistent prüft den Token in diesem Schritt noch nicht. Du kannst die Verbindung nach dem Setup jederzeit im Einstellungsfenster mit Test connection prüfen. Bei Erfolg erscheint dort ✓ Connected to Klar.

Setup-Assistent, Schritt 2 von 3, mit den Feldern API URL und Access/Bearer token.

Schritt 3 von 3 — Sync settings

Hier legst du fest, wie weit die Historie zurückreichen soll und wie schnell das Programm arbeiten darf.

Order history

Wähle bei Import orders from den Monat und das Jahr, ab dem Klar deine Bestellungen sehen soll. Vorbelegt sind 24 Monate zurück, damit du in Klar sofort einen Vorjahresvergleich hast.
Aktiviere Import the entire history instead, wenn Klar wirklich alles sehen soll.
Lies die Schätzung unter dem Feld. Der Assistent fragt JTL, wie viele Bestellungen in dem gewählten Zeitraum liegen, und nennt die zu erwartende Dauer. Die Schätzung aktualisiert sich, wenn du Zeitraum oder Geschwindigkeit änderst.

Sync behaviour

Wähle bei Check JTL every, wie oft nach dem Import nach neuen Bestellungen gesucht wird. Zur Auswahl stehen 15 Minuten, 30 Minuten, 1, 2, 4, 8, 12 und 24 Stunden. Standard ist 1 hour.
Wähle bei Speed, wie stark das Programm die JTL-API belasten darf:

Speed	Wann
Conservative (5 requests/second) — Standard	JTL-Wawi läuft auf einem Arbeitsplatzrechner oder auf einem Server, auf dem noch anderes läuft
Balanced (15 requests/second)	Ein dedizierter JTL-Server
Fast (30 requests/second)	Ein Rechner, der nichts anderes tut

Klicke danach auf Finish and start sync.

Der Assistent verschlüsselt die Zugangsdaten und startet den Dienst. Danach erscheint die Meldung Setup complete. Du kannst das Fenster schließen.

Setup-Assistent, Schritt 3 von 3, mit Import orders from, der Schätzung, Check JTL every und Speed.

Abschlussmeldung Setup complete.

Achtung: Der gewählte Startmonat bestimmt, was Klar an Historie sieht. Du kannst den Zeitraum später mit Re-import a date range… im Taskleisten-Menü erweitern, aber es ist einfacher, ihn hier gleich richtig zu wählen. Wähle nicht knapper als 24 Monate, wenn du Vorjahresvergleiche brauchst.

7. Der erste Import

Der Dienst startet sofort. Der erste Durchlauf überträgt die gewählte Historie. Das dauert, und der Assistent hat dir dafür bereits eine Schätzung genannt.

Diese Werte kommen aus einem Testsystem und gelten für Conservative, also 5 Anfragen pro Sekunde. Sie sind Richtwerte und können auf deinem Rechner abweichen:

Vorgang	Gemessene Zeit
Erster Import von 5.000 Bestellungen	etwa 19 Minuten
Ein Durchlauf mit 140 neuen Bestellungen	etwa 32 Sekunden
Ein Durchlauf ohne neue Bestellungen	etwa 2,4 Sekunden
Arbeitsspeicher des Dienstes	unter 100 MB

Eine Historie mit 200.000 Bestellungen braucht mehrere Stunden. Das Taskleisten-Menü zeigt währenddessen den Fortschritt, zum Beispiel Status: Importing order history: 1.200 of 203.400 (0%).

Lass den Rechner an, bis der erste Import fertig ist. Wenn der Rechner ausgeht, setzt das Programm nach dem nächsten Start an der letzten Position fort. Es geht keine Bestellung verloren, und keine Bestellung wird doppelt gezählt.

8. Das Taskleisten-Symbol

Das Symbol ist das Klar-Zeichen, neben der Uhr. Es hat drei Zustände:

Symbol	Bedeutung
Zeichen ohne Punkt	Der Dienst ist im Ruhezustand
Zeichen mit pulsierendem Punkt	Gerade läuft ein Sync
Zeichen mit orangem Punkt	Eine neue Version steht bereit (siehe Abschnitt 10)

Die Animation startet erst, wenn ein Vorgang länger als 2 Sekunden dauert. Ein kurzer Durchlauf zeigt deshalb keine Animation.

Zeige mit der Maus auf das Symbol, um den Status als Text zu sehen.

Taskleiste mit dem Klar-Symbol und Tooltip Update 1.0.0-beta.8 available - JTL-to-Klar Sync: idle.

Wenn das Symbol fehlt, ist das Taskleisten-Programm nicht gestartet. Starte JTL-to-Klar Sync über das Startmenü. Prüfe auch den Bereich der ausgeblendeten Symbole.

Klicke einmal auf das Symbol, um das Menü zu öffnen.

Taskleisten-Menü im Normalzustand.

Die Statuszeilen

Die oberen Zeilen zeigen den Status. Sie sind nicht anklickbar.

Zeile	Bedeutung
Status: Idle, up to date	Was der Dienst gerade macht. Während eines Imports steht hier der Fortschritt.
Last Sync: 2026-08-11 12:46:38 · no changes	Zeitpunkt des letzten Durchlaufs, und was er bewirkt hat: no changes, 1 order oder zum Beispiel 1.072 orders.
Synced to Klar: 465 orders since 01.01.2026	So viele Bestellungen verwaltet diese Installation in Klar, und ab welchem Datum. Bei vollständiger Historie steht dort (full history).
Errors: 0	Anzahl der Bestellungen, die auf einen neuen Versuch warten. Alles außer 0 blockiert neue Bestellungen.
JTL: ✓ · Klar: ✓ · 1.072 orders in JTL	Zustand der beiden Verbindungen, und wie viele Bestellungen JTL-Wawi insgesamt hat.

Gut zu wissen: Synced to Klar und orders in JTL sind absichtlich zwei getrennte Zahlen und kein Bruch. Die erste Zahl gilt nur für den Zeitraum, den du beim Setup gewählt hast. Die zweite ist der Gesamtbestand in JTL-Wawi, auch aus Jahren, die nie synchronisiert werden sollten. Es ist normal und kein Fehler, dass die erste Zahl kleiner ist.

Braucht das Programm deine Hilfe, erscheint unter den Statuszeilen eine Zeile mit einem ⚠. Sie nennt in einem Satz, was zu tun ist.

Die Menüpunkte

Punkt	Funktion
⚠ Update to … available	Erscheint nur, wenn eine neue Version bereitsteht. Öffnet das Update-Fenster (Abschnitt 10).
Tenant: default	Wählt die JTL-Wawi-Installation, für die das Menü gilt. Normalerweise gibt es nur eine.
Sync Now	Startet einen Durchlauf innerhalb weniger Sekunden. Nutze das nach einer Änderung in JTL-Wawi.
Re-export: all synced	Sendet alle bekannten Bestellungen erneut an Klar, aus der lokalen Kopie
Re-export: full refresh from JTL	Liest alle Bestellungen neu aus JTL-Wawi und sendet sie erneut an Klar
Re-import a date range…	Liest einen Zeitraum neu aus JTL-Wawi. Damit holst du Historie nach, die außerhalb des gewählten Startmonats liegt.
View Logs	Öffnet die Logdatei
Settings…	Öffnet das Einstellungsfenster
Version 1.0.0-beta.8	Zeigt die laufende Version. Nenne sie, wenn du den Support kontaktierst.
Quit	Beendet das Taskleisten-Programm. Der Dienst läuft weiter.

Taskleisten-Menü mit der Update-Zeile ganz oben.

Einen Zeitraum nachladen

Klicke auf Re-import a date range….
Trage bei From und To die Grenzen im Format TT.MM.JJJJ ein. Das Enddatum gehört dazu.
Aktiviere Ignore the local cache and re-import everything in this range, wenn der Zeitraum vollständig neu gelesen werden soll.
Klicke auf Start re-import.

Die Re-Export-Varianten

Alle Re-Export-Punkte fragen vorher nach einer Bestätigung.

Re-export: all synced — wenn in Klar Daten fehlen, die das Programm schon übertragen hatte.
Re-export: full refresh from JTL — wenn die Daten in Klar falsch sind, weil sich die Zuordnung geändert hat: eine neue Programmversion, eine geänderte GA transaction id oder neue Produkt-Tags. Nur dieser Modus liest die Daten neu aus JTL-Wawi.

Achtung: Re-export: full refresh from JTL stellt eine Anfrage pro Bestellung. Auf einer großen Installation dauert das mehrere Stunden. Der normale Sync wartet, bis der Re-Export fertig ist. Du kannst ihn nicht abbrechen und nach einem Neustart nicht fortsetzen.

Frage bei Unsicherheit bei [email protected] nach, bevor du einen Re-Export startest.

10. Updates

Das Programm sucht selbst nach neuen Versionen und meldet sie dir. Es installiert nichts ohne deine Zustimmung.

Steht eine neue Version bereit, siehst du das an drei Stellen:

Am Taskleisten-Symbol erscheint ein oranger Punkt.
Im Taskleisten-Menü steht oben ⚠ Update to 1.0.0-beta.8 available.
Einmal am Tag erscheint eine Windows-Benachrichtigung.

Klicke auf die Update-Zeile im Menü, um das Update-Fenster zu öffnen.

Das Update-Fenster mit What's changed und den Schaltflächen Install now und Remind me tomorrow.

Das Fenster nennt die neue und die laufende Version, wie lange das Update schon wartet, und was sich geändert hat. Du hast zwei Möglichkeiten:

Schaltfläche	Wirkung
Install now	Installiert die neue Version. Es dauert etwa eine Minute.
Remind me tomorrow	Blendet Fenster und Benachrichtigung für 24 Stunden aus. Punkt und Menüzeile bleiben.

Was bei der Installation passiert

Das Programm prüft die heruntergeladene Datei: Prüfsumme und Signatur. Eine Datei, die nicht von Klar Insights GmbH signiert ist, wird nicht installiert.
Windows fragt nach Administratorrechten. Bestätige mit Ja.
Der Installer stoppt den Dienst, ersetzt das Programm und startet den Dienst wieder.
Update-Fenster und Taskleisten-Symbol schließen sich und kommen von selbst zurück.

Konfiguration, Zugangsdaten und der gesamte Sync-Stand bleiben erhalten. Es geht keine Bestellung verloren, und keine wird doppelt gezählt.

Wie oft erinnert wird

Wartezeit	Was passiert
Tag 0 bis 2	Punkt am Symbol, Zeile im Menü, eine Benachrichtigung pro Tag
Ab Tag 3	Die Menüzeile wechselt zu ⚠ UPDATE OVERDUE. Das Fenster öffnet sich bei der Anmeldung und alle 4 Stunden.
Ab Tag 7	Das Fenster öffnet sich jede Stunde. Die Schaltflächen sind die ersten 10 Sekunden gesperrt.

Remind me tomorrow setzt diese Uhr nicht zurück. Sie läuft ab dem Zeitpunkt, an dem das Update gefunden wurde. Installiere Beta-Updates zeitnah — sie enthalten die Korrekturen, um die wir dich im Beta-Test gebeten haben.

11. Die Startmenü-Einträge

Eintrag	Funktion	Adminrechte nötig
JTL-to-Klar Sync	Startet das Taskleisten-Programm	nein
Settings	Öffnet das Einstellungsfenster	nein
Restart Service	Stoppt den Dienst und startet ihn neu	nein
Factory Reset	Löscht die Konfiguration und den gesamten Zustand	ja

Nutze Restart Service, nachdem du config.yaml manuell geändert hast, oder wenn der Dienst nicht antwortet.

⚠️ Warnung: Factory Reset löscht die Konfiguration, den Klar-Token und alle Sync-Positionen. Nutze ihn nur nach Absprache mit dem Support. Sichere vorher config.yaml.

Factory Reset macht Folgendes:

Er stoppt den Dienst.
Er löscht die Dateien in C:\ProgramData\JtlKlarSync\.
Er bewahrt den JTL-Wawi-API-Key auf, weil JTL ihn nicht erneut ausgeben kann.
Er lässt den Dienst gestoppt.

Der nächste Start des Programms öffnet den Setup-Assistenten. Er bietet den aufbewahrten API-Key an, sofern dieser noch funktioniert.

Die Bestellungen in Klar bleiben erhalten. Ein neuer Sync sendet sie erneut und ersetzt sie über die Bestell-ID. Es entstehen keine Duplikate.

12. Das Einstellungsfenster

Öffne es über Settings… im Taskleisten-Menü oder über den Startmenü-Eintrag Settings. Unten links steht die laufende Version.

JTL-Wawi connection

Feld	Funktion
API URL	Die Adresse des JTL-API-Servers
API key	Zeigt die Schaltfläche Re-register with JTL. Der Key selbst ist nicht sichtbar.
Test connection	Stellt eine Anfrage an JTL-Wawi. Bei Erfolg erscheint ✓ Reached Wawi. N orders visible.

Klar connection

Feld	Funktion
API URL	Muss mit `https://` beginnen
Access token	Leer lassen, um den gespeicherten Token zu behalten
Test connection	Stellt eine Anfrage an Klar. Bei Erfolg erscheint ✓ Connected to Klar.

Einstellungsfenster: die beiden Verbindungen.

Sync behaviour

Feld	Funktion
Poll every	Der Abstand zwischen zwei Durchläufen. Auswahlliste: 15 Minuten bis 24 Stunden, Standard 1 hour.
Re-check window	Anzahl der Tage für die Änderungserkennung, Standard 90. Ältere Bestellungen werden in Klar nicht mehr aktualisiert.
Hash salt	Macht die Kunden-E-Mail pseudonym. Leer = die Adresse wird gesendet. Siehe Abschnitt 2.
GA transaction id	Welches JTL-Feld als Google-Analytics-Transaktions-ID gesendet wird. Siehe Abschnitt 2.
Sync full order history on first run	Überträgt beim ersten Durchlauf die komplette Historie
ID prefix	Nur nötig, wenn mehrere JTL-Wawi-Installationen einen Klar-Token teilen

Einstellungsfenster: Sync behaviour mit GA transaction id.

Klicke auf Save changes, um die Konfiguration zu schreiben. Es erscheint ✓ Saved. The service picks the change up within a few seconds. Die meisten Änderungen übernimmt der Dienst ohne Neustart. Eine Änderung an der Tenant-Liste startet den Dienst automatisch neu.

13. Mehrere JTL-Wawi-Installationen

Eine Installation des Programms kann mehrere JTL-Wawi-Installationen bedienen. Jede davon ist ein Tenant. Jeder Tenant hat eigene Zugangsdaten, einen eigenen Zustand und einen eigenen Status.

Füge einen Tenant im Einstellungsfenster mit Add tenant… hinzu. Jeder Tenant braucht eine ID. Verwende nur Buchstaben, Zahlen, Bindestrich und Unterstrich, zum Beispiel shop-de. Mit Remove tenant… entfernst du einen Tenant wieder; die Bestellungen in Klar bleiben davon unberührt.

Achtung: Wenn zwei Tenants in dasselbe Klar-Konto schreiben, braucht jeder Tenant ein eigenes ID prefix. Ohne Präfix kollidieren die Bestell-IDs der beiden Tenants in Klar. Das Einstellungsfenster verweigert das Speichern in diesem Fall.

Die meisten Beta-Installationen haben genau einen Tenant. Dann musst du hier nichts tun.

14. Dateien und Ordner

Programmordner: C:\Program Files\JtlKlarSync\

Datenordner: C:\ProgramData\JtlKlarSync\

Datei	Inhalt
`config.yaml`	Die Konfiguration. Die Zugangsdaten darin sind verschlüsselt.
`logs\jtl-klar-sync.log`	Das Log des Dienstes. Bei 10 MB rotiert die Datei; es bleiben bis zu 7 alte Dateien und höchstens 7 Tage.
`tenants\<ID>\sync.db`	Der lokale Zustand: Positionen, Vergleichsdaten, fehlgeschlagene Gruppen
`tenants\<ID>\status.json`	Der Status für das Taskleisten-Programm
`updates\<Version>\`	Die heruntergeladene Installationsdatei einer neuen Version

Das Taskleisten-Programm hat ein eigenes Log unter %LOCALAPPDATA%\JtlKlarSync\logs\jtl-klar-sync.log. Das ist eine andere Datei, weil das Taskleisten-Programm ohne Administratorrechte läuft.

Im Programmordner liegt nach einem Update zusätzlich jtl-klar-sync.exe.previous, die Vorgängerversion. Lösche sie nicht — der Support braucht sie, wenn eine neue Version ein Problem hat.

Die Konfigurationsdatei

Du kannst config.yaml mit einem Texteditor bearbeiten. Für alle Werte, die das Einstellungsfenster zeigt, ist das Einstellungsfenster der bessere Weg.

Das sind die wichtigsten Standardwerte:

sync:
  pollInterval: 1h                                  # Abstand zwischen zwei Durchläufen
  batchSize: 1000                                   # max. Bestellungen pro Anfrage an Klar
  recheckWindowDays: 90                             # Tage, die auf Änderungen geprüft werden
  fullRecheckIntervalHours: 24                      # Intervall für den langsamen Durchgang
  googleAnalyticsTransactionIdSource: orderNumber   # orderNumber | orderName | id

rateLimit:
  jtlRequestsPerSecond: 5.0                         # 5 = Conservative, 15 = Balanced, 30 = Fast
  klarRequestsPerSecond: 2.0

logging:
  level: "info"                                     # debug, info, warn oder error
  maxSizeMB: 10
  maxBackups: 7
  maxAgeDays: 7

update:
  checkInterval: 24h
  channel: "beta"                                   # im Beta-Test

Gut zu wissen: Starte den Dienst nach einer manuellen Änderung an config.yaml neu. Nutze dafür den Startmenü-Eintrag Restart Service. Ändere update: nicht ohne Absprache — sonst bekommst du keine Beta-Updates mehr.

15. Beta-Test: worauf wir uns freuen

Wir bitten dich als Beta-Tester um diese Rückmeldungen:

Die Anzahl der Bestellungen in deiner JTL-Wawi und der gewählte Startmonat.
Die Dauer des ersten Imports und die gewählte Speed-Stufe.
Jeden Unterschied zwischen JTL-Wawi und Klar, der dir auffällt — mit Bestellnummer.
Ob die Google-Analytics-Transaktions-IDs in Klar zu deinem GA4-Konto passen.
Die Logdateien, wenn im Taskleisten-Menü eine Warnung erscheint.
Alles, was beim Update von einer Version auf die nächste nicht glatt läuft.

Schicke alles an [email protected]. Nenne dabei bitte die Version aus dem Taskleisten-Menü.

Installiere neue Versionen zügig. Im Beta-Test erscheinen sie häufig, und jede enthält Korrekturen aus dem Feedback der anderen Tester.

16. Wenn etwas nicht funktioniert

Schau zuerst in das Taskleisten-Menü. Die Statuszeilen und die ⚠-Zeile nennen die Ursache.

Alle Meldungen, ihre Ursachen und die passenden Maßnahmen stehen in einem eigenen Artikel: JTL-Klar-Sync: Fehler beheben (Beta). Dort steht auch, wie du die Logdateien an den Support schickst.

JTL-Wawi 1.x mit Klar verbinden (Beta)