DataFirefly Factur-X SW — Fattura elettronica Shopware 6: guida completa

Panoramica

DfFacturX SW genera fatture elettroniche conformi a EN 16931 per Shopware 6.5, 6.6 e 6.7. A ogni creazione di un documento di fattura, il plugin costruisce un XML UN/CEFACT CII e, secondo il profilo scelto, lo incorpora nel PDF di fattura (Factur-X / ZUGFeRD) o lo fornisce come file autonomo (XRechnung 3.0 per il B2G tedesco).

• Factur-X / ZUGFeRD EN 16931 — profilo raccomandato per il B2B: il PDF che il vostro cliente scarica è la fattura elettronica ibrida.
• Factur-X BASIC — profilo alleggerito, per destinatari che non richiedono il set di dati EN 16931 completo.
• XRechnung 3.0 — XML autonomo in sintassi CII per fatturare le amministrazioni tedesche, con Leitweg-ID obbligatorio.

Installazione

1. Copiate la cartella del plugin in custom/plugins/DfFacturX (o caricate lo ZIP dall’admin, Estensioni e Le mie estensioni).
2. Eseguite:

bin/console plugin:refresh
bin/console plugin:install --activate DfFacturX
bin/console cache:clear

Configurazione

Admin, Estensioni, DfFacturX, Configurazione. Tutte le impostazioni sono applicate per canale di vendita.

Generale

• Attivare la generazione — crea l’XML a ogni nuovo documento di fattura.
• Profilo — Factur-X EN 16931, Factur-X BASIC o XRechnung 3.0.
• Incorporare l’XML nel PDF — per i profili Factur-X; il media del documento viene sostituito dal PDF ibrido.
• Allegare l’XML alle e-mail — aggiunge factur-x.xml (o numero-xrechnung.xml) alle e-mail d’ordine.
• Solo B2B — genera soltanto se l’ordine riporta una ragione sociale o una partita IVA.

Venditore

Ragione sociale, via, codice postale, città, paese (ISO-2), partita IVA (BT-31), numero fiscale (BT-32), e-mail (BT-34), telefono e persona di contatto (BG-6). E-mail e contatto sono richiesti da XRechnung.

Pagamento

IBAN e BIC (bonifico SEPA, codice 58), testo dei termini di pagamento (BT-20) e giorni di scadenza (BT-9). Senza IBAN, il mezzo di pagamento viene dichiarato come codice 1 (non definito).

Gestione IVA

Per le aliquote allo 0 %, la modalità Automatica applica: K cessione intracomunitaria (acquirente con partita IVA in un altro paese UE), G esportazione extra UE, Z negli altri casi. Potete forzare una categoria fissa (Z, E, K, G) e personalizzare il motivo di esenzione (BT-120).

XRechnung

Nome tecnico del campo personalizzato contenente il riferimento acquirente (predefinito df_facturx_buyer_reference) e valore di riserva se nessun campo è compilato.

Leitweg-ID e riferimento acquirente (BT-10)

Inserite il Leitweg-ID una volta sulla scheda cliente (scheda campi personalizzati): verrà riutilizzato su tutte le sue fatture. Per un caso puntuale, compilatelo direttamente sull’ordine — il valore ordine prevale sul valore cliente, che prevale sul valore di riserva.

Funzionamento

1. Alla creazione del documento di fattura (admin, Flow Builder o API), il plugin carica l’ordine nella sua versione d’ordine esatta.
2. L’XML CII viene costruito e memorizzato nei campi personalizzati del documento (df_facturx_xml, df_facturx_profile, df_facturx_generated_at).
3. Con un profilo Factur-X, l’XML viene incorporato nel PDF tramite aggiornamento incrementale: file factur-x.xml allegato, metadati XMP PDF A-3 e schema di estensione Factur-X. Il media del documento viene sostituito sul posto.
4. Se l’opzione è attiva, l’XML viene allegato alle e-mail d’ordine.

Modello contabile EN 16931

• Modello netto — gli ordini con IVA inclusa vengono convertiti tramite le imposte calcolate di Shopware.
• Promozioni — convertite in sconti a livello documento (BG-20), una voce per aliquota IVA, perché la norma vieta le righe negative (BR-27).
• Spese di spedizione — dichiarate come oneri a livello documento (BG-21), una voce per aliquota.
• RoundingAmount (BT-114) — assorbe ogni scostamento di arrotondamento: il GrandTotal dell’XML è strettamente uguale al totale dell’ordine Shopware.
• Pagamento SEPA — bonifico codice 58 con IBAN/BIC, scadenza calcolata dalla data di fattura.

Comando console

# Rigenerare la fattura elettronica dell'ultima fattura di un ordine
bin/console df:facturx:generate 10042 --force

# Esportare l'XML in un file (per un validatore)
bin/console df:facturx:generate 10042 --output=/tmp/10042.xml

# Forzare un profilo puntualmente (implica la rigenerazione)
bin/console df:facturx:generate 10042 --profile=xrechnung-30

Checklist di convalida prima della produzione

1. Create ordini di prova che coprano i vostri casi reali: canale con IVA inclusa e canale netto, promozione, spese di spedizione, vendita intracomunitaria con partita IVA, esportazione extra UE.
2. Generate la fattura per ciascuno, poi esportate l’XML con --output.
3. Convalidate: validatore KOSIT per XRechnung, Mustang per Factur-X / ZUGFeRD.
4. Aprite il PDF ibrido in Adobe Acrobat e verificate la presenza dell’allegato factur-x.xml.

Risoluzione dei problemi

• Nessun XML generato — verificate che il plugin sia attivo per il canale di vendita, che il tipo di documento sia fattura e che la modalità solo B2B non filtri l’ordine. Consultate i log (var/log).
• Errore «Missing seller configuration» — completate la scheda Venditore (campi minimi sopra indicati).
• Avviso «PDF embedding skipped» — la struttura del PDF non ha permesso l’incorporamento; l’XML resta disponibile come allegato e-mail e via console. Caso tipico: PDF generato da un motore di terze parti.
• XRechnung rifiutato — riferimento acquirente mancante: compilate il campo personalizzato o il valore di riserva, poi --force.
• Rigenerazione dopo modifiche di configurazione — i documenti già elaborati non vengono rielaborati automaticamente; usate df:facturx:generate --force.

Limiti noti e roadmap

• Versione 1.0: solo fatture (codice 380). Note di credito (381) e fatture rettificative (384) previste per la 1.1.
• La conformità stretta PDF/A-3B dipende anche da proprietà del PDF sorgente prodotto dal motore dompdf di Shopware (font incorporati, output intent). I destinatari e gli strumenti contabili sfruttano l’XML incorporato in ogni caso; per un requisito stretto PDF/A-3B, usate il profilo XRechnung o l’allegato XML.
• Una sola riga IVA per riga d’ordine (comportamento standard di Shopware).