Invoice Pilot

Invoice Pilot estende WooCommerce con una fatturazione country-aware per i 27 stati membri dell’UE. Cattura i campi di fatturazione corretti al checkout (codici SDI / PEC italiani, SIRET francese, Leitweg-ID tedesco, NIP polacco, CUI rumeno, e così via), poi emette fatture, note di credito, proforma e preventivi immutabili in PDF e XML a partire dall’ordine. Il PDF è renderizzato con mPDF; l’envelope XML viene scelto automaticamente dal paese del compratore e copre undici profili nazionali, tra cui FatturaPA (IT), XRechnung (DE), KSeF FA(2) (PL), Factur-X (FR), CIUS_RO (RO), Facturae (ES) e UBL 2.1 / PEPPOL BIS 3.0 come fallback generico.

Oltre al motore di documenti, Invoice Pilot include integrazioni di prima classe con sei provider contabili — SmartBill (Romania), Fatture in Cloud (Italia), Xero, QuickBooks Online, Fortnox (Svezia) e Sage — un validatore VAT che consulta il servizio europeo VIES con fallback su regex per paese, una dashboard con card KPI e grafici di trend, e un layer AI multi-provider opzionale (Anthropic Claude, OpenAI, Google Gemini, DeepSeek, Grok xAI) per smart-fill al checkout, pre-flight di compliance, traduzione delle righe e ricerca documenti in linguaggio naturale. Il plugin supporta anche WordPress Multisite, con tabelle per sito e una pagina di overview a livello network.

Punti di forza

• Ciclo di vita dei documenti WooCommerce-driven per fatture, note di credito, proforma e preventivi, con serie di numerazione riservate, un flusso pulito emetti / rigenera / riemetti / annulla / nota di credito, e styling per tipo di documento (banner disclaimer sui documenti non fiscali, etichette “Valido fino a” sui preventivi, “Totale rimborso” sulle note di credito, blocco pagamento nascosto su preventivi e note di credito).
• Campi di fatturazione per paese UE-27 registrati sia sul checkout shortcode legacy sia sul block checkout di WooCommerce 8.6+ (via Additional Checkout Fields API).
• Rendering PDF tramite mPDF usando uno dei tre template inclusi (Minimal, Classic, Modern), con selettore di colore accent, colore testo, font family e logo del venditore.
• Undici writer XML, dispatchati automaticamente dal paese del compratore: FatturaPA (IT), Factur-X / CII (FR), XRechnung 3.0 (DE), KSeF FA(2) (PL), CIUS_RO 1.0.0 (RO), Facturae 3.2.2 (ES), SAF-T PT (PT), OIOUBL (DK), Finvoice 3.0 (FI), ebInterface 6.1 (AT), myDATA InvoicesDoc (GR / EL), con UBL 2.1 / PEPPOL BIS 3.0 come fallback universale.
• Catena di validazione VAT che combina il servizio SOAP europeo VIES con validazione regex offline per paese, una cache DB-backed e un cron orario che rivalida le entry stale.
• Sei integrazioni contabili — SmartBill, Fatture in Cloud, Xero, QuickBooks Online, Fortnox e Sage — ciascuna con credenziali cifrate, operazioni di push / status / void e una coda di retry. La tab Integrations usa un selettore di provider sticky, così il pannello che stavi configurando resta aperto tra un salvataggio e l’altro.
• Layer AI opzionale con cinque provider (Anthropic, OpenAI, Google Gemini, DeepSeek, Grok xAI) che copre smart-fill, check di compliance, traduzione righe e ricerca in linguaggio naturale; il plugin funziona pienamente anche senza API key.
• Dashboard con selettore di periodo, cinque card KPI e due grafici di trend; un Integration Log separato registra ogni push e ogni fallimento.
• Supporto WordPress Multisite — ogni sub-site ha le proprie tabelle, impostazioni e contatori di numerazione, con una pagina network admin che aggrega le statistiche.

Requisiti

L’integrazione block-checkout è registrata sulla Additional Checkout Fields API di WooCommerce (introdotta in WooCommerce 8.6). Sulle versioni più vecchie di WooCommerce il filtro legacy woocommerce_billing_fields continua ad aggiungere i campi VAT, codice fiscale e country-specific allo shortcode checkout, così il plugin degrada con grazia.

Installazione

1. Scarica l’ultimo file ZIP di Invoice Pilot dalla pagina Releases  su GitHub.
2. In WordPress apri Plugin → Aggiungi nuovo → Carica plugin.
3. Scegli lo ZIP e clicca Installa ora.
4. Clicca Attiva plugin.
5. Apri Invoice Pilot → Impostazioni per configurare venditore, serie di numerazione e integrazioni opzionali.

L’attivazione crea le tabelle del plugin, installa le impostazioni di default e crea cinque serie di numerazione (una per tipo di documento): INV (fattura, default), REC (ricevuta), CN (nota di credito), PRO (proforma) e Q (preventivo), tutte con pattern YYYY-NNNN e reset annuale. Vengono schedulati anche quattro job cron: pulizia giornaliera del log, retry ogni quindici minuti dei push integration falliti, rivalidazione VIES oraria e refresh giornaliero del token Fatture in Cloud.

Su WordPress Multisite lo stesso bootstrap per-sito gira automaticamente quando si crea un nuovo sub-site (wp_initialize_site).

Configurazione

Tutte le schermate di Invoice Pilot vivono sotto il menu top-level Invoice Pilot nella sidebar admin:

• Dashboard — card KPI e grafici di trend.
• Documenti — data-grid moderna che elenca ogni documento emesso (fattura, nota di credito, proforma, preventivo, ricevuta) con una toolbar unificata (ricerca AI + filtro per tipo), pill di stato colorate (paid / void / converted / draft / issued), paginazione a 20 righe e azioni inline PDF / XML / Delete.
• Impostazioni — pagina di configurazione a otto tab (documentata qui sotto).
• Log — entry del log integrazioni con retention e un’azione di pulizia manuale.

La pagina Impostazioni si divide nelle seguenti tab, nell’ordine in cui appaiono nell’UI:

1. Generale
2. Serie
3. Tipi di documento
4. Template
5. Validazione VAT
6. Integrazioni
7. AI
8. Avanzate

Generale

La tab Generale è divisa in tre card: Licenza, Dati venditore e Default documenti.

Licenza

Dati venditore porta l’identità stampata su ogni documento emesso; Default documenti porta un piccolo numero di default a livello WooCommerce.

Serie

La tab Serie è una tabella CRUD sulle serie di numerazione memorizzate nella tabella series del plugin. Ogni riga controlla come vengono numerati i documenti di un certo tipo.

Colonne: Slug, Pattern, Contatore, Reset, Default, Abilitata, Azioni (Modifica / Elimina).

Il form Aggiungi / Modifica espone:

Rinominare uno slug aggiorna la riga della serie sul posto (preservando l’id intero e ogni riferimento) e migra l’impostazione default_series automaticamente se puntava al vecchio slug. Cancellare una serie non rimuove i documenti esistenti; mantengono i loro numeri.

Tipi di documento

La tab Tipi di documento abilita i tipi di documento opzionali ed espone le impostazioni FatturaPA specifiche per bollo e ritenuta.

Card Tipi di documento

Card FatturaPA — B2B italiano

Template

Scegli uno dei tre template PDF inclusi e personalizza colori e tipografia.

Campi aggiuntivi:

La tab include anche un’anteprima PDF live (renderizzata contro l’endpoint REST /wp-json/invoice-pilot/v1/preview-template) così puoi confrontare i template fianco a fianco prima di salvare. Cambiare radio sostituisce l’iframe subito; la scelta persiste solo quando premi Salva template.

Sopra l’iframe c’è un selettore di Tipo documento così puoi vedere come viene renderizzato ciascuno dei quattro tipi — invoice, credit_note, proforma, quote — con lo stesso template e stessi venditore e compratore di esempio. Le differenze applicate per tipo sono:

I preventivi rinominano in più le celle prominenti “Issued” / “Due date” in Valid until, e il totale hero in Estimated total; le note di credito lo rinominano in Refund total. Queste differenze vengono da una mappa di override delle etichette per tipo e da un helper doc_type_context() passato al template engine, così i tre design inclusi (Minimal / Classic / Modern) mantengono identità visiva consistente tra tipi senza duplicare i file di template.

Il footer porta sempre il paese del compratore nella sua forma estesa in inglese (es. Germany, non DE) — il codice ISO dell’ordine viene risolto attraverso Locale::getDisplayRegion() di PHP prima del render, così la fattura resta leggibile sia per il compratore umano sia per il fisco. Il VAT del venditore viene invece stampato secondo l’impostazione Formato VAT su PDF in Generali → Default documenti — di default in forma con prefisso VIES (VAT IT04032690614), con opzione Nudo per le giurisdizioni che preferiscono il numero nudo.

Il dispatcher che sceglie l’envelope XML giusto per paese del compratore è il filtro invoice_pilot_xml_writer_for_country, quindi il codice host può fare override per ISO (vedi Hook e filtri).

Validazione VAT

Le partite IVA inserite al checkout (e su qualunque schermata indirizzo che esponga il campo) vengono fatte passare per una catena di validatori. Ogni validatore è abilitato da un toggle indipendente e gira in ordine fino a quando uno restituisce risultato positivo; sia le risposte positive che quelle negative vengono messe in cache per il TTL configurato.

Una riga read-only Stato cache riporta il numero di entry in cache e quante sono scadute in attesa di eviction.

Test validazione VAT — una card più piccola sotto le impostazioni esegue ogni provider direttamente contro una singola P.IVA, bypassando l’ordine della catena e la cache, così puoi verificare se VIES ha davvero confermato il numero o se ha risposto solo il check di formato offline.

Popola aliquote IVA standard UE-27 — la card in fondo popola WooCommerce → Impostazioni → Tasse → Aliquote standard con l’aliquota standard corrente per ogni Stato membro UE-27 (AT 20% BE 21% BG 20% HR 25% CY 19% CZ 21% DK 25% EE 22% FI 25.5% FR 20% DE 19% GR 24% HU 27% IE 23% IT 22% LV 21% LT 21% LU 17% MT 18% NL 21% PL 23% PT 23% RO 21% SK 23% SI 22% ES 21% SE 25%). Di default vengono inserite solo le righe mancanti; spunta Sovrascrivi aliquote esistenti per forzare il refresh al valore canonico (utile dopo un aumento nazionale dell’IVA). La card lista anche ogni coppia (ISO, aliquota) così vedi esattamente cosa verrà scritto prima di premere il bottone.

Integrazioni

La tab Integrazioni mostra un pannello per ciascun provider di integrazione registrato dietro un singolo selettore Provider in alto — scegli il provider da configurare e solo la sua card è visibile, le altre restano nel DOM nascoste. Il selettore è sticky tra i salvataggi: quando salvi il form di un provider (o atterri sulla tab con ?integration=<id> nell’URL), il render successivo mantiene quel provider selezionato, così non vieni rimbalzato sul primo provider registrato.

Di default Invoice Pilot include sei provider; codice di terze parti può registrarne altri tramite il filtro invoice_pilot_integration_providers.

Ogni pannello provider è chiuso da una card Connection Status con un pulsante Test Connection. Il pulsante manda una richiesta leggera contro le credenziali salvate e stampa la risposta upstream — salva il form prima, se hai appena incollato nuovi token.

SmartBill

Provider di fatturazione rumeno. Le credenziali sono cifrate a riposo tramite il layer di crittografia simmetrica del plugin.

Quando abilitato, Invoice Pilot chiama POST /SBORO/api/v2/invoice all’emissione, poi pull_status per riconciliare e void quando una fattura viene annullata.

Fatture in Cloud

Provider di fatturazione italiano. I token OAuth sono memorizzati cifrati a riposo. Il cron giornaliero invoice_pilot_refresh_fic_token rinfresca automaticamente l’access token quando l’integrazione è abilitata.

Come da policy di prodotto di Fatture in Cloud, Invoice Pilot non invia la FatturaPA al SDI per tuo conto. L’invio al SDI resta uno step manuale da fare dal tuo account FIC.

Xero

Piattaforma contabile globale. I token OAuth 2.0 sono cifrati a riposo. La tab di impostazioni è organizzata come Connection (status + pulsanti Connect / Disconnect) in alto e Settings (credenziali dell’app + comportamento di push) in basso.

Connessione

Invoice Pilot include un flusso OAuth integrato — non devi più fare la danza in Postman e incollare quattro stringhe nel form. Il setup end-to-end è:

1. Crea una Web app su developer.xero.com  con la redirect URI stampata nel pannello Connection — copiala alla lettera, Xero la confronta carattere per carattere. Le app create dopo il 2 marzo 2026 possono richiedere solo il set di scope granulare; Invoice Pilot sceglie quello giusto in automatico.
2. Genera un Client secret sulla pagina dell’app Xero (Xero lo mostra una sola volta), poi incolla Client ID e Client secret nel form Settings e salva.
3. Clicca Connect to Xero. Verrai instradato attraverso la schermata di consenso standard e, se il tuo account ha l’autorizzazione su più di un’organizzazione, verrai reindirizzato a un picker in-card per scegliere il tenant target. I token vengono scambiati e persistiti automaticamente.
4. Disconnect azzera i token di access + refresh e il tenant id, mantenendo invece le credenziali dell’app per facilitare una riconnessione.

I push usano POST /Invoices con l’header standard Idempotency-Key derivato dall’id e dal numero della fattura locale, così un retry di rete collassa sullo stesso InvoiceID Xero invece di creare un duplicato. Il refresh token viene ruotato automaticamente sul 401; se mai dovesse scadere (Xero invalida i refresh token dopo 60 giorni di inattività) basta premere di nuovo Connect.

Campi

QuickBooks Online

Intuit QuickBooks Online — US / CA / UK / globale. I token OAuth 2.0 sono cifrati a riposo. La tab di impostazioni è organizzata come Connection (status + pulsanti Connect / Disconnect) in alto e Settings (credenziali dell’app + comportamento di push) in basso.

Connessione

Invoice Pilot include un flusso OAuth integrato — non devi più fare la danza in Postman e incollare cinque stringhe nel form. Il setup end-to-end è:

1. Crea un’app su developer.intuit.com  con QuickBooks Online and Payments come piattaforma e lo scope com.intuit.quickbooks.accounting. Apri la tab Keys & OAuth e alterna tra Development e Production a seconda dell’environment che vuoi usare — ciascuno ha la sua coppia client_id + secret.
2. Aggiungi la redirect URI stampata nel pannello Connection alla lista Redirect URIs e clicca Save — Intuit accetta http://localhost per le app in Development.
3. Incolla Client ID e Client secret nel form Settings, scegli l’Environment corrispondente (Sandbox / Production) e salva.
4. Clicca Connect to QuickBooks. La schermata di consenso di Intuit ti fa scegliere la company contro cui l’integrazione scriverà; il realmId selezionato viene restituito nell’URL di callback e salvato automaticamente — non c’è un picker tenant separato.
5. Disconnect azzera i token di access + refresh e il realm id, mantenendo invece le credenziali dell’app per facilitare una riconnessione.

Ogni push usa POST /v3/company/{realmId}/invoice con il parametro di query requestid impostato a un valore stabile per fattura — QBO collassa i POST ritentati sulla risposta originale, così un retry di rete non creerà mai un duplicato. I push portano anche minorversion=75 così che QBO restituisca le shape correnti delle entità (senza, l’API fa silenziosamente downgrade al contratto del 2017). I refresh token durano 100 giorni dall’emissione e ruotano a ogni uso; il plugin gestisce la rotazione in modo trasparente sul 401.

Campi

Fortnox

Piattaforma contabile svedese. Credenziali OAuth 2.0 cifrate a riposo.

Sage

Piattaforma contabile OAuth 2.0 (Sage Accounting / Business Cloud).

AI

La tab AI è divisa in due card: Provider Configuration e Features. Il plugin funziona pienamente senza API key; questa tab aggiunge capacità AI-powered opzionali.

Provider Configuration

Modelli offerti per provider:

Features

Avanzate

Retention e disinstallazione

Azioni di manutenzione

• Lancia ora la pulizia log — fa scattare immediatamente l’azione invoice_pilot_cleanup_logs invece di aspettare il cron giornaliero.
• Purge della cache di validazione — cancella ogni riga dalla tabella di cache della validazione VAT.

Una piccola riga Versioni in fondo stampa la versione corrente del plugin e dello schema database.

Utilizzo

Auto-emissione di una fattura da un ordine WooCommerce

Il flusso di default non richiede azione manuale.

1. Un cliente piazza un ordine su WooCommerce. Il checkout espone i campi Partita IVA e Codice fiscale più i campi country-specific registrati per il paese di fatturazione (per esempio Codice destinatario SDI e PEC sugli ordini IT). Il campo VAT viene validato live mentre l’utente digita — un badge ✓ verde appare dentro l’input quando la catena conferma il numero, ✕ rosso quando fallisce. Se il buyer è in uno Stato membro UE diverso e la VAT è valida, WooCommerce azzera automaticamente l’IVA sul carrello (reverse charge B2B intra-UE — vedi Impostazioni → Validazione VAT).
2. Quando l’ordine raggiunge lo stato trigger definito sotto Impostazioni → Generale → Stato trigger (processing di default), Invoice Pilot emette una fattura usando la Serie di default (INV di default), persiste uno snapshot JSON immutabile dell’ordine, renderizza il PDF, genera l’envelope XML per il paese del compratore e pusha verso ogni integrazione abilitata.
3. La schermata ordine guadagna una meta box Invoice Pilot che elenca i documenti emessi con link a PDF e XML, più pulsanti d’azione per Rigenera, Riemetti, Annulla, Crea nota di credito, Crea proforma, Crea preventivo e Push al provider.

La meta box Invoice Pilot espone, per l’ultimo documento non annullato dell’ordine: il numero del documento (per esempio INV-2026-0063), la pill di stato (Issued / Paid / Void), i pulsanti di download PDF e XML (link REST firmati con token), un’azione Regenerate document che ri-renderizza gli artefatti contro il template corrente e le impostazioni venditore senza cambiare il numero del documento, e una sezione Other documents che espone pulsanti Create proforma e Create quote one-click. Quando un’integrazione è abilitata, un pulsante Push to provider appare accanto ai link PDF / XML e replica la chiamata di integrazione contro il target configurato.

Emissione manuale

Se l’emissione automatica è disabilitata o l’ordine non ha ancora raggiunto lo stato trigger, la meta box dell’ordine espone un pulsante Emetti ora. Vale lo stesso flusso — snapshot, PDF, XML, push integration — ma gira on demand.

Note di credito dai rimborsi

Quando Auto-emetti nota di credito al rimborso WC è on (il default), qualunque rimborso WooCommerce creato contro un ordine con fattura esistente triggera una nota di credito nella serie CN. La nota di credito collega indietro alla fattura genitore e la referenzia nell’XML. Il PDF renderizzato porta un banner disclaimer “Refund of INV-…” in cima, una status pill CREDIT NOTE, Refund total nella cella hero, e nasconde il footer IBAN / metodo di pagamento (il flusso di pagamento originale non si applica più). Puoi anche emettere una nota di credito manualmente — completa o parziale — dalla card Actions sulla schermata di modifica della fattura, purché la fattura genitore sia in status issued.

Proforma e preventivi

Quando i toggle corrispondenti sono on, la schermata ordine espone anche pulsanti Crea proforma e Crea preventivo. Entrambi producono documenti non fiscali — viene renderizzato un PDF ma per i preventivi non viene generato XML. Il PDF renderizzato porta un trattamento visivo specifico al tipo: un banner disclaimer in cima (“Proforma — not a fiscal document.” / “Quote — not a fiscal document, subject to acceptance.”), una status pill “QUOTE” / “PROFORMA” al posto di “ISSUED”, e sui preventivi l’etichetta della data prominente passa a Valid until e il totale hero a Estimated total. I preventivi nascondono il blocco IBAN / metodo di pagamento perché non c’è un pagamento dovuto.

Una proforma può essere convertita in fattura con l’azione Convert, che ri-numera il documento sotto la serie fatture configurata.

Inviare una fattura al cliente

Il plugin registra un’azione d’ordine Send Invoice Pilot invoice to customer sotto il dropdown standard di azioni ordine di WooCommerce, che spedisce il PDF al compratore tramite wp_mail() di WordPress.

Download dei documenti

PDF ed envelope XML vengono serviti da un endpoint REST indirizzabile pubblicamente ma firmato con token:

GET /wp-json/invoice-pilot/v1/download/{id}/{format}?token=…

{format} è pdf o xml. Il token viene generato all’emissione del documento e stampato nella meta box dell’ordine e nella tabella elenco fatture.

Dashboard

Invoice Pilot → Dashboard apre una card Activity overview sopra una card Trends. L’Activity overview espone una barra periodo con quattro finestre — 7 giorni, 14 giorni, 30 giorni (default) e 90 giorni — e cinque card KPI:

• Fatture — conteggio totale dei documenti emessi nel periodo.
• Net revenue — somma dei totali netti nella valuta del negozio, renderizzata con il simbolo di valuta del locale e due decimali (es. €3,876.09 o 3.876,09 € a seconda del locale dell’admin).
• VAT collected — somma dei totali IVA dallo snapshot immutabile. Stessa formattazione di valuta locale-aware di Net revenue. Una migrazione di schema separata fa il backfill di questo valore per le fatture emesse prima della schema version 1.3.1, quando la colonna non veniva popolata in scrittura.
• Avg value — net revenue diviso per il conteggio fatture, anch’esso formattato come valuta.
• B2B / B2C — ripartizione tra fatture B2B (il compratore ha una P.IVA) e B2C nello stesso periodo.

Sotto i KPI, la card Trends renderizza due grafici fianco a fianco — Invoices over time (un grafico dual-axis a linea + area con il conteggio fatture sull’asse sinistro e il trend del fatturato netto riempito sull’asse destro) e By buyer country (un grafico a ciambella dei top codici ISO compratore, con la legenda colori sotto). Tutti i numeri sono idratati da /wp-json/invoice-pilot/v1/dashboard?days=N.

Lista documenti

Invoice Pilot → Documenti elenca ogni documento emesso con pill di stato (paid / void / converted / draft / issued — colorate per stato di lifecycle), una colonna Compliance che porta il badge colorato prodotto dal pre-flight AI, e azioni inline PDF / XML / Delete per riga. La pagina pagina a 20 righe per volta ed espone una toolbar unificata che combina la ricerca AI free-text con un filtro per tipo di documento (invoice / credit_note / proforma / quote / receipt) più un contatore corrente a destra. Quando la ricerca AI è abilitata, la casella di ricerca accetta query free-text (per esempio, “German invoices last month over 1,000 EUR”) che il provider configurato traduce in una query di lista; i filter chip risolti appaiono sopra la tabella, così vedi esattamente come il modello ha interpretato la tua frase.

Lista ordini WooCommerce

Invoice Pilot aggiunge un’unica colonna Invoice alla lista ordini standard di WooCommerce (/wp-admin/admin.php?page=wc-orders) così il negoziante vede a colpo d’occhio quali ordini hanno già un documento e quali no, senza uscire dalla schermata ordini. La colonna sta fra Ordine e Data e mostra il numero documento assegnato dalla serie configurata (per esempio INV-2026-0063) letto alla lettera dalla colonna immutabile number, con una piccola icona di anteprima eye a fianco del numero che apre inline il PDF renderizzato in una nuova tab.

Gli ordini senza documento emesso renderizzano una lineetta — utile per individuare disallineamenti di stato trigger o per filtrare gli ordini che richiedono un’esecuzione manuale di wp invoice-pilot issue. Lo stesso renderer cabla sia la colonna legacy della tabella post (manage_edit-shop_order_columns) sia la colonna HPOS (manage_woocommerce_page_wc-orders_columns), così l’esperienza è identica indipendentemente dallo storage ordini in cui si trova il tuo negozio.

Log integrazioni

Invoice Pilot → Log registra ogni push, risposta e fallimento di integrazione. La toolbar in cima combina un selettore Bulk actions + pulsante Apply (al momento un’unica bulk-delete), un dropdown provider e un dropdown action — entrambi popolati dai valori effettivamente visti nel log così mostrano solo filtri che corrispondono a una riga reale — e un conteggio entry corrente a destra.

La data grid porta otto colonne:

I campi sensibili del payload sono redatti in scrittura dal Core\Logger del plugin, così i body di request e response possono restare nel log senza problemi. Le entry vecchie sono purgate dal cron giornaliero invoice_pilot_cleanup_logs secondo l’impostazione Retention log (giorni) nella tab Avanzate.

Network admin (Multisite)

Su un network Multisite compare una pagina Invoice Pilot Network aggiuntiva nella sidebar network admin. Aggrega conteggi e totali di fatture su ogni sub-site che ha Invoice Pilot attivo.

Fatturazione UE-27

Invoice Pilot include un registry di campi di fatturazione country-specific per ognuno dei 27 stati membri UE. Ogni campo è opzionale al checkout (il plugin non forza dati B2B-only su un ordine B2C); la validazione scatta solo quando il paese del compratore coincide con l’ISO del campo.

Il registry copre attualmente:

L’integrazione block-checkout registra i campi sotto il namespace invoice-pilot/... tramite la Additional Checkout Fields API. Di default, sul block checkout sono esposti solo i campi italiani per non sovraccaricare gli shopper non italiani; il toggle Tutti i campi UE-27 al checkout in Generale attiva il set completo. Il checkout shortcode legacy renderizza sempre il registry completo filtrato per paese di fatturazione selezionato.

I campi country vengono persistiti sull’ordine, copiati nello snapshot immutabile della fattura, e consumati dai writer XML — per esempio il ei_recipient_code italiano diventa CodiceDestinatario / PECDestinatario nell’envelope FatturaPA, mentre il leitweg_id tedesco diventa BuyerReference / EndpointID 0204 in XRechnung.

Integrazioni

SmartBill

SmartBill (Romania) è cablato nell’IntegrationManager del plugin tramite il filtro invoice_pilot_integration_providers ed espone l’interfaccia provider standard: push, pull_status, void e test_connection.

• Push mappa lo snapshot della fattura allo schema JSON SmartBill e chiama POST /SBORO/api/v2/invoice con CIF e serie configurati.
• Status sync riconcilia lo stato draft / issued / paid quando gira il cron di retry da quindici minuti.
• Void annulla su SmartBill una fattura precedentemente pushata quando la fattura sorgente viene annullata in WordPress.

Tutte le azioni sono loggate nel log integrazioni. I fallimenti vengono accodati e ritentati dal cron invoice_pilot_retry_integrations.

Fatture in Cloud

Fatture in Cloud (Italia) segue la stessa interfaccia provider e mappa lo snapshot della fattura sulla forma entity / items_list attesa dall’endpoint issued-document di FIC. I campi country-specific italiani sono mappati esplicitamente:

• ei_recipient_code → ei_code
• ei_certified_email → certified_email
• VAT / codice fiscale / provincia / paese del compratore → chiavi corrispondenti in entity

Le credenziali OAuth sono cifrate a riposo. Il cron giornaliero invoice_pilot_refresh_fic_token rinfresca l’access token quando l’integrazione è abilitata. Mettere Crea clienti su on fa sì che l’integrazione crei un nuovo record cliente in FIC alla prima fattura per un compratore.

Invoice Pilot non invia la FatturaPA al SDI per tuo conto. L’invio al SDI resta uno step manuale da fare dal tuo account Fatture in Cloud.

AI smart-fill

Il layer AI è completamente opzionale. Senza un’API key configurata il plugin continua a emettere fatture, renderizzare PDF e XML, validare VAT e pushare verso le integrazioni — solo le quattro feature AI qui sotto non sono disponibili.

Cinque provider sono supportati:

L’API key è memorizzata cifrata a riposo tramite il layer di crittografia simmetrica del plugin. Premere Test Connection manda una richiesta minima all’endpoint scelto e fa emergere l’errore upstream se le credenziali sono sbagliate.

Quattro feature possono essere togglate indipendentemente una volta che una chiave è in archivio:

• Smart-fill al checkout — al checkout compare una textarea “Paste billing details”. Il modello parsa il testo free-form e compila il form di fatturazione strutturato di WooCommerce, inclusi i campi country-specific. Rate-limited per sessione.
• Compliance pre-flight check — ogni fattura viene passata al modello appena prima dell’emissione, con l’opzione di bloccare l’emissione su finding di livello error quando viene rilevato un problema critico (per esempio una fattura B2B italiana senza codice destinatario SDI).
• Auto-traduzione delle righe — le descrizioni delle righe fattura vengono tradotte nella lingua del compratore. Quando il plugin gemello Polyglot  è installato, la pipeline di traduzione viene delegata a lui.
• Ricerca documenti in linguaggio naturale — la casella di ricerca sulla pagina admin Documenti accetta query free-text che il modello traduce in una query di lista.

Ogni feature ha il proprio rate limit orario.

Hook e filtri

I nomi dei hook centralizzati vivono nella classe \InvoicePilot\Core\Hooks. Lista completa:

Registrare un writer XML custom:

add_filter(
    'invoice_pilot_xml_writer_for_country',
    function ( $writer, $iso ) {
        if ( 'NL' === $iso ) {
            return new My_Custom_Nl_Writer();
        }
        return $writer;
    },
    20,
    2
);

Registrare un provider di integrazione custom:

add_filter(
    'invoice_pilot_integration_providers',
    function ( array $providers ) {
        $providers[] = new My_Custom_Provider();
        return $providers;
    }
);

Nascondere o estendere i campi di checkout country-specific (per esempio per togliere i prompt ei_certified_email (PEC) e fiscal_regime (codice RF) di Italia quando il tuo negozio non ne ha bisogno — senza dover forkare il plugin):

add_filter(
    'invoice_pilot_country_fields',
    function ( array $fields, string $iso ) {
        if ( 'IT' === $iso ) {
            $fields = array_values(
                array_filter(
                    $fields,
                    fn ( $f ) => ! in_array(
                        $f->name,
                        [ 'ei_certified_email', 'fiscal_regime' ],
                        true
                    )
                )
            );
        }
        return $fields;
    },
    10,
    2
);

Il filtro viene eseguito sia sul percorso PHP di validazione del submit sia sullo snapshot JS servito al checkout WC Blocks, in modo che i due livelli restino allineati. Nomi macchina dei campi attualmente forniti (da usare nel filtro):

La registry completa per paese è definita in CountryFieldRegistry::install_defaults() e copre tutti gli ISO EU-27.

FAQ

Invoice Pilot invia la FatturaPA al SDI?

No. Invoice Pilot genera l’XML FatturaPA e lo memorizza sull’ordine; l’invio al SDI è intenzionalmente lasciato a uno step manuale separato (o all’integrazione Fatture in Cloud sul tuo account).

Posso aggiungere un writer per un paese non incluso?

Sì. Aggancia il filtro invoice_pilot_xml_writer_for_country e restituisci la tua implementazione di \InvoicePilot\Modules\Xml\XmlWriterInterface.

Funziona sul block checkout di WooCommerce?

Sì. I campi country-specific sono registrati tramite la Additional Checkout Fields API di WooCommerce 8.6+, quindi appaiono sia sul block checkout sia sullo shortcode checkout legacy. Sulle versioni WooCommerce precedenti alla 8.6 si usa solo il path filter legacy.

Funziona su WordPress Multisite?

Sì. Ogni sub-site ha le proprie tabelle, impostazioni e contatori di numerazione. Una pagina network admin sotto Network Admin → Invoice Pilot Network aggrega i conteggi fatture su tutto il network. Sui nuovi sub-site, tabelle e serie di default vengono create automaticamente tramite l’hook wp_initialize_site.

Le credenziali sono cifrate?

Sì. Token SmartBill, token OAuth Fatture in Cloud e l’API key AI sono cifrati a riposo tramite \InvoicePilot\Core\Crypto. Lasciare vuoto un campo token al prossimo salvataggio mantiene il valore già memorizzato.

Cosa succede ai miei dati se elimino il plugin?

Niente, a meno che tu non lo chieda. Il default per Avanzate → Wipe dei dati alla disinstallazione è off, quindi tabelle, opzioni, log integrazioni e cache di validazione vengono preservati tra disattivazione e riattivazione. Attiva l’opzione se vuoi che la routine uninstall.php droppi tutto quando WordPress elimina il plugin.

Dove prendo un’API key per le feature AI?

Ogni provider ha la propria console: Anthropic su console.anthropic.com , OpenAI su platform.openai.com , Google AI Studio su aistudio.google.com , DeepSeek su platform.deepseek.com , e Grok su console.x.ai . La tab AI linka direttamente alla console del provider scelto.

Mi serve una API key AI per far funzionare il plugin?

No. Le feature AI (smart-fill, check di compliance, traduzione righe, ricerca in linguaggio naturale) sono opzionali. Il motore core di fatturazione — ciclo di vita dei documenti, generazione PDF e XML, validazione VAT, integrazioni, dashboard — gira senza API key.

Troubleshooting

La fattura non viene emessa quando l’ordine passa in Processing

Controlla Impostazioni → Generale → Stato trigger. Il default è processing; se l’hai personalizzato (per esempio su completed), la routine di auto-emissione scatta solo sullo stato configurato. Puoi anche premere Emetti ora dalla meta box dell’ordine per emettere manualmente a prescindere dal trigger.

Il checkout mostra troppi (o troppo pochi) campi country

Il default espone solo i campi SDI italiani. Apri Impostazioni → Generale → Document defaults → Campi di fatturazione country-specific e scegli l’ambito:

• Off — vengono mostrati solo i campi universali VAT e codice fiscale.
• Solo Italia (SDI / PEC / regime fiscale) — default.
• Tutti i campi UE-27 country-specific — ogni ISO del registry.

L’impostazione si applica sia al block checkout sia al checkout shortcode legacy. I campi country-specific restano comunque nascosti client-side quando il paese di fatturazione non corrisponde.

La validazione VAT si impalla o va in timeout

Il servizio VIES è ogni tanto lento o non disponibile. Il plugin mantiene una cache per-VAT per il TTL configurato (24 ore di default) e rivalida le entry stale ogni ora tramite il cron invoice_pilot_revalidate_vies. Se VIES è offline, il validatore Formato per paese accetta comunque i numeri ben formati. Puoi anche alzare il TTL della cache sotto Impostazioni → Validazione VAT.

La dashboard non mostra dati

La SQL della dashboard si appoggia su JSON_EXTRACT / JSON_UNQUOTE contro la colonna snapshot immutabile delle fatture. Assicurati che il database server sia MySQL 5.7+ o MariaDB 10.2+. Se la barra del periodo mostra la finestra giusta ma le card restano su --, apri direttamente /wp-json/invoice-pilot/v1/dashboard?days=30 e controlla la risposta — i fallimenti di autenticazione REST appaiono come rest_forbidden.

Un push integration fallisce

Apri Invoice Pilot → Log e individua la entry fallita — la colonna HTTP segnala le risposte non-2xx con un badge colorato e la colonna Error mostra in rosso il messaggio d’errore upstream. La entry fallita viene ritentata automaticamente dal cron invoice_pilot_retry_integrations ogni quindici minuti; puoi anche premere Push to provider nella meta box dell’ordine per ritentare subito. Usa l’azione Delete su una riga per ripulire una entry one-off senza aspettare il cron di retention.

Test Connection sulla tab AI riporta un errore

Il messaggio restituito in rosso viene direttamente dall’endpoint del provider. Cause comuni:

• API key non valida o revocata — generane una nuova e incollala nel campo API Key, poi salva.
• Un nome di modello a cui l’account non ha accesso — scegli un modello diverso dal dropdown.
• Egress di rete bloccato dall’host — verifica che l’HTTPS in uscita verso api.anthropic.com, api.openai.com, generativelanguage.googleapis.com, api.deepseek.com o api.x.ai sia permesso.

Gli alert email al cliente non arrivano

Le email fattura al cliente sono inviate tramite la funzione wp_mail() di WordPress. Se non arriva nessuna email, il problema è quasi sempre della configurazione mail del sito, non di Invoice Pilot. Installa un plugin di mail transazionale (per esempio uno che indirizza la mail WordPress via SMTP) e ritriggera l’azione d’ordine Send Invoice Pilot invoice to customer da un ordine di test.