View Categories

Hook per personalizzazione dati

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:

  1. Calcolo di centro ricavo, marca da bollo (stamp_duty), dati fiscali del cliente, ei_raw per clienti esteri, destinazione DDT.
  2. Costruzione dell’array $data_pre.
  3. Log del payload con wfic_log(print_r($data_pre, true)).
  4. Esecuzione del filtro add_custom_data_pre_wfic.
  5. json_encode($data_pre) e inclusione di send_data.php, che esegue la chiamata.

Firma e parametri #

$data_pre = apply_filters( 'add_custom_data_pre_wfic', $data_pre, $id_ordine_scelto, $order );
ParametroTipoDescrizione
$data_prearrayPayload completo del documento da inviare a Fatture in Cloud (struttura nella sezione successiva).
$id_ordine_sceltoint|stringIdentificativo dell’ordine usato anche in visible_subject. Viene valorizzato a monte di questo file: verificare se corrisponde all’ID o al numero ordine.
$orderWC_OrderOggetto 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 dataValore assegnato dal plugin
entity$entity_result (dati cliente)
type$doc_type_wfic (es. invoice, receipt, delivery_note)
language.codeit
visible_subjectopzione woo_fic_oggetto_custom (default “Ordine numero”) + $id_ordine_scelto
rc_centeropzione 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_duty0 o 2 secondo la logica marca da bollo
use_gross_pricesfalse
e_invoice$invoice_elet_type_wfic
amount_net, amount_vat, amount_grosscalcolati 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_listun solo pagamento: amount, due_date, paid_date, status, payment_account
show_payments, show_payment_method, show_totalstrue, $mostra_info_pagamento, all
ei_data.payment_method$payment_method_fic_ei_code
payment_method.id$payment_method_woo_fic_order
ei_rawnull, 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 return o restituisce un valore non array, json_encode() produce null o 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_vat o amount_gross, i totali e payments_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. Per ei_raw, che può essere null, usare array_replace_recursive( (array) $data_pre['data']['ei_raw'], [...] ).
  • Logica già eseguita. Al momento del filtro marca da bollo e contatore count_wfic_marca_bollo sono già stati elaborati: cambiare stamp_duty nel 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.

Powered by BetterDocs