Documentazione Pulsante di Recesso

Passaggi di installazione e un riferimento completo per ogni campo e funzione dell'admin, con esempi concreti — lo stesso livello di dettaglio che usiamo per assistere i clienti.

Installazione

Requisiti

Magento 2.4.x — testato su 2.4.9, compatibile con le versioni 2.4.* precedenti. PHP 8.1–8.5. Compatibile sia con il tema Luma di default sia con il tema Hyvä. Richiede i moduli nativi Magento_ReCaptcha* per la protezione reCAPTCHA opzionale (già inclusi nel core di Magento).

Passaggi di setup

1. Aggiungi le credenziali ricevute via email ad auth.json nella root del progetto Magento:
```
{ "http-basic": { "repo.codingrow.com": { "username": "...", "password": "..." } } }
```
2. composer config repositories.codingrow composer https://repo.codingrow.com
3. composer require codingrow/module-withdrawal-button
4. bin/magento module:enable Codingrow_WithdrawalButton
5. bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush
6. Incolla la chiave di licenza in Admin → Stores → Configuration → Codingrow Extensions → Withdrawal Button → License → License Key, salva, poi bin/magento cache:flush.
7. Posiziona il link di richiesta dove i clienti possano trovarlo — vedi Posizionare il widget più sotto.

L'intero modulo frontend, le email e l'interfaccia admin sono disponibili in 7 lingue, selezionate automaticamente in base alla lingua di store/admin:

Disinstallazione

composer remove codingrow/module-withdrawal-button poi bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush. Le richieste già registrate in codingrow_withdrawalbutton_request non vengono mai eliminate automaticamente — esporta prima la griglia se vuoi conservarne una copia.

Guida utente

La pagina di richiesta recesso

Una pagina, due passaggi, esattamente come richiesto dalla direttiva di riferimento: il cliente prima compila i campi fissi (nome, email, numero ordine, data di ricezione) più eventuali campi personalizzati abilitati, vede un riepilogo di sola lettura di tutto quanto inserito, e solo allora conferma su un tasto finale separato. I campi nascosti che portano avanti i dati tra i due passaggi vengono rivalidati lato server alla conferma — un cliente non può mai bypassare i controlli forzando direttamente il passaggio "confermato".

Verifica dell'ordine

Prima di accettare una richiesta, il modulo controlla che il numero d'ordine esista davvero e che l'indirizzo email corrisponda a quello sull'ordine (senza distinzione tra maiuscole/minuscole, funziona sia per ordini ospite che per clienti registrati). Se uno dei due controlli fallisce, viene mostrato in entrambi i casi lo stesso messaggio generico "non trovato" — è deliberato: rivelare "email sbagliata" invece di "l'ordine non esiste" permetterebbe di individuare numeri d'ordine validi per tentativi.

Stato ordine e termine di recesso

Due impostazioni in Stores → Configuration → Codingrow Extensions → Withdrawal Button → General controllano quali richieste vengono accettate, oltre alla verifica obbligatoria di ordine/email descritta sopra.

Order statuses eligible for withdrawal — una multiselect nativa di Magento (Pending / Processing / Complete / Closed / Canceled / On Hold). Una richiesta viene accettata solo se lo stato attuale dell'ordine è tra quelli selezionati; preselezionati all'installazione su Pending, Processing, Complete, Closed e On Hold. Lasciare l'elenco vuoto blocca ogni richiesta indipendentemente dallo stato dell'ordine — una scelta esplicita del merchant, non un bug.
Withdrawal period (days) — quanti giorni sono ammessi tra la data di ricezione dichiarata e il momento dell'invio della richiesta (14 di default, il minimo previsto dalla normativa UE sul recesso). Trascorso quel termine la richiesta viene rifiutata con un messaggio che invita il cliente a contattare direttamente il negozio; la colonna dei giorni trascorsi nella griglia admin segnala le richieste oltre lo stesso limite.

Prevenzione richieste duplicate

Un ordine può avere solo una richiesta di recesso attiva, indipendentemente dal suo stato — anche una "Rifiutata". Un cliente che non è d'accordo con un rifiuto non può semplicemente inviare di nuovo la stessa richiesta per aggirarlo; se serve una vera eccezione, l'admin elimina prima la richiesta precedente dalla griglia.

Data di ricezione e giorni trascorsi

Il periodo di recesso (configurabile, 14 giorni di default) parte da quando la merce è stata ricevuta, non dalla data di acquisto o fattura — un'informazione che Magento non può conoscere da solo, dato che dipende dal corriere. Il modulo la richiede con un selettore data HTML5 nativo (senza dipendenza da jQuery UI che potrebbe entrare in conflitto con un tema), limitato in modo che non si possa inserire una data futura. La data dell'ordine viene invece letta automaticamente dall'ordine collegato — il cliente non deve mai digitarla. Entrambe le date, più i giorni trascorsi dalla ricezione, sono mostrati nella griglia admin (segnalati oltre quel termine) e disponibili come variabili email.

Costruttore di campi personalizzati

Oltre ai quattro campi richiesti per legge (nome, email, numero ordine, data di ricezione — sempre obbligatori, mai rimovibili), puoi aggiungere un numero illimitato di campi tuoi da Stores → Configuration → Codingrow Extensions → Withdrawal Button → Custom Fields: etichetta, tipo, se è obbligatorio, e se è attualmente mostrato nel modulo — l'ordine delle righe nell'elenco è l'ordine di visualizzazione nel form.

Tipo	Reso come
Testo	Campo a riga singola
Area di testo	Riquadro multi-riga
Menu a tendina	Un `<select>` con le opzioni digitate, una per riga
Checkbox	Una singola casella (es. "Ho ancora la confezione originale")

Esempio — un campo Menu a tendina obbligatorio "Motivo del reso" con opzioni "Difettoso / Non corrisponde alla descrizione / Ripensamento": i clienti devono sceglierne una per poter inviare, e il valore scelto compare nella colonna "Campi personalizzati" della griglia admin e in entrambe le email di notifica.

I valori inviati per un campo che viene disabilitato in seguito restano nella cronologia della richiesta e continuano a essere mostrati ovunque siano stati registrati — solo l'etichetta del campo viene ricalcolata in base all'ID, quindi rinominare un campo aggiorna l'etichetta ovunque compaiano anche le sue vecchie risposte.

Colori e testo del pulsante

Due campi colore esadecimale (testo e sfondo) permettono di abbinare il pulsante al tuo brand — cambiano solo i colori; forma, padding e font restano sempre quelli già usati dal tuo tema (Luma o Hyvä), così il pulsante non può mai risultare visivamente rotto. Un valore esadecimale non valido viene semplicemente ignorato, tornando al colore di default del tema. Anche il testo del pulsante è configurabile, mostrato esattamente come digitato (maiuscole/minuscole preservate, nessuna capitalizzazione automatica) — lascialo vuoto per mantenere l'etichetta tradotta di default.

Protezione reCAPTCHA

Pulsante di Recesso si registra come modulo protetto nel sistema reCAPTCHA nativo di Magento — Stores → Configuration → Customers → Google reCAPTCHA → Storefront → "Enable for Withdrawal Button". La versione già configurata per il resto dello store (v2 checkbox, v2 invisibile, o v3) si applica automaticamente; non c'è nessuna configurazione captcha separata da mantenere.

Griglia admin e azioni di massa

Ogni richiesta finisce in Codingrow Extensions → Withdrawal Button, paginata e filtrabile, con colonne per numero ordine, cliente, data di ricezione, giorni trascorsi (segnalati oltre i 14), valori dei campi personalizzati e stato. Le azioni di massa permettono di aggiornare lo stato di più richieste selezionate insieme, o eliminare righe per ripulire i dati di test.

Stato	Significato
In attesa	Appena inviata, non ancora esaminata.
In lavorazione	In gestione da parte del negozio.
Completata	Reso/rimborso concluso.
Rifiutata	Il negozio ha rifiutato la richiesta.
Annullata	Il cliente ha ritirato la propria richiesta.

Modelli email e variabili

Due modelli email nativi di Magento — una ricevuta al cliente (la conferma su supporto durevole richiesta per legge) e una notifica interna all'admin — inviate automaticamente tramite TransportBuilder, esattamente come le email d'ordine native di Magento. Clona uno dei due da Marketing → Email Templates, modifica il testo con l'editor WYSIWYG nativo, poi seleziona la tua copia in Configuration → Email Templates — nessun codice di templating personalizzato coinvolto.

Variabile	Contenuto
`order_increment_id`	Il numero d'ordine
`order_date`	La data dell'ordine stesso, letta automaticamente
`receipt_date`	La data in cui il cliente ha dichiarato di aver ricevuto la merce
`days_since_receipt`	Giorni trascorsi da quella data
`request_id`	Numero di riferimento interno per questa richiesta
`submitted_at`	Data e ora esatte in cui la richiesta è stata confermata
`custom_fields_text`	Tutti i campi personalizzati compilati, formattati come righe "Etichetta: valore"

Etichetta di reso PDF

Un semplice foglio opzionale (logo, nome mittente, indirizzo di reso, istruzioni di imballaggio) generato internamente con Zend_Pdf — la stessa libreria PDF che usa il core di Magento per fatture e spedizioni, nessuna dipendenza esterna aggiunta — e allegato automaticamente all'email di ricevuta del cliente una volta abilitato in Configuration → Return Label. Carica un logo, compila l'indirizzo di reso ed eventuali istruzioni di imballaggio, e ogni futura email di conferma richiesta porterà un'etichetta pronta da stampare con il numero di riferimento, il numero d'ordine, il nome cliente e la data di ricezione di quella richiesta, oltre agli eventuali campi personalizzati compilati dal cliente.

Il link di richiesta non è mai inserito staticamente nel tema — viene posizionato esclusivamente tramite il sistema Widget nativo di Magento, così il negoziante controlla pienamente se, e dove, compare. Due modi per farlo, a seconda di quanto vuoi che sia mostrato:

Metodo	Adatto per
Content → Elements → Widgets	Mostrare il link su molte/tutte le pagine insieme, o in una posizione fissa del layout (footer, sidebar) su tutto il sito.
Insert Widget nel contenuto di una pagina CMS	Posizionarlo su una sola pagina specifica — es. la homepage — esattamente dove vuoi nel contenuto di quella pagina, senza toccare le altre.

Su tutto il sito, via Content → Elements → Widgets:

1. Content → Elements → Widgets → Add Widget, scegli il widget link di Withdrawal Button.
2. Assegnalo a "All Pages" o "Specified Page(s)" e imposta il contenitore di visualizzazione (es. content o sidebar.additional) — sui temi Hyvä, il contenitore "Footer" potrebbe non essere disponibile nel selettore widget; in quel caso usa invece l'area di contenuto principale, subito prima del footer.
3. Salva e ricarica le pagine di destinazione — non serve svuotare la cache per una nuova istanza widget appena salvata.

Su una sola pagina specifica, es. la homepage:

1. Content → Pages, apri la pagina (es. "Home page").
2. Nell'editor WYSIWYG del tab Content, posiziona il cursore dove vuoi il pulsante e clicca Insert Widget.
3. Scegli il widget link di Withdrawal Button, imposta il testo dell'etichetta e la classe CSS, poi Insert — questo inserisce una direttiva {{widget type="Codingrow\WithdrawalButton\Block\Widget\Link" ...}} direttamente nel contenuto di quella pagina, senza toccare le altre.
4. Salva la pagina.

Nota: il widget è l'unico modo supportato per esporre il link — il modulo non lo inserisce mai automaticamente nel footer o in altri template, perché il negoziante potrebbe legittimamente volerlo altrove (una pagina ordini, una pagina CMS dedicata, una categoria prodotto specifica) o non mostrarlo affatto su tutto il sito.

Licenza

Senza una chiave di licenza valida, la pagina di recesso resta visibile (un negoziante non deve mai restare senza il pulsante richiesto per legge solo perché una licenza è scaduta) ma i nuovi invii vengono bloccati finché non viene inserita una chiave in Configuration → License → License Key.