Custom Checkout Fields: documentazione

Panoramica

DataFirefly Custom Checkout Fields aggiunge campi personalizzati al checkout e al modulo di registrazione di PrestaShop 8 e 9: numero d’ordine d’acquisto, data di consegna desiderata, SIRET, settore di attività, allegato o qualsiasi altro campo che crei. I valori vengono controllati prima della conferma dell’ordine e poi riportati nella pagina ordine, nella fattura PDF, nel documento di trasporto, nelle email, negli elenchi del back office, nelle esportazioni CSV e nel webservice.

Installazione

1. Nel back office apri Moduli > Gestione moduli e fai clic su Carica un modulo.
2. Seleziona il file dfcheckoutfields.zip.
3. L’installazione crea tre tabelle, la cartella protetta upload/dfcheckoutfields, i menu Ordini > Campi personalizzati e Ordini > Esporta campi, e cinque campi pronti all’uso.
4. Fai clic su Configura per impostare le opzioni generali.

Per aggiornare, carica il nuovo ZIP sopra il precedente: gli script di aggiornamento aggiungono le nuove colonne senza toccare i tuoi campi né i valori salvati.

Campi creati all’installazione

• Numero d’ordine d’acquisto (po_number): testo di massimo 50 caratteri, salvato sull’ordine, visibile in fattura, nel documento di trasporto e come colonna dell’elenco ordini.
• Data di consegna desiderata (desired_date): al più presto oggi + 2 giorni, solo giorni lavorativi.
• Numero SIRET (siret): controllato con la chiave di Luhn, salvato sull’account cliente, richiesto alla registrazione e al checkout, limitato ai clienti della Francia.
• Settore di attività (sector): elenco di otto settori, salvato sull’account cliente, richiesto alla registrazione.
• Allegato (attachment): PDF, immagini e documenti Office, massimo 8 MB.

Nessuno di questi campi è obbligatorio per impostazione predefinita. Modificali, disattivali o eliminali secondo le tue esigenze.

Impostazioni generali

Moduli > Gestione moduli > Campi personalizzati per ordine e registrazione > Configura.

• Posizione del blocco nel checkout: passaggio di pagamento, sopra i metodi di pagamento (predefinito), o passaggio di spedizione, sotto i corrieri. I carrelli con soli prodotti virtuali usano sempre il passaggio di pagamento.
• Titolo del blocco: mostrato al checkout, nelle pagine ordine, nei PDF e nelle email, per lingua.
• Posizione sulla fattura PDF: intestazione sotto il numero di fattura, o in fondo alla fattura. Vedi Fattura e documento di trasporto.
• Nota privata se manca un campo obbligatorio: aggiunge l’elenco dei campi mancanti alla nota privata dell’ordine quando un modulo di pagamento aggira il controllo del checkout.
• Copia i campi SIRET nel SIRET nativo del cliente: mantiene aggiornato il campo SIRET della scheda cliente, usato dalla modalità B2B di PrestaShop.

Creare o modificare un campo

Ordini > Campi personalizzati, poi Aggiungi un campo o la matita di una riga. Il modulo mostra solo le opzioni utili per il tipo e il salvataggio scelti.

Campo

• Etichetta, segnaposto e testo di aiuto: per lingua. Una lingua vuota riprende l’etichetta della lingua predefinita.
• Codice: identificativo tecnico in lettere minuscole, cifre e trattini bassi. Serve anche come variabile email {dfcf_CODE} e nel webservice.
• Tipo: testo, testo su più righe, numero, email, data, elenco a discesa, casella, SIRET o file.
• Salvato su: Ordine (un valore per ordine) o Account cliente (valore conservato nella scheda cliente, precompilato al checkout e copiato su ogni ordine).
• Opzioni dell’elenco: un’opzione per riga nel formato chiave|Etichetta, per esempio industry|Industria. Mantieni le stesse chiavi in tutte le lingue.

Dove e quando

• Mostra alla registrazione e obbligatorio alla registrazione: solo campi dell’account cliente, tipo file escluso. Compaiono anche nel modulo Dati personali dell’account.
• Mostra al checkout e obbligatorio al checkout.
• Mostra solo se: vedi Visualizzazione condizionale.
• Paesi: paese dell’indirizzo di fatturazione al checkout, del visitatore alla registrazione. Vuoto per tutti i paesi.
• Gruppi di clienti: tutto deselezionato per tutti i gruppi.

Convalida

• Lunghezza massima: 0 per il valore predefinito (255 caratteri, 2000 su più righe).
• Modello di convalida: espressione regolare senza delimitatori, per esempio ^[A-Z]{2}[0-9]{6}$.
• Preavviso minimo e orizzonte massimo in giorni per una data salvata sull’ordine.
• Solo giorni lavorativi: rifiuta sabato e domenica.
• Giorni di chiusura: uno per riga, 2026-12-24 per un giorno, 2026-08-01:2026-08-21 per un periodo, 12-25 per ogni anno.
• Estensioni consentite e dimensione massima per un file. Script ed eseguibili sono sempre rifiutati.

Documenti ed esportazioni

Mostra al cliente (conferma, account cliente, email al cliente), sulla fattura PDF, sul documento di trasporto, come colonna filtrabile degli elenchi del back office, nelle esportazioni CSV.

Elenco dei campi

Le icone dell’elenco attivano o disattivano un’impostazione con un clic. Trascina le righe per cambiare l’ordine. L’azione Duplica crea una copia disattivata con il codice code_copy. Un campo con valori sugli ordini non può essere eliminato: disattivalo per conservare lo storico.

Visualizzazione condizionale

Esempio: mostrare il SIRET solo alle aziende.

1. Crea un campo Casella salvato sull’account cliente, codice is_company, etichetta Sono un’azienda.
2. Modifica il campo SIRET, sezione Dove e quando, e scegli Mostra solo se: Sono un’azienda. Lascia vuoto «ha uno di questi valori»: per una casella significa spuntata.

Per un elenco a discesa indica le chiavi attese separate da virgole, per esempio health,public. Le condizioni si concatenano: un campo il cui campo padre è nascosto è nascosto anch’esso. Un campo nascosto non è mai obbligatorio e il suo valore non viene conservato. Il campo padre deve essere mostrato nello stesso punto (registrazione o checkout) o essere già compilato nell’account cliente.

Lato cliente

Al checkout

Il blocco compare nel passaggio scelto. Ogni valore viene salvato durante la digitazione. Finché un campo obbligatorio è vuoto o non valido, il clic su Ordina (o Continua nel passaggio di spedizione) è bloccato, il messaggio compare sotto il campo e la pagina scorre fino ad esso. L’allegato si invia trascinandolo o con un clic, con una barra di avanzamento. Il cliente può rimuoverlo e inviarne un altro.

Alla registrazione e in Dati personali

I campi dell’account cliente contrassegnati Mostra alla registrazione vengono aggiunti al modulo nativo di creazione account, al modulo ospite del checkout e al modulo Dati personali. Gli errori vengono mostrati come quelli dei campi PrestaShop.

Dopo l’ordine

I valori contrassegnati Mostra al cliente compaiono nella pagina di conferma e nel dettaglio ordine dell’account cliente. Il cliente titolare dell’ordine può scaricare lì l’allegato.

Fattura e documento di trasporto

In fondo alla fattura: il modulo usa l’hook displayPDFInvoice e stampa una tabella dopo i totali. Nessun file viene modificato.

Intestazione, sotto il numero di fattura: PrestaShop non ha un hook in quel punto. Salvando questa impostazione, il modulo aggiunge un blocco delimitato da {* dfcf:start *} e {* dfcf:end *} alla fine di themes/IL_TUO_TEMA/pdf/invoice.summary-tab.tpl. Se il file non esiste, viene creato a partire da quello di PrestaShop. Se esiste già, il modulo lo completa e salva una copia .dfcf-backup. Tornare a In fondo alla fattura o disinstallare rimuove il blocco. Se il file non è scrivibile, un messaggio ne indica il percorso.

Con DataFirefly Invoice Editor, che sostituisce la resa della fattura, usa In fondo alla fattura: l’editor riporta il contenuto dei moduli nella posizione che scegli.

Il documento di trasporto usa l’hook displayPDFDeliverySlip, campo per campo.

Email

Nelle email che contengono l’ID ordine, tra cui order_conf e new_order, sono disponibili due tipi di variabili:

• {dfcf_fields}: tutti i valori in una tabella. In order_conf solo i campi contrassegnati Mostra al cliente, in new_order, destinata al negoziante, tutti i campi.
• {dfcf_CODE}: un solo valore, per esempio {dfcf_po_number} o {dfcf_desired_date}.

Aggiungile in Aspetto > Tema email, o nei file email del tuo tema.

Back office

• Pagina ordine: scheda Campi personalizzati con tutti i valori. Il pulsante Modifica permette di correggere un valore o sostituire l’allegato.
• Scheda cliente: scheda con i campi dell’account cliente, modificabile allo stesso modo.
• Elenchi: ogni campo contrassegnato come colonna filtrabile compare nell’elenco ordini con un filtro di testo. I campi dell’account cliente compaiono anche nell’elenco clienti.

Esportazione CSV

Ordini > Esporta campi. Scegli Ordini o Clienti, il periodo, gli stati dell’ordine (tutto deselezionato per tutti), il separatore e se esportare solo le righe con almeno un valore. Il file è in UTF-8 con BOM e si apre direttamente in Excel. Gli ordini vengono esportati con riferimento, data, stato, cliente, totali IVA esclusa e inclusa e valuta, seguiti dai campi contrassegnati Includi nelle esportazioni CSV.

Webservice

1. Parametri avanzati > Webservice: attiva il webservice e crea o modifica una chiave.
2. Spunta GET sulla risorsa dfcf_values.
3. Chiama /api/dfcf_values?filter[id_order]=[123]&display=full.

Ogni valore viene restituito con id_dfcf_field, id_order, id_customer, id_cart, value, value_display, field_code, field_label e has_file. I valori del profilo cliente hanno id_order e id_cart a 0.

Allegati e sicurezza

Ogni file viene controllato per estensione (elenco del campo) e per contenuto reale: uno script rinominato in .pdf viene rifiutato. Viene salvato in upload/dfcheckoutfields con un nome casuale e senza estensione, in una cartella il cui accesso diretto è vietato da un file .htaccess. Su Nginx aggiungi la regola location ^~ /upload/dfcheckoutfields/ { deny all; }. Il download passa sempre dal modulo, che verifica che il visitatore sia il cliente dell’ordine o un dipendente.

GDPR

I valori salvati su un account cliente vengono eliminati con il cliente. Il modulo risponde alle richieste di esportazione e cancellazione del modulo GDPR ufficiale di PrestaShop. I valori copiati sugli ordini restano con l’ordine.

Risoluzione dei problemi

Il blocco non compare al checkout

Verifica che il campo sia attivo, contrassegnato Mostra al checkout, e che gruppo e paese del cliente corrispondano alle sue limitazioni. Se hai scelto il passaggio di spedizione, verifica che il tema chiami l’hook displayAfterCarrier.

Il pulsante Ordina non viene bloccato

Il modulo riconosce il pulsante dei temi Classic e Hummingbird. Un tema che sostituisce il pulsante con un altro elemento, o un pagamento express avviato dalla scheda prodotto, non è coperto: attiva la nota privata per essere avvisato degli ordini incompleti.

I campi non compaiono nell’intestazione della fattura

Verifica che il file pdf/invoice.summary-tab.tpl del tema sia scrivibile, salva di nuovo le impostazioni e svuota la cache in Parametri avanzati > Prestazioni.

Una variabile email compare così com’è

Viene compilata solo nelle email che contengono l’ID ordine. Verifica anche che il codice corrisponda esattamente a quello del campo.