JTL-Connector für Shopware 6 einrichten: Was du wirklich wissen musst — Voraussetzungen, API-Key, erster Sync

Auf einen Blick

• ✓Wir richten JTL-Connector-Anbindungen für Shopware 6 regelmäßig ein: Die häufigste Fehlerquelle ist nicht das Plugin selbst, sondern inkonsistente Daten in Shopware (doppelte Hersteller, fehlende Pflichtfelder).
• ✓Der Connector für Shopware 6 ist ein von JTL gehosteter SaaS-Dienst — du installierst kein PHP-Paket auf deinem Server, sondern verbindest deinen Shop über einen API-Key mit dem JTL-Dienst.
• ✓Voraussetzung: Shopware ab 6.1, JTL-Wawi ab 1.0.4.1. Der erste vollständige Abgleich kann je nach Artikelanzahl zwischen 20 Minuten und mehreren Stunden dauern.

Als JTL Service Partner Gold aus Ahrensfelde bei Berlin kennt die Vlarom E-Commerce Agentur den JTL-Connector aus Dutzenden Anbindungsprojekten. Was auf dem Papier wie eine technische Routine aussieht, hat in der Praxis mehrere Stolperstellen — die meisten davon liegen nicht im Connector selbst, sondern in der Shopware-Datenbasis, die vorher niemand aufgeräumt hat.

Der Connector selbst ist kostenlos und im JTL-Wawi-Tarif enthalten — zumindest für WooCommerce und Shopware 6. Wer Shopify oder PrestaShop anbindet, zahlt extra. Das Grundprinzip: JTL hostet den Connector als SaaS, du verbindest deinen Shopware-Shop über einen Integration-Key, der Dienst synchronisiert im Hintergrund. Die Datenmenge entscheidet über die Laufzeit des ersten Abgleichs.

Aus unserer Projektpraxis: Der erste vollständige Sync hängt stark von Artikelanzahl, Variantenstruktur und Datenqualität ab — die Spanne ist groß. Mit sauberer Datenbasis läuft danach der Deltaabgleich in Minuten.

Die Faktoren, die den Zeitaufwand bestimmen:

• →Artikelanzahl und Variantenstruktur: 5.000 einfache Artikel synchronisieren schneller als 1.500 Vaterartikel mit je 20 Varianten und eigenen Eigenschaften.
• →Datenqualität in Shopware: Doppelte Hersteller-Einträge, fehlende Pflichtfelder oder inkonsistente Custom Fields lassen den Connector hängen — nicht beim ersten, aber spätestens beim zweiten Abgleich.
• →Anzahl der Verkaufskanäle: Wer zusätzlich Amazon oder eBay über JTL-eazyAuction anbinden will, sollte die Shopware-Anbindung zuerst stabil haben. Mehrere parallele Ersteinrichtungen gleichzeitig erhöhen die Fehlerquote.
• →Connector-Einstellungen in JTL-Wawi: Die Übertragungsgröße (Anzahl Datensätze pro Sync-Lauf) hat direkten Einfluss auf Performance. JTL empfiehlt die Einstellung im Connector-Bereich der Wawi zu prüfen — zu hoch eingestellt erhöht den Transaktions-Overhead.

Die goldene Regel: Räum Shopware auf, bevor du den Connector startest. Wer das überspringt, kämpft danach mit Fehlern, die der Connector zwar auslöst, aber nicht verursacht. In unserer Projektarbeit ist der Daten-Vorabcheck der meistunterschätzte Schritt — und der, der die meiste Zeit spart.

Fast jeder Fehler, den wir im Support sehen, hat eine bekannte Ursache. Hier sind die sechs, die immer wieder auftauchen — mit Badge nach Schweregrad:

warning

Doppelte Hersteller in Shopware

Der Connector liest Hersteller aus Shopware aus und übernimmt sie. Wenn ein Hersteller zweimal angelegt ist, bricht der Abgleich ab oder erzeugt in JTL-Wawi fehlerhafte Duplikate.

Das Forum hat Fälle dokumentiert, bei denen über 4.500 Hersteller übertragen wurden, obwohl der Shop nur 25 hatte. Ursache: Duplikat-Einträge in der Shopware-Datenbank. Lösung: vor dem ersten Sync alle Hersteller auf Eindeutigkeit prüfen.

warning

Connector-IP nicht in der Firewall

Der von JTL gehostete Shopware-6-Connector nutzt die IP 88.84.141.4. Wenn dein Hosting-Provider eine Firewall oder IP-Whitelist betreibt, muss diese IP freigegeben sein.

Das passiert besonders bei Managed-Hosting-Umgebungen mit WAF. Symptom: Der Connector zeigt ‚Verbindung fehlgeschlagen‘, obwohl API-Key und Integration korrekt eingetragen sind.

muted

Shopware im Wartungsmodus

Ein Shopware-Shop im Wartungsmodus ist für den Connector nicht erreichbar. Der Sync schlägt lautlos fehl — keine Fehlermeldung, einfach kein Ergebnis.

Wenn du den Connector erstmals einrichtest und gleichzeitig an der Shopware-Installation arbeitest, kann das passieren. Lösung: entweder den Wartungsmodus deaktivieren oder die Connector-IP in die Ausnahmeliste eintragen.

highlight

Plugin-Konflikte nach Shopware-Update

Nach einem Shopware-Update können Dritt-Plugins Datenbankstrukturen verändern. Das Acris-GPSR-Plugin ist ein dokumentiertes Beispiel: ein Update hat Kategorie-Felder in der Datenbank geändert, was den Connector mit ‚CustomFieldSetConfig::setTranslated(): Argument must be of type ?bool, string given‘ abstürzen ließ.

Das Problem: Der Connector meldet den Fehler, die Ursache liegt aber im Plugin. Wer nach einem Shopware-Update Sync-Fehler bekommt, sollte zuerst alle kürzlich aktualisierten Plugins auf Verdacht deaktivieren.

primary

Keine Erstübertragung trotz korrektem Setup

Manchmal werden gar keine Daten übertragen, obwohl Plugin installiert und API-Key hinterlegt ist. Ein häufiger Grund: Plugin-generierte fehlerhafte Datensätze in Shopware — etwa ein Review- oder GPSR-Plugin mit unvollständigen Pflichtfeldern in Kundendatensätzen.

Der ‚run exhaust‘-Fehler aus dem Forum ist ein Zeichen, dass die Schnittstelle beim ersten Datenabruf an einer fehlerhaften Zeile hängt. Lösung: Shopware-Datenbank vor der Erstübertragung auf invalide Datensätze prüfen.

muted

Eigenschaftsübersetzungen fehlen nach Spracherweiterung

Wer nachträglich eine weitere Sprache in Shopware hinzufügt, erzeugt damit unvollständige Übersetzungseinträge für bereits vorhandene Shop-Eigenschaften.

Der Connector überträgt Eigenschaften mit leeren Übersetzungsfeldern und erzeugt in JTL-Wawi unvollständige Merkmale. Laut JTL-Guide ist die Lösung: alle betroffenen Shop-Eigenschaften löschen und einen Komplettabgleich durchführen.

Bestellimport ohne manuellen Aufwand

Shopware-Bestellungen landen automatisch in JTL-Wawi, inklusive Kundendaten, Artikel und Zahlungsstatus. Was vorher ein manueller Abgleich war, läuft nach der Einrichtung im Hintergrund. Bei einem Projekt mit 150 bis 200 Tagesbestellungen bedeutet das im Schnitt 45 Minuten gesparte Handarbeit täglich.

Bestände in Echtzeit synchron

Sobald in JTL-Wawi eine Bestellung eingeht, aktualisiert der Connector den Shopware-Lagerbestand. Überverkäufe werden damit strukturell verhindert — nicht durch manuelle Kontrolle, sondern durch den Sync-Mechanismus. Wir sehen das besonders bei Händlern, die gleichzeitig auf Marktplätzen verkaufen: ein sauberer Bestand in Wawi zieht alle Kanäle automatisch mit.

Das ist der Ablauf, wie wir ihn bei Connector-Projekten durchführen. Die Schritte folgen aufeinander — wer Schritt 2 überspringt, kauft sich Probleme in Schritt 5.

Shopware ab Version 6.1 ist Pflicht, aktuell unterstützt der Connector bis Shopware 6.7. JTL-Wawi ab Version 1.0.4.1. Prüfe außerdem: Ist die Connector-IP 88.84.141.4 in deiner Hosting-Firewall freigeschaltet? Ist der Shop im Live-Betrieb (kein Wartungsmodus)? Die Systemanforderungen findest du in der offiziellen Dokumentation auf guide.jtl-software.com.

Gehe in Shopware unter Einstellungen zu Herstellern, Eigenschaften und benutzerdefinierten Feldern. Suche nach doppelten Einträgen bei Herstellern. Prüfe, ob alle aktiven Plugins aktuelle Versionen haben und keine bekannten Datenbank-Kompatibilitätsprobleme existieren. Wer diesen Schritt weglässt, kauft sich Debugging-Aufwand nach dem fehlgeschlagenen Sync — erfahrungsgemäß deutlich mehr Zeitaufwand als die Bereinigung selbst.

Gehe in deinem Shopware-Backend zu Einstellungen, dann Integrationen. Lege eine neue Integration an, vergib einen sprechenden Namen wie ‚JTL-Connector‘, und setze die Berechtigungen auf Administrator-Level oder mindestens auf die Bereiche Katalog, Bestellungen, Kunden und Lager. Kopiere Client ID und Client Secret — du brauchst beide für den nächsten Schritt. Die JTL-Dokumentation beschreibt diesen Schritt unter guide.jtl-software.com/jtl-connector/shopware-6.

Melde dich im JTL-Kundencenter an und gehe zu Produkte, dann Shop-Connectoren. Wähle ‚Shopware 6‘ aus, erstelle eine neue Connector-Instanz und trage die Shop-URL ein. Das System generiert einen Connector-Key, den du in JTL-Wawi unter dem Reiter Shopware-Connector einträgst. Füge dort auch Client ID und Client Secret aus Shopware ein. Speichern und Verbindung testen.

Starte in JTL-Wawi unter dem Shopware-Connector-Reiter einen Komplettabgleich. Taucht sofort eine Fehlermeldung zu Herstellern, Custom Fields oder Plugins auf, unterbreche den Abgleich und behebt die Datenquelle in Shopware zuerst. Ein erfolgreicher Abgleich überträgt Artikel, Kategorien und Bestandsmengen. Danach den Deltaabgleich-Intervall in den Connector-Einstellungen setzen. Wichtig: Lieferstatus in JTL-Wawi mit den Lieferzeitnamen in Shopware abgleichen — der Name muss exakt übereinstimmen, sonst werden Lieferzeiten nicht korrekt übertragen.

Autor

Alexander Luft

JTL Service Partner Gold · Vlarom E-Commerce Agentur · Ahrensfelde bei Berlin