WooCommerce nasce negli Stati Uniti e il suo checkout lo dimostra: nome, indirizzo, email, telefono. Di partita IVA, codice fiscale e codice destinatario non c’è traccia, e senza quei tre dati in Italia non emetti una fattura elettronica valida.
Personalizzare i campi checkout WooCommerce è quindi il primo intervento che serve a chi vende anche a partite IVA. In questa guida vediamo come farlo con il checkout a blocchi, come farlo con quello classico e perché quasi tutte le guide che trovi in giro ti fanno perdere tempo con codice che non funziona più.
Quali campi servono davvero per fatturare in Italia
Prima del codice, un chiarimento su cosa raccogliere. Aggiungere campi checkout WooCommerce a caso allunga il modulo e basta: ogni campo in più abbassa il tasso di conversione, quindi vanno messi solo quelli che poi finiscono davvero in fattura.
I dati minimi per generare un XML accettato dal Sistema di Interscambio sono quattro.
- Partita IVA. Undici cifre numeriche. Serve per i clienti soggetti IVA.
- Codice fiscale. Sedici caratteri alfanumerici per le persone fisiche, undici numerici per gli enti. Per le ditte individuali è diverso dalla partita IVA e vanno raccolti entrambi.
- Codice destinatario. Sette caratteri per i privati, sei per la Pubblica Amministrazione. Se il cliente non ce l’ha si usano sette zeri.
- PEC. Alternativa al codice destinatario quando il cliente riceve le fatture via posta certificata.
Il codice fiscale merita una nota a parte. Molti dimenticano che per le ditte individuali partita IVA e codice fiscale sono due numeri diversi, e che il tracciato XML li vuole in campi separati: raccoglierne uno solo significa generare fatture destinate allo scarto.
Un quinto campo che conviene aggiungere è il selettore tra privato e azienda, perché ti permette di mostrare i campi fiscali solo a chi serve e di non spaventare il cliente consumatore con un modulo lungo il doppio.
Campi checkout WooCommerce: prima verifica quale versione hai
Questa è la domanda che determina tutto il resto, ed è anche il motivo per cui tante guide ti fanno perdere un pomeriggio.
Fino a qualche anno fa esisteva un solo modo di personalizzare i campi checkout WooCommerce: il filtro PHP woocommerce_checkout_fields. Poi è arrivato il checkout a blocchi, costruito in React, dove quel filtro semplicemente non viene eseguito. Se copi uno snippet del 2021 su un’installazione recente non succede nulla, e passi il pomeriggio a cercare l’errore in un codice che è corretto ma inutile.
La verifica dura dieci secondi. Apri la pagina Checkout nell’editor di WordPress. Se vedi un blocco unico chiamato Checkout con i suoi blocchi interni, sei sul checkout a blocchi. Se vedi uno shortcode woocommerce_checkout dentro un blocco di testo, sei su quello classico.
Le nuove installazioni usano i blocchi per impostazione predefinita. I siti più vecchi spesso hanno ancora lo shortcode, e molti ci restano perché qualche plugin di terze parti non è compatibile.
Campi checkout WooCommerce nel checkout a blocchi
Dalla versione 8.9 WooCommerce mette a disposizione le Additional Checkout Fields API, che registrano campi compatibili sia con il form React sia con la Store API.
Ci sono tre posizioni disponibili: contact in cima al modulo accanto all’email, address dentro gli indirizzi e order nella sezione delle informazioni d’ordine.
Per i dati fiscali consiglio contact. Il motivo è pratico: i campi registrati lì vengono salvati sull’account del cliente e ricompilati automaticamente agli ordini successivi, un vantaggio enorme se lavori in B2B con clienti ricorrenti. La posizione address sembrerebbe più logica, ma genera due valori distinti, uno per la fatturazione e uno per la spedizione, e per una partita IVA è una complicazione inutile.
Ecco la registrazione dei campi. Il codice va in un plugin custom o nel file functions.php del tema child.
add_action( 'woocommerce_init', function () {
if ( ! function_exists( 'woocommerce_register_additional_checkout_field' ) ) {
return;
}
woocommerce_register_additional_checkout_field(
array(
'id' => 'cosmocode/partita-iva',
'label' => 'Partita IVA',
'optionalLabel' => 'Partita IVA (se sei un\'azienda)',
'location' => 'contact',
'type' => 'text',
'required' => false,
'attributes' => array(
'autocomplete' => 'off',
'maxLength' => 11,
'pattern' => '[0-9]{11}',
'title' => 'Undici cifre, senza spazi e senza il prefisso IT',
),
)
);
woocommerce_register_additional_checkout_field(
array(
'id' => 'cosmocode/codice-destinatario',
'label' => 'Codice destinatario SdI',
'optionalLabel' => 'Codice destinatario (opzionale)',
'location' => 'contact',
'type' => 'text',
'required' => false,
'attributes' => array(
'maxLength' => 7,
'title' => 'Sette caratteri, oppure 0000000 se non lo hai',
),
)
);
} );Nota il formato dell’identificativo: uno spazio dei nomi, una barra e il nome del campo. È obbligatorio e serve a evitare collisioni con altri plugin.
Validare i campi checkout WooCommerce lato server
Senza validazione hai solo spostato il problema più avanti, allo scarto del Sistema di Interscambio. La partita IVA italiana ha un carattere di controllo calcolato con l’algoritmo di Luhn, quindi puoi verificarla lato server senza interrogare nessun servizio esterno.
function cosmocode_valida_partita_iva( $piva ) {
if ( ! preg_match( '/^[0-9]{11}$/', $piva ) ) {
return false;
}
$somma = 0;
for ( $i = 0; $i < 11; $i++ ) {
$cifra = (int) $piva[ $i ];
if ( 1 === $i % 2 ) {
$cifra *= 2;
if ( $cifra > 9 ) {
$cifra -= 9;
}
}
$somma += $cifra;
}
return 0 === $somma % 10;
}
add_action( 'woocommerce_sanitize_additional_field', function ( $value, $key ) {
if ( 'cosmocode/partita-iva' === $key ) {
$value = preg_replace( '/[^0-9]/', '', $value );
}
if ( 'cosmocode/codice-destinatario' === $key ) {
$value = strtoupper( preg_replace( '/[^A-Za-z0-9]/', '', $value ) );
}
return $value;
}, 10, 2 );
add_action( 'woocommerce_validate_additional_field', function ( WP_Error $errors, $key, $value ) {
if ( 'cosmocode/partita-iva' === $key && '' !== $value ) {
if ( ! cosmocode_valida_partita_iva( $value ) ) {
$errors->add(
'cosmocode_piva_non_valida',
'La partita IVA inserita non è valida. Controlla le undici cifre.'
);
}
}
if ( 'cosmocode/codice-destinatario' === $key && '' !== $value ) {
if ( ! preg_match( '/^[A-Z0-9]{6,7}$/', $value ) ) {
$errors->add(
'cosmocode_sdi_non_valido',
'Il codice destinatario deve avere 6 o 7 caratteri alfanumerici.'
);
}
}
}, 10, 3 );La sanificazione gira prima della validazione e serve a normalizzare il dato: toglie spazi, punti e il prefisso IT che i clienti inseriscono sistematicamente. La validazione blocca l’ordine e mostra il messaggio direttamente sotto il campo.
Un dettaglio importante: l’hook di validazione deve aggiungere gli errori all’oggetto WP_Error che riceve. Se restituisci un oggetto nuovo, gli errori non compaiono e l’ordine passa lo stesso.
Mostrare i campi checkout WooCommerce solo alle aziende
Le versioni recenti supportano condizioni scritte in JSON Schema sulle proprietà required e hidden. Aggiungi un selettore del tipo di cliente e leghi i campi fiscali al suo valore.
woocommerce_register_additional_checkout_field(
array(
'id' => 'cosmocode/tipo-cliente',
'label' => 'Tipo di cliente',
'location' => 'contact',
'type' => 'select',
'required' => true,
'placeholder' => 'Seleziona una voce',
'options' => array(
array( 'value' => 'privato', 'label' => 'Privato' ),
array( 'value' => 'azienda', 'label' => 'Azienda o professionista' ),
),
)
);
// Da usare nell'array di registrazione della partita IVA.
$solo_aziende = array(
'type' => 'object',
'properties' => array(
'customer' => array(
'properties' => array(
'additional_fields' => array(
'properties' => array(
'cosmocode/tipo-cliente' => array( 'const' => 'azienda' ),
),
),
),
),
),
);Passi $solo_aziende alla chiave required del campo partita IVA e la condizione inversa alla chiave hidden. Verifica il comportamento su un ambiente di staging prima di andare in produzione, perché la valutazione dello schema dipende dalla versione di WooCommerce installata.
Campi checkout WooCommerce nel checkout classico
Se il sito usa ancora lo shortcode, il lavoro è diverso e più breve.
add_filter( 'woocommerce_checkout_fields', function ( $fields ) {
$fields['billing']['billing_partita_iva'] = array(
'label' => 'Partita IVA',
'required' => false,
'class' => array( 'form-row-first' ),
'priority' => 35,
);
$fields['billing']['billing_codice_destinatario'] = array(
'label' => 'Codice destinatario SdI',
'required' => false,
'class' => array( 'form-row-last' ),
'priority' => 36,
);
return $fields;
} );
add_action( 'woocommerce_checkout_process', function () {
$piva = isset( $_POST['billing_partita_iva'] )
? sanitize_text_field( wp_unslash( $_POST['billing_partita_iva'] ) )
: '';
if ( '' !== $piva && ! cosmocode_valida_partita_iva( $piva ) ) {
wc_add_notice( 'La partita IVA inserita non è valida.', 'error' );
}
} );
add_action( 'woocommerce_checkout_create_order', function ( $order, $data ) {
if ( ! empty( $_POST['billing_partita_iva'] ) ) {
$order->update_meta_data(
'_billing_partita_iva',
sanitize_text_field( wp_unslash( $_POST['billing_partita_iva'] ) )
);
}
}, 10, 2 );Usa woocommerce_checkout_create_order per salvare i metadati invece dei vecchi hook basati sull’ID ordine: è l’approccio compatibile con l’archiviazione ordini ad alte prestazioni, che nelle installazioni recenti è attiva per impostazione predefinita.
Dove finiscono i dati dei campi checkout WooCommerce
Con l’API a blocchi non decidi tu la chiave del metadato. WooCommerce antepone un prefisso in base alla posizione del campo: _wc_other/ per contatto e ordine, _wc_billing/ e _wc_shipping/ per gli indirizzi.
$order = wc_get_order( $order_id );
$piva = $order->get_meta( '_wc_other/cosmocode/partita-iva' );
$sdi = $order->get_meta( '_wc_other/cosmocode/codice-destinatario' );È il punto in cui i campi checkout WooCommerce smettono di essere un esercizio di frontend e diventano il ponte verso la fatturazione: quei due valori finiscono dritti nei blocchi CessionarioCommittente e DatiTrasmissione del file XML. Il passaggio successivo lo trovi nella guida su come generare in automatico le fatture elettroniche XML da WooCommerce.
5 errori che vediamo più spesso
Sono i problemi che ci arrivano più di frequente quando un cliente ci chiede di sistemare campi checkout WooCommerce aggiunti da qualcun altro.
- Rendere i campi obbligatori per tutti. Un consumatore privato che si trova davanti la richiesta della partita IVA abbandona il carrello. Condizionali o niente.
- Validare solo lato client. L’attributo
patternmigliora l’esperienza ma si aggira in tre secondi con gli strumenti per sviluppatori. La validazione lato server non è opzionale. - Dimenticare le ditte individuali. Hanno partita IVA e codice fiscale diversi e servono entrambi. Un solo campo genera fatture scartate.
- Non normalizzare l’input. Gli utenti scrivono IT01234567890, mettono spazi, incollano da un PDF con caratteri invisibili. Senza sanificazione quei valori arrivano intatti nell’XML.
- Personalizzare senza tema child. Il primo aggiornamento del tema cancella tutto. Plugin custom o tema child, sempre.
Codice su misura o plugin già pronto?
La risposta onesta dipende da cosa ti serve, e non è sempre il codice.
Scrivere codice per i campi checkout WooCommerce ha senso quando i campi da aggiungere sono pochi, il flusso è standard e in azienda c’è chi può metterci mano dopo un aggiornamento di WooCommerce. Il vantaggio è il controllo totale e nessuna dipendenza esterna.
Un plugin ha senso quando i campi fiscali sono solo l’inizio, cioè quando ti serve anche generare l’XML, numerare le fatture, gestire il regime forfettario, inviare al Sistema di Interscambio e conservare i documenti. In quel caso stai per riscrivere un gestionale, e conviene partire da qualcosa che esiste già. Sul tema abbiamo una guida dedicata a come configurare la fattura elettronica su WooCommerce.
Domande Frequenti
In sintesi
Personalizzare i campi checkout WooCommerce per la fatturazione italiana richiede prima di tutto una diagnosi: capire se hai il checkout a blocchi o quello classico, perché gli strumenti sono diversi e non intercambiabili. Poi registrazione, sanificazione, validazione lato server e lettura dei valori nel formato giusto.
Se preferisci che se ne occupi qualcuno, sviluppiamo plugin WordPress e integrazioni WooCommerce su misura da anni. Raccontaci il tuo progetto e ti diciamo in modo diretto se conviene scrivere codice o partire da una soluzione esistente.