Return Portal + Auto-Label — Documentation complète

Version : 1.0.7
Compatibilité : WordPress 6.2+ • WooCommerce 8.0+ • PHP 8.0+ • HPOS et Blocks Cart/Checkout

Vue d’ensemble

Return Portal + Auto-Label automatise tout le cycle de vie d’un retour produit pour votre boutique WooCommerce :

• Côté client : le client demande son retour sans contact support, sélectionne ses articles, choisit un motif et reçoit immédiatement son étiquette PDF.
• Côté admin : tableau de bord avec timeline, inspection ligne par ligne, journal d’activité complet et résolution automatique.
• 6 transporteurs : Manuel (PDF natif), Colissimo, Mondial Relay, Chronopost, UPS, DPD.
• 3 résolutions : remboursement WooCommerce natif, avoir bonifié (+X%) ou remplacement automatique.

Statuts d’un retour

Un retour parcourt jusqu’à 7 étapes :

Statut	Description
requested	Demande reçue, en attente de validation
approved	Approuvée par l’admin (ou auto-approuvée sous seuil)
label_sent	Étiquette générée et envoyée au client
in_transit	Colis en cours d’acheminement
received	Colis réceptionné en entrepôt
inspecting	Inspection des articles en cours
resolved	Résolution appliquée (remboursement / avoir / remplacement)

Deux statuts terminaux supplémentaires : rejected (refus) et cancelled (annulation).

Installation

Méthode 1 — Via l’admin WordPress

1. Téléchargez le ZIP dfreturnportal.zip.
2. Dans WordPress, allez dans Extensions → Ajouter → Téléverser une extension.
3. Sélectionnez le ZIP, cliquez Installer maintenant.
4. Activez l’extension.

Méthode 2 — Via FTP/SSH

cd wp-content/plugins/
unzip dfreturnportal.zip
# Activez ensuite depuis l'admin WordPress

Vérifications post-installation

• Un menu Retours apparaît dans la barre latérale WordPress.
• Un endpoint /mon-compte/retours/ est créé automatiquement.
• Les tables custom wp_dfrp_returns, wp_dfrp_return_items, wp_dfrp_history, wp_dfrp_attachments sont créées.

Configuration initiale

Allez dans Retours → Réglages.

Général

Réglage	Description
Fenêtre d’éligibilité	Nombre de jours après la commande pendant lesquels un retour est autorisé. Défaut : 30 jours.
Page du portail client	Page WordPress où sera affiché le shortcode [dfrp_portal]. Optionnel si vous utilisez uniquement l’endpoint Mon Compte.
Notifications admin	Adresse e-mail qui recevra les notifications de nouvelles demandes. Défaut : admin du site.

Transporteur

Sélectionnez le transporteur actif parmi les 6 disponibles. Vous pouvez aussi configurer le format d’étiquette (A4, A5, A6, 10×15).

Adresse de retour

Renseignez l’adresse physique où les colis retours seront expédiés. Obligatoire pour générer les étiquettes. Champs : Société, Rue, Ville, Code postal, Pays (code ISO 2 lettres), Téléphone, E-mail.

Identifiants transporteurs

Pour chaque transporteur API (Colissimo, Mondial Relay, etc.), un bloc dépliable contient les identifiants requis. Renseignez uniquement ceux du transporteur que vous utilisez.

Résolution

Réglage	Description
Bonus avoir (%)	Pourcentage ajouté au montant remboursé lorsque le client choisit l’avoir bonifié. Défaut : 10%.
Seuil auto-approbation	Sous ce montant (devise du shop), les demandes sont approuvées automatiquement et l’étiquette est générée sans intervention admin. Mettre 0 pour désactiver.
Résolution proposée par motif	Pour chaque motif (8 motifs par défaut), choisissez la résolution proposée : remboursement / avoir bonifié / remplacement.

Exclusions

• Catégories exclues : IDs WooCommerce séparés par virgules. Les produits de ces catégories ne seront jamais éligibles au retour.
• SKUs exclus : un SKU par ligne. Idem.

Expérience client

Via la page Mon Compte (clients connectés)

Le plus simple et le plus utilisé. L’onglet Retours s’affiche automatiquement dans le menu /mon-compte/ à côté de « Commandes », « Adresses », etc.

Le client clique sur Retours, voit la liste de ses commandes éligibles (pas besoin de saisir email/numéro), clique Démarrer un retour sur la commande concernée, sélectionne les articles, choisit un motif et une quantité par article, ajoute éventuellement des photos (si le motif l’exige), choisit sa résolution préférée et reçoit immédiatement un numéro de RMA (ex : RMA-20260523-A1B2C3) plus un email de confirmation.

Via une page publique (clients non connectés)

Créez une page WordPress, insérez le shortcode :

[dfrp_portal]

Le client devra saisir son numéro de commande + son e-mail pour s’authentifier. Le reste du flow est identique.

Suivi d’une demande existante

Sur la page publique du portail, un bloc « Suivre une demande existante » permet aux clients invités de vérifier l’état de leur RMA (statut, numéro de suivi transporteur, lien vers l’étiquette).

Personnalisation du shortcode

[dfrp_portal title="Demande de retour" context="page"]

Attribut	Valeurs	Description
title	texte libre	Titre du portail (rarement utilisé visuellement).
context	page ou myaccount	Force le contexte. myaccount saute l’étape lookup pour les utilisateurs connectés.

Workflow administrateur

Tableau de bord

Accessible via Retours → Tableau de bord. Contient 9 cartes de statistiques colorées (compte par statut, cliquables pour filtrer la liste), les 10 derniers RMA avec accès rapide au détail, et un bandeau URL du portail client avec bouton « Copier » pour partager.

Liste des demandes

Accessible via Retours → Toutes les demandes. Table avec filtres par statut, recherche libre (RMA, email client, numéro de commande) et pagination (20 par page).

Page détail d’une demande

Composants :

1. En-tête : code RMA + badge statut + retour à la liste.
2. Timeline : 7 dots colorés montrant la progression visuelle.
3. Articles à retourner : table avec produit, SKU, quantité, PU, motif, et inspection par article (déroulant Conforme / Partiellement / Refusé — activé après statut received).
4. Photos client : galerie si le client a uploadé des justificatifs.
5. Journal d’activité : historique chronologique complet.
6. Informations : email client, lien commande, préférence de résolution, note client.
7. Étiquette retour : transporteur, numéro de suivi, bouton télécharger PDF, bouton régénérer.
8. Actions : boutons « Passer à : [statut suivant] » selon la state machine.
9. Résoudre (visible si statut received ou inspecting) : sélecteur de résolution + bouton « Appliquer ».

Transitions possibles

La state machine empêche les transitions invalides :

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

Les statuts resolved, rejected et cancelled sont terminaux.

Auto-approbation

Si vous avez configuré un seuil d’auto-approbation (ex : 50 €), toute demande dont le montant total est inférieur ou égal au seuil est automatiquement passée de requested à approved, l’étiquette est générée immédiatement et envoyée au client, sans intervention admin requise.

Transporteurs supportés

Manuel (sans API)

Idéal pour démarrer. Génère un bordereau PDF natif avec QR code, sans aucune dépendance API externe. Zéro configuration, gratuit, fonctionne immédiatement. Limite : pas de suivi automatique. Usage : le client imprime, vous le mettez dans le colis lors de l’expédition initiale ou il le scotche dessus pour le retour postal classique.

Colissimo (La Poste)

API REST officielle (Service Sls generateLabel). Identifiants requis : Contract Number, Password. Particularités : génère un code-barre parcelNumber, type retour « 3 » (retour Avec correspondance), format PDF par défaut.

Mondial Relay

API SOAP (WSI4_CreationEtiquette). Identifiants requis : Enseigne, Private Key, Pickup Point. Particularités : mode de collecte CCC (Colis Confié Client), signature MD5 obligatoire.

Chronopost

API SOAP (shippingMultiParcelV5). Identifiants requis : Account Number, Password, Subaccount. Particularités : Product Code 8R (retour Relais), mode retour 2.

UPS

API REST v2403 (/ship). Identifiants requis : Client ID (OAuth2), Client Secret, Shipper Number. Particularités : ReturnService.Code = 8 (Electronic Return Label), format GIF base64 par défaut.

DPD

API REST (cargonet endpoint). Identifiants requis : Username, Password, Customer ID. Particularités : Authentification Basic Auth, format PDF A6.

Résolutions

Remboursement

Utilise la fonction native wc_create_refund() de WooCommerce. Re-crédite le moyen de paiement initial, restock automatique des articles (configurable), crée une note de remboursement dans la commande et génère un email natif WooCommerce de confirmation.

Avoir bonifié (Store Credit)

Crée automatiquement un coupon WooCommerce :

• Montant = total retour + bonus (% configurable, défaut 10 %).
• Restriction email : utilisable uniquement par l’email du client.
• Expiration : 6 mois par défaut.
• Usage unique.

Le client reçoit un email avec son code coupon en grand.

Remplacement

Crée une nouvelle commande WooCommerce à 0 € (gratuite pour le client). Adresses livraison/facturation copiées de la commande d’origine, articles identiques aux articles retournés conformes, statut initial processing (vous l’expédiez normalement). Le client reçoit un email avec le numéro de la nouvelle commande.

Proposition automatique

Le moteur analyse les motifs des articles retournés et propose la résolution la plus pertinente. Configuration dans Retours → Réglages → Résolution proposée par motif. Mapping par défaut :

Motif	Résolution proposée
Article endommagé	Remplacement
Article défectueux	Remplacement
Mauvais article reçu	Remplacement
Conforme au descriptif mais ne convient pas	Remboursement
Changement d’avis	Avoir bonifié
Taille ou couleur incorrecte	Avoir bonifié
Livraison en retard	Remboursement
Autre	Remboursement

Personnalisation

Override des templates

Tous les templates email sont overridables via votre thème. Copiez le fichier source templates/emails/*.php dans 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);

Filtres

// Personnaliser les statuts de commande éligibles (défaut : ['completed', 'processing'])
add_filter('dfrp_eligible_order_statuses', function($statuses) {
    $statuses[] = 'on-hold';
    return $statuses;
});

// Personnaliser les motifs de retour
add_filter('dfrp_reasons', function($reasons) {
    $reasons[] = [
        'code'          => 'custom_motif',
        'label'         => 'Mon motif personnalisé',
        'require_photo' => false,
    ];
    return $reasons;
});

// Personnaliser le slug de l'endpoint Mon Compte (défaut : 'returns')
add_filter('dfrp_myaccount_endpoint', function() {
    return 'mes-retours';
});

// Personnaliser le label du menu Mon Compte
add_filter('dfrp_myaccount_menu_label', function() {
    return 'Mes retours produits';
});

// Ajouter un transporteur custom
add_filter('dfrp_register_carriers', function($carriers) {
    $carriers[] = new MonTransporteurCustom();
    return $carriers;
});

Désinstallation propre

Par défaut, la désinstallation conserve les données (tables et options). Pour purger entièrement à la désinstallation, ajoutez dans wp-config.php :

define('DFRP_DELETE_DATA_ON_UNINSTALL', true);

API REST

Tous les endpoints sont sous le namespace dfrp/v1. URL de base : https://votresite.com/wp-json/dfrp/v1/.

Endpoints publics

Endpoint	Méthode	Description
/lookup	POST	Recherche une commande par numéro + email.
/create	POST	Crée une nouvelle demande de retour.
/track	POST	Suit un RMA via code + email.
/upload-photo	POST	Upload une photo justificative (multipart).

Endpoints client connecté

Endpoint	Méthode	Description
/my-orders	GET	Liste les commandes éligibles du client connecté.

Endpoints admin (capability manage_woocommerce)

Endpoint	Méthode	Description
/admin/returns	GET	Liste paginée avec filtres.
/admin/returns/{id}	GET	Détail d’un retour.
/admin/returns/{id}/transition	POST	Changer le statut.
/admin/returns/{id}/inspect-item	POST	Résultat d’inspection d’un article.
/admin/returns/{id}/resolve	POST	Appliquer une résolution.
/admin/returns/{id}/regenerate-label	POST	Régénérer l’étiquette.

Dépannage

Le portail affiche « Chargement… » indéfiniment

• Vérifiez la console navigateur (F12) — vous devez voir [Return Portal] script frontend.js exécuté.
• Si rien n’apparaît, un plugin de sécurité (Wordfence, Sucuri, NinjaFirewall) bloque l’inline script. Désactivez temporairement pour tester.
• Vérifiez aussi les optimiseurs JS (WP Rocket « Delay JS », Autoptimize, Cloudflare Rocket Loader) — le plugin émet déjà les attributs opt-out nécessaires, mais certaines configurations agressives peuvent encore bloquer.

L’onglet « Retours » n’apparaît pas dans Mon Compte

Allez dans Réglages → Permaliens et cliquez sur « Enregistrer les modifications » (sans rien changer). Cela force WordPress à régénérer les règles de réécriture.

Erreur « Constant DFRP_VERSION already defined »

Le dossier plugin est dupliqué. Vérifiez :

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

Supprimez les copies en doublon (ex : dfreturnportal-old/, dfreturnportal-1/).

Le client ne reçoit pas les e-mails

• Vérifiez que l’envoi d’e-mails fonctionne globalement.
• Configurez un SMTP propre (WP Mail SMTP, FluentSMTP).
• Vérifiez les logs spam du domaine destinataire.

L’étiquette PDF est vide ou corrompue

• Vérifiez que l’adresse de retour est complètement renseignée.
• Pour les transporteurs API, vérifiez les identifiants en mode test d’abord.
• Consultez les logs PHP (/wp-content/debug.log si WP_DEBUG_LOG est actif).

FAQ

Le plugin nécessite-t-il un abonnement à un transporteur ?
Non. Le mode Manuel génère un bordereau PDF natif sans aucune dépendance API. Les modes API (Colissimo, etc.) sont optionnels.

Compatible HPOS (High-Performance Order Storage) ?
Oui, totalement. Le plugin déclare sa compatibilité au démarrage de WooCommerce.

Compatible Cart/Checkout Blocks ?
Oui.

Les variations produits sont-elles gérées ?
Oui, chaque variation est traitée comme un article distinct.

Et les produits virtuels ou téléchargeables ?
Ils sont automatiquement exclus des retours.

Le client peut-il retourner partiellement une commande ?
Oui. L’éligibilité tient compte des quantités déjà retournées par RMA précédent.

Multi-langue ?
Le plugin est prêt pour la traduction (Text Domain dfreturnportal, fichier .pot fourni). Compatible WPML, Polylang, TranslatePress.

Les photos client sont-elles stockées de manière sécurisée ?
Oui, dans la médiathèque WordPress avec des règles d’accès .htaccess empêchant la liste de répertoire.