# 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… - Pagina: - Lingua: it - Aggiornato il: 2026-09-30 - Altre lingue: [fr](https://www.datafirefly.com/documentation/dfcheckoutfields/index.md), [en](https://www.datafirefly.com/en/documentation/dfcheckoutfields/index.md), [es](https://www.datafirefly.com/es/documentation/dfcheckoutfields/index.md), [de](https://www.datafirefly.com/de/documentation/dfcheckoutfields/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfcheckoutfields/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfcheckoutfields/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfcheckoutfields/index.md) - Indice: ## 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.