Return Portal + Auto-Label: volledige documentatie

Versie: 1.0.7
Compatibiliteit: WordPress 6.2+ • WooCommerce 8.0+ • PHP 8.0+ • HPOS en Cart/Checkout Blocks

Overzicht

Return Portal + Auto-Label automatiseert de volledige levenscyclus van een productretour voor uw WooCommerce-winkel:

• Aan klantzijde: de klant vraagt zijn retour aan zonder contact met de klantenservice, selecteert zijn artikelen, kiest een reden en ontvangt meteen zijn PDF-etiket.
• Aan beheerderszijde: een dashboard met tijdlijn, inspectie per regel, een volledig activiteitenlogboek en automatische afhandeling.
• 6 vervoerders: Handmatig (ingebouwde PDF), Colissimo, Mondial Relay, Chronopost, UPS en DPD.
• 3 afhandelingen: terugbetaling via WooCommerce zelf, tegoed met bonus (plus X procent) of automatische vervanging.

Statussen van een retour

Een retour doorloopt tot 7 stappen:

Status	Beschrijving
requested	Aanvraag ontvangen, wacht op goedkeuring
approved	Goedgekeurd door de beheerder (of automatisch onder de drempel)
label_sent	Etiket gegenereerd en naar de klant gestuurd
in_transit	Pakket onderweg
received	Pakket ontvangen in het magazijn
inspecting	Inspectie van de artikelen bezig
resolved	Afhandeling toegepast (terugbetaling, tegoed of vervanging)

Er zijn twee extra eindstatussen: rejected (geweigerd) en cancelled (geannuleerd).

Installatie

Methode 1: via het WordPress-beheer

1. Download de ZIP dfreturnportal.zip.
2. Ga in WordPress naar Plugins → Nieuwe plugin → Plugin uploaden.
3. Selecteer de ZIP en klik op Nu installeren.
4. Activeer de plugin.

Methode 2: via FTP of SSH

cd wp-content/plugins/
unzip dfreturnportal.zip
# Activeer daarna vanuit het WordPress-beheer

Controles na de installatie

• Er verschijnt een menu Retouren in de WordPress-zijbalk.
• Er wordt automatisch een endpoint /my-account/retours/ aangemaakt.
• De eigen tabellen wp_dfrp_returns, wp_dfrp_return_items, wp_dfrp_history en wp_dfrp_attachments worden aangemaakt.

Eerste configuratie

Ga naar Retouren → Instellingen.

Algemeen

Instelling	Beschrijving
Retourtermijn	Het aantal dagen na de bestelling waarin een retour is toegestaan. Standaard 30 dagen.
Pagina van het klantportaal	De WordPress-pagina waarop de shortcode [dfrp_portal] wordt getoond. Optioneel als u alleen het endpoint in Mijn account gebruikt.
Beheerdersmeldingen	Het e-mailadres dat meldingen van nieuwe aanvragen ontvangt. Standaard de sitebeheerder.

Vervoerder

Kies de actieve vervoerder uit de 6 beschikbare. U kunt ook het etiketformaat instellen (A4, A5, A6, 10×15).

Retouradres

Vul het fysieke adres in waarnaar de retourpakketten worden gestuurd. Dit is verplicht om etiketten te kunnen genereren. Velden: bedrijf, straat, plaats, postcode, land (ISO-code van 2 letters), telefoon en e-mail.

Inloggegevens van de vervoerders

Voor elke vervoerder met een API (Colissimo, Mondial Relay en de andere) bevat een uitklapbaar blok de vereiste gegevens. Vul alleen die van de vervoerder in die u gebruikt.

Afhandeling

Instelling	Beschrijving
Bonus op tegoed (procent)	Het percentage dat bij het terugbetaalde bedrag komt wanneer de klant voor tegoed met bonus kiest. Standaard 10 procent.
Drempel voor automatische goedkeuring	Onder dit bedrag (in de valuta van de winkel) worden aanvragen automatisch goedgekeurd en wordt het etiket zonder tussenkomst van een beheerder aangemaakt. Zet 0 om dit uit te schakelen.
Voorgestelde afhandeling per reden	Kies voor elke reden (standaard 8 redenen) de voorgestelde afhandeling: terugbetaling, tegoed met bonus of vervanging.

Uitsluitingen

• Uitgesloten categorieën: WooCommerce-ID’s gescheiden door komma’s. Producten uit die categorieën komen nooit in aanmerking voor retour.
• Uitgesloten SKU’s: één SKU per regel. Idem.

Klantervaring

Via de pagina Mijn account (ingelogde klanten)

Dit is de eenvoudigste en meest gebruikte weg. Het tabblad Retouren verschijnt automatisch in het menu /my-account/, naast “Bestellingen”, “Adressen” en de rest.

De klant klikt op Retouren, ziet de lijst met zijn in aanmerking komende bestellingen (zonder e-mailadres of nummer in te typen), klikt op Retour starten bij de betreffende bestelling, selecteert de artikelen, kiest per artikel een reden en een aantal, voegt eventueel foto’s toe (als de reden dat vereist), kiest zijn voorkeursafhandeling en ontvangt meteen een RMA-nummer (bijvoorbeeld RMA-20260523-A1B2C3) plus een bevestigingsmail.

Via een publieke pagina (niet-ingelogde klanten)

Maak een WordPress-pagina aan en voeg de shortcode in:

[dfrp_portal]

De klant moet zijn bestelnummer en zijn e-mailadres invullen om zich te identificeren. De rest van het traject is identiek.

Een bestaande aanvraag volgen

Op de publieke portaalpagina staat een blok “Een bestaande aanvraag volgen”, waarmee gastklanten de stand van hun RMA kunnen nakijken (status, trackingnummer van de vervoerder, link naar het etiket).

De shortcode aanpassen

[dfrp_portal title="Retouraanvraag" context="page"]

Attribuut	Waarden	Beschrijving
title	vrije tekst	Titel van het portaal (zelden visueel gebruikt).
context	page of myaccount	Legt de context vast. Met myaccount wordt de opzoekstap voor ingelogde gebruikers overgeslagen.

Workflow voor de beheerder

Dashboard

Bereikbaar via Retouren → Dashboard. Het bevat 9 gekleurde statistiekkaarten (aantal per status, aanklikbaar om de lijst te filteren), de 10 laatste RMA’s met snelle toegang tot het detail, en een balk met de URL van het klantportaal met een knop “Kopiëren” om die te delen.

Lijst met aanvragen

Bereikbaar via Retouren → Alle aanvragen. Een tabel met filters op status, vrij zoeken (RMA, e-mailadres van de klant, bestelnummer) en paginering (20 per pagina).

Detailpagina van een aanvraag

Onderdelen:

1. Kop: RMA-code, statusbadge en terug naar de lijst.
2. Tijdlijn: 7 gekleurde punten die de voortgang visueel tonen.
3. Terug te sturen artikelen: een tabel met product, SKU, aantal, stukprijs, reden en inspectie per artikel (keuzelijst Conform / Deels / Geweigerd, beschikbaar vanaf de status received).
4. Klantfoto’s: een galerij als de klant bewijsmateriaal heeft geüpload.
5. Activiteitenlogboek: de volledige chronologische historiek.
6. Informatie: e-mailadres van de klant, link naar de bestelling, voorkeursafhandeling en klantnotitie.
7. Retouretiket: vervoerder, trackingnummer, knop om de PDF te downloaden en knop om opnieuw te genereren.
8. Acties: knoppen “Ga naar: [volgende status]” volgens de state machine.
9. Afhandelen (zichtbaar bij de status received of inspecting): keuzelijst met afhandelingen en de knop “Toepassen”.

Mogelijke overgangen

De state machine verhindert ongeldige overgangen:

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

De statussen resolved, rejected en cancelled zijn eindstatussen.

Automatische goedkeuring

Hebt u een drempel voor automatische goedkeuring ingesteld (bijvoorbeeld 50 euro), dan gaat elke aanvraag met een totaalbedrag onder of gelijk aan die drempel automatisch van requested naar approved, wordt het etiket meteen aangemaakt en naar de klant gestuurd, en hoeft een beheerder niets te doen.

Ondersteunde vervoerders

Handmatig (zonder API)

Ideaal om mee te beginnen. Genereert een ingebouwde PDF-bon met QR-code, zonder enige externe API-afhankelijkheid. Geen configuratie nodig, gratis, werkt meteen. Beperking: geen automatische tracking. Gebruik: de klant drukt de bon af, u legt hem bij de oorspronkelijke zending of hij plakt hem erop voor een klassieke postretour.

Colissimo (La Poste)

Officiële REST API (dienst Sls generateLabel). Vereiste gegevens: contractnummer en wachtwoord. Bijzonderheden: genereert een barcode parcelNumber, retourtype “3” (retour met correspondentie), standaard PDF-formaat.

Mondial Relay

SOAP API (WSI4_CreationEtiquette). Vereiste gegevens: enseigne, private key en afhaalpunt. Bijzonderheden: ophaalmodus CCC (Colis Confié Client), MD5-handtekening verplicht.

Chronopost

SOAP API (shippingMultiParcelV5). Vereiste gegevens: accountnummer, wachtwoord en subaccount. Bijzonderheden: productcode 8R (retour via afhaalpunt), retourmodus 2.

UPS

REST API v2403 (/ship). Vereiste gegevens: Client ID (OAuth2), Client Secret en Shipper Number. Bijzonderheden: ReturnService.Code is 8 (Electronic Return Label), standaard GIF in base64.

DPD

REST API (cargonet-endpoint). Vereiste gegevens: gebruikersnaam, wachtwoord en klantnummer. Bijzonderheden: authenticatie met Basic Auth, PDF-formaat A6.

Afhandelingen

Terugbetaling

Gebruikt de ingebouwde functie wc_create_refund() van WooCommerce. Crediteert de oorspronkelijke betaalmethode, zet de artikelen automatisch terug in voorraad (instelbaar), maakt een terugbetalingsnotitie bij de bestelling aan en genereert een ingebouwde WooCommerce-bevestigingsmail.

Tegoed met bonus (store credit)

Maakt automatisch een WooCommerce-coupon aan:

• Bedrag: het retourtotaal plus de bonus (instelbaar percentage, standaard 10 procent).
• Beperking op e-mailadres: alleen bruikbaar door het e-mailadres van de klant.
• Vervaldatum: standaard 6 maanden.
• Eenmalig te gebruiken.

De klant ontvangt een e-mail met zijn couponcode groot in beeld.

Vervanging

Maakt een nieuwe WooCommerce-bestelling aan van 0 euro (gratis voor de klant). De verzend- en factuuradressen worden uit de oorspronkelijke bestelling overgenomen, de artikelen komen overeen met de conform bevonden geretourneerde artikelen en de beginstatus is processing (u verzendt gewoon). De klant ontvangt een e-mail met het nummer van de nieuwe bestelling.

Automatisch voorstel

De motor analyseert de redenen van de geretourneerde artikelen en stelt de meest passende afhandeling voor. Instelbaar via Retouren → Instellingen → Voorgestelde afhandeling per reden. Standaardkoppeling:

Reden	Voorgestelde afhandeling
Beschadigd artikel	Vervanging
Defect artikel	Vervanging
Verkeerd artikel ontvangen	Vervanging
Komt overeen met de beschrijving maar bevalt niet	Terugbetaling
Van gedachten veranderd	Tegoed met bonus
Verkeerde maat of kleur	Tegoed met bonus
Late levering	Terugbetaling
Andere	Terugbetaling

Aanpassen

Templates overschrijven

Alle e-mailtemplates kunt u via uw thema overschrijven. Kopieer het bronbestand templates/emails/*.php naar uwthema/dfreturnportal/emails/*.php.

Hooks (acties)

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);

Filters

// De in aanmerking komende bestelstatussen aanpassen (standaard: ['completed', 'processing'])
add_filter('dfrp_eligible_order_statuses', function($statuses) {
    $statuses[] = 'on-hold';
    return $statuses;
});

// De retourredenen aanpassen
add_filter('dfrp_reasons', function($reasons) {
    $reasons[] = [
        'code'          => 'custom_motif',
        'label'         => 'Mijn eigen reden',
        'require_photo' => false,
    ];
    return $reasons;
});

// De slug van het endpoint in Mijn account aanpassen (standaard: 'returns')
add_filter('dfrp_myaccount_endpoint', function() {
    return 'mijn-retouren';
});

// Het label van het menu-item in Mijn account aanpassen
add_filter('dfrp_myaccount_menu_label', function() {
    return 'Mijn productretouren';
});

// Een eigen vervoerder toevoegen
add_filter('dfrp_register_carriers', function($carriers) {
    $carriers[] = new MijnEigenVervoerder();
    return $carriers;
});

Netjes verwijderen

Standaard behoudt het verwijderen de gegevens (tabellen en opties). Om bij het verwijderen alles op te ruimen, voegt u dit toe aan wp-config.php:

define('DFRP_DELETE_DATA_ON_UNINSTALL', true);

REST API

Alle endpoints staan onder de namespace dfrp/v1. Basis-URL: https://uwsite.com/wp-json/dfrp/v1/.

Publieke endpoints

Endpoint	Methode	Beschrijving
/lookup	POST	Zoekt een bestelling op nummer plus e-mailadres.
/create	POST	Maakt een nieuwe retouraanvraag aan.
/track	POST	Volgt een RMA via code plus e-mailadres.
/upload-photo	POST	Uploadt een bewijsfoto (multipart).

Endpoints voor ingelogde klanten

Endpoint	Methode	Beschrijving
/my-orders	GET	Toont de in aanmerking komende bestellingen van de ingelogde klant.

Beheerdersendpoints (capability manage_woocommerce)

Endpoint	Methode	Beschrijving
/admin/returns	GET	Gepagineerde lijst met filters.
/admin/returns/{id}	GET	Detail van een retour.
/admin/returns/{id}/transition	POST	De status wijzigen.
/admin/returns/{id}/inspect-item	POST	Inspectieresultaat van een artikel.
/admin/returns/{id}/resolve	POST	Een afhandeling toepassen.
/admin/returns/{id}/regenerate-label	POST	Het etiket opnieuw genereren.

Probleemoplossing

Het portaal blijft “Laden…” tonen

• Controleer de browserconsole (F12): u hoort [Return Portal] script frontend.js exécuté te zien.
• Verschijnt er niets, dan blokkeert een beveiligingsplugin (Wordfence, Sucuri, NinjaFirewall) het inline script. Schakel die tijdelijk uit om te testen.
• Controleer ook de JS-optimalisatoren (WP Rocket “Delay JS”, Autoptimize, Cloudflare Rocket Loader). De plugin stuurt de nodige opt-out-attributen al mee, maar zeer agressieve configuraties kunnen het toch blokkeren.

Het tabblad “Retouren” verschijnt niet in Mijn account

Ga naar Instellingen → Permalinks en klik op “Wijzigingen opslaan” (zonder iets te wijzigen). Zo dwingt u WordPress om de rewrite rules opnieuw op te bouwen.

Foutmelding “Constant DFRP_VERSION already defined”

De pluginmap staat er dubbel in. Controleer:

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

Verwijder de dubbele kopieën (bijvoorbeeld dfreturnportal-old/ of dfreturnportal-1/).

De klant ontvangt de e-mails niet

• Controleer of het versturen van e-mails in het algemeen werkt.
• Stel een degelijke SMTP in (WP Mail SMTP, FluentSMTP).
• Controleer de spamlogs van het ontvangende domein.

Het PDF-etiket is leeg of beschadigd

• Controleer of het retouradres volledig is ingevuld.
• Test bij vervoerders met een API eerst de inloggegevens in testmodus.
• Raadpleeg de PHP-logs (/wp-content/debug.log als WP_DEBUG_LOG actief is).

Veelgestelde vragen

Heb ik een abonnement bij een vervoerder nodig?
Nee. De modus Handmatig genereert een ingebouwde PDF-bon zonder enige API-afhankelijkheid. De API-modi (Colissimo en de rest) zijn optioneel.

Compatibel met HPOS (High-Performance Order Storage)?
Ja, volledig. De plugin verklaart haar compatibiliteit bij het opstarten van WooCommerce.

Compatibel met Cart/Checkout Blocks?
Ja.

Worden productvariaties ondersteund?
Ja, elke variatie wordt als een apart artikel behandeld.

En virtuele of downloadbare producten?
Die worden automatisch van retour uitgesloten.

Kan de klant een bestelling gedeeltelijk retourneren?
Ja. Bij de beoordeling wordt rekening gehouden met de aantallen die via een eerdere RMA al zijn geretourneerd.

Meertalig?
De plugin is klaar voor vertaling (text domain dfreturnportal, met meegeleverd .pot-bestand). Compatibel met WPML, Polylang en TranslatePress.

Worden de klantfoto’s veilig opgeslagen?
Ja, in de WordPress-mediabibliotheek, met .htaccess-regels die directory listing verhinderen.