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.

Version 1.0.0
Das Programm ist von Klar Insights GmbH signiert und hält sich selbst aktuell: Es prüft täglich auf neue Versionen und bietet sie im Taskleisten-Menü an.
Download: jtl-klar-sync-setup.exe
Fragen und Probleme: [email protected]

Noch auf einer Beta-Version? Dann gibt es einmalig eine Sache zu tun. Abschnitt 15. Upgrade von einer Beta-Version erklärt es.

1. Was das Programm macht

Das Programm besteht aus drei Teilen:

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

Die Arbeit erledigt der Dienst. Die Taskleisten-App zeigt nur den Status. Wenn du sie schließt, läuft die Übertragung weiter.

Der Dienst macht in jedem Zyklus diese Schritte:

Er sendet Bestellungen erneut, die in einem früheren Zyklus 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 Zyklen ist 1 Stunde. Du kannst ihn im Einstellungsfenster ändern.

Warum ein Fehler alles stoppt

Wenn Klar eine Gruppe von Bestellungen ablehnt, stoppt der Dienst. Er liest keine neuen Bestellungen. Er sendet die fehlgeschlagene Gruppe erneut, mit zunehmender Wartezeit, bis Klar sie annimmt.

Das ist Absicht. So geht keine Bestellung verloren. Es bedeutet aber auch, dass ein dauerhafter Fehler alle neuen Bestellungen stoppt. Prüfe das Taskleisten-Menü, sobald die Zeile Errors nicht mehr 0 ist.

Wie Änderungen erkannt werden

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

Eine Art von Änderung wird nur mit Verzögerung erkannt: eine Änderung an einer Position, die den Bestellwert nicht ändert – zum Beispiel eine korrigierte SKU. Das Programm findet diese über einen langsamen Durchlauf, der jede Bestellung einmal innerhalb von 24 Stunden erneut prüft. Die maximale Verzögerung beträgt daher 24 Stunden.

Wie Löschungen erkannt werden

Wenn eine Bestellung nicht mehr in der Antwort von JTL-Wawi enthalten ist, fragt das Programm JTL-Wawi noch einmal nach genau dieser Bestellung. Antwortet JTL-Wawi, dass die Bestellung nicht existiert, gilt sie als gelöscht. Das Programm meldet sie dann Klar als storniert, mit dem zuletzt bekannten Stand der Bestellung.

2. Welche Daten an Klar gehen

Nur Bestelldaten gehen 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, Summen, Steuern und Rabatte
Den Namen der Zahlungsmethode und des Payment Gateways
Sales Channel und Plattform der Bestellung (siehe unten)
Die Positionen: SKU, Produktname, Menge, Beträge, Steuern und Rabatte
Produkt-Tags: die Kategoriepfade des Artikels, seine Warengruppe und freigegebene benutzerdefinierte Felder
Kunden-Tags: Kundengruppe und Kundenkategorie
Versandkosten und Versandsteuern
Erstattungen aus Retouren und aus Gutschriften (siehe unten)
Die Kundennummer aus JTL-Wawi
Die E-Mail-Adresse des Kunden oder einen Hash davon (siehe unten)
Aus der Lieferadresse: Stadt, Bundesland, Postleitzahl und Land
Die Google-Analytics-Transaktions-ID (siehe unten)

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

Erstattungen: Retouren und Gutschriften

Klar erhält Erstattungen aus zwei Quellen in JTL-Wawi:

aus Retouren, inklusive des Retourengrunds, den dein Team erfasst hat
aus Gutschriften und Rechnungskorrekturen

Die zweite Quelle zählt für alles, was ohne Retoure erstattet wird: Kulanz, Preiskorrekturen, Teilerstattungen. Diese Beträge fehlten bisher in Klar.

Wenn eine Retoure und eine Gutschrift dieselbe Erstattung beschreiben, gewinnt die Gutschrift, und der Grund der Retoure wird übernommen. Nichts wird doppelt gezählt.

Nicht übertragen:

Stornos – die Bestellung selbst wird bereits als storniert gemeldet.
Erstattete Versandkosten und Gutschein-Positionen – Klar erfasst Erstattungen pro Artikel. Erstattete Artikel und Mengen sind daher korrekt; erstatteter Versand wird in Klar nicht abgebildet.

Hinweis: Für Bestellungen, die bereits vor Version 1.0.0 übertragen wurden, füllt das Programm Gutschriften nicht von selbst nach. Das erfordert ein einmaliges Re-export: full refresh from JTL (Abschnitt 9).

Sales Channel und Plattform

Jede Bestellung bekommt in Klar einen Sales Channel und eine Plattform, sodass du siehst, über welchen Shop oder Marktplatz sie verkauft wurde.

Woher die Bestellung kam	Sales Channel	Plattform
JTL-Shop	Der Name des Shops aus JTL-Wawi	Online-Shop
eBay	Der Name des eBay-Kontos	eBay
Amazon	Der Name des Amazon-Kontos	Amazon
SCX-Marktplatz (OTTO, Kaufland und andere)	Der Marktplatzname	SCX - <marketplace>
Direkt in JTL-Wawi erfasst	JTL-Wawi	JTL-Wawi
REST API, XML-Import, Fulfillment, POS	entsprechend	REST-API, XML-Import, JTL-Fulfillment-Network, JTL-POS

Gut zu wissen: Für manche Shops meldet JTL-Wawi über die API keinen Namen – vor allem B2B-Shops und gelöschte Shops. In Klar heißen diese dann zum Beispiel Online-Shop 2. Das ist kein Fehler. Wenn du einen neuen Shop anlegst, übernimmt das Programm ihn ohne Neustart.

Einen Shop in JTL-Wawi umzubenennen löst für sich genommen keine erneute Übertragung aus. Für Bestellungen von vor Version 1.0.0 brauchst du ein einmaliges Re-export: full refresh from JTL, damit Channel und Plattform in Klar erscheinen.

Die E-Mail-Adresse

Standardmäßig sendet das Programm die E-Mail-Adresse des Kunden an Klar.

Du kannst im Einstellungsfenster einen Hash salt setzen. Das Programm sendet dann einen SHA1-Hash der Adresse statt der Adresse selbst, und die Adresse verlässt den Rechner nie.

Achtung: Der Salt muss derselbe Salt sein, den Klar nutzt. Stimme ihn mit uns ab. Wenn du den Salt später änderst, sieht Klar jeden Kunden als neu.

Die Google-Analytics-Transaktions-ID

Klar nutzt diese ID, um eine Bestellung der passenden Transaktion in GA4 zuzuordnen. Dafür muss das Programm dasselbe Feld senden, das dein Shop an GA4 sendet.

Du wählst das Feld im Einstellungsfenster unter GA transaction id:

Option	Was gesendet wird
externalNumber (fällt zurück auf number) – Standard	Die externe Bestellnummer aus JTL, zum Beispiel die Bestellnummer aus dem JTL-Shop oder von einem Marktplatz. Fehlt sie, sendet das Programm die JTL-Bestellnummer.
id	Die interne, numerische Bestell-ID aus JTL-Wawi
number	Immer die JTL-Bestellnummer, ohne Fallback

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

Hinweis: Eine Änderung wirkt nur auf neue und geänderte Bestellungen. Um bereits übertragene Bestellungen nachzufüllen, nutze Re-export: full refresh from JTL (Abschnitt 9).

Wo die Zugangsdaten liegen

Das Programm speichert den JTL-Wawi-API-Key und das Klar-Token in 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 Installation und Updates
Speicherplatz	100 MB für das Programm. Etwa 2 MB pro 1.000 Bestellungen.
Netzwerk	Ausgehendes HTTPS zur Klar-API und zum Klar-Update-Server

Das Programm braucht keine separate Datenbank und keinen separaten Webserver.

Windows Server oder Remote Desktop? Der Setup-Assistent und das Einstellungsfenster brauchen einen Grafiktreiber mit OpenGL 2.1. Server ohne Grafikkarte und manche Remote-Desktop-Sitzungen haben keinen. Der Installer hat dafür die Option Software OpenGL – siehe Abschnitt 5. Der Dienst selbst und das Taskleisten-Icon brauchen kein OpenGL.

4. Bevor du startest

Halte diese fünf Dinge vor der Installation bereit:

Den Installer: jtl-klar-sync-setup.exe
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.
Das Klar Access Token (siehe unten).

Gut zu wissen: Die JTL-Wawi-API ist kostenlos, solange die JTL-API in der Beta ist. Danach berechnet JTL sie.

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

Das Klar Access Token erstellen

Das Token autorisiert das Programm, deine Bestellungen in Klar zu schreiben. Du erstellst es im Klar-Dashboard.

Geh auf Settings → Store Configurator → dein Store → Data Sources.
Klicke auf Connect Data Source.
Wähle im Dialog Klar API.
Gib der Data Source einen Namen, zum Beispiel JTL-Wawi, und speichere sie.
Öffne die neue Data Source.
Geh auf den Tab Access Token.
Klicke auf Copy Token.

Das Token ist eine lange Zeichenkette, die mit eyJ beginnt. Vollständige Beschreibung: API Authentication.

Achtung: Erstelle eine eigene Data Source für JTL-Wawi. Nutze nicht das Token einer bestehenden Data Source, die bereits 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 Benutzerkontensteuerung mit Ja. Als Herausgeber wird Klar Insights GmbH angezeigt.
Lass auf der Komponenten-Seite die Standardauswahl und klicke auf Next. Setze Software OpenGL nur dann, wenn dieser Rechner keinen Grafiktreiber hat – also auf Windows Server oder wenn du über Remote Desktop arbeitest. Auf einem normalen PC ersetzt die Option einen funktionierenden Treiber, und die Fenster öffnen sich eventuell gar nicht.
Bestätige den vorgeschlagenen Zielordner und klicke auf Install.
Warte, bis die Installation abgeschlossen ist.
Klicke auf Close.

Installer: Auswahl des Zielordners, mit dem Install-Button.

Gut zu wissen: Bei einer brandneuen Version zeigt Windows trotz gültiger Signatur eventuell einmalig einen SmartScreen-Hinweis, weil die Datei noch nicht oft heruntergeladen wurde. Prüfe, 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.
Sie legt vier Startmenü-Einträge an (siehe Abschnitt 11).
Sie fügt einen Autostart-Eintrag hinzu, damit die Taskleisten-App bei jedem Login startet.
Sie startet die Taskleisten-App.

Bei einer Erstinstallation startet der Installer den Dienst noch nicht. Das übernimmt der Setup-Assistent, der sich danach automatisch öffnet.

6. Der Setup-Assistent

Der Assistent hat drei Schritte. Schließe das Fenster nicht, bevor Schritt 3 abgeschlossen ist. Der Assistent ist auf Englisch; JTL-Wawi ist auf Deutsch.

Schritt 1 von 3: Connect to JTL WaWi

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

Wichtig: Öffne die App-Registrierung zuerst in JTL-Wawi. JTL-Wawi muss auf die Anfrage warten, bevor du sie aus dem Assistenten sendest, sonst weist die API sie 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 Standard ist http://127.0.0.1:5883/api/eazybusiness/.
Ändere den Port, falls der JTL-API-Server einen anderen nutzt.
Klicke auf Register with JTL-Wawi.

Setup-Assistent, Schritt 1 von 3, mit dem Feld API URL und dem Register with JTL-Wawi-Button.

Wechsle jetzt zu JTL-Wawi und schließe die Registrierung dort ab:

Nimm die Anfrage Klar Sync an.
Weise den JTL-Wawi-Benutzer zu, als der das Programm handeln soll.
Erteile die angeforderte Berechtigung. Das Programm braucht nur Lesezugriff (all.read).
Klicke auf Fertigstellen.

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

JTL-Wawi: den Benutzer zuweisen und die Berechtigung erteilen, mit dem Fertigstellen-Button.

Wechsle zurück zum Assistenten. Er zeigt ✓ Registered: API key received. Click Continue. Klicke auf Continue ▸.

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

Der Assistent fragt JTL-Wawi alle 3 Sekunden nach dem Ergebnis und gibt nach 10 Minuten auf. Starte den Vorgang neu, falls das passiert.

Achtung: JTL-Wawi gibt den API-Key nur einmal aus, pro App-ID, und kann denselben Key nicht erneut ausstellen. Bewahre eine Kopie an einem sicheren Ort auf.

Wenn du bereits einen API-Key hast – zum Beispiel nach einer Neuinstallation: Klicke auf I already have an API key, gib den Key ein und klicke auf Continue ▸. Nach einem Factory Reset bietet der Assistent den alten Key selbst an, wenn er noch funktioniert; dann erscheint Use the preserved API key.

Schritt 2 von 3: Connect to Klar

Lass die vorausgefüllte API URL unverändert, außer Klar hat dir etwas anderes gesagt.
Füge das Klar-Token in das Feld Access token ein.
Klicke auf Continue ▸.

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

Gut zu wissen: Der Assistent prüft das Token in diesem Schritt nicht. Du kannst die Verbindung jederzeit nach dem Setup mit Test connection im Einstellungsfenster testen. Bei Erfolg zeigt er ✓ Connected to Klar.

Schritt 3 von 3: Sync settings

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

Bestellhistorie

Wähle unter Import orders from den Monat und das Jahr, ab dem Klar deine Bestellungen sehen soll. Der Standard sind 24 Monate zurück, damit du in Klar sofort einen Jahresvergleich hast.
Setze 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 den gewählten Zeitraum fallen, und nennt die erwartete Dauer. Sie aktualisiert sich, wenn du den Zeitraum oder die Geschwindigkeit änderst.

Sync-Verhalten

Wähle unter Check JTL every, wie oft nach dem Import nach neuen Bestellungen gesucht wird. Die Optionen sind 15 Minuten, 30 Minuten, 1, 2, 4, 8, 12 und 24 Stunden. Der Standard ist 1 hour.
Wähle unter Speed, wie stark das Programm die JTL-API beanspruchen darf.

Speed	Wann
Conservative (5 requests/second) – Standard	JTL-Wawi läuft auf einem Arbeitsplatzrechner oder auf einem Server, der auch andere Arbeit macht
Balanced (15 requests/second)	Ein dedizierter JTL-Server
Fast (30 requests/second)	Ein Rechner, der nichts anderes macht

Klicke dann auf Finish and start sync.

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

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

Die Meldung Setup complete.

Achtung: Der Startmonat, den du wählst, entscheidet, welche Historie Klar sieht. Du kannst sie später mit Re-import a date range… im Taskleisten-Menü erweitern, aber es ist einfacher, es hier gleich richtig zu machen. Geh nicht unter 24 Monate, wenn du Jahresvergleiche brauchst.

7. Der erste Import

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

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

Aufgabe	Gemessene Zeit
Erster Import von 5.000 Bestellungen	etwa 19 Minuten
Ein Zyklus mit 140 neuen Bestellungen	etwa 32 Sekunden
Ein Zyklus ohne neue Bestellungen	etwa 2,4 Sekunden
Vom Dienst genutzter Arbeitsspeicher	unter 100 MB

Eine Historie von 200.000 Bestellungen dauert 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. Fährt er herunter, setzt das Programm nach dem nächsten Start an seiner letzten Position fort. Keine Bestellung geht verloren und keine wird doppelt gezählt.

8. Das Taskleisten-Icon

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

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

Die Animation startet nur, wenn eine Aufgabe länger als 2 Sekunden dauert, ein kurzer Zyklus zeigt also keine. Fahre mit der Maus über das Icon, um den Status als Text zu sehen.

Die Taskleiste mit dem Klar-Icon und dem Tooltip für ein verfügbares Update.

Fehlt das Icon, läuft die Taskleisten-App nicht. Starte JTL-to-Klar Sync aus dem Startmenü. Prüfe auch den Bereich der ausgeblendeten Symbole.

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

Das 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 erscheint hier der Fortschritt.
Last Sync: 2026-08-11 12:46:38 · no changes	Wann der letzte Zyklus lief und was er getan hat: no changes, 1 order oder zum Beispiel 1.072 orders.
Synced to Klar: 465 orders since 01.01.2026	Wie viele Bestellungen diese Installation in Klar verwaltet, und ab welchem Datum. Bei vollständiger Historie steht hier (full history).
Errors: 0	Bestellungen, die das Programm noch erneut versucht. Alles außer 0 blockiert neue Bestellungen.
Validation errors: 0	Bestellungen, die Klar abgelehnt hat und bei denen das Programm aufgegeben hat. Sie blockieren nichts, fehlen aber in Klar.
JTL: ✓ · Klar: ✓ · 1.072 orders in JTL	Der Zustand beider Verbindungen und wie viele Bestellungen JTL-Wawi insgesamt enthält.

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

Wenn das Programm deine Hilfe braucht, erscheint unter den Statuszeilen eine Zeile mit einem ⚠. Sie nennt die Aktion in einem Satz.

Die Menüpunkte

Punkt	Funktion
⚠ Update to … available	Erscheint nur, wenn eine neue Version bereit ist. Öffnet das Update-Fenster (Abschnitt 10).
Tenant: default	Wählt die JTL-Wawi-Installation, auf die sich das Menü bezieht. Normalerweise gibt es nur eine.
Sync Now	Startet innerhalb weniger Sekunden einen Zyklus. Nutze es nach einer Änderung in JTL-Wawi.
Re-export: all synced	Sendet alle bekannten Bestellungen aus der lokalen Kopie erneut an Klar
Re-export: full refresh from JTL	Liest alle Bestellungen erneut aus JTL-Wawi und sendet sie erneut an Klar
Re-export orders with validation errors	Liest nur die von Klar abgelehnten Bestellungen erneut aus JTL-Wawi und sendet jede einmal. Ausgegraut, solange Validation errors 0 ist.
Re-import a date range…	Liest einen Zeitraum erneut aus JTL-Wawi. Nutze es, um Historie außerhalb des gewählten Startmonats nachzufüllen.
View Logs	Öffnet die Logdatei
Settings…	Öffnet das Einstellungsfenster
Version 1.0.0	Zeigt die laufende Version. Nenne sie, wenn du den Support kontaktierst.
Quit	Schließt die Taskleisten-App. Der Dienst läuft weiter.

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

Einen Zeitraum nachfüllen

Klicke auf Re-import a date range….
Gib die Grenzen in From und To im Format TT.MM.JJJJ ein. Das Enddatum ist eingeschlossen.
Setze Ignore the local cache and re-import everything in this range, wenn der Zeitraum komplett neu gelesen werden soll.
Klicke auf Start re-import.

Die Re-Export-Optionen

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

Re-export: all synced – wenn in Klar Daten fehlen, die das Programm bereits übertragen hatte.
Re-export orders with validation errors – nachdem du die Ursache einer Ablehnung in JTL-Wawi behoben hast.
Re-export: full refresh from JTL – wenn Daten in Klar aktualisiert werden müssen, weil sich das Mapping geändert hat: eine neue Programmversion, eine geänderte GA transaction id, Gutschriften oder Sales-Channel-Namen. Nur dieser Modus liest die Daten erneut aus JTL-Wawi.

Achtung: Re-export: full refresh from JTL macht eine Anfrage pro Bestellung. Bei einer großen Installation dauert das mehrere Stunden. Der normale Sync wartet, bis es fertig ist. Du kannst es nicht stoppen und nach einem Neustart nicht fortsetzen. Ab etwa 20.000 Bestellungen arbeite es stattdessen Quartal für Quartal mit Re-import a date range… ab.

10. Updates

Das Programm prüft täglich auf neue Versionen und informiert dich darüber. Es installiert nichts ohne deine Zustimmung, und du musst nichts konfigurieren.

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

Ein oranger Punkt erscheint auf dem Taskleisten-Icon.
Das Taskleisten-Menü zeigt oben ⚠ Update to … available.
Einmal am Tag erscheint eine Windows-Benachrichtigung.

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

Das Update-Fenster mit What's changed und den Buttons 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 Optionen:

Button	Effekt
Install now	Installiert die neue Version. Es dauert etwa eine Minute.
Remind me tomorrow	Blendet das Fenster und die Benachrichtigung für 24 Stunden aus. Der Punkt und die Menüzeile bleiben.

Was bei der Installation passiert

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

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

Wie oft du erinnert wirst

Wartezeit	Was passiert
Tag 0 bis 2	Punkt auf dem Icon, Zeile im Menü, eine Benachrichtigung pro Tag
Ab Tag 3	Die Menüzeile ändert sich zu ⚠ UPDATE OVERDUE. Das Fenster öffnet sich beim Login und alle 4 Stunden.
Ab Tag 7	Das Fenster öffnet sich jede Stunde. Die Buttons sind die ersten 10 Sekunden deaktiviert.

Remind me tomorrow setzt diese Uhr nicht zurück. Sie läuft ab dem Moment, in dem das Update gefunden wurde.

11. Die Startmenü-Einträge

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

Nutze Restart Service, nachdem du config.yaml von Hand bearbeitet hast, oder wenn der Dienst nicht reagiert.

⚠️ Warnung: Factory Reset löscht die Konfiguration, das Klar-Token und alle Sync-Positionen. Nutze es nur nach Rücksprache mit dem Support, und sichere vorher config.yaml.

Der Factory Reset bewahrt den JTL-Wawi-API-Key, weil JTL ihn nicht erneut ausstellen kann. Der nächste Start öffnet den Setup-Assistenten, der den Key erneut anbietet, wenn er noch funktioniert. Die Bestellungen in Klar bleiben; ein neuer Sync ersetzt sie anhand der Bestell-ID, ohne Dubletten.

12. Das Einstellungsfenster

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

JTL-Wawi connection und Klar connection

Feld	Funktion
API URL (JTL)	Die Adresse des JTL-API-Servers
API key	Zeigt den Button Re-register with JTL. Der Key selbst ist nicht sichtbar.
API URL (Klar)	Muss mit `https://` beginnen
Access token	Leer lassen, um das gespeicherte Token zu behalten
Test connection	Testet die jeweilige Verbindung. Bei Erfolg zeigt es ✓ Reached Wawi. N orders visible. oder ✓ Connected to Klar.

Einstellungsfenster: die beiden Verbindungen.

Sync-Verhalten

Feld	Funktion
Poll every	Der Abstand zwischen zwei Zyklen. Eine Liste von 15 Minuten bis 24 Stunden, Standard 1 hour.
Re-check window	Wie viele Tage zurück nach Änderungen gesucht wird, Standard 90. Ältere Bestellungen aktualisieren sich in Klar nicht mehr.
Hash salt	Pseudonymisiert die Kunden-E-Mail. Leer = die Adresse wird gesendet. Siehe Abschnitt 2.
GA transaction id	Welches JTL-Feld als Google-Analytics-Transaktions-ID gesendet wird. Siehe Abschnitt 2.
Earliest order date	Bestellungen, die vor diesem Tag datiert sind, werden nie an Klar gesendet, von keinem Sync und keinem Re-Export. Leer = keine Grenze. Choose… öffnet einen Kalender.
Sync full order history on first run	Überträgt im ersten Zyklus die vollständige Historie
ID prefix	Nur nötig, wenn mehrere JTL-Wawi-Installationen ein Klar-Token teilen

Einstellungsfenster: Sync-Verhalten.

Gut zu wissen: Earliest order date entfernt nichts, was bereits in Klar ist. Es verhindert nur, dass ältere Bestellungen künftig gesendet werden – nützlich, wenn deine Bücher erst ab einem bestimmten Datum sauber sind.

Klicke auf Save changes, um die Konfiguration zu schreiben. Du siehst dann ✓ Saved. The service picks the change up within a few seconds. Der Dienst übernimmt die meisten Änderungen 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 ist ein Tenant, mit eigenen Zugangsdaten, eigenem Stand und eigenem Status.

Füge einen Tenant im Einstellungsfenster mit Add tenant… hinzu. Jeder Tenant braucht eine ID aus Buchstaben, Ziffern, Bindestrich und Unterstrich, zum Beispiel shop-de. Remove tenant… entfernt einen wieder; die Bestellungen in Klar sind davon nicht betroffen.

Achtung: Wenn zwei Tenants in dasselbe Klar-Konto schreiben, braucht jeder sein eigenes ID prefix. Ohne eins kollidieren die Bestell-IDs in Klar. Das Einstellungsfenster weigert sich, diese Konfiguration zu speichern.

Die meisten Installationen haben genau einen Tenant. Dann gibt es hier nichts zu 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 Dienst-Log. Die Datei rotiert bei 10 MB; bis zu 7 alte Dateien werden aufbewahrt, höchstens 7 Tage lang.
`tenants\<ID>\sync.db`	Der lokale Stand: Positionen, Vergleichsdaten, fehlgeschlagene Gruppen
`tenants\<ID>\status.json`	Der Status für die Taskleisten-App
`updates\<version>\`	Der heruntergeladene Installer einer neuen Version

Die Taskleisten-App hat ihr eigenes Log unter %LOCALAPPDATA%\JtlKlarSync\logs\jtl-klar-sync.log, weil sie ohne Administratorrechte läuft. Nach einem Update enthält der Programmordner außerdem jtl-klar-sync.exe.previous, die vorherige Version. Lösche sie nicht – der Support braucht sie, falls eine neue Version ein Problem hat.

Die Konfigurationsdatei

Du kannst config.yaml in einem Texteditor bearbeiten. Für alles, was das Einstellungsfenster zeigt, ist das Einstellungsfenster der bessere Weg. Zwei Einstellungen gibt es nur hier:

Key	Bedeutung
`sync.productTagCustomFields`	Liste von JTL-Wawi-Freifeldern, deren Werte als Produkt-Tags an Klar gehen. Namen wie in JTL-Wawi, Groß-/Kleinschreibung egal. Leer = keine.
`sync.importCreditNotes`	Gutschriften als Erstattungen übertragen. Fehlt der Key, ist es an. `false` schaltet es ab.

Die wichtigsten Standardwerte:

sync:
  pollInterval: 1h                                  # Abstand zwischen zwei Zyklen
  batchSize: 1000                                   # max. Bestellungen pro Anfrage an Klar
  recheckWindowDays: 90                             # Tage, die auf Änderungen geprüft werden
  fullRecheckIntervalHours: 24                      # Abstand für den langsamen Durchlauf
  googleAnalyticsTransactionIdSource: orderNumber   # orderNumber | id | orderName
  productTagCustomFields: []                        # Freifelder als Produkt-Tags

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:
  checkUrl: "https://update.getklar.com/jtl/"
  checkInterval: 24h
  channel: "stable"

Gut zu wissen: Starte den Dienst neu, nachdem du config.yaml von Hand bearbeitet hast – Startmenü-Eintrag Restart Service. Lass den Abschnitt update: unverändert, sonst erhältst du keine Updates mehr.

15. Upgrade von einer Beta-Version

Installationen aus der Beta-Phase prüfen nicht selbst auf Updates. Sie brauchen einmal deine Hilfe. Danach hält sich das Programm selbst aktuell.

Prüfe zuerst im Taskleisten-Menü die laufende Version. Steht dort 1.0.0 oder neuer, gibt es nichts zu tun.

Lade den aktuellen Installer herunter: jtl-klar-sync-setup.exe
Führe ihn auf dem JTL-Wawi-Rechner aus, über die bestehende Installation.
Bestätige die Benutzerkontensteuerung und klicke dich durch den Installer.

Der Installer stoppt den Dienst, ersetzt das Programm und startet den Dienst wieder. Konfiguration, Klar-Token, JTL-Registrierung und der gesamte Sync-Stand bleiben erhalten. Du musst dich nicht erneut registrieren, und es wird nichts neu importiert.

Ein Nachfüllen danach: Version 1.0.0 überträgt Dinge, die es vorher nicht gab – Gutschriften als Erstattungen sowie Sales Channel und Plattform. Für Bestellungen, die bereits in Klar sind, füllt das Programm diese nicht von selbst nach.

Starte Re-export: full refresh from JTL aus dem Taskleisten-Menü. Bei mehr als etwa 20.000 Bestellungen nutze stattdessen Re-import a date range… und arbeite es Quartal für Quartal ab, mit gesetztem Ignore the local cache.

Plane den Re-Export für eine ruhige Zeit auf diesem Rechner. Während er läuft, pausiert der normale Sync.

16. Wenn etwas nicht funktioniert

Prüfe zuerst das Taskleisten-Menü. Die Statuszeilen und die ⚠-Zeile nennen die Ursache.

Jede Meldung, ihre Ursache und die passende Aktion stehen in einem eigenen Artikel: JTL-Klar-Sync: Fehler beheben. Er erklärt auch, wie du die Logdateien an den Support schickst.

Wir beantworten Fragen unter [email protected]. Bitte nenne die Version aus dem Taskleisten-Menü.

JTL-Wawi 1.x mit Klar verbinden