Factur-X: volledige gids (PrestaShop 8 en 9)

Deze gids behandelt de installatie, de configuratie en het gebruik van de module DataFirefly Factur-X (dffacturx) voor PrestaShop 8 en 9. De module zet uw bestellingen om in hybride elektronische facturen in het Factur-X-formaat: een leesbare en afdrukbare PDF/A-3b die intern de gestructureerde factuurgegevens in XML CII bevat (de norm EN 16931).

Overzicht

Een Factur-X-factuur is één bestand dat twee doelen dient. Uw klant opent een gewone PDF die hij kan lezen, afdrukken en archiveren. Zijn boekhoudsoftware, of het platform dat de factuur verwerkt, leest rechtstreeks de ingebouwde XML zonder de afbeelding te moeten interpreteren. Er zijn geen twee bestanden meer om gelijk te houden, dus ook geen risico op verschil tussen wat er staat en wat er wordt verwerkt.

De module verzorgt het aanmaken van die bestanden: hij bouwt de XML op, maakt de PDF op en bouwt het ene in het andere in, met de verwachte metadata. Het doorsturen via een erkend platform is een aparte laag, die verderop bij de reikwijdte aan bod komt.

Vereisten

• PrestaShop 8.0 tot 9.x
• PHP 7.4 minimaal, 8.1 of hoger aanbevolen
• TCPDF, dat standaard met PrestaShop meekomt, zonder extra installatie
• PHP-extensies: dom (om de XML op te bouwen), zlib (om de gecomprimeerde XMP-metadata te lezen) en zip (voor de bulkgeneratie)

Installatie

1. Ga in de backoffice naar Modules → Modulebeheer → Een module installeren.
2. Plaats het bestand dffacturx.zip. U kunt de map dffacturx ook rechtstreeks naar de map modules/ van uw winkel kopiëren.
3. Start de installatie. De module registreert zijn hooks en maakt een tabblad Factur-X aan onder het menu Bestellingen.
4. Open de configuratie en vul de identiteit van de verkoper in voordat u uw eerste factuur aanmaakt.

Configuratie

Identiteit van de verkoper

Dit is de verplichte stap. Deze gegevens voeden zowel de zichtbare PDF als de gestructureerde XML. Zonder die gegevens wijst een validator de XML af.

• Maatschappelijke naam: vooraf ingevuld met de naam van uw winkel, aan te passen als uw wettelijke benaming afwijkt.
• SIREN: 9 cijfers, zonder spaties. Onmisbaar: het gaat met de juiste schema-identificatie mee in de XML.
• SIRET: 14 cijfers, optioneel maar aan te raden.
• Intracommunautair btw-nummer: onmisbaar als u btw-plichtig bent (bijvoorbeeld FR12345678901).
• Rechtsvorm en maatschappelijk kapitaal: verschijnen in de wettelijke vermeldingen onder aan de factuur.
• Adres, postcode, plaats en land: het land wordt verwacht als ISO-code van twee letters (bijvoorbeeld FR).
• Contact, telefoon en e-mail: worden in de XML overgenomen bij het profiel EN 16931 en hoger.

Factur-X-profiel

Het profiel bepaalt hoe gedetailleerd de XML is en welke specificatie-identificatie erin staat. De module past die automatisch aan uw keuze aan.

• EN 16931: aanbevolen. Komt overeen met de volledige basis van de Europese norm en wordt overal aanvaard.
• BASIC: een lichtere XML, met behoud van het regeldetail.
• EXTENDED: uitgebreid profiel, voor situaties die extra gegevens vragen.
• MINIMUM en BASIC WL: profielen zonder regeldetail, voor specifieke toepassingen.

Opties

• Downloaden door de klant: zet een link in de accountzone. De module controleert of de bestelling wel van de ingelogde klant is voordat hij het bestand levert.
• Automatisch aanmaken: vult u een identificatie van een besteltoestand in, dan wordt er een factuur aangemaakt en in de map generated van de module bewaard zodra een bestelling die toestand bereikt. Eventuele fouten komen in de PrestaShop-logboeken terecht zonder de statuswijziging te blokkeren.

Een factuur aanmaken

Vanaf de bestelfiche

Open een bestelling in de backoffice: onder aan de hoofdpagina verschijnt een paneel Factur-X. Het herhaalt het actieve profiel en biedt twee knoppen: Factur-X-PDF downloaden voor het volledige hybride bestand, en XML downloaden voor alleen de XML, wat handig is tijdens het testen en valideren.

Bulkgeneratie

Het menu Bestellingen → Factur-X toont uw bestellingen met per regel rechtstreekse toegang tot de PDF en de XML. Wilt u een reeks verwerken, vink dan de betrokken bestellingen aan en kies de groepsactie De Factur-X-bestanden downloaden (ZIP): de module bundelt alle facturen in één archief. Mislukt een bestelling, dan wordt die overgeslagen en de fout gelogd; het archief blijft bruikbaar.

Aan klantzijde

Staat de optie aan, dan verschijnt in de accountzone een link Mijn Factur-X-facturen. De frontcontroller controleert of de klant is ingelogd en of de bestelling van hem is, en stuurt hem anders naar de bestelhistoriek.

Wat het aangemaakte bestand bevat

De opgemaakte PDF is een PDF/A-3b die door de TCPDF van PrestaShop wordt gerenderd. De module voegt daar vervolgens via een incrementele update de onderdelen aan toe die er een Factur-X-factuur van maken:

• een ingebouwd bestandsobject met de XML, met de naam factur-x.xml;
• een vermelding in de tabel met gekoppelde bestanden van de catalogus, met de relatie Data;
• een vermelding in het woordenboek met de benoemde ingebouwde bestanden;
• XMP-metadata die het documenttype, de bestandsnaam, de versie en het conformiteitsniveau beschrijven, samen met het overeenkomstige PDF/A-uitbreidingsschema.

De incrementele update voegt die objecten achteraan het bestand toe zonder ook maar één byte van het gerenderde document te wijzigen. De lettertypen, de contentstromen en het kleurprofiel die TCPDF heeft aangemaakt, blijven ongemoeid, en de module hangt van geen enkel intern detail van TCPDF af, dus ook van geen enkele bepaalde versie.

De XML is een CrossIndustryInvoice van UN/CEFACT. Die bevat de documentcontext met de specificatie-identificatie van het profiel, de factuurkop, de regels waar van toepassing, de handelsovereenkomst (verkoper en koper), de levering, en de afwikkeling met de btw-opsplitsing, de kortingen, de kosten en het monetaire overzicht.

Boekhoudkundige modellering

Factur-X-validators vergelijken uw totalen niet met die van PrestaShop: zij controleren of het document met zichzelf samenhangt. De module herberekent daarom alle bedragen uit de regels en de btw-opsplitsing, om aan de evenwichtsregels van de norm te voldoen.

• Regels: de nettostukprijs wordt afgeleid uit het regeltotaal gedeeld door het aantal. De gebruikte eenheid is de algemene eenheidscode.
• Verzendkosten: gemodelleerd als een kost op documentniveau, met een eigen btw-tarief.
• Kortingen: gemodelleerd als een allowance op documentniveau, evenredig verdeeld over de verschillende btw-grondslagen.
• Btw-opsplitsing: één vermelding per voorkomend tarief, met grondslag, bedrag en categorie.
• Btw-categorie: de standaardcategorie bij een tarief boven nul, anders de nulcategorie.
• Voorschot: het vooraf betaalde bedrag staat op nul en het te betalen nettobedrag is gelijk aan het totaal inclusief btw: de factuur is uitgereikt en het geheel blijft in de zin van het document verschuldigd.

Bijzondere btw-gevallen (vrijstelling, verlegging, intracommunautaire levering) worden niet automatisch afgeleid. Komen die in uw activiteit voor, laat dan enkele representatieve facturen valideren en pas de gebruikte categorie aan.

Valideren vóór de productie

Die stap is niet optioneel. Maak enkele facturen aan die representatief zijn voor uw activiteit (een eenvoudige bestelling, een bestelling met korting, een bestelling met meerdere btw-tarieven) en controleer ze met:

• de validator van de FNFE-MPE, de Franse referentie voor Factur-X;
• Mustangproject, een opensourcevalidator voor de conformiteit met EN 16931;
• veraPDF, voor de conformiteit van de PDF/A-3-container.

De knop om alleen de XML te downloaden is voor die fase bedoeld: zo hoeft u de bijlage niet bij elke poging handmatig uit de PDF te halen.

Wettelijke reikwijdte

De Franse hervorming van de elektronische facturatie volgt een kalender in twee fasen. Op 1 september 2026 moeten alle btw-plichtige ondernemingen elektronische facturen kunnen ontvangen, en moeten grote ondernemingen en middelgrote bedrijven ze ook uitsturen. Op 1 september 2027 geldt de verplichting om uit te sturen ook voor kmo’s, kleine ondernemingen en micro-ondernemingen. De meeste PrestaShop-handelaars moeten dus vanaf 2026 ontvangen en vanaf 2027 uitsturen.

Er zijn drie rollen te onderscheiden:

• Aanmaken van conforme Factur-X-bestanden, wat deze module doet. Daarvoor is geen certificering of registratie nodig.
• Doorsturen van de facturen via een erkend platform (voorheen PDP). De handelaar kiest zijn platform en bezorgt het de bestanden.
• Zelf een erkend platform zijn, een activiteit waarvoor de staat een registratie oplegt en die buiten het bereik van de module valt.

Problemen oplossen

De validator weigert de XML

Controleer eerst de identiteit van de verkoper, en dan vooral het SIREN en het btw-nummer: dat zijn de meest voorkomende oorzaken van afwijzing. Controleer daarna het factuuradres van de klant, want een ontbrekend land of een ontbrekende postcode kan de validatie eveneens doen mislukken.

Melding dat TCPDF niet beschikbaar is

De module gebruikt de TCPDF-klasse die PrestaShop meelevert en probeert die anders uit de map met tools te laden. Blijft de fout, dan is de bibliotheek uit uw installatie verwijderd: zet die terug vanuit een PrestaShop-archief van dezelfde versie.

De ZIP-groepsactie is niet beschikbaar

De PHP-extensie zip staat niet aan op de server. Losse downloads vanaf elke bestelfiche blijven zonder die extensie beschikbaar.

Het automatisch aanmaken levert niets op

Controleer of de identificatie van de besteltoestand in de configuratie is ingevuld, en daarna of de map generated van de module beschrijfbaar is. Fouten bij het aanmaken komen in de PrestaShop-logboeken terecht met het voorvoegsel Factur-X.

De PDF opent maar de bijlage verschijnt niet

Niet elke lezer toont het bijlagenpaneel standaard. Open het daarvoor bestemde deelvenster van uw PDF-lezer, of download alleen de XML om de inhoud ervan te controleren.

Architectuur

De module volgt een klassieke indeling, met een handmatige PSR-4-autoloader waarvan de namespacewortel DataFirefly/FacturX naar de map src wijst.

• src/Builder: de definitie van de profielen en de opbouw van de XML CII.
• src/Pdf: het renderen van de PDF/A-3b en het inbouwen van de XML.
• src/Service: het ophalen van de bestelgegevens en de aansturing.
• src/Install: de installatie, het beheertabblad en de hooks.
• controllers/admin en controllers/front: de downloadcontrollers voor de backoffice en de frontoffice.

De architectuur steunt op ModuleAdminController en Smarty, die in PrestaShop 8 en 9 gelijk zijn, zonder aparte codetak en zonder specifieke Symfony-afhankelijkheid.

Changelog

1.0.0, 4 juni 2026

• Aanmaken van hybride Factur-X-facturen: PDF/A-3b met ingebouwde XML CII.
• De profielen BASIC, EN 16931 en EXTENDED zijn te kiezen.
• Opbouw van de XML CII conform UN/CEFACT, met btw-opsplitsing per tarief.
• Zelfstandig inbouwen van de XML via een incrementele update van de PDF.
• XMP-metadata voor Factur-X en het PDF/A-uitbreidingsschema worden geïnjecteerd.
• Volledig instelbare identiteit van de verkoper.
• PDF en XML downloaden vanaf de bestelfiche, en bulkgeneratie als ZIP.
• Downloadlink in de klantenzone, in te schakelen.
• Optioneel automatisch aanmaken bij het bereiken van een besteltoestand.
• Werkt met PrestaShop 8.0 tot 9.0 zonder aparte codetak.