L’ Hook WordPress add_custom_data_pre_wfic permette di personalizzare la generazione delle fatture su Fattureincloud.it
Utilizzando la funzionalità nativa dei WordPress Hooks illustrata nella documentazione ufficiale:
https://developer.wordpress.org/plugins/hooks/
è possibile modificare i dati generati nei documenti generati su Fatture in Cloud inviati tramite la variabile $data_pre
Panoramica #
add_custom_data_pre_wfic è un filtro WordPress che permette di modificare il payload del documento (fattura, ricevuta, DDT, ecc.) subito prima che venga codificato in JSON e inviato all’endpoint Fatture in Cloud API v2 POST https://api-v2.fattureincloud.it/c/{company_id}/issued_documents.
Sequenza nel file di invio:
- Calcolo di centro ricavo, marca da bollo (
stamp_duty), dati fiscali del cliente,ei_rawper clienti esteri, destinazione DDT. - Costruzione dell’array
$data_pre. - Log del payload con
wfic_log(print_r($data_pre, true)). - Esecuzione del filtro
add_custom_data_pre_wfic. json_encode($data_pre)e inclusione disend_data.php, che esegue la chiamata.
Firma e parametri #
$data_pre = apply_filters( 'add_custom_data_pre_wfic', $data_pre, $id_ordine_scelto, $order );| Parametro | Tipo | Descrizione |
|---|---|---|
$data_pre | array | Payload completo del documento da inviare a Fatture in Cloud (struttura nella sezione successiva). |
$id_ordine_scelto | int|string | Identificativo dell’ordine usato anche in visible_subject. Viene valorizzato a monte di questo file: verificare se corrisponde all’ID o al numero ordine. |
$order | WC_Order | Oggetto ordine WooCommerce. |
Ritorno: l’array $data_pre, modificato o invariato. Il valore restituito viene passato direttamente a json_encode() e inviato.
Per ricevere tutti e tre i parametri la callback va registrata con accepted_args = 3:
add_filter( 'add_custom_data_pre_wfic', 'mia_callback', 10, 3 );Struttura di $data_pre #
L’array ha due chiavi di primo livello: options (contiene solo fix_payments => true) e data, che contiene i campi del documento. Le chiavi di data impostate dal plugin:
Chiave in data | Valore assegnato dal plugin |
|---|---|
entity | $entity_result (dati cliente) |
type | $doc_type_wfic (es. invoice, receipt, delivery_note) |
language.code | it |
visible_subject | opzione woo_fic_oggetto_custom (default “Ordine numero”) + $id_ordine_scelto |
rc_center | opzione woo_fic_ricavo o stringa vuota |
numeration | $sezionale_woofatture |
notes | $order_note |
dn_ai_causal, dn_ai_destination | “Vendita” e indirizzo di spedizione/fatturazione, solo per delivery_note; altrimenti vuoti |
rivalsa, cassa, withholding_tax | $rivalsa, $cassa_wfic, $ritenuta |
stamp_duty | 0 o 2 secondo la logica marca da bollo |
use_gross_prices | false |
e_invoice | $invoice_elet_type_wfic |
amount_net, amount_vat, amount_gross | calcolati da $order_data['total'] e $order_data['total_tax'] |
date | $data_scadenza |
ei_cassa_type, ei_withholding_tax_causal | $tipo_cassa (o null), $causale_ritenuta |
items_list | $lista_articoli_api2 |
payments_list | un solo pagamento: amount, due_date, paid_date, status, payment_account |
show_payments, show_payment_method, show_totals | true, $mostra_info_pagamento, all |
ei_data.payment_method | $payment_method_fic_ei_code |
payment_method.id | $payment_method_woo_fic_order |
ei_raw | null, oppure IdFiscaleIVA con IdCodice = ESTERO per clienti esteri senza CF/P.IVA in fattura elettronica |
I nomi e i valori ammessi dei campi sono quelli dell’endpoint issued_documents dell’API v2 di Fatture in Cloud: per aggiungere campi non presenti qui fare riferimento alla documentazione ufficiale dell’API.
Esempi d’uso #
Esempi per esigenze di settore che il plugin non copre di serie. Il codice va in un mu-plugin, in un plugin custom o nel functions.php del tema child. Lle chiavi meta (_vet_*) e gli slug di categoria (noleggio, soggiorni) sono segnaposto da adattare ai campi del checkout e del catalogo.
1. Veterinario: dati del paziente nelle righe del documento
Aggiunge nome dell’animale e microchip alla descrizione di ogni riga, così la prestazione resta riconducibile al paziente.
add_filter( 'add_custom_data_pre_wfic', function ( $data_pre, $id_ordine, $order ) {
$animale = $order->get_meta( '_vet_nome_animale' );
$microchip = $order->get_meta( '_vet_microchip' );
if ( empty( $animale ) && empty( $microchip ) ) {
return $data_pre;
}
$rif = array_filter( [
$animale ? 'Paziente: ' . $animale : '',
$microchip ? 'Microchip: ' . $microchip : '',
] );
$rif = implode( ' - ', $rif );
foreach ( $data_pre['data']['items_list'] as $i => $riga ) {
$descrizione = $riga['description'] ?? '';
$data_pre['data']['items_list'][ $i ]['description'] = trim( $descrizione . "\n" . $rif );
}
return $data_pre;
}, 10, 3 );2. Noleggio attrezzature: causale del DDT
Se l’ordine contiene prodotti della categoria noleggio, il DDT esce con causale “Noleggio” invece di “Vendita”.
add_filter( 'add_custom_data_pre_wfic', function ( $data_pre, $id_ordine, $order ) {
if ( $data_pre['data']['type'] !== 'delivery_note' ) {
return $data_pre;
}
foreach ( $order->get_items() as $item ) {
if ( has_term( 'noleggio', 'product_cat', $item->get_product_id() ) ) {
$data_pre['data']['dn_ai_causal'] = 'Noleggio';
break;
}
}
return $data_pre;
}, 10, 3 );3. Agriturismo: centro di ricavo per soggiorni e ristorazione
Assegna il centro di ricavo “Alloggio” agli ordini di soli soggiorni e “Ristorazione e prodotti” agli altri; sugli ordini misti resta il centro impostato nel plugin.
add_filter( 'add_custom_data_pre_wfic', function ( $data_pre, $id_ordine, $order ) {
$categorie = [];
foreach ( $order->get_items() as $item ) {
if ( has_term( 'soggiorni', 'product_cat', $item->get_product_id() ) ) {
$categorie['Alloggio'] = true;
} else {
$categorie['Ristorazione e prodotti'] = true;
}
}
if ( count( $categorie ) === 1 ) {
$data_pre['data']['rc_center'] = array_key_first( $categorie );
}
return $data_pre;
}, 10, 3 );Note e avvertenze #
- Restituire sempre l’array. Se la callback non ha
returno restituisce un valore non array,json_encode()producenullo un payload vuoto e l’invio fallisce. - Il log precede il filtro. La riga
[INVIO] data inviati =>mostra il payload prima delle modifiche; per vedere quello effettivamente inviato registrare una callback con priorità PHP_INT_MAX che chiami wfic_log(). - Coerenza degli importi. Se si modificano
items_list,amount_net,amount_vatoamount_gross, i totali epayments_list[0]['amount']devono restare coerenti con le righe, altrimenti l’API può rifiutare il documento. - Modificare, non sostituire. Lavorare sulle singole chiavi (
$data_pre['data']['...']) invece di ricostruire l’array, per non perdere i campi calcolati dal plugin. Perei_raw, che può esserenull, usarearray_replace_recursive( (array) $data_pre['data']['ei_raw'], [...] ). - Logica già eseguita. Al momento del filtro marca da bollo e contatore
count_wfic_marca_bollosono già stati elaborati: cambiarestamp_dutynel filtro non aggiorna il contatore. - Nessun annullamento. Il filtro non prevede un modo per bloccare l’invio; il documento parte comunque con il payload restituito.
