Ficoo – Filtri e azioni personalizzabili #

Ficoo mette a disposizione una serie di filtri e azioni WordPress che permettono di personalizzare il comportamento del plugin senza modificare il codice sorgente. Questi hook possono essere usati nel file functions.php del tema o in un plugin personalizzato.

Documento #

ficoo_core_custom_filter_document_numeration #

Modifica la numerazione del documento prima dell’invio a Fatture in Cloud.

Parametro	Tipo	Descrizione
$numeration	string	Numerazione corrente (da impostazioni Ficoo)
$order_object	WC_Order	Oggetto ordine WooCommerce

add_filter( 'ficoo_core_custom_filter_document_numeration', function( $numeration, $order_object ) {
    // Usa una numerazione diversa per gli ordini internazionali.
    if ( 'IT' !== $order_object->get_billing_country() ) {
        return 'INT';
    }
    return $numeration;
}, 10, 2 );

---

ficoo_core_custom_filter_document_subject #

Modifica l’oggetto nascosto del documento (campo “subject” su Fatture in Cloud).

Parametro	Tipo	Descrizione
$subject	string	Oggetto nascosto con i placeholder già sostituiti
$order_object	WC_Order	Oggetto ordine WooCommerce

add_filter( 'ficoo_core_custom_filter_document_subject', function( $subject, $order_object ) {
    return $subject . ' - Rif. cliente: ' . $order_object->get_billing_company();
}, 10, 2 );

---

ficoo_core_custom_filter_document_visible_subject #

Modifica l’oggetto visibile del documento (stampato sul documento).

Parametro	Tipo	Descrizione
$visible_subject	string	Oggetto visibile con i placeholder già sostituiti
$order_object	WC_Order	Oggetto ordine WooCommerce

add_filter( 'ficoo_core_custom_filter_document_visible_subject', function( $visible_subject, $order_object ) {
    return 'Ordine WooCommerce #' . $order_object->get_id();
}, 10, 2 );

---

ficoo_core_custom_filter_document_rc_center #

Modifica il centro di ricavo/costo (rc_center) del documento.

Parametro	Tipo	Descrizione
$rc_center	string	Centro di ricavo/costo corrente (da impostazioni Ficoo)
$order_object	WC_Order	Oggetto ordine WooCommerce

add_filter( 'ficoo_core_custom_filter_document_rc_center', function( $rc_center, $order_object ) {
    // Imposta il rc_center in base al paese di fatturazione.
    return $order_object->get_billing_country();
}, 10, 2 );

---

ficoo_core_custom_filter_prepare_document_request #

Filtro finale sulla request completa del documento, prima dell’invio all’API di Fatture in Cloud. Permette di modificare qualsiasi campo della request.

Parametro	Tipo	Descrizione
$php_object_request	array	Array completo della request (data, options, ecc.)
$order_object	WC_Order	Oggetto ordine WooCommerce

add_filter( 'ficoo_core_custom_filter_prepare_document_request', function( $request, $order_object ) {
    // Aggiungi una nota personalizzata al documento.
    $request['data']['notes'] = 'Grazie per il tuo ordine!';
    return $request;
}, 10, 2 );

Tipo documento #

ficoo_core_custom_filter_document_type_processed_orders #

Modifica il tipo di documento per ordini processati da Ficoo (ordini con i campi fiscali compilati al checkout).

Parametro	Tipo	Descrizione
$doc_type	string	Tipo documento corrente (invoice, receipt, proforma, ecc.)
$order_object	WC_Order	Oggetto ordine WooCommerce

add_filter( 'ficoo_core_custom_filter_document_type_processed_orders', function( $doc_type, $order_object ) {
    // Forza proforma per ordini con pagamento in contrassegno.
    if ( 'cod' === $order_object->get_payment_method() ) {
        return 'proforma';
    }
    return $doc_type;
}, 10, 2 );

---

ficoo_core_custom_filter_document_type_unprocessed_orders #

Modifica il tipo di documento per ordini NON processati da Ficoo (ordini creati manualmente o da altri plugin).

Parametro	Tipo	Descrizione
$doc_type	string	Tipo documento corrente (stringa vuota di default)
$order_object	WC_Order	Oggetto ordine WooCommerce

add_filter( 'ficoo_core_custom_filter_document_type_unprocessed_orders', function( $doc_type, $order_object ) {
    // Default a ricevuta per ordini non processati.
    return 'receipt';
}, 10, 2 );

Cliente #

ficoo_core_custom_filter_customer_billing_array #

Modifica i dati di fatturazione del cliente prima della creazione/ricerca su Fatture in Cloud.

Parametro	Tipo	Descrizione
$customer_billing_array	array	Array con i dati del cliente (name, vat_number, tax_code, ecc.)
$billing_data	array	Contesto: order_object, document_type, orig_customer_array

add_filter( 'ficoo_core_custom_filter_customer_billing_array', function( $customer, $billing_data ) {
    // Forza il codice fiscale in maiuscolo.
    if ( isset( $customer['tax_code'] ) ) {
        $customer['tax_code'] = strtoupper( $customer['tax_code'] );
    }
    return $customer;
}, 10, 2 );

---

ficoo_core_custom_filter_update_wp_user_from_fic_client_billing_map #

Modifica la mappa di corrispondenza tra i campi del cliente su Fatture in Cloud e i meta WordPress per i dati di fatturazione. Viene applicato durante la sincronizzazione via webhook (automazione “Update Clients”).

Parametro	Tipo	Descrizione
$billing_map	array	Array associativo campo_fic => meta_wp per i dati di fatturazione
$client	array	Dati del cliente ricevuti da Fatture in Cloud
$webhook_context	mixed	Contesto del webhook (può essere null fuori dal flusso webhook)

add_filter( 'ficoo_core_custom_filter_update_wp_user_from_fic_client_billing_map', function( $billing_map, $client, $webhook_context ) {
    // Mappa anche il campo "website" di FIC a un meta personalizzato.
    $billing_map['web_site'] = 'billing_website';
    return $billing_map;
}, 10, 3 );

---

ficoo_core_custom_filter_update_wp_user_from_fic_client_fiscal_map_legacy #

Modifica la mappa dei campi fiscali Ficoo salvati come user meta standard (checkout legacy). Viene applicato durante la sincronizzazione via webhook (automazione “Update Clients”).

Parametro	Tipo	Descrizione
$fiscal_map_legacy	array	Array associativo campo_fic => meta_wp per i campi fiscali (legacy shortcode)
$client	array	Dati del cliente ricevuti da Fatture in Cloud
$webhook_context	mixed	Contesto del webhook

add_filter( 'ficoo_core_custom_filter_update_wp_user_from_fic_client_fiscal_map_legacy', function( $fiscal_map, $client, $webhook_context ) {
    // Rimuovi la sincronizzazione del codice SDI.
    unset( $fiscal_map['ei_code'] );
    return $fiscal_map;
}, 10, 3 );

---

ficoo_core_custom_filter_update_wp_user_from_fic_client_fiscal_map_block #

Modifica la mappa dei campi fiscali Ficoo salvati come user meta per il Block Checkout. Viene applicato durante la sincronizzazione via webhook (automazione “Update Clients”).

Parametro	Tipo	Descrizione
$fiscal_map_block	array	Array associativo campo_fic => meta_wp per i campi fiscali (Block Checkout)
$client	array	Dati del cliente ricevuti da Fatture in Cloud
$webhook_context	mixed	Contesto del webhook

add_filter( 'ficoo_core_custom_filter_update_wp_user_from_fic_client_fiscal_map_block', function( $fiscal_map, $client, $webhook_context ) {
    // Rimuovi la sincronizzazione del codice SDI anche per Block Checkout.
    unset( $fiscal_map['ei_code'] );
    return $fiscal_map;
}, 10, 3 );

---

ficoo_core_customer_filter_schedule_email_request #

Permette di saltare l’invio automatico dell’email al cliente dopo la creazione del documento su Fatture in Cloud. Restituisci true per saltare l’invio, false per inviarla. Il valore di default ricevuto dal filtro corrisponde al parametro $skip_auto_email di handle_create_document_request(): false nel flusso automatico (checkout), true quando l’invio è stato disabilitato dall’utente tramite l’opzione “manual send” nella pagina di modifica ordine.

Parametro	Tipo	Descrizione
$skip_auto_email	bool	Flag corrente (proveniente dal parametro del metodo handle_create_document_request)
$php_object_request	array	Payload della richiesta inviata a Fatture in Cloud
$php_object_response	array	Risposta ricevuta da Fatture in Cloud (contiene i dati del documento creato)
$order_object	WC_Order	Oggetto ordine WooCommerce

add_filter( 'ficoo_core_customer_filter_schedule_email_request', function( $skip_auto_email, $request, $response, $order_object ) {
    // Salta l'invio automatico per gli ordini con metodo di pagamento "bonifico".
    if ( 'bacs' === $order_object->get_payment_method() ) {
        return true;
    }
    return $skip_auto_email;
}, 10, 4 );

Prodotti e Items #

ficoo_core_custom_filter_item_title #

Modifica il nome/titolo di un prodotto nella lista articoli del documento.

Parametro	Tipo	Descrizione
$name	string	Nome del prodotto
$item	WC_Order_Item	Item dell’ordine WooCommerce

add_filter( 'ficoo_core_custom_filter_item_title', function( $name, $item ) {
    // Aggiungi il SKU al nome del prodotto.
    $product = $item->get_product();
    if ( $product && $product->get_sku() ) {
        return $product->get_sku() . ' - ' . $name;
    }
    return $name;
}, 10, 2 );

---

ficoo_core_custom_filter_product_item #

Modifica un singolo elemento prodotto prima che venga aggiunto alla lista articoli del documento.

Parametro	Tipo	Descrizione
$product_item	array	Array del prodotto (name, net_price, gross_price, vat, discount, ecc.)
$item	WC_Order_Item	Item dell’ordine WooCommerce
$wc_item	WC_Product o false	Prodotto WooCommerce (false se eliminato dal catalogo)
$order_object	WC_Order	Oggetto ordine WooCommerce

add_filter( 'ficoo_core_custom_filter_product_item', function( $product_item, $item, $wc_item, $order_object ) {
    // Aggiungi una descrizione personalizzata.
    $product_item['description'] = 'Rif. ordine #' . $order_object->get_id();
    return $product_item;
}, 10, 4 );

---

ficoo_core_custom_filter_product_attribute_terms #

Modifica la lista degli attributi di un prodotto visualizzati nella descrizione dell’articolo in documento.

Parametro	Tipo	Descrizione
$attributes_list	array	Array associativo label => value degli attributi
$product	WC_Product	Oggetto prodotto WooCommerce

add_filter( 'ficoo_core_custom_filter_product_attribute_terms', function( $attributes, $product ) {
    // Rimuovi l'attributo colore dalla descrizione.
    unset( $attributes['Colore'] );
    return $attributes;
}, 10, 2 );

Checkout #

ficoo_core_custom_filter_checkout_fields #

Modifica i campi fiscali Ficoo visualizzati al checkout classico (legacy shortcode).

Parametro	Tipo	Descrizione
$fields	array	Array dei campi di checkout Ficoo

add_filter( 'ficoo_core_custom_filter_checkout_fields', function( $fields ) {
    // Rendi la PEC obbligatoria.
    if ( isset( $fields['billing_ficoo_customer_email_pec'] ) ) {
        $fields['billing_ficoo_customer_email_pec']['required'] = true;
    }
    return $fields;
} );

---

ficoo_core_custom_filter_checkout_fields_properties #

Modifica le proprietà (classi CSS, priorità, required) dei campi al checkout classico, inclusi i campi standard di WooCommerce.

Parametro	Tipo	Descrizione
$fields	array	Array completo dei campi di checkout WooCommerce

add_filter( 'ficoo_core_custom_filter_checkout_fields_properties', function( $fields ) {
    // Cambia la priorità del campo azienda.
    $fields['billing']['billing_company']['priority'] = 25;
    return $fields;
} );

---

ficoo_core_custom_filter_stop_if_different_shipping_country #

Blocca l’invio del checkout se il paese di spedizione è diverso dal paese di fatturazione.

Parametro	Tipo	Descrizione
$stop	bool	false di default. Ritorna true per attivare il blocco

add_filter( 'ficoo_core_custom_filter_stop_if_different_shipping_country', '__return_true' );

---

ficoo_core_custom_filter_clean_unused_checkout_fields #

Pulisce (svuota) i campi fiscali Ficoo quando non sono necessari (es. quando il cliente sceglie ricevuta).

Parametro	Tipo	Descrizione
$clean	bool	false di default. Ritorna true per attivare la pulizia

add_filter( 'ficoo_core_custom_filter_clean_unused_checkout_fields', '__return_true' );

---

ficoo_core_custom_filter_vat_is_valid Ficoo Pro #

Modifica il risultato della validazione della Partita IVA al checkout classico. Disponibile solo con Ficoo Pro.

Parametro	Tipo	Descrizione
$vat_is_valid	bool	Risultato della validazione
$is_eu_country	bool	Se il paese è nell’Unione Europea
$country	string	Codice ISO del paese
$vat_number	string	Partita IVA inserita

add_filter( 'ficoo_core_custom_filter_vat_is_valid', function( $valid, $is_eu, $country, $vat ) {
    // Accetta sempre P.IVA svizzere.
    if ( 'CH' === $country ) {
        return true;
    }
    return $valid;
}, 10, 4 );

---

ficoo_pro_custom_filter___bypass_vies_validation___ Ficoo Pro #

Bypassa la verifica VIES per la Partita IVA estera al checkout Block. Se restituisce true, l’esenzione IVA viene applicata senza interrogare il servizio VIES.

Parametro	Tipo	Descrizione
$bypass	bool	false di default. Ritorna true per bypassare VIES
$vat_number	string	Partita IVA inserita
$target_country	string	Codice ISO del paese di fatturazione

add_filter( 'ficoo_pro_custom_filter___bypass_vies_validation___', function( $bypass, $vat_number, $target_country ) {
    // Bypassa VIES per clienti svizzeri (non-UE, ma accettati).
    if ( 'CH' === $target_country ) {
        return true;
    }
    return $bypass;
}, 10, 3 );

---

ficoo_pro_custom_filter___validate_foreign_tax_code Ficoo Pro #

Gestisce la validazione del codice fiscale per clienti stranieri (non italiani). Di default Ficoo restituisce true (valido) per i codici fiscali esteri; questo filtro permette di implementare una logica personalizzata.

Parametro	Tipo	Descrizione
$is_valid	bool	true di default per clienti non italiani
$args	array	Contesto: doc_type, billing_or_shipping_country, tax_code

add_filter( 'ficoo_pro_custom_filter___validate_foreign_tax_code', function( $is_valid, $args ) {
    // Richiedi almeno 5 caratteri per CF esteri.
    return strlen( $args['tax_code'] ) >= 5;
}, 10, 2 );

---

ficoo_pro_custom_filter___validate_tax_code Ficoo Pro #

Gestisce la validazione di codici fiscali italiani che non rientrano nei formati standard (11 cifre numeriche o 16 caratteri alfanumerici). Di default Ficoo restituisce false (non valido) per questi casi.

Parametro	Tipo	Descrizione
$is_valid	bool	false di default per formati non standard
$args	array	Contesto: doc_type, billing_or_shipping_country, tax_code

add_filter( 'ficoo_pro_custom_filter___validate_tax_code', function( $is_valid, $args ) {
    // Accetta anche codici fiscali di lunghezza 11 non numerici (es. stranieri residenti).
    if ( strlen( $args['tax_code'] ) === 11 ) {
        return true;
    }
    return $is_valid;
}, 10, 2 );

---

ficoo_pro_custom_filter___apply_ritenuta_only_dor_italian_customers Ficoo Pro #

Limita l’applicazione della ritenuta d’acconto al carrello ai soli clienti italiani. Di default la ritenuta viene applicata a tutti i clienti.

Parametro	Tipo	Descrizione
$only_it	bool	false di default. Ritorna true per limitare ai clienti italiani

add_filter( 'ficoo_pro_custom_filter___apply_ritenuta_only_dor_italian_customers', '__return_true' );

---

ficoo_pro_custom_filter_finalize_corrispettivi Ficoo Pro #

Filtro finale sulla request del corrispettivo prima dell’invio all’API di Fatture in Cloud. Permette di modificare qualsiasi campo della request dopo la trasformazione in formato corrispettivo.

Parametro	Tipo	Descrizione
$php_object_request	array	Array completo della request del corrispettivo
$order_object	WC_Order	Oggetto ordine WooCommerce

add_filter( 'ficoo_pro_custom_filter_finalize_corrispettivi', function( $request, $order_object ) {
    // Forza l'autocomplete del numero documento.
    $request['autocomplete_number'] = true;
    return $request;
}, 10, 2 );

Webhook e Automazioni Ficoo Pro #

ficoo_webhook_automation_catalog #

Permette di aggiungere nuove automazioni al catalogo webhook di Ficoo o di modificare quelle esistenti. Le automazioni aggiunte via questo filtro appaiono nell’interfaccia di configurazione webhook del plugin.

Parametro	Tipo	Descrizione
$catalog	array	Array associativo action_id => array(domain, label, description)

Struttura di una voce del catalogo:

'my_custom_action' => array(
    'domain'      => 'products',   // 'products', 'documents', 'entities'
    'label'       => 'Descrizione breve',
    'description' => 'Descrizione estesa mostrata nell\'interfaccia.',
),

add_filter( 'ficoo_webhook_automation_catalog', function( $catalog ) {
    $catalog['my_sync_action'] = array(
        'domain'      => 'products',
        'label'       => 'Sincronizza prezzo personalizzato',
        'description' => 'Aggiorna il meta _custom_price del prodotto WooCommerce quando il prodotto FIC viene modificato.',
    );
    return $catalog;
} );

---

ficoo_pro_webhook_received Azione Ficoo Pro #

Si attiva ogni volta che un webhook viene ricevuto da Fatture in Cloud e superato il controllo di deduplicazione. Permette di agganciare logiche personalizzate a qualsiasi evento webhook FIC.

Parametro	Tipo	Descrizione
$event_type	string	Tipo CloudEvents (es. it.fattureincloud.webhooks.products.update)
$resource_ids	array	Array di ID risorsa FIC coinvolti nell’evento
$data	array	Payload dell’evento (contiene l’array ids)
$body	array	Envelope CloudEvents completo grezzo

add_action( 'ficoo_pro_webhook_received', function( $event_type, $resource_ids, $data, $body ) {
    // Logga tutti gli eventi webhook in arrivo.
    error_log( '[MY_PLUGIN] Webhook FIC ricevuto: ' . $event_type . ' - IDs: ' . implode( ', ', $resource_ids ) );
}, 10, 4 );

---

ficoo_pro_webhook_received_{event_type} Azione Ficoo Pro #

Variante specifica per tipo evento dell’azione ficoo_pro_webhook_received. Il suffisso {event_type} viene sanificato con sanitize_key() (punti sostituiti da trattini). Permette di agganciare logiche a un singolo tipo di evento senza dover filtrare all’interno del callback.

Parametro	Tipo	Descrizione
$resource_ids	array	Array di ID risorsa FIC coinvolti nell’evento
$data	array	Payload dell’evento
$body	array	Envelope CloudEvents completo grezzo

Esempi di nome hook generato:

• ficoo_pro_webhook_received_it-fattureincloud-webhooks-products-update
• ficoo_pro_webhook_received_it-fattureincloud-webhooks-issued_documents-create

// Agisce solo sugli aggiornamenti di prodotto FIC.
add_action(
    'ficoo_pro_webhook_received_it-fattureincloud-webhooks-products-update',
    function( $resource_ids, $data, $body ) {
        foreach ( $resource_ids as $fic_product_id ) {
            // Esegui logica personalizzata per ogni prodotto aggiornato.
        }
    },
    10,
    3
);

Listino prezzi Ficoo Pro #

I filtri seguenti permettono di escludere specifici prodotti o variazioni dalla sovrascrittura del prezzo effettuata dalla funzionalità Listino Prezzi di Ficoo Pro. Tutti i filtri ricevono false come valore di default (nessuno skip).

ficoo_pro_custom_price_list_skip_simple_price #

Salta la sovrascrittura del prezzo generico per un prodotto semplice.

Parametro	Tipo	Descrizione
$skip	bool	false di default. Ritorna true per escludere il prodotto
$product	WC_Product	Oggetto prodotto WooCommerce

---

ficoo_pro_custom_price_list_skip_simple_regular_price #

Salta la sovrascrittura del prezzo di listino per un prodotto semplice.

Parametro	Tipo	Descrizione
$skip	bool	false di default. Ritorna true per escludere il prodotto
$product	WC_Product	Oggetto prodotto WooCommerce

---

ficoo_pro_custom_price_list_skip_simple_sale_price #

Salta la sovrascrittura del prezzo scontato per un prodotto semplice.

Parametro	Tipo	Descrizione
$skip	bool	false di default. Ritorna true per escludere il prodotto
$product	WC_Product	Oggetto prodotto WooCommerce

---

ficoo_pro_custom_price_list_skip_variation_price #

Salta la sovrascrittura del prezzo generico per una variazione di prodotto.

Parametro	Tipo	Descrizione
$skip	bool	false di default. Ritorna true per escludere la variazione
$product	WC_Product	Oggetto variazione WooCommerce

---

ficoo_pro_custom_price_list_skip_variation_regular_price #

Salta la sovrascrittura del prezzo di listino per una variazione di prodotto.

Parametro	Tipo	Descrizione
$skip	bool	false di default. Ritorna true per escludere la variazione
$product	WC_Product	Oggetto variazione WooCommerce

---

ficoo_pro_custom_price_list_skip_variation_sale_price #

Salta la sovrascrittura del prezzo scontato per una variazione di prodotto.

Parametro	Tipo	Descrizione
$skip	bool	false di default. Ritorna true per escludere la variazione
$product	WC_Product	Oggetto variazione WooCommerce

Esempio (pattern comune per i filtri skip del listino):

add_filter( 'ficoo_pro_custom_price_list_skip_simple_price', function( $skip, $product ) {
    // Escludi dal listino i prodotti con una categoria specifica.
    if ( has_term( 'escludi-listino', 'product_cat', $product->get_id() ) ) {
        return true;
    }
    return $skip;
}, 10, 2 );

Filtri deprecati #

I seguenti filtri sono ancora funzionanti ma deprecati. Verranno rimossi in una versione futura. Utilizzare i filtri sostitutivi indicati.

Filtro deprecato	Sostituto	Dalla versione
ficoo_core_filter___invoice_numeration___	ficoo_core_custom_filter_document_numeration	4.0.0
ficoo_core_custom_filter___set_document_type_for_processed_orders___	ficoo_core_custom_filter_document_type_processed_orders	4.0.0
ficoo_core_custom_filter___set_default_document_type_for_unprocessed_orders___	ficoo_core_custom_filter_document_type_unprocessed_orders	4.0.0
ficoo_core_custom_filter___edit_customer_billing_array___	ficoo_core_custom_filter_customer_billing_array	4.0.0
ficoo_core_custom_filter___override_items_title_on_document___	ficoo_core_custom_filter_item_title	4.0.0
ficoo_core_custom_filter___items_list_product_item___	ficoo_core_custom_filter_product_item	4.0.0
ficoo_core_custom_filter___product_attribute_terms___	ficoo_core_custom_filter_product_attribute_terms	4.0.0
ficoo_core_custom_filter___checkout_fields___	ficoo_core_custom_filter_checkout_fields	4.0.0
ficoo_core_user_filter___checkout_fields___	ficoo_core_custom_filter_checkout_fields	3.0.0
ficoo_core_custom_filter___override_fields_properties_on_checkout___	ficoo_core_custom_filter_checkout_fields_properties	4.0.0
ficoo_core_user_filter___override_fields_properties_on_checkout___	ficoo_core_custom_filter_checkout_fields_properties	3.0.0