DataFirefly Factur-X SW — Facture électronique Shopware 6 : guide complet

Présentation

DfFacturX SW génère des factures électroniques conformes EN 16931 pour Shopware 6.5, 6.6 et 6.7. À chaque création d’un document de facture, le plugin construit un XML UN/CEFACT CII et, selon le profil choisi, l’embarque dans le PDF de facture (Factur-X / ZUGFeRD) ou le fournit en fichier autonome (XRechnung 3.0 pour le B2G allemand).

• Factur-X / ZUGFeRD EN 16931 — profil recommandé pour le B2B : le PDF téléchargé par le client est l’e-facture hybride.
• Factur-X BASIC — profil allégé, pour les destinataires qui n’exigent pas le jeu complet EN 16931.
• XRechnung 3.0 — XML autonome en syntaxe CII pour facturer les administrations allemandes, avec Leitweg-ID obligatoire.

Installation

1. Copiez le dossier du plugin dans custom/plugins/DfFacturX (ou uploadez le ZIP depuis l’admin, Extensions puis Mes extensions).
2. Exécutez :

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

Configuration

Admin, Extensions, DfFacturX, Configuration. Tous les réglages sont scopés par canal de vente.

Général

• Activer la génération — déclenche la création du XML à chaque nouveau document de facture.
• Profil — Factur-X EN 16931, Factur-X BASIC ou XRechnung 3.0.
• Embarquer le XML dans le PDF — pour les profils Factur-X ; le média du document est remplacé par le PDF hybride.
• Joindre le XML aux e-mails — ajoute factur-x.xml (ou numéro-xrechnung.xml) aux e-mails de commande.
• B2B uniquement — ne génère que si la commande porte une société ou un numéro de TVA.

Vendeur

Raison sociale, rue, code postal, ville, pays (ISO-2), numéro de TVA (BT-31), numéro fiscal (BT-32), e-mail (BT-34), téléphone et personne de contact (BG-6). L’e-mail et le contact sont exigés par XRechnung.

Paiement

IBAN et BIC (virement SEPA, code 58), texte des conditions de paiement (BT-20) et délai d’échéance en jours (BT-9). Sans IBAN, le moyen de paiement est déclaré en code 1 (non défini).

Gestion de la TVA

Pour les taux à 0 %, le mode Automatique applique : K livraison intracommunautaire (acheteur avec TVA dans un autre pays UE), G export hors UE, Z sinon. Vous pouvez forcer une catégorie fixe (Z, E, K, G) et personnaliser le motif d’exonération (BT-120).

XRechnung

Nom technique du champ personnalisé contenant la référence acheteur (par défaut df_facturx_buyer_reference) et valeur de repli si aucun champ n’est renseigné.

Leitweg-ID et référence acheteur (BT-10)

Saisissez le Leitweg-ID une fois sur la fiche client (onglet champs personnalisés) : il sera repris sur toutes ses factures. Pour un cas ponctuel, renseignez-le directement sur la commande — la valeur commande prime sur la valeur client, qui prime sur la valeur de repli.

Fonctionnement

1. À la création du document de facture (admin, Flow Builder ou API), le plugin charge la commande dans sa version de commande exacte.
2. Le XML CII est construit puis stocké dans les champs personnalisés du document (df_facturx_xml, df_facturx_profile, df_facturx_generated_at).
3. En profil Factur-X, le XML est embarqué dans le PDF par mise à jour incrémentale : fichier factur-x.xml attaché, métadonnées XMP PDF A-3 et schéma d’extension Factur-X. Le média du document est remplacé en place.
4. Si l’option est active, le XML est joint aux e-mails de commande.

Modèle comptable EN 16931

• Modèle net — les commandes TTC sont converties via les taxes calculées de Shopware.
• Promotions — converties en remises au niveau document (BG-20), une entrée par taux de TVA, car la norme interdit les lignes négatives (BR-27).
• Frais de port — déclarés en charges au niveau document (BG-21), une entrée par taux.
• RoundingAmount (BT-114) — absorbe toute dérive d’arrondi : le GrandTotal du XML est strictement égal au total de la commande Shopware.
• Paiement SEPA — virement code 58 avec IBAN/BIC, échéance calculée depuis la date de facture.

Commande console

# Régénérer l'e-facture de la dernière facture d'une commande
bin/console df:facturx:generate 10042 --force

# Exporter le XML vers un fichier (pour un validateur)
bin/console df:facturx:generate 10042 --output=/tmp/10042.xml

# Forcer un profil ponctuellement (implique la régénération)
bin/console df:facturx:generate 10042 --profile=xrechnung-30

Checklist de validation avant production

1. Créez des commandes de test couvrant vos cas réels : canal TTC et canal HT, promotion, frais de port, vente intracommunautaire avec numéro de TVA, export hors UE.
2. Générez la facture pour chacune, puis exportez le XML avec --output.
3. Validez : validateur KOSIT pour XRechnung, Mustang pour Factur-X / ZUGFeRD.
4. Ouvrez le PDF hybride dans Adobe Acrobat et vérifiez la présence de la pièce jointe factur-x.xml.

Dépannage

• Aucun XML généré — vérifiez que le plugin est activé pour le canal de vente, que le type de document est bien facture, et que le mode B2B uniquement ne filtre pas la commande. Consultez les logs (var/log).
• Erreur « Missing seller configuration » — complétez la carte Vendeur (champs minimum ci-dessus).
• Avertissement « PDF embedding skipped » — la structure du PDF n’a pas permis l’embedding ; le XML reste disponible en pièce jointe e-mail et via la console. Cas typique : PDF généré par un moteur tiers.
• XRechnung refusé — référence acheteur absente : renseignez le champ personnalisé ou la valeur de repli, puis --force.
• Régénération après changement de configuration — les documents déjà traités ne sont pas retraités automatiquement ; utilisez df:facturx:generate --force.

Limites connues et feuille de route

• Version 1.0 : factures uniquement (code 380). Avoirs (381) et factures rectificatives (384) prévus en 1.1.
• La conformité stricte PDF/A-3B dépend aussi de propriétés du PDF source produit par le moteur dompdf de Shopware (polices embarquées, output intent). Les destinataires et outils comptables exploitent le XML embarqué dans tous les cas ; pour une exigence stricte PDF/A-3B, utilisez le profil XRechnung ou la pièce jointe XML.
• Une seule ligne de TVA par ligne de commande (comportement standard Shopware).