Markdown (Eisvogel)

itkloyaltypoints-anwenderdokumentation.md

---
title: "ItkLoyaltyPoints"
subtitle: "Anwenderdokumentation"
author: ["André Fischer"]
date: "30-03-2026"
lang: de
titlepage: true
titlepage-color: "1E3A5F"
titlepage-text-color: "FFFFFF"
titlepage-rule-color: "4A90D9"
titlepage-rule-height: 4
toc: true
toc-own-page: true
numbersections: true
header-left: "ItkLoyaltyPoints"
header-right: "Anwenderdokumentation"
footer-left: "ITK Computer GmbH"
---

# Zweck und Funktionsumfang

Du willst Kunden für wiederholte Käufe belohnen, optional einen **geschlossenen Club** mit eigenen Landingpages fahren und vielleicht noch **Wallet-Pässe** (PassCreator) anbieten – **ItkLoyaltyPoints** bündelt das in einem Plugin: Punktekonto, Buchungen, Checkout-Einlösung, Verfall/Sperre, E-Mail-Warnungen vor Ablauf und eine Menge **Werkzeuge für den Betrieb** (CLI, Admin am Kunden).

**ItkLoyaltyPoints** ist das Treuepunkte-System inklusive optional **25now Club**: Kunden sammeln Punkte (Bestellungen, Willkommenspunkte, PassCreator-Bonus), lösen sie im Checkout als Rabatt ein, und können über **CMS-Elemente** (Punktestand, Club-Modal, Teilnahmebedingungen, PassCreator-Kachel) im Erlebniswelt-Editor eingebunden werden.

Wesentliche Bausteine:

- **Punktekonto** pro Kunde, gebucht über Transaktionen (DAL-Entity `itk_loyalty_transaction`)
- **Sperre und Verfall** für Bestell- und Willkommenspunkte (konfigurierbar)
- **Einlösung** über **RedeemPointsCartProcessor** / Checkout-Route
- **Club:** Kundengruppe, Weiterleitungen, Modal, Newsletter-HTML, ActiveCampaign-Liste, Webhooks
- **PassCreator:** Wallet-Karten, Sync-Task, Webhook bei Download
- **E-Mails** zu ablaufenden Punkten (Scheduled Task + Worker)
- **Admin:** Loyalty-Daten zum Kunden (Controller im Admin)

Diese Datei soll auch für Grenzfälle reichen: Gerade Themen wie **Storno**, **teilweise Erstattung**, **Worker**, **Club-Zugriff** und **PassCreator** sind deshalb hier ausdrücklich mit aufgenommen, damit du nicht noch zusätzliche Projektdokumente brauchst.

---

## Diagramm: Punkte im Ueberblick

```mermaid
flowchart LR
  K[Kauf und Aktionen] --> T[Punktekonto]
  T --> C[Checkout Einloesung]
  T --> V[Verfall und E-Mail]
```

# Konfiguration (überblick)

Alles unter **Einstellungen → System → Plugins** → **25now Loyalty Club** → **Konfiguration**, **pro Sales Channel** (außer wo Global explizit genannt).

## Punkte

| Feld | Kurzbeschreibung |
|------|------------------|
| Plugin aktivieren | Hauptschalter |
| Punkte pro Euro | float, z. B. 1.0 |
| Punktewert in Cent | float, z. B. 1.0 = 1 Punkt = 1 Cent Rabatt |
| Sale: keine Punkte sammeln | Rabattierte Artikel (Streichpreis) ohne Award |
| Sperrtage (Bestellungen) | Punkte nach Bestellung gesperrt |
| Verfallstage (Bestellpunkte) | 0 = kein Verfall |
| System global | Punkte sales-channel-übergreifend gültig |
| Kategorie Teilnahmebedingungen | Link-Ziel für Modal „gesperrte Punkte“ |
| Teilnahmebedingungen gültig ab | Erzwingt erneute Zustimmung für Clubkunden nach Datum |

## Club

| Feld | Kurzbeschreibung |
|------|------------------|
| Club-Zugriff Kundengruppe | Nur diese Gruppe hat Club-Zugang; leer = alle |
| Clubanmeldung Kategorie | Redirect für Nicht-Mitglieder |
| Clubbereich Kategorie | Ziel für berechtigte Kunden |
| Club Newsletter Formular (HTML) | HTML im Club-Modal |
| ActiveCampaign Base URL / Token / Club-Listen-ID | Club-Newsletter-Sync |
| Club DOI E-Mail-Template | Optional |
| Club-Beitritt Webhook Secret | **?secret=** an Webhook-URL |

## Einlösung

| Feld | Kurzbeschreibung |
|------|------------------|
| Mindestbestellwert (€) | 0 = aus |
| Mindestanzahl Punkte zum Einlösen | 0 = aus |
| Max. Punkte pro Bestellung | 0 = unbegrenzt |
| Nur registrierte Kunden | Empfohlen an |
| Sale: nicht mit Punkten bezahlen | Einlösung blockiert bei Sale-Positionen |
| Gutschein-Produktnummer | Produkt für Rabatt-LineItem |

## Willkommenspunkte

Anzahl, Beschreibungstext, Sperrtage, Verfallstage (siehe Hilfetexte in der `config.xml`).

## PassCreator (Wallet)

API-URL, Key, Template-ID, Auto-Sync, Intervall, Bonuspunkte für Download inkl. Sperre/Verfall – exakte Feldnamen in der Admin-Oberfläche.

## E-Mail (Ablauf)

Aktivierung, Template-ID, Warnungstage vor Ablauf, Absender – `Worker/Cron` für Scheduled Tasks erforderlich.

---

# Storefront für Kund:innen

- **Konto:** Route `/account/loyalty` (Punktestand, Historie – siehe Theme)
- **Checkout:** Einlösen per XHR **POST /checkout/loyalty/redeem**
- **Club:** diverse Routen (Registrierung, Modal, Membership, Redirects – Details Entwicklerdoku)
- **PassCreator:** eigene Controller unter `PassCreator/`

---

# CMS (Erlebniswelten)

Folgende **CMS-Element-Resolver** existieren (im Code unter `Core/Content/Cms/` bzw. `PassCreator/…`):

- Treuepunkte-Anzeige (**LoyaltyPointsCmsElementResolver**)
- Teilnahmebedingungen (**LoyaltyConditionsCmsElementResolver**)
- Club-Zugang-Modal (**ClubAccessModalCmsElementResolver**)
- PassCreator-Kachel (**PassCreatorCmsElementResolver**)

Redakteure binden die Blöcke im **Shopping Experiences**-Editor ein; technische Felder pro Element im Admin-Modul des Plugins.

---

# Bestellstatus, Storno und Erstattung

Das Plugin reagiert auf **Bestellstatus** und **Zahlungsstatus**. Für dich im Alltag wichtig:

- **Normale Bestellung:** Punkte werden vergeben bzw. bei Einlösung abgezogen.
- **Komplette Stornierung:** Bereits vergebene Punkte werden mit einer Gegenbuchung wieder aus der Bilanz genommen.
- **Komplette Rückerstattung:** Dasselbe Prinzip gilt auch auf Zahlungs-/Transaktionsebene bei **refunded**.
- **Teilweise Rückerstattung:** Das Plugin versucht, den Punkteabzug **anteilig** zu berechnen. Technisch wird dafür der Unterschied zwischen ursprünglichem und aktuellem Bestellwert betrachtet; daraus ergibt sich ein prozentualer Abzug.
- **Doppelte Events vermeiden:** Wenn eine Bestellung fast gleichzeitig über Bestellung **und** Zahlung in Rückabwicklung läuft, prüft das Plugin aktiv, ob schon eine Reversal-Buchung existiert. So soll verhindert werden, dass Punkte doppelt abgezogen werden.
- **Reaktivierte Bestellung:** Wird eine zuvor stornierte Bestellung wieder auf **open / in_progress / completed** gesetzt, markiert das Plugin die vorherigen Storno-Gegenbuchungen über **expiresAt** als nicht mehr wirksam.

Für den Support heißt das: Bei „falschem“ Punktestand immer sowohl den **Bestellstatus**, den **Zahlungsstatus** als auch die einzelnen **Loyalty-Transaktionen** des Kunden zusammen ansehen.

---

# CLI-Befehle (Vollständige Liste)

| Befehl | Zweck (laut Plugin) |
|--------|----------------------|
| `itk:loyalty:ac:remove` | E-Mail(s) von der konfigurierten AC-Club-Liste entfernen |
| `itk:loyalty:customer:adjust` | Manuelle Punktekorrektur |
| `itk:loyalty:customer:points` | Übersicht Punkte für einen Kunden |
| `itk:loyalty:bulk:delete` | Viele Transaktionen löschen |
| `itk:loyalty:bulk:create` | Transaktionen aus CSV/JSON anlegen |
| `itk:loyalty:welcome:award` | Willkommenspunkte nachziehen |
| `itk:loyalty:expire:mark` | Abgelaufene Transaktionen markieren |
| `itk:loyalty:transaction:delete` | Eine Transaktion löschen |
| `itk:loyalty:passcreator:sync:run` | PassCreator-Sync manuell |
| `itk:loyalty:process-refunded-orders` | Erstattungen nachverarbeiten |
| `itk:loyalty:order:recalculate` | Punkte zu Bestellungen neu berechnen |
| `itk:loyalty:stats:overview` / `itk:loyalty:stats:customer` | Statistik |
| `itk:loyalty:transaction:create` / **update** / **list** / **export** | Transaktions-CRUD/Export |
| `itk:loyalty:fraud:detect` | Auffälligkeiten |
| `itk:loyalty:generate-dummy-transactions` | Testdaten |
| `itk:loyalty:email:expiring:run` | Ablauf-Mails manuell anstoßen |

Immer **php bin/console <befehl> --help** für Argumente nutzen.

---

# Logs

Standard: `var/log/loyalty_points.log` (Monolog-Channel im Plugin – bei Abweichung `services.xml` prüfen).

---

# E-Mail-Templates

Für Ablauf-Warnungen und ähnliche Benachrichtigungen nutzt das Plugin normale **Shopware-Mail-Templates** bzw. entsprechende Template-Inhalte. Im Betrieb ist für dich wichtiger als Beispiel-Markdown:

- Ist die Funktion in der Konfiguration aktiviert?
- Sind Warnungstage, Absender und Template sauber gepflegt?
- Läuft der Worker, damit die Mail überhaupt versendet wird?

---

# Womit du im Alltag am weitesten kommst

Wenn du im Tagesgeschäft etwas prüfen musst, reichen fast immer diese vier Blickrichtungen:

1. **Konfiguration** im Plugin.
2. **Punktetransaktionen** des betroffenen Kunden.
3. **Bestell- und Zahlungsstatus** der betroffenen Bestellung.
4. **Worker / Scheduled Tasks**, falls E-Mails oder Synchronisationen fehlen.

Damit bekommst du die meisten Support- und Betriebsfälle direkt aus dieser Doku heraus eingegrenzt.

---

# Worker und geplante Aufgaben (kurz)

**Ablauf-E-Mails** und andere zeitgesteuerte Logik laufen über Shopware **Scheduled Tasks** – dafür muss der **Message Queue Worker** bzw. Cron auf dem Server **zuverlässig** laufen (**bin/console messenger:consume** oder euer Hosting-Setup). Ohne Worker bleiben Mails und Hintergrundjobs stecken; das ist kein Bug im Plugin, sondern Infrastruktur.

---

# FAQ

**Kann ich Punkte nur in einem Sales Channel nutzen?**  
Über die Option **System global** steuerst du, ob Konten kanalübergreifend gelten. Ist sie aus, hängen Buchungen und Verfügbarkeit stärker am jeweiligen Sales Channel.

**Was passiert bei Storno?**  
Bei kompletter Stornierung oder Rückerstattung erzeugt das Plugin Gegenbuchungen. Bei Teil-Erstattungen versucht es den Abzug anteilig zu berechnen. Wenn es merkwürdig aussieht, prüf immer die Transaktionshistorie des Kunden und ob schon eine frühere Gegenbuchung existiert.

**Club ohne ActiveCampaign?**  
Dann die AC-Felder leer lassen und nur die Shop-internen Redirects/Modal nutzen – sofern das für euer Konzept reicht.

**Mindestbestellwert greift nicht?**  
Checkout-Konfiguration und ggf. Theme prüfen; **RedeemPointsCartProcessor** hängt am Warenkorb – Logs `loyalty_points.log` helfen.