Markdown (Eisvogel)

itkreturnform-anwenderdokumentation.md

---
title: "ItkReturnForm"
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: "ItkReturnForm"
header-right: "Anwenderdokumentation"
footer-left: "ITK Computer GmbH"
---

# Zweck

Wenn ein Privatkunde **Widerruf oder Rückgabe** melden soll, reicht oft eine Mail – aber du willst **strukturierte Daten**, Mengen pro Position und einen **Nachweis in Shopware**. **ItkReturnForm** liefert genau das: Formular im Storefront, Speicherung in der DB, Benachrichtigung per E-Mail und Verwaltung im Admin.

**ItkReturnForm** ist ein `Widerrufs-/Rückgabeformular` für **eingeloggte Privatkunden**: Pro Bestellung können ausgewählte Positionen mit Mengen angegeben, Gründe und Empfangsdaten erfasst und der Vorgang per E-Mail an Support- und Widerrufs-Adressen gemeldet werden. Die Einträge werden in der Datenbank gespeichert und im **Shopware-Admin** in einem **eigenen Modul** verwaltet.

**Geschäftskunden** (`customer.company` gesetzt) werden abgewiesen und zur Startseite geleitet.

---

# Konfiguration

Unter **Erweiterungen → Meine Erweiterungen** → **Widerrufsformular** → **Konfiguration**:

| Feld | Bedeutung |
|------|-----------|
| **Widerrufsfrist in Tagen** | Wird u. a. in Twig über die Funktion **`getReturnDaysLimit()`** bereitgestellt (Anzeige/Logik im Theme). Standard 28. |
| **Support E-Mail** | Empfänger der Benachrichtigung mit Falldetails. |
| **Widerrufs E-Mail** | Zweiter Empfänger (z. B. dediziertes Widerrufs-Postfach). |

---

# Kundenseite (Ablauf)

## Diagramm: Ablauf im Storefront

```mermaid
flowchart TD
  L[Eingeloggt Privatkunde] --> O[Formular zur Bestellung]
  O --> V[Pruefung und Restmengen]
  V --> S[Submit]
  S --> D[Speicherung DB]
  D --> E[E-Mails]
```
1. Kunde ist eingeloggt und öffnet das Formular unter `/return-form/{orderId}` (Route `frontend.return.form`).
2. Das System prüft: Login, **kein** B2B-Kunde, Bestellung existiert und **gehört** zum eingeloggten Kunden.
3. Bereits erfasste Widerrufe derselben Bestellung werden berücksichtigt: **Restmengen** pro Produkt dürfen nicht überschritten werden.
4. Absenden per **POST /return-form/submit** (`frontend.return.form.submit`):
   - Pflicht: mindestens eine Position, `Datenschutz/AGB/Widerruf`-Checkbox (**privacyPolicy**)
   - **Empfangsdatum** *oder* Checkbox **„Ware nicht erhalten“** (**wareNotReceived**)
   - Empfangsdatum darf nicht in der Zukunft liegen
5. Nach Speichern: E-Mails an die konfigurierten Adressen, Anzeige einer Erfolgsseite (Theme-Template).

**Hinweis:** Feldnamen im Request u. a. `products_ids[]`, `products_quantities[]`, **reason**, **orderId**, **receivedDate**.

---

# Admin

- Verwaltung der **Rueckruf**-Einträge läuft über das vom Plugin registrierte **Administration-Modul** in Shopware.
- Funktionen typischerweise: Liste, Detail, Status/Bearbeitung, ggf. E-Mail-Templates (je nach eurer Ausbaustufe).

---

# CLI

| Befehl | Beschreibung |
|--------|----------------|
| **php bin/console itk:list:rueckrufe** | Listet alle gespeicherten Einträge tabellarisch (Sortierung nach **createdAt** absteigend). |

---

# Datenhaltung

Tabelle **rueckruf**, DAL-Entity **rueckruf** (**RueckrufEntityDefinition**). Felder u. a.:

- **orderId**, **customerId**, **reason**, **createdAt**, **updatedAt**
- **processed** (boolean)
- **voucherWanted**, **wareNotReceived** (optional booleans in DB)
- **returnedProductIds** (JSON-Array mit **id** und **quantity** pro Position)
- **receivedDate** (optional)

---

# E-Mails

Der Versand läuft über den Shopware-**MailService**. Das Plugin rendert dafür eigene Twig-Templates aus `Resources/views` und schickt die Nachricht an die in der Konfiguration hinterlegten Mailadressen. Wenn ihr das Layout oder die Texte anpassen wollt, passiert das je nach Projekt entweder direkt über diese Templates oder über registrierte Shopware-Mailvorlagen im Admin.

---

# Typische Probleme

- **403 / Umleitung:** Falscher Kunde, B2B-Kunde, oder falsche **orderId**.
- **Mengenfehler:** Summe aus früheren Widerrufen + neuer Antrag > bestellte Menge.
- **Keine Mail:** Shopware-Mailer, Spam-Ordner, **supportMailAddress** / **returnMailAddress**.

---

# FAQ

**Warum kann mein Geschäftskunde das Formular nicht nutzen?**  
Absicht: B2B wird auf die Startseite geleitet – für B2B braucht ihr meist andere Prozesse.

**Kann derselbe Artikel mehrfach widerrufen werden?**  
Ja, bis die **kumulierte Menge** die bestellte Menge erreicht hat.

**Wo finde ich die Fälle im Admin?**  
Im vom Plugin registrierten **Admin-Modul** (Menüpunkt je nach Snippet/Übersetzung).