Return Portal + Auto-Label — Documentazione completa

Versione: 1.0.7
Compatibilità: WordPress 6.2+ • WooCommerce 8.0+ • PHP 8.0+ • HPOS e Cart/Checkout Blocks

Panoramica

Return Portal + Auto-Label automatizza l’intero ciclo di vita di un reso prodotto per il tuo negozio WooCommerce:

• Lato cliente: il cliente richiede il reso senza contattare il supporto, seleziona gli articoli, sceglie un motivo e riceve immediatamente l’etichetta PDF.
• Lato admin: dashboard con timeline, ispezione riga per riga, registro attività completo e risoluzione automatica.
• 6 corrieri: Manuale (PDF nativo), Colissimo, Mondial Relay, Chronopost, UPS, DPD.
• 3 risoluzioni: rimborso WooCommerce nativo, buono bonificato (+X%) o sostituzione automatica.

Stati di un reso

Un reso attraversa fino a 7 fasi:

Stato	Descrizione
requested	Richiesta ricevuta, in attesa di validazione
approved	Approvata dall’admin (o auto-approvata sotto soglia)
label_sent	Etichetta generata e inviata al cliente
in_transit	Pacco in transito
received	Pacco ricevuto in magazzino
inspecting	Articoli in ispezione
resolved	Risoluzione applicata (rimborso / buono / sostituzione)

Due stati terminali aggiuntivi: rejected e cancelled.

Installazione

Metodo 1 — Via admin WordPress

1. Scarica il file ZIP dfreturnportal.zip.
2. In WordPress, vai a Plugin → Aggiungi nuovo → Carica plugin.
3. Seleziona il file ZIP, clicca su Installa ora.
4. Attiva il plugin.

Metodo 2 — Via FTP/SSH

cd wp-content/plugins/
unzip dfreturnportal.zip
# Poi attiva dall'admin WordPress

Verifiche post-installazione

• Appare un menu Resi nella barra laterale di WordPress.
• Viene creato automaticamente un endpoint /il-mio-account/resi/.
• Vengono create le tabelle custom wp_dfrp_returns, wp_dfrp_return_items, wp_dfrp_history, wp_dfrp_attachments.

Configurazione iniziale

Vai a Resi → Impostazioni.

Generale

Impostazione	Descrizione
Finestra di eleggibilità	Numero di giorni dopo l’ordine durante i quali è consentito un reso. Predefinito: 30 giorni.
Pagina del portale cliente	Pagina WordPress dove verrà mostrato lo shortcode [dfrp_portal]. Opzionale se usi solo l’endpoint Il Mio Account.
Notifiche admin	Indirizzo email che riceverà le notifiche di nuove richieste. Predefinito: admin del sito.

Corriere

Seleziona il corriere attivo tra i 6 disponibili. Puoi anche configurare il formato etichetta (A4, A5, A6, 10×15).

Indirizzo di reso

Indica l’indirizzo fisico dove verranno spediti i pacchi di reso. Obbligatorio per generare le etichette. Campi: Azienda, Via, Città, CAP, Paese (codice ISO 2 lettere), Telefono, Email.

Credenziali corrieri

Per ogni corriere API (Colissimo, Mondial Relay, ecc.), un blocco espandibile contiene le credenziali richieste. Compila solo quelle del corriere che usi effettivamente.

Risoluzione

Impostazione	Descrizione
Bonus buono (%)	Percentuale aggiunta all’importo rimborsato quando il cliente sceglie il buono bonificato. Predefinito: 10%.
Soglia di auto-approvazione	Sotto questo importo (valuta del negozio), le richieste vengono auto-approvate e l’etichetta viene generata senza intervento admin. Imposta a 0 per disabilitare.
Risoluzione proposta per motivo	Per ogni motivo (8 motivi predefiniti), scegli la risoluzione proposta: rimborso / buono bonificato / sostituzione.

Esclusioni

• Categorie escluse: ID WooCommerce separati da virgole. I prodotti in queste categorie non saranno mai eleggibili al reso.
• SKU esclusi: un SKU per riga.

Esperienza cliente

Via la pagina Il Mio Account (clienti loggati)

Il flusso più semplice e usato. La scheda Resi appare automaticamente nel menu /il-mio-account/ accanto a “Ordini”, “Indirizzi”, ecc.

Il cliente clicca su Resi, vede la lista dei suoi ordini eleggibili (senza dover inserire email/numero), clicca su Avvia un reso sull’ordine in questione, seleziona gli articoli, sceglie un motivo e una quantità per articolo, aggiunge opzionalmente delle foto (se il motivo lo richiede), sceglie la sua risoluzione preferita e riceve immediatamente un numero RMA (es.: RMA-20260523-A1B2C3) più un’email di conferma.

Via una pagina pubblica (clienti ospiti)

Crea una pagina WordPress, inserisci lo shortcode:

[dfrp_portal]

Il cliente dovrà inserire il suo numero d’ordine + email per autenticarsi. Il resto del flusso è identico.

Tracciamento di una richiesta esistente

Nella pagina pubblica del portale, un blocco “Traccia una richiesta esistente” permette ai clienti ospiti di verificare lo stato del loro RMA (stato, numero di tracciamento del corriere, link all’etichetta).

Personalizzazione dello shortcode

[dfrp_portal title="Richiesta di reso" context="page"]

Attributo	Valori	Descrizione
title	testo libero	Titolo del portale (raramente usato visivamente).
context	page o myaccount	Forza il contesto. myaccount salta lo step di lookup per gli utenti loggati.

Workflow amministratore

Dashboard

Accessibile tramite Resi → Dashboard. Contiene 9 carte statistiche colorate (conteggio per stato, cliccabili per filtrare la lista), gli ultimi 10 RMA con accesso rapido al dettaglio, e un banner con l’URL del portale cliente con pulsante “Copia” per condividere.

Lista delle richieste

Accessibile tramite Resi → Tutte le richieste. Tabella con filtri per stato, ricerca libera (RMA, email cliente, numero d’ordine) e paginazione (20 per pagina).

Pagina dettaglio di una richiesta

Componenti:

1. Intestazione: codice RMA + badge di stato + ritorno alla lista.
2. Timeline: 7 punti colorati che mostrano il progresso visivo.
3. Articoli da restituire: tabella con prodotto, SKU, quantità, prezzo unitario, motivo e ispezione per articolo (dropdown Conforme / Parzialmente / Rifiutato — attivato dopo stato received).
4. Foto cliente: galleria se il cliente ha caricato giustificativi.
5. Registro attività: cronologia cronologica completa.
6. Informazioni: email cliente, link ordine, preferenza di risoluzione, nota cliente.
7. Etichetta di reso: corriere, numero di tracciamento, pulsante scarica PDF, pulsante rigenera.
8. Azioni: pulsanti “Passa a: [stato successivo]” secondo la state machine.
9. Risolvi (visibile se stato received o inspecting): selettore di risoluzione + pulsante “Applica”.

Transizioni consentite

La state machine impedisce transizioni non valide:

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

Gli stati resolved, rejected e cancelled sono terminali.

Auto-approvazione

Se hai configurato una soglia di auto-approvazione (es.: 50 €), ogni richiesta il cui importo totale è minore o uguale alla soglia passa automaticamente da requested ad approved, l’etichetta viene generata immediatamente e inviata al cliente, senza intervento admin.

Corrieri supportati

Manuale (senza API)

Ideale per iniziare. Genera una distinta PDF nativa con codice QR, senza alcuna dipendenza da API esterne. Zero configurazione, gratuito, funziona immediatamente. Limitazione: nessun tracciamento automatico. Uso: il cliente la stampa, tu la metti nel pacco alla spedizione iniziale o lui la incolla per il reso postale classico.

Colissimo (La Poste)

API REST ufficiale (Sls Service generateLabel). Credenziali richieste: Contract Number, Password. Particolarità: genera un codice a barre parcelNumber, tipo di reso “3”, formato PDF predefinito.

Mondial Relay

API SOAP (WSI4_CreationEtiquette). Credenziali richieste: Enseigne, Private Key, Pickup Point. Particolarità: modalità di ritiro CCC (Pacco Affidato al Cliente), firma MD5 obbligatoria.

Chronopost

API SOAP (shippingMultiParcelV5). Credenziali richieste: Account Number, Password, Subaccount. Particolarità: Product Code 8R (reso Relais), modalità reso 2.

UPS

API REST v2403 (/ship). Credenziali richieste: Client ID (OAuth2), Client Secret, Shipper Number. Particolarità: ReturnService.Code = 8 (Electronic Return Label), formato GIF base64 predefinito.

DPD

API REST (cargonet endpoint). Credenziali richieste: Username, Password, Customer ID. Particolarità: Autenticazione Basic Auth, formato PDF A6.

Risoluzioni

Rimborso

Usa la funzione nativa wc_create_refund() di WooCommerce. Riaccredita il metodo di pagamento originale, restock automatico degli articoli (configurabile), crea una nota di rimborso nell’ordine e genera un’email di conferma nativa WooCommerce.

Buono bonificato

Crea automaticamente un coupon WooCommerce:

• Importo = totale reso + bonus (% configurabile, predefinito 10%).
• Restrizione email: utilizzabile solo dall’email del cliente.
• Scadenza: 6 mesi predefiniti.
• Uso singolo.

Il cliente riceve un’email con il suo codice coupon in grande.

Sostituzione

Crea un nuovo ordine WooCommerce a 0 € (gratuito per il cliente). Indirizzi di spedizione/fatturazione copiati dall’ordine originale, articoli identici a quelli restituiti conformi, stato iniziale processing (lo spedisci normalmente). Il cliente riceve un’email con il numero del nuovo ordine.

Proposta automatica

Il motore analizza i motivi degli articoli restituiti e propone la risoluzione più pertinente. Configurazione in Resi → Impostazioni → Risoluzione proposta per motivo. Mapping predefinito:

Motivo	Risoluzione proposta
Articolo danneggiato	Sostituzione
Articolo difettoso	Sostituzione
Articolo sbagliato ricevuto	Sostituzione
Conforme alla descrizione ma non adatto	Rimborso
Cambio di idea	Buono bonificato
Taglia o colore errati	Buono bonificato
Consegna in ritardo	Rimborso
Altro	Rimborso

Personalizzazione

Override dei template

Tutti i template email sono sovrascrivibili tramite il tuo tema. Copia il file sorgente templates/emails/*.php in yourtheme/dfreturnportal/emails/*.php.

Hook (azioni)

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

Filtri

// Personalizza gli stati d'ordine eleggibili (predefinito: ['completed', 'processing'])
add_filter('dfrp_eligible_order_statuses', function($statuses) {
    $statuses[] = 'on-hold';
    return $statuses;
});

// Personalizza i motivi di reso
add_filter('dfrp_reasons', function($reasons) {
    $reasons[] = [
        'code'          => 'motivo_custom',
        'label'         => 'Il mio motivo personalizzato',
        'require_photo' => false,
    ];
    return $reasons;
});

// Personalizza lo slug dell'endpoint Il Mio Account (predefinito: 'returns')
add_filter('dfrp_myaccount_endpoint', function() {
    return 'miei-resi';
});

// Personalizza l'etichetta del menu Il Mio Account
add_filter('dfrp_myaccount_menu_label', function() {
    return 'I miei resi';
});

// Aggiungi un corriere personalizzato
add_filter('dfrp_register_carriers', function($carriers) {
    $carriers[] = new MioCorriereCustom();
    return $carriers;
});

Disinstallazione pulita

Per impostazione predefinita, la disinstallazione conserva i dati (tabelle e opzioni). Per cancellare tutto alla disinstallazione, aggiungi in wp-config.php:

define('DFRP_DELETE_DATA_ON_UNINSTALL', true);

API REST

Tutti gli endpoint sono sotto il namespace dfrp/v1. URL base: https://tuosito.com/wp-json/dfrp/v1/.

Endpoint pubblici

Endpoint	Metodo	Descrizione
/lookup	POST	Cerca un ordine per numero + email.
/create	POST	Crea una nuova richiesta di reso.
/track	POST	Traccia un RMA tramite codice + email.
/upload-photo	POST	Carica una foto giustificativa (multipart).

Endpoint cliente loggato

Endpoint	Metodo	Descrizione
/my-orders	GET	Lista gli ordini eleggibili del cliente loggato.

Endpoint admin (capability manage_woocommerce)

Endpoint	Metodo	Descrizione
/admin/returns	GET	Lista paginata con filtri.
/admin/returns/{id}	GET	Dettaglio di un reso.
/admin/returns/{id}/transition	POST	Cambia lo stato.
/admin/returns/{id}/inspect-item	POST	Risultato di ispezione di un articolo.
/admin/returns/{id}/resolve	POST	Applica una risoluzione.
/admin/returns/{id}/regenerate-label	POST	Rigenera l’etichetta.

Risoluzione dei problemi

Il portale mostra “Caricamento…” all’infinito

• Verifica la console del browser (F12) — dovresti vedere [Return Portal] script frontend.js eseguito.
• Se non appare nulla, un plugin di sicurezza (Wordfence, Sucuri, NinjaFirewall) sta bloccando lo script inline. Disattivalo temporaneamente per testare.
• Verifica anche gli ottimizzatori JS (WP Rocket “Delay JS”, Autoptimize, Cloudflare Rocket Loader) — il plugin emette già gli attributi opt-out necessari, ma configurazioni molto aggressive possono comunque bloccare.

La scheda “Resi” non appare nel Mio Account

Vai a Impostazioni → Permalink e clicca su “Salva modifiche” (senza cambiare nulla). Questo forza WordPress a rigenerare le regole di riscrittura.

Errore “Constant DFRP_VERSION already defined”

La cartella del plugin è duplicata. Verifica:

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

Elimina le copie duplicate (es.: dfreturnportal-old/, dfreturnportal-1/).

Il cliente non riceve le email

• Verifica che l’invio email funzioni globalmente.
• Configura un SMTP appropriato (WP Mail SMTP, FluentSMTP).
• Verifica i log spam del dominio destinatario.

L’etichetta PDF è vuota o corrotta

• Verifica che l’indirizzo di reso sia completamente compilato.
• Per i corrieri API, verifica le credenziali in modalità test prima.
• Consulta i log PHP (/wp-content/debug.log se WP_DEBUG_LOG è attivo).

FAQ

Il plugin richiede un abbonamento a un corriere?
No. La modalità Manuale genera una distinta PDF nativa senza alcuna dipendenza API. Le modalità API (Colissimo, ecc.) sono opzionali.

Compatibile HPOS (High-Performance Order Storage)?
Sì, totalmente. Il plugin dichiara la sua compatibilità all’avvio di WooCommerce.

Compatibile Cart/Checkout Blocks?
Sì.

Le variazioni di prodotto sono gestite?
Sì, ogni variazione è trattata come un articolo distinto.

E i prodotti virtuali o scaricabili?
Sono automaticamente esclusi dai resi.

Il cliente può restituire parzialmente un ordine?
Sì. L’eleggibilità tiene conto delle quantità già restituite tramite RMA precedenti.

Multilingua?
Il plugin è pronto per la traduzione (Text Domain dfreturnportal, file .pot fornito). Compatibile con WPML, Polylang, TranslatePress.

Le foto cliente sono memorizzate in modo sicuro?
Sì, nella libreria media di WordPress con regole .htaccess che impediscono l’elenco delle directory.