Return Portal + Auto-Label — Vollständige Dokumentation

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

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.

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, 10×15) 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)

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

// 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:

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:

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.