Geburtstags-Gutschein

Das Plugin kann Kunden automatisch am Geburtstag einen JTL-Gutschein zuschicken. Der Versand wird über den Shopware Flow Builder gesteuert — Sie entscheiden, welche Aktion ausgeführt wird und können beliebige weitere Flow-Schritte ergänzen.

Funktionsweise

Jeden Tag sucht ein geplanter Hintergrund-Task (Scheduled Task) alle Kunden, deren Geburtsdatum auf das heutige Datum fällt und die in diesem Kalenderjahr noch keinen Geburtstagsgutschein erhalten haben. Für jeden gefundenen Kunden wird das Flow-Event i7_jtl_vouchers.customer_birthday ausgelöst.

Im Flow Builder hängen Sie an dieses Event die Aktion „Geschenk-Gutschein versenden". Die Aktion erstellt einen neuen JTL-Gutschein mit dem konfigurierten Betrag und versendet ihn per E-Mail an den Kunden.

Eine Deduplizierungs-Tabelle (i7_birthday_voucher_log) stellt sicher, dass pro Kunde und Kalenderjahr nur ein Gutschein versendet wird — auch bei mehrfachem Task-Lauf am selben Tag.

Voraussetzungen

• Geburtsdatum muss im Kundenkonto hinterlegt sein (Shopware-Standardfeld). Das Feld ist im Standard-Registrierungsformular meist deaktiviert — aktivieren Sie es unter Einstellungen > Shop > Storefront.
• Message Queue Worker muss laufen, damit E-Mails asynchron versendet werden.
• Flow Builder ist in Shopware 6.4+ standardmäßig verfügbar.
• JTL API-Verbindung muss eingerichtet sein (siehe Verbindung herstellen).

Einrichtung

1. Betrag konfigurieren

Öffnen Sie Erweiterungen > Meine Erweiterungen > JTL Vouchers Schnittstelle > Konfiguration und scrollen Sie zur Karte „Geburtstags-Gutschein".

Feld	Standard	Beschreibung
Standard-Betrag (EUR)	10	Gutscheinwert in EUR, wenn kein abweichender Betrag im Flow konfiguriert wird

2. Flow anlegen

1. Navigieren Sie zu Marketing > Flow Builder > Flow anlegen
2. Geben Sie dem Flow einen Namen (Pflichtfeld)
3. Wählen Sie als Trigger: JTL Gutscheine: Kundengeburtstag (i7_jtl_vouchers.customer_birthday)
4. Fügen Sie die Aktion „Geschenk-Gutschein versenden" hinzu
5. Optional: Konfigurieren Sie im Action-Dialog einen abweichenden Gutscheinbetrag (leer = System-Standard)
6. Speichern und aktivieren Sie den Flow

3. Flow testen

Da der Task einmal täglich läuft, können Sie einen Testkunden mit dem heutigen Datum als Geburtstag anlegen und den Scheduled Task manuell auslösen:

# Prüfen ob Testkunde gefunden wird
bin/console dbal:run-sql "SELECT email, birthday FROM customer WHERE MONTH(birthday) = MONTH(CURDATE()) AND DAY(birthday) = DAY(CURDATE()) AND active = 1"

# Task sofort auslösen
bin/console dbal:run-sql "UPDATE scheduled_task SET next_execution_time = '2000-01-01' WHERE name = 'i7_jtl_vouchers.birthday_voucher'"
bin/console messenger:consume scheduled_task --limit=1 -vv

# E-Mail-Versand verarbeiten
bin/console messenger:consume async --limit=5 -vv

TIP

Prüfen Sie im Anschluss die Plugin-Log-Datei unter var/log/I7JtlVouchers-YYYY-MM-DD.log auf Fehler.

Häufige Probleme

Kunden erhalten keinen Gutschein

• Ist das Geburtsdatum im Kundenkonto gesetzt?
• Läuft der Message Queue Worker? (bin/console messenger:consume async)
• Ist der Flow aktiv und der Trigger korrekt ausgewählt?
• Prüfen Sie das Plugin-Log auf API-Fehler.

Kunden erhalten Gutschein mehrfach

Das sollte durch die Deduplizierungstabelle verhindert werden. Falls es doch passiert, prüfen Sie, ob die Migration Migration1775220000AddBirthdayVoucherLog ausgeführt wurde:

bin/console database:migrate --all I7JtlVouchers