# Return Portal + Auto-Label — Vollständige Dokumentation

> Self-Service-Retourenportal für Kunden, automatisch generierte Multi-Carrier-Rücksendelabels, Admin-Inspektions-Workflow und Resolution-Engine (Rückerstattung, bonifiziertes Guthaben, Ersatz) für WooCommerce. Version: 1.0.7 Kompatibilität: WordPress 6.2+ • WooCommerce 8.0+ • PHP 8.0+ • HPOS und Cart/Checkout…

- Seite: <https://www.datafirefly.com/de/documentation/dfreturnportal/>
- Sprache: de
- Aktualisiert am: 2026-06-27
- Weitere Sprachen: [fr](https://www.datafirefly.com/documentation/dfreturnportal/index.md), [en](https://www.datafirefly.com/en/documentation/dfreturnportal/index.md), [es](https://www.datafirefly.com/es/documentation/dfreturnportal/index.md), [it](https://www.datafirefly.com/it/documentation/dfreturnportal/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfreturnportal/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfreturnportal/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfreturnportal/index.md)
- Index: <https://www.datafirefly.com/de/documentation/llms.txt>

Self-Service-Retourenportal für Kunden, automatisch generierte Multi-Carrier-Rücksendelabels, Admin-Inspektions-Workflow und Resolution-Engine (Rückerstattung, bonifiziertes Guthaben, Ersatz) für WooCommerce.

**Version:** 1.0.7
**Kompatibilität:** WordPress 6.2+ • WooCommerce 8.0+ • PHP 8.0+ • HPOS und Cart/Checkout Blocks

## Überblick

Return Portal + Auto-Label automatisiert den gesamten Lebenszyklus einer Produktretoure in Ihrem WooCommerce-Shop:

- **Kundenseite**: Der Kunde beantragt die Rücksendung ohne Support-Kontakt, wählt Artikel aus, wählt einen Grund und erhält sofort sein PDF-Label.
- **Admin-Seite**: Dashboard mit Timeline, zeilenweiser Inspektion, vollständigem Aktivitätsprotokoll und automatischer Auflösung.
- **6 Versanddienstleister**: Manuell (natives PDF), Colissimo, Mondial Relay, Chronopost, UPS, DPD.
- **3 Auflösungen**: native WooCommerce-Rückerstattung, bonifiziertes Guthaben (+X%) oder automatischer Ersatz.

### Retouren-Status

Eine Retoure durchläuft bis zu 7 Phasen:

| Status | Beschreibung |
| --- | --- |
| `requested` | Antrag erhalten, wartet auf Validierung |
| `approved` | Vom Admin genehmigt (oder unter Schwellenwert automatisch genehmigt) |
| `label_sent` | Label erstellt und an Kunden gesendet |
| `in_transit` | Paket im Transit |
| `received` | Paket im Lager empfangen |
| `inspecting` | Artikel in Inspektion |
| `resolved` | Auflösung angewendet (Rückerstattung / Guthaben / Ersatz) |

Zwei zusätzliche terminale Status: `rejected` und `cancelled`.

## Installation

### Methode 1 — Über WordPress-Admin

1. Laden Sie die ZIP-Datei `dfreturnportal.zip` herunter.
2. Gehen Sie in WordPress zu **Plugins → Installieren → Plugin hochladen**.
3. Wählen Sie die ZIP-Datei aus und klicken Sie auf **Jetzt installieren**.
4. Aktivieren Sie das Plugin.

### Methode 2 — Über FTP/SSH

```bash
cd wp-content/plugins/
unzip dfreturnportal.zip
# Dann aus dem WordPress-Admin aktivieren
```

### Prüfungen nach der Installation

- Ein Menü **Retouren** erscheint in der WordPress-Seitenleiste.
- Ein Endpoint `/mein-konto/retouren/` wird automatisch erstellt.
- Die benutzerdefinierten Tabellen `wp_dfrp_returns`, `wp_dfrp_return_items`, `wp_dfrp_history`, `wp_dfrp_attachments` werden erstellt.

Falls der Tab "Retouren" nicht im Mein Konto erscheint, gehen Sie zu **Einstellungen → Permalinks** und klicken Sie "Speichern", um die Rewrite-Regeln zu aktualisieren.

## Erstkonfiguration

Gehen Sie zu **Retouren → Einstellungen**.

### Allgemein

| Einstellung | Beschreibung |
| --- | --- |
| **Berechtigungsfenster** | Anzahl der Tage nach der Bestellung, in denen eine Rücksendung erlaubt ist. Standard: 30 Tage. |
| **Kundenportal-Seite** | WordPress-Seite, auf der der Shortcode `[dfrp_portal]` angezeigt wird. Optional, wenn Sie nur den Mein-Konto-Endpoint verwenden. |
| **Admin-Benachrichtigungen** | E-Mail-Adresse, die Benachrichtigungen über neue Anträge erhält. Standard: Site-Admin. |

### Versanddienstleister

Wählen Sie den **aktiven** Versanddienstleister aus den 6 verfügbaren aus. Sie können auch das **Label-Format** (A4, A5, A6, 10x15) konfigurieren.

### Rücksendeadresse

Geben Sie die physische Adresse an, an die Rücksendungen geschickt werden. **Erforderlich**, um Labels zu generieren. Felder: Firma, Straße, Ort, PLZ, Land (ISO 2-Buchstaben-Code), Telefon, E-Mail.

### Versanddienstleister-Zugangsdaten

Für jeden API-Versanddienstleister (Colissimo, Mondial Relay usw.) enthält ein aufklappbarer Block die erforderlichen Zugangsdaten. Füllen Sie **nur** die Zugangsdaten des Versanddienstleisters aus, den Sie tatsächlich verwenden.

### Auflösung

| Einstellung | Beschreibung |
| --- | --- |
| **Guthaben-Bonus (%)** | Prozentsatz, der zum erstatteten Betrag hinzugefügt wird, wenn der Kunde das bonifizierte Guthaben wählt. Standard: 10%. |
| **Auto-Genehmigungsschwelle** | Unter diesem Betrag (Shop-Währung) werden Anträge automatisch genehmigt und das Label ohne Admin-Eingriff generiert. Auf 0 setzen, um zu deaktivieren. |
| **Vorgeschlagene Auflösung pro Grund** | Für jeden Grund (8 Standardgründe) wählen Sie die vorgeschlagene Auflösung: Rückerstattung / bonifiziertes Guthaben / Ersatz. |

### Ausschlüsse

- **Ausgeschlossene Kategorien**: WooCommerce-IDs, durch Kommas getrennt. Produkte in diesen Kategorien sind niemals retournierbar.
- **Ausgeschlossene SKUs**: eine SKU pro Zeile.

## Kundenerlebnis

### Über die Mein-Konto-Seite (eingeloggte Kunden)

Der einfachste und am häufigsten genutzte Ablauf. Der Tab **Retouren** erscheint automatisch im Menü `/mein-konto/` neben "Bestellungen", "Adressen" usw.

Der Kunde klickt auf Retouren, sieht die Liste seiner berechtigten Bestellungen (kein E-Mail/Nummer-Eintrag nötig), klickt Rücksendung starten bei der betreffenden Bestellung, wählt Artikel aus, wählt einen Grund und Menge pro Artikel, fügt optional Fotos hinzu (wenn der Grund es erfordert), wählt seine bevorzugte Auflösung und erhält sofort eine RMA-Nummer (z.B. `RMA-20260523-A1B2C3`) plus eine Bestätigungs-E-Mail.

### Über eine öffentliche Seite (Gastkunden)

Erstellen Sie eine WordPress-Seite, fügen Sie den Shortcode ein:

```
[dfrp_portal]
```

Der Kunde muss seine **Bestellnummer** + **E-Mail** zur Authentifizierung eingeben. Der Rest des Ablaufs ist identisch.

### Bestehende Anfrage verfolgen

Auf der öffentlichen Portalseite ermöglicht ein Block "Bestehende Anfrage verfolgen" Gastkunden, ihren RMA-Status zu prüfen (Status, Versand-Trackingnummer, Link zum Label).

### Shortcode-Anpassung

```
[dfrp_portal title="Rücksendeantrag" context="page"]
```

| Attribut | Werte | Beschreibung |
| --- | --- | --- |
| `title` | freier Text | Portal-Titel (visuell selten genutzt). |
| `context` | `page` oder `myaccount` | Erzwingt den Kontext. `myaccount` überspringt den Lookup-Schritt für eingeloggte Nutzer. |

## Admin-Workflow

### Dashboard

Zugänglich über **Retouren → Dashboard**. Enthält 9 farbige Statistikkarten (Anzahl pro Status, klickbar zur Listenfilterung), die 10 neuesten RMAs mit Schnellzugriff auf das Detail, und ein Banner mit der Kundenportal-URL mit "Kopieren"-Button zum Teilen.

### Anfragenliste

Zugänglich über **Retouren → Alle Anfragen**. Tabelle mit Filtern nach Status, Freitextsuche (RMA, Kunden-E-Mail, Bestellnummer) und Paginierung (20 pro Seite).

### Detailseite einer Anfrage

Komponenten:

1. **Kopfzeile**: RMA-Code + Status-Badge + Zurück zur Liste.
2. **Timeline**: 7 farbige Punkte, die den visuellen Fortschritt zeigen.
3. **Zu retournierende Artikel**: Tabelle mit Produkt, SKU, Menge, Einzelpreis, Grund und artikelbezogener Inspektion (Dropdown Konform / Teilweise / Abgelehnt — aktiviert nach Status `received`).
4. **Kundenfotos**: Galerie, wenn der Kunde Belege hochgeladen hat.
5. **Aktivitätsprotokoll**: vollständige chronologische Historie.
6. **Informationen**: Kunden-E-Mail, Bestelllink, Auflösungspräferenz, Kundennotiz.
7. **Rücksendelabel**: Versanddienstleister, Trackingnummer, PDF-Download-Button, Regenerieren-Button.
8. **Aktionen**: "Wechseln zu: [nächster Status]"-Buttons gemäß State Machine.
9. **Auflösen** (sichtbar, wenn Status `received` oder `inspecting`): Auflösungsauswahl + "Anwenden"-Button.

### Erlaubte Übergänge

Die State Machine verhindert ungültige Übergänge:

```
requested  → approved | rejected | cancelled
approved   → label_sent | rejected | cancelled
label_sent → in_transit | cancelled
in_transit → received
received   → inspecting
inspecting → resolved | rejected
```

Die Status `resolved`, `rejected` und `cancelled` sind terminal.

### Automatische Genehmigung

Falls Sie eine Auto-Genehmigungsschwelle konfiguriert haben (z.B. 50 €), wird jede Anfrage, deren Gesamtbetrag kleiner oder gleich der Schwelle ist, automatisch von `requested` auf `approved` gesetzt, das Label sofort generiert und an den Kunden gesendet — ohne Admin-Eingriff.

## Unterstützte Versanddienstleister

### Manuell (ohne API)

**Ideal zum Starten.** Generiert einen nativen PDF-Beleg mit QR-Code, ohne externe API-Abhängigkeit. Null Konfiguration, kostenlos, funktioniert sofort. Einschränkung: keine automatische Verfolgung. Verwendung: Der Kunde druckt es aus, Sie legen es beim Erstversand bei oder er klebt es für die klassische Postrücksendung darauf.

### Colissimo (La Poste)

Offizielle REST API (Sls Service `generateLabel`). Erforderliche Zugangsdaten: Contract Number, Password. Besonderheiten: erzeugt einen `parcelNumber`-Barcode, Rücksendetyp "3", Standard-PDF-Format.

### Mondial Relay

SOAP API (`WSI4_CreationEtiquette`). Erforderliche Zugangsdaten: Enseigne, Private Key, Pickup Point. Besonderheiten: `CCC`-Abholmodus (Vom Kunden anvertrautes Paket), MD5-Signatur obligatorisch.

### Chronopost

SOAP API (`shippingMultiParcelV5`). Erforderliche Zugangsdaten: Account Number, Password, Subaccount. Besonderheiten: Product Code `8R` (Relais-Rücksendung), Rücksendemodus `2`.

### UPS

REST API v2403 (`/ship`). Erforderliche Zugangsdaten: Client ID (OAuth2), Client Secret, Shipper Number. Besonderheiten: `ReturnService.Code` = `8` (Electronic Return Label), Standard-Format base64 GIF.

### DPD

REST API (cargonet-Endpoint). Erforderliche Zugangsdaten: Username, Password, Customer ID. Besonderheiten: Basic Auth-Authentifizierung, PDF A6-Format.

## Auflösungen

### Rückerstattung

Verwendet die native `wc_create_refund()`-Funktion von WooCommerce. Erstattet das ursprüngliche Zahlungsmittel, automatischer Restock (konfigurierbar), erstellt eine Erstattungsnotiz in der Bestellung und löst eine native WooCommerce-Bestätigungs-E-Mail aus.

### Bonifiziertes Guthaben

Erstellt automatisch einen WooCommerce-Gutschein:

- **Betrag** = Rücksendetotal + Bonus (konfigurierbarer %, Standard 10%).
- **E-Mail-Beschränkung**: nur durch die E-Mail des Kunden nutzbar.
- **Ablauf**: 6 Monate standardmäßig.
- **Einmalige Verwendung**.

Der Kunde erhält eine E-Mail mit seinem Gutscheincode in großer Schrift.

### Ersatz

Erstellt eine **neue WooCommerce-Bestellung** zu 0 € (kostenlos für den Kunden). Liefer-/Rechnungsadressen werden von der Originalbestellung kopiert, Artikel identisch zu den genehmigten retournierten Artikeln, Anfangsstatus `processing` (Sie versenden wie üblich). Der Kunde erhält eine E-Mail mit der neuen Bestellnummer.

### Automatischer Vorschlag

Die Engine analysiert die Gründe der retournierten Artikel und schlägt die relevanteste Auflösung vor. Konfiguration in **Retouren → Einstellungen → Vorgeschlagene Auflösung pro Grund**. Standardzuordnung:

| Grund | Vorgeschlagene Auflösung |
| --- | --- |
| Beschädigter Artikel | Ersatz |
| Defekter Artikel | Ersatz |
| Falscher Artikel erhalten | Ersatz |
| Entspricht der Beschreibung, passt aber nicht | Rückerstattung |
| Meinung geändert | Bonifiziertes Guthaben |
| Falsche Größe oder Farbe | Bonifiziertes Guthaben |
| Verspätete Lieferung | Rückerstattung |
| Sonstiges | Rückerstattung |

## Anpassung

### Template-Überschreibungen

Alle E-Mail-Templates können über Ihr Theme überschrieben werden. Kopieren Sie die Quelldatei `templates/emails/*.php` nach `yourtheme/dfreturnportal/emails/*.php`.

### Hooks (Actions)

```php
do_action('dfrp_after_return_created', int $returnId, array $return);
do_action('dfrp_status_changed', int $returnId, string $fromStatus, string $toStatus);
do_action('dfrp_label_generated', int $returnId, array $label);
do_action('dfrp_before_resolution', int $returnId, string $resolution);
do_action('dfrp_after_resolution', int $returnId, string $resolution, array $result);
```

### Filter

```php
// Berechtigte Bestellstatus anpassen (Standard: ['completed', 'processing'])
add_filter('dfrp_eligible_order_statuses', function($statuses) {
    $statuses[] = 'on-hold';
    return $statuses;
});

// Rücksendegründe anpassen
add_filter('dfrp_reasons', function($reasons) {
    $reasons[] = [
        'code'          => 'eigener_grund',
        'label'         => 'Mein benutzerdefinierter Grund',
        'require_photo' => false,
    ];
    return $reasons;
});

// Mein-Konto-Endpoint-Slug anpassen (Standard: 'returns')
add_filter('dfrp_myaccount_endpoint', function() {
    return 'meine-retouren';
});

// Mein-Konto-Menü-Label anpassen
add_filter('dfrp_myaccount_menu_label', function() {
    return 'Meine Retouren';
});

// Benutzerdefinierten Versanddienstleister hinzufügen
add_filter('dfrp_register_carriers', function($carriers) {
    $carriers[] = new MeinEigenerVersanddienstleister();
    return $carriers;
});
```

### Saubere Deinstallation

Standardmäßig **behält** die Deinstallation die Daten (Tabellen und Optionen). Um alles bei der Deinstallation zu löschen, fügen Sie in `wp-config.php` hinzu:

```php
define('DFRP_DELETE_DATA_ON_UNINSTALL', true);
```

## REST API

Alle Endpoints befinden sich unter dem Namespace `dfrp/v1`. Basis-URL: `https://ihresite.com/wp-json/dfrp/v1/`.

### Öffentliche Endpoints

| Endpoint | Methode | Beschreibung |
| --- | --- | --- |
| `/lookup` | POST | Bestellung anhand Nummer + E-Mail suchen. |
| `/create` | POST | Neuen Rücksendeantrag erstellen. |
| `/track` | POST | Eine RMA per Code + E-Mail verfolgen. |
| `/upload-photo` | POST | Belegfoto hochladen (multipart). |

### Eingeloggte Kunden-Endpoints

| Endpoint | Methode | Beschreibung |
| --- | --- | --- |
| `/my-orders` | GET | Liste der berechtigten Bestellungen des eingeloggten Kunden. |

### Admin-Endpoints (Capability `manage_woocommerce`)

| Endpoint | Methode | Beschreibung |
| --- | --- | --- |
| `/admin/returns` | GET | Paginierte Liste mit Filtern. |
| `/admin/returns/{id}` | GET | Detail einer Retoure. |
| `/admin/returns/{id}/transition` | POST | Status ändern. |
| `/admin/returns/{id}/inspect-item` | POST | Inspektionsergebnis eines Artikels. |
| `/admin/returns/{id}/resolve` | POST | Eine Auflösung anwenden. |
| `/admin/returns/{id}/regenerate-label` | POST | Label regenerieren. |

## Fehlerbehebung

### Das Portal zeigt unendlich "Laden..." an

- Prüfen Sie die Browser-Konsole (F12) — Sie sollten `[Return Portal] script frontend.js ausgeführt` sehen.
- Falls nichts erscheint, blockiert ein Sicherheits-Plugin (Wordfence, Sucuri, NinjaFirewall) das Inline-Skript. Deaktivieren Sie es vorübergehend zum Testen.
- Prüfen Sie auch JS-Optimierer (WP Rocket "Delay JS", Autoptimize, Cloudflare Rocket Loader) — das Plugin gibt bereits die nötigen Opt-out-Attribute aus, aber sehr aggressive Konfigurationen können dennoch blockieren.

### Der "Retouren"-Tab erscheint nicht im Mein Konto

Gehen Sie zu **Einstellungen → Permalinks** und klicken Sie auf "Änderungen speichern" (ohne etwas zu ändern). Das zwingt WordPress, die Rewrite-Regeln neu zu generieren.

### Fehler "Constant DFRP_VERSION already defined"

Der Plugin-Ordner ist dupliziert. Prüfen Sie:

```bash
ls -la wp-content/plugins/ | grep dfreturnportal
```

Löschen Sie doppelte Kopien (z.B. `dfreturnportal-old/`, `dfreturnportal-1/`).

### Der Kunde erhält keine E-Mails

- Prüfen Sie, ob der E-Mail-Versand grundsätzlich funktioniert.
- Konfigurieren Sie einen ordentlichen SMTP (WP Mail SMTP, FluentSMTP).
- Prüfen Sie die Spam-Logs der Empfänger-Domain.

### Das PDF-Label ist leer oder beschädigt

- Prüfen Sie, ob die Rücksendeadresse vollständig ausgefüllt ist.
- Für API-Versanddienstleister validieren Sie die Zugangsdaten zuerst im Testmodus.
- Prüfen Sie die PHP-Logs (`/wp-content/debug.log`, wenn `WP_DEBUG_LOG` aktiv ist).

## FAQ

**Benötigt das Plugin ein Versanddienstleister-Abonnement?**
Nein. Der **Manuell**-Modus generiert einen nativen PDF-Beleg ohne API-Abhängigkeit. API-Modi (Colissimo usw.) sind optional.

**HPOS (High-Performance Order Storage) kompatibel?**
Ja, vollständig. Das Plugin deklariert seine Kompatibilität beim WooCommerce-Start.

**Cart/Checkout Blocks kompatibel?**
Ja.

**Werden Produktvariationen unterstützt?**
Ja, jede Variation wird als eigener Artikel behandelt.

**Und virtuelle oder herunterladbare Produkte?**
Diese werden automatisch von Retouren ausgeschlossen.

**Kann der Kunde eine Bestellung teilweise retournieren?**
Ja. Die Berechtigung berücksichtigt bereits zurückgegebene Mengen über vorherige RMAs.

**Mehrsprachig?**
Das Plugin ist übersetzungsbereit (Text Domain `dfreturnportal`, `.pot`-Datei mitgeliefert). Kompatibel mit WPML, Polylang, TranslatePress.

**Werden Kundenfotos sicher gespeichert?**
Ja, in der WordPress-Medienbibliothek mit `.htaccess`-Regeln, die Verzeichnisauflistung verhindern.