# 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… - Pagina: - Lingua: it - Aggiornato il: 2026-07-22 - Altre lingue: [fr](https://www.datafirefly.com/documentation/dffacturx/index.md), [en](https://www.datafirefly.com/en/documentation/dffacturx/index.md), [es](https://www.datafirefly.com/es/documentation/dffacturx/index.md), [de](https://www.datafirefly.com/de/documentation/dffacturx/index.md), [pl](https://www.datafirefly.com/pl/documentation/dffacturx/index.md), [pt](https://www.datafirefly.com/pt/documentation/dffacturx/index.md), [nl](https://www.datafirefly.com/nl/documentation/dffacturx/index.md) - Indice: 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) Il modulo non utilizza Composer. Le classi sono caricate da un autoloader PSR-4 manuale incluso nel modulo, il che evita qualsiasi conflitto di dipendenze con la sua installazione. ## 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. Finché il SIREN non è compilato, un avviso appare sulla scheda ordine. La generazione resta possibile, ma il file prodotto non supererà un controllo di conformità. ### 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. Uno scostamento di un centesimo rispetto ai totali mostrati da PrestaShop è possibile in casi limite di arrotondamento. È previsto: prevale la coerenza interna del documento, ed è proprio quella che i validatori controllano. 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. Installare questo modulo non basta, da solo, a metterla in piena conformità con la riforma. Produce il formato atteso, che è la base indispensabile, ma la trasmissione tramite una piattaforma resta da organizzare da parte sua. ## 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.