# Return Portal + Auto-Label — Documentazione completa

> Portale di reso self-service per clienti, etichette di reso multi-corriere generate automaticamente, workflow di ispezione admin e motore di risoluzione (rimborso, buono bonificato, sostituzione) per WooCommerce. Versione: 1.0.7 Compatibilità: WordPress…

- Pagina: <https://www.datafirefly.com/it/documentation/dfreturnportal/>
- Lingua: it
- Aggiornato il: 2026-06-27
- Altre lingue: [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), [pl](https://www.datafirefly.com/pl/documentation/dfreturnportal/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfreturnportal/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfreturnportal/index.md)
- Indice: <https://www.datafirefly.com/it/documentation/llms.txt>

Portale di reso self-service per clienti, etichette di reso multi-corriere generate automaticamente, workflow di ispezione admin e motore di risoluzione (rimborso, buono bonificato, sostituzione) per WooCommerce.

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

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

Se la scheda "Resi" non appare nel Mio Account, vai a **Impostazioni → Permalink** e clicca "Salva" per aggiornare le regole di riscrittura.

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

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

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

### Filtri

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

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

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