AI Returns Predictor — Complete handleiding

AI Returns Predictor analyseert elke bestelling direct na de validatie en kent haar een retourrisicoscore toe van 0 tot 100, ingedeeld in drie niveaus (Laag, Gemiddeld, Hoog). De score wordt rechtstreeks op de bestelpagina getoond, met het detail van de factoren, en uw logistiek wordt vóór verzending per e-mail gewaarschuwd wanneer een bestelling de hoogrisicodrempel overschrijdt. Deze handleiding behandelt de installatie, de configuratie, de werking van de scoringengine en de optionele AI-laag.

Installatie

1. Download het archief dfreturnspredictor.zip via uw DataFirefly-account.
2. PrestaShop-backoffice → Modules → Een module uploaden → verstuur de ZIP.
3. Bij de installatie maakt de module haar tabel df_return_risk aan, registreert haar hooks en voegt het tabblad Verzending → Returns Predictor toe.

Algemene configuratie

Ga naar Modules → AI Returns Predictor → Configureren.

Risicodrempels

Twee drempels bepalen het niveau dat elke bestelling op basis van haar score krijgt:

• Drempel Gemiddeld (standaard 40): score vanaf welke een bestelling naar risico Gemiddeld gaat.
• Drempel Hoog (standaard 70): score vanaf welke een bestelling naar risico Hoog gaat en de logistieke waarschuwing triggert.

Onder de drempel Gemiddeld wordt de bestelling als Laag geclassificeerd. De drempels moeten voldoen aan de regel 1 ≤ Gemiddeld < Hoog ≤ 100.

Categorieën met hoog retourpercentage

Vul de lijst in met de id’s van categorieën die bekendstaan om frequente retouren (mode, textiel, schoenen…), gescheiden door komma’s. Producten uit deze categorieën verhogen de score van de bestelling.

Logistieke waarschuwing

• E-mailadres logistieke waarschuwing: adres dat wordt genotificeerd wanneer een bestelling de hoogrisicodrempel overschrijdt. Laat het veld leeg om e-mailwaarschuwingen uit te schakelen.

AI-laag (optioneel)

De module werkt zonder AI dankzij haar heuristische engine. U kunt een optionele AI-laag inschakelen om de score te verfijnen en een korte uitleg te genereren.

• AI-verfijning inschakelen: indien uitgeschakeld wordt geen enkele externe aanroep gedaan.
• Mistral API-sleutel: aan serverzijde opgeslagen, nooit blootgesteld aan de frontoffice.
• Mistral-model: bijvoorbeeld mistral-small-latest.

Hoe de score wordt berekend

De heuristische engine combineert zes verklaarbare factoren, elk met een gemaximeerd aantal punten. Het totaal is begrensd tussen 0 en 100.

• Retourgeschiedenis van de klant (0–30): verhouding tussen het aantal eerdere retouren en het aantal geldige bestellingen van de klant.
• Bracketing van maten / varianten (0–25): hetzelfde product besteld in meerdere varianten (maten, kleuren), een teken van pasintentie.
• Winkelwagenwaarde (0–15): bedrag van de bestelling afgezet tegen de gemiddelde winkelwagen van de winkel.
• Risicocategorieën (0–20): aanwezigheid van producten in de door u opgegeven categorieën.
• Nieuwe klant (0–8): geen bruikbare aankoopgeschiedenis.
• Winkelwagengrootte (0–10): aantal verschillende artikelen in de bestelling.

Het risicopaneel op de bestelling

Op elke bestelpagina (hook displayAdminOrderSide) toont een paneel “Retourrisico”:

• de score op 100 en het gekleurde niveau (Laag / Gemiddeld / Hoog);
• het detail van de bijdragende factoren met hun punten;
• de AI-uitleg, indien van toepassing;
• een knop Herberekenen die de scoring via AJAX opnieuw start zonder de pagina te herladen.

De score wordt automatisch berekend bij de validatie van de bestelling (hook actionValidateOrder) en ververst bij statuswijzigingen (hook actionOrderStatusPostUpdate).

Het logistieke dashboard

Het tabblad Verzending → Returns Predictor toont alle gescoorde bestellingen, gesorteerd op aflopende score. U vindt er de referentie, de klant, de status, de score, het niveau en de waarschuwingsindicator. Filter op niveau om de bestellingen met hoog risico te isoleren vóór het klaarmaken van de pakketten. De actie “Bekijken” opent direct de betreffende bestelpagina.

De e-mailwaarschuwing

Wanneer een bestelling bij haar aanmaak de hoogrisicodrempel overschrijdt, vertrekt een samenvattende e-mail naar het geconfigureerde logistieke adres: bestelreferentie, score, niveau, klant, bijdragende factoren en eventuele AI-notitie. De e-mailsjablonen worden geleverd in het Frans en het Engels, en de verzending houdt rekening met de taal van de klant en de winkel van herkomst van de bestelling.

Compatibiliteit en technische notities

• PrestaShop 8.0 tot 9.x, multistore en meertalig.
• Legacy-admincontroller (geen Symfony-controller) voor PS8/PS9-compatibiliteit.
• Backoffice AJAX-endpoint via het 4e argument van getAdminLink(); JSON-rendering via een aparte methode.
• Tabel df_return_risk: één record per bestelling, met score, niveau, factoren (JSON) en waarschuwingsindicator.
• Optionele AI-laag: alleen de voor de berekening noodzakelijke gegevens worden naar Mistral verstuurd; automatische fallback naar de heuristiek.

FAQ en probleemoplossing

Het risicopaneel verschijnt niet op de bestelpagina. Controleer of de module aan de hook displayAdminOrderSide is gekoppeld en of de bestelling na de installatie is aangemaakt. Gebruik de knop “Herberekenen” om de scoring te forceren.

Er komt geen e-mailwaarschuwing binnen. Controleer of het waarschuwingsadres is ingevuld en geldig is, en of de bestelling de drempel Hoog daadwerkelijk overschrijdt. De waarschuwing wordt slechts één keer per bestelling verstuurd.

De AI geeft geen uitleg terug. Controleer de API-sleutel en de naam van het Mistral-model. De module valt hoe dan ook terug op de heuristische score; er gaat geen enkele score verloren.

Worden alle nieuwe klanten als risicovol beschouwd? Nee. Het ontbreken van een geschiedenis voegt slechts een lichte verhoging toe; de score hangt vooral af van de andere factoren (bracketing, categorieën, winkelwagenwaarde).