Factur-X — Guida completa (PrestaShop 8 & 9)

Questa guida copre l’installazione, la configurazione e l’uso del modulo DataFirefly Factur-X (dffacturx) per PrestaShop 8 e 9. Il modulo trasforma i suoi ordini in fatture elettroniche ibride in formato Factur-X: un PDF/A-3b leggibile e stampabile che contiene, incorporati al suo interno, i dati strutturati della fattura in formato XML CII (standard EN 16931).

Panoramica

Una fattura Factur-X è un unico file che serve due scopi. Il suo cliente apre un PDF classico, che può leggere, stampare e archiviare. Il suo software contabile, o la piattaforma che elabora la fattura, legge direttamente l’XML incorporato senza dover interpretare l’immagine. Non ci sono più due file da mantenere allineati, quindi nessun rischio di scostamento tra ciò che è visualizzato e ciò che viene elaborato.

Il modulo copre la generazione di questi file: produce l’XML, genera il PDF e incorpora l’uno nell’altro con i metadati previsti. La trasmissione tramite una Piattaforma Accreditata è uno strato distinto, descritto nella sezione sull’ambito normativo.

Requisiti

• PrestaShop 8.0 a 9.x
• PHP 7.4 minimo, 8.1 o superiore consigliato
• TCPDF, incluso di serie in PrestaShop — nessuna installazione aggiuntiva
• Estensioni PHP: dom (costruzione dell’XML), zlib (lettura dei metadati XMP compressi), zip (generazione massiva)

Installazione

1. Nel back-office, vada su Moduli → Gestore dei moduli → Carica un modulo.
2. Carichi il file dffacturx.zip. Può anche copiare la cartella dffacturx direttamente nella directory modules/ del suo negozio.
3. Avvii l’installazione. Il modulo registra i suoi hook e crea una scheda Factur-X sotto il menu Ordini.
4. Apra la configurazione e compili l’identità del venditore prima di generare la sua prima fattura.

Configurazione

Identità del venditore

È il passaggio obbligatorio. Questi dati alimentano sia il PDF visibile sia l’XML strutturato. Senza di essi, l’XML verrà rifiutato da un validatore.

• Ragione sociale — precompilata con il nome del suo negozio, da correggere se la denominazione legale differisce.
• SIREN — 9 cifre, senza spazi. Indispensabile: viene trasmesso nell’XML con l’identificatore di schema adeguato.
• SIRET — 14 cifre, opzionale ma consigliato.
• Partita IVA intracomunitaria — indispensabile se è soggetto passivo (es. FR12345678901).
• Forma giuridica e capitale sociale — mostrati nelle menzioni legali a piè di fattura.
• Indirizzo, CAP, città, paese — il paese è atteso in formato ISO a due lettere (es. FR).
• Contatto, telefono, email — riportati nell’XML nei profili EN 16931 e superiori.

Profilo Factur-X

Il profilo determina il livello di dettaglio dell’XML e l’identificatore di specifica che vi viene iscritto. Il modulo lo imposta automaticamente in base alla sua scelta.

• EN 16931 — consigliato. Corrisponde al nucleo completo dello standard europeo, accettato ovunque.
• BASIC — XML più leggero, conserva il dettaglio delle righe.
• EXTENDED — profilo esteso, per casi che richiedono dati aggiuntivi.
• MINIMUM e BASIC WL — profili senza dettaglio delle righe, riservati a usi specifici.

Opzioni

• Download lato cliente — attiva un link nell’area account. Il modulo verifica che l’ordine appartenga al cliente connesso prima di servire il file.
• Generazione automatica — se indica un identificatore di stato ordine, una fattura viene generata e salvata nella cartella generated del modulo non appena un ordine raggiunge quello stato. Eventuali errori sono scritti nei log di PrestaShop senza bloccare il cambio di stato.

Generare una fattura

Dalla scheda ordine

Apra un ordine nel back-office: un pannello Factur-X appare in fondo alla pagina principale. Mostra il profilo attivo e propone due pulsanti — Scarica PDF Factur-X per il file ibrido completo, e Scarica XML per il solo XML, utile nelle fasi di test e validazione.

Generazione massiva

Il menu Ordini → Factur-X elenca i suoi ordini con accesso diretto al PDF e all’XML su ogni riga. Per elaborare un lotto, selezioni gli ordini interessati e scelga l’azione in blocco Scarica le Factur-X (ZIP): il modulo raccoglie tutte le fatture in un archivio. Se un ordine fallisce, viene ignorato e l’errore registrato — l’archivio resta utilizzabile.

Lato cliente

Se l’opzione è attiva, un link Le mie fatture Factur-X appare nell’area account. Il controller front verifica che il cliente sia connesso e che l’ordine gli appartenga, altrimenti reindirizza allo storico degli ordini.

Cosa contiene il file generato

Il PDF prodotto è un PDF/A-3b generato dal TCPDF di PrestaShop. Il modulo aggiunge poi, tramite aggiornamento incrementale, gli elementi che ne fanno una fattura Factur-X:

• un oggetto file incorporato contenente l’XML, denominato factur-x.xml;
• una voce nell’array dei file associati del catalogo, con la relazione Data;
• una voce nel dizionario dei file incorporati con nome;
• metadati XMP che descrivono il tipo di documento, il nome del file, la versione e il livello di conformità, insieme al corrispondente schema di estensione PDF/A.

L’aggiornamento incrementale aggiunge questi oggetti in fondo al file senza modificare un solo byte del documento generato. I font, i flussi di contenuto e il profilo colore prodotti da TCPDF restano intatti — e il modulo non dipende da alcun dettaglio interno di TCPDF, quindi da nessuna versione particolare.

L’XML è un CrossIndustryInvoice UN/CEFACT. Contiene il contesto del documento con l’identificatore di specifica del profilo, l’intestazione della fattura, le righe se previste, l’accordo commerciale (venditore e acquirente), la consegna, e la liquidazione con la ripartizione IVA, gli sconti, gli addebiti e il riepilogo monetario.

Modellazione contabile

I validatori Factur-X non confrontano i suoi totali con quelli di PrestaShop: verificano che il documento sia coerente con sé stesso. Il modulo ricalcola quindi tutti gli importi a partire dalle righe e dalla ripartizione IVA, per soddisfare le regole di equilibrio dello standard.

• Righe — il prezzo unitario netto è dedotto dal totale riga diviso per la quantità. L’unità utilizzata è il codice unità generico.
• Spese di spedizione — modellate come addebito a livello di documento, con la propria aliquota IVA.
• Sconti — modellati come allowance a livello di documento, ripartiti proporzionalmente tra le diverse basi IVA.
• Ripartizione IVA — una occorrenza per ogni aliquota incontrata, con base, importo e categoria.
• Categoria IVA — categoria standard se l’aliquota è superiore a zero, categoria zero altrimenti.
• Acconto — l’importo prepagato è zero e l’importo dovuto equivale al totale IVA inclusa: la fattura è emessa, l’intero importo resta dovuto ai sensi del documento.

I casi IVA particolari — esenzione, inversione contabile, cessione intracomunitaria — non sono derivati automaticamente. Se la sua attività li comporta, faccia validare alcune fatture rappresentative e adatti la categoria utilizzata.

Validare prima della messa in produzione

Questo passaggio non è opzionale. Generi alcune fatture rappresentative della sua attività — un ordine semplice, un ordine con sconto, un ordine con più aliquote IVA — poi le controlli con:

• il validatore della FNFE-MPE, riferimento francese per Factur-X;
• Mustangproject, validatore open source per la conformità EN 16931;
• veraPDF, per la conformità del contenitore PDF/A-3.

Il pulsante di download del solo XML è pensato per questa fase: le evita di estrarre manualmente l’allegato dal PDF a ogni tentativo.

Ambito normativo

La riforma francese della fatturazione elettronica segue un calendario in due tempi. Dal 1º settembre 2026, tutte le imprese soggette a IVA devono poter ricevere fatture elettroniche, e le grandi imprese e le imprese a media capitalizzazione devono emetterle. Dal 1º settembre 2027, l’obbligo di emissione si estende alle PMI, alle microimprese e ai lavoratori autonomi. La maggior parte dei commercianti PrestaShop deve quindi ricevere dal 2026 ed emettere dal 2027.

Vanno distinti tre ruoli:

• Generare file Factur-X conformi — ciò che fa questo modulo. Non è richiesta alcuna certificazione o registrazione.
• Trasmettere le fatture tramite una Piattaforma Accreditata (già PDP). Il commerciante sceglie la sua piattaforma e le consegna i file.
• Essere una Piattaforma Accreditata — attività soggetta a registrazione statale, fuori dall’ambito del modulo.

Risoluzione dei problemi

Il validatore rifiuta l’XML

Verifichi anzitutto l’identità del venditore, in particolare il SIREN e la partita IVA: sono le cause di rifiuto più frequenti. Controlli poi l’indirizzo di fatturazione del cliente — un paese o un CAP mancante può ugualmente far fallire la validazione.

Messaggio che indica che TCPDF non è disponibile

Il modulo utilizza la classe TCPDF fornita da PrestaShop e, in mancanza, tenta di caricarla dalla directory degli strumenti. Se l’errore persiste, significa che la libreria è stata rimossa dalla sua installazione: la ripristini da un archivio PrestaShop della stessa versione.

L’azione in blocco ZIP non è disponibile

L’estensione PHP zip non è attiva sul server. Il download singolo da ogni scheda ordine resta disponibile senza di essa.

La generazione automatica non produce nulla

Verifichi che l’identificatore di stato ordine sia indicato nella configurazione e che la cartella generated del modulo sia scrivibile. Gli errori di generazione sono registrati nei log di PrestaShop con il prefisso Factur-X.

Il PDF si apre ma l’allegato non appare

Non tutti i lettori mostrano il pannello degli allegati per impostazione predefinita. Apra il riquadro dedicato del suo lettore PDF, oppure utilizzi il download del solo XML per controllarne il contenuto.

Architettura

Il modulo segue un’organizzazione classica, con un autoloader PSR-4 manuale la cui radice di namespace DataFirefly/FacturX punta alla cartella src.

• src/Builder — definizione dei profili e costruzione dell’XML CII.
• src/Pdf — generazione del PDF/A-3b e incorporazione dell’XML.
• src/Service — estrazione dei dati dell’ordine e orchestrazione.
• src/Install — installazione, scheda di amministrazione e hook.
• controllers/admin e controllers/front — controller di download back-office e front-office.

L’architettura si basa su ModuleAdminController e Smarty, identici tra PrestaShop 8 e 9, senza ramo di codice separato né dipendenza Symfony specifica.

Changelog

1.0.0 — 4 giugno 2026

• Generazione di fatture ibride Factur-X: PDF/A-3b con XML CII incorporato.
• Profili BASIC, EN 16931 ed EXTENDED selezionabili.
• Costruzione dell’XML CII conforme a UN/CEFACT con ripartizione IVA per aliquota.
• Incorporazione autonoma dell’XML tramite aggiornamento incrementale del PDF.
• Metadati XMP Factur-X e schema di estensione PDF/A iniettati.
• Identità del venditore completamente configurabile.
• Download di PDF e XML dalla scheda ordine, generazione massiva in ZIP.
• Link di download nell’area cliente, attivabile.
• Generazione automatica opzionale al cambio di stato dell’ordine.
• Compatibile con PrestaShop 8.0 a 9.0 senza ramo di codice separato.