# Return Portal + Auto-Label: volledige documentatie

> Selfservice-retourportaal voor klanten, automatisch gegenereerde retouretiketten bij meerdere vervoerders, inspectieworkflow voor beheerders en een afhandelingsmotor (terugbetaling, tegoed met bonus, vervanging) voor WooCommerce. Versie: 1.0.7 Compatibiliteit: WordPress 6.2+ • WooCommerce 8.0+…

- Pagina: <https://www.datafirefly.com/nl/documentation/dfreturnportal/>
- Taal: nl
- Bijgewerkt op: 2026-08-19
- Andere talen: [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), [de](https://www.datafirefly.com/de/documentation/dfreturnportal/index.md), [it](https://www.datafirefly.com/it/documentation/dfreturnportal/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfreturnportal/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfreturnportal/index.md)
- Index: <https://www.datafirefly.com/nl/documentation/llms.txt>

Selfservice-retourportaal voor klanten, automatisch gegenereerde retouretiketten bij meerdere vervoerders, inspectieworkflow voor beheerders en een afhandelingsmotor (terugbetaling, tegoed met bonus, vervanging) voor WooCommerce.

**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

```bash
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.

Verschijnt het tabblad "Retouren" niet in Mijn account, ga dan naar **Instellingen → Permalinks** en klik op "Wijzigingen opslaan" om de rewrite rules te verversen.

## 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, 10x15).

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

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

### Filters

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

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

```bash
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.