JTL-Vouchers mit JTL-Shop verbinden: Plugin, API und Checkout-Integration richtig aufsetzen

Auf einen Blick

• ✓Die häufigste Ursache für „Gutschein nicht erkannt“ ist keine technische Fehlfunktion, sondern eine fehlende oder veraltete Client-Konfiguration im Vouchers-Portal. Das lässt sich in unter 10 Minuten beheben. Wir sehen dieses Muster in fast jedem Projekt.
• ✓JTL-Vouchers benötigt mindestens JTL-Shop 5.1 und Plugin-Version 1.0.0. Die PIN zur Verbindung ist nur 30 Minuten gültig. Wer zu langsam ist oder den Tab wechselt, bekommt eine Verbindungsablehnung und muss von vorne anfangen.
• ✓Laut Issue-Tracker (SHOP-8832): Ist der Vouchers-Server nicht erreichbar, kann das den gesamten JTL-Shop blockieren. Wer Vouchers produktiv einsetzt, braucht ein Monitoring auf den Vouchers-Dienst. Wir richten das standardmäßig mit ein.

Wir sehen dieses Setup regelmäßig in Kundenprojekten: Händler die JTL-Vouchers schon in der Wawi oder an der POS nutzen, wollen die Gutscheine auch im Online-Shop einlösbar machen. Technisch ist das der richtige Weg — ein Gutschein, ein Guthaben, einlösbar überall. Vlarom E-Commerce Agentur aus Ahrensfelde bei Berlin ist JTL Service Partner Gold und hat diese Anbindung in Dutzenden Kundenprojekten umgesetzt. Wir kennen die typischen Fehler bei der Shop-Anbindung und wissen, warum manche Setups funktionieren und andere nicht.

JTL-Vouchers ist als eigenständiges SaaS-Produkt konzipiert, kein lokales System, sondern ein Cloud-Dienst der über eine API mit den angebundenen Systemen kommuniziert. Der JTL-Shop spricht dabei nicht direkt mit Wawi, sondern über den zentralen Vouchers-Server. Das hat Vorteile (einheitlicher Gutschein-Stand überall), aber auch eine klare Abhängigkeit: fällt der Vouchers-Dienst aus, fehlt dem Shop die Referenz für jede Gutschein-Prüfung.

Quelle JTL Issue-Tracker (SHOP-8832): Wenn die Vouchers-Dienste nicht erreichbar sind, sind auch alle Shops nicht erreichbar, welche das Vouchers-Plugin aktiviert haben. Der Status dieses Tickets: abgewiesen. Bedeutet: das Verhalten ist bekannt und bleibt vorerst so. Wer das Plugin aktiv einsetzt, muss das einkalkulieren.

Was du für eine saubere Anbindung brauchst:

• →JTL-Shop-Version: Mindestens JTL-Shop 5.1 — ältere Versionen werden vom Plugin nicht unterstützt (Quelle: JTL Systemvoraussetzungen)
• →Plugin-Version: JTL-Vouchers Plugin 1.0.0 oder höher, beziehbar über den JTL-Extension Store
• →Aktive Wawi-Verbindung: Für den Gutschein-Verkauf im Shop wird zusätzlich eine verbundene JTL-Wawi benötigt — ohne Wawi kein Artikel-Sync, kein Gutschein-Produkt im Shop
• →Client-Gruppe in Vouchers: Mindestens eine Client-Gruppe und ein Client müssen im Vouchers-Portal angelegt sein, bevor du die Shop-Verbindung herstellst — fehlende Client-Gruppen sind Fehlerquelle Nummer 1
• →30-Minuten-PIN: Die PIN zur Verbindung ist 30 Minuten gültig. Danach muss sie neu generiert werden. Wer sie nicht sofort einträgt, bekommt beim Verbinden eine Ablehnung ohne sprechende Fehlermeldung

Der wichtigste Punkt vor der technischen Einrichtung: die Vouchers-Konfiguration muss vollständig sein. Plugin installieren bevor Clients angelegt sind führt zu einer Verbindung, die zwar grün leuchtet, aber keine Gutscheine kennt.

Wir haben diese Anbindung in mehreren Projekten aufgesetzt und immer wieder sehen wir die gleichen Fehlerbilder — unabhängig davon ob der Händler technisch versiert ist oder nicht. Hier sind die Fehler und was dahinter steckt.

1

Gutschein-Code nicht erkannt im Checkout

Der Kunde gibt einen Gutschein-Code ein, der Shop meldet ‚ungültiger Code‘ — obwohl der Code im Vouchers-Portal als gültig angezeigt wird. Ursache fast immer: der Shop-Client ist in der falschen Client-Gruppe, oder die Einlöse-Optionen sind so konfiguriert, dass diese Gruppe für diesen Shop nicht einlösen darf.

Die Einlöseoptionen in JTL-Vouchers sind granular: du kannst per Checkbox steuern, welche Client-Gruppe an welchem Standort (Shop, POS, Wawi) einlösen darf. Standardmäßig ist alles erlaubt — aber wer die Einstellungen berührt hat, kann versehentlich eine Kombination gesperrt haben (Quelle: guide.jtl-software.com/jtl-vouchers/einrichtung/einloeseoptionen-in-jtl-vouchers/).

2

Code bereits eingeloest obwohl nicht

Der häufigste Sync-Fehler: ein Gutschein zeigt im Portal ‚eingelöst‘, obwohl der Kauf nie abgeschlossen wurde. Das passiert wenn ein Checkout-Abbruch die Reservierung nicht sauber zurückschreibt — etwa bei einem Timeout zwischen Shop und Vouchers-Dienst.

JTL reserviert einen Gutschein beim Einlösen im Checkout und gibt ihn frei wenn der Kauf abbricht. Bricht die Verbindung während dieser Freigabe ab, bleibt der Gutschein im reserviert-Status hängen. Im Vouchers-Portal lässt sich der Status manuell zurücksetzen — eine automatische Bereinigung nach Timeout gibt es bisher nicht.

3

Plugin-Version passt nicht zur Shop-Version

Wer JTL-Shop aktualisiert hat ohne das Vouchers-Plugin zu aktualisieren, bekommt im Checkout manchmal stille Fehler: die Gutschein-Eingabe erscheint, der Code wird akzeptiert, aber der Betrag wird nicht abgezogen.

Das Plugin wird über den Extension Store gepflegt und nicht automatisch mit dem Shop-Update mitgezogen. Nach jedem Shop-Update sollte das Vouchers-Plugin auf Kompatibilität geprüft werden. Im Plugin-Bereich des Shop-Backends steht welche Version aktiv ist und ob ein Update verfügbar ist.

4

Vouchers-Server nicht erreichbar blockiert Shop

Der kritischste Fehler in der Produktion: der Vouchers-Dienst ist temporär nicht erreichbar und der Shop ist komplett nicht aufrufbar. Das ist kein Einzelfall, sondern ein dokumentiertes Verhalten (Issue SHOP-8832, Status: abgewiesen).

Wer JTL-Vouchers produktiv einsetzt, sollte den Vouchers-Dienst ins Monitoring aufnehmen. Wenn der Dienst öfter als erwartet ausfällt, kann es sinnvoll sein, die Plugin-Aktivierung auf Phasen zu beschränken wo aktiv Gutscheine verkauft werden.

5

Teileinlösung funktioniert nicht

Händler erwarten, dass Kunden einen Gutschein über 50 Euro auch bei einem Warenkorb von 30 Euro einlösen können und den Restbetrag behalten. Das funktioniert — aber nur wenn der Gutschein als Mehrweckgutschein (multi-purpose voucher) angelegt ist.

Einzweckgutscheine (single-purpose) werden im Checkout als negativer Rechnungsposten behandelt und haben keine Restbetrag-Logik. Der Typ muss beim Anlegen des Gutscheins gewählt werden — nachträglich lässt er sich nicht ändern. Wer Teileinlösung braucht, muss das von Anfang an einplanen.

6

Fehlende Wawi-Verbindung unterbricht Gutschein-Verkauf

JTL-Vouchers kann im Shop Gutscheine einlösen lassen ohne aktive Wawi-Verbindung. Aber Gutscheine im Shop zu verkaufen — als Produkt anbieten, kaufen, per E-Mail versenden — setzt eine funktionierende Wawi-Anbindung voraus.

Shops die den Wawi-Abgleich temporär pausieren verlieren in dieser Zeit die Fähigkeit, neue Gutschein-Codes an Kunden auszuliefern. Gutschein-Einlösungen laufen weiter, weil die direkt über den Vouchers-Dienst gehen.

Ein Gutschein, einlösbar überall

Der größte Vorteil von JTL-Vouchers gegenüber selbst gebauten Gutschein-Lösungen: ein Guthaben, sichtbar und einlösbar in JTL-Shop, JTL-POS und JTL-Wawi gleichzeitig. Ein Kunde kauft einen Gutschein online und löst ihn im stationären Laden ein — das funktioniert ohne manuelle Abstimmung zwischen den Systemen. Wir sehen das besonders bei Händlern die Online- und Offline-Kanäle kombinieren: der manuelle Abgleich-Aufwand fällt komplett weg.

Zentrales Gutschein-Management statt Tabellen

Ohne JTL-Vouchers landen Gutschein-Codes oft in Excel-Listen die niemand aktuell hält. Mit der integrierten Lösung hat das Vouchers-Portal den Stand aller Codes in Echtzeit: welche wurden generiert, welche eingelöst, welche reserviert, welche abgelaufen. Vor allem bei Gutscheinkampagnen ist das der Unterschied zwischen einem überschaubaren Prozess und einem Chaos aus manuellen Prüfungen. Für Händler die mehr als 20 Gutscheine pro Monat ausgeben, ist JTL-Vouchers die sauberere Lösung.

Die Verbindung zwischen JTL-Vouchers und deinem JTL-Shop hat eine feste Reihenfolge. Wer Schritte überspringt oder die Reihenfolge dreht, bekommt Fehler die auf den ersten Blick nicht erklärbar sind. Hier ist der Ablauf so wie wir ihn in der Praxis umsetzen.

Prüfe zuerst die Shop-Version: JTL-Shop 5.1 ist das Minimum, neuere Versionen sind problemlos. Prüfe außerdem ob bereits eine Wawi-Verbindung besteht — für den Gutschein-Verkauf (nicht nur Einlösung) wird sie gebraucht. Dann: ins JTL-Vouchers-Portal einloggen und kontrollieren, ob mindestens eine Client-Gruppe und ein Client angelegt sind. Ohne diese Basis schlägt die Verbindung fehl oder zeigt einen grünen Status ohne echte Funktion. Das Plugin erst dann aus dem Extension Store buchen — nicht früher.

Im JTL-Extension Store nach JTL-Vouchers suchen und die Erweiterung buchen. Danach im JTL-Shop-Backend unter Plugins > Installierte Plugins das JTL-Vouchers-Plugin aktivieren. Wichtig: Plugin-Aktivierung und PIN-Eingabe sollten direkt nacheinander erfolgen — nicht den Tab wechseln oder den Browser schließen. Die PIN ist nur 30 Minuten gültig. Details zur Plugin-Konfiguration: guide.jtl-software.com.

Im JTL-Vouchers-Portal im Menüpunkt Clients den betreffenden Client aufrufen und über die Link-Schaltfläche eine PIN generieren. Diese PIN sofort kopieren — sie ist nur 30 Minuten gültig. Zurück im JTL-Shop-Backend das Vouchers-Plugin öffnen, die PIN eintragen und auf Verbinden klicken. Bei Erfolg erscheint eine Verbindungsbestätigung. Schlägt die Verbindung fehl, liegt es fast immer an einer abgelaufenen PIN oder einem fehlenden Client im Portal.

Im Vouchers-Portal einen Test-Gutschein erstellen: Typ Mehrweck für Teileinlösung, Wert z.B. 50 Euro, Gültigkeitsdauer festlegen. Den generierten Code notieren. Im JTL-Shop einen Warenkorb aufbauen und den Code im Checkout-Feld eingeben. Gutschein muss erkannt und abgezogen werden. Dann den Kauf abbrechen und prüfen ob der Code im Portal wieder als verfügbar erscheint — das testet die Reservierungs-Rückbuchung. Danach einen Kauf abschließen und den Restbetrag im Portal kontrollieren.

Im Plugin-Bereich unter Einstellungen kannst du festlegen, ob Kunden beim Einlösen eine PIN eingeben müssen. Für B2C-Shops lohnt sich diese Option deaktiviert — zu viel Reibung im Checkout. Für B2B oder interne Gutscheine kann sie sinnvoll sein. Abschließend: den Vouchers-Dienst in dein Monitoring aufnehmen. So merkst du rechtzeitig wenn der Dienst nicht erreichbar ist, bevor dein Shop davon betroffen wird. Weitere Informationen zu Einlöseoptionen: guide.jtl-software.com.