Factur-X: kompletny przewodnik (PrestaShop 8 i 9)

Ten przewodnik obejmuje instalację, konfigurację i użycie modułu DataFirefly Factur-X (dffacturx) dla PrestaShop 8 i 9. Moduł zamienia Twoje zamówienia w hybrydowe e-faktury w formacie Factur-X: czytelny i drukowalny PDF/A-3b, który zawiera osadzone w środku ustrukturyzowane dane faktury w formacie XML CII (norma EN 16931).

Prezentacja

Faktura Factur-X to jeden plik łączący dwa zastosowania. Twój klient otwiera klasyczny PDF, który może przeczytać, wydrukować i zarchiwizować. Jego program księgowy lub platforma przetwarzająca fakturę czyta bezpośrednio osadzony XML, bez interpretowania obrazu. Nie ma już dwóch plików do synchronizowania, więc znika ryzyko rozbieżności między tym, co wyświetlane, a tym, co przetwarzane.

Moduł pokrywa generowanie tych plików: produkuje XML, renderuje PDF i osadza jedno w drugim wraz z oczekiwanymi metadanymi. Transmisja przez Platformę Akredytowaną to osobna warstwa, opisana w sekcji o zakresie regulacyjnym.

Wymagania

• PrestaShop 8.0 do 9.x
• PHP minimum 7.4, zalecane 8.1 lub nowsze
• TCPDF, dostarczany fabrycznie z PrestaShop: żadnej dodatkowej instalacji
• Rozszerzenia PHP: dom (budowa XML), zlib (odczyt skompresowanych metadanych XMP), zip (generowanie masowe)

Instalacja

1. W zapleczu przejdź do Moduły → Menedżer modułów → Zainstaluj moduł.
2. Prześlij plik dffacturx.zip. Możesz też skopiować katalog dffacturx bezpośrednio do katalogu modules/ sklepu.
3. Uruchom instalację. Moduł rejestruje hooki i tworzy zakładkę Factur-X pod menu Zamówienia.
4. Otwórz konfigurację i uzupełnij tożsamość sprzedawcy przed wygenerowaniem pierwszej faktury.

Konfiguracja

Tożsamość sprzedawcy

To etap obowiązkowy. Te informacje zasilają zarówno widoczny PDF, jak i ustrukturyzowany XML. Bez nich XML zostanie odrzucony przez walidator.

• Nazwa firmy: wstępnie wypełniona nazwą sklepu, do poprawienia, jeśli Twoja nazwa prawna się różni.
• SIREN: 9 cyfr, bez spacji. Niezbędny: jest przekazywany w XML z właściwym identyfikatorem schematu.
• SIRET: 14 cyfr, opcjonalny, ale zalecany.
• Numer VAT UE: niezbędny, jeśli jesteś podatnikiem VAT (np. FR12345678901).
• Forma prawna i kapitał zakładowy: wyświetlane w notach prawnych w stopce faktury.
• Adres, kod pocztowy, miasto, kraj: kraj jest oczekiwany w dwuliterowym formacie ISO (np. FR).
• Kontakt, telefon, e-mail: przenoszone do XML w profilach EN 16931 i wyższych.

Profil Factur-X

Profil określa poziom szczegółowości XML i identyfikator specyfikacji, który jest w nim zapisywany. Moduł dopasowuje go automatycznie do Twojego wyboru.

• EN 16931: zalecany. Odpowiada pełnemu fundamentowi normy europejskiej, akceptowany wszędzie.
• BASIC: lżejszy XML, zachowuje szczegóły pozycji.
• EXTENDED: profil rozszerzony, dla przypadków wymagających dodatkowych danych.
• MINIMUM i BASIC WL: profile bez szczegółów pozycji, zarezerwowane dla zastosowań specyficznych.

Opcje

• Pobieranie po stronie klienta: aktywuje link w panelu konta. Moduł sprawdza, czy zamówienie należy do zalogowanego klienta, zanim wyda plik.
• Automatyczne generowanie: jeśli podasz identyfikator statusu zamówienia, faktura jest generowana i zapisywana w katalogu generated modułu, gdy tylko zamówienie osiągnie ten status. Ewentualne błędy są zapisywane w logach PrestaShop, nie blokując zmiany statusu.

Generowanie faktury

Z karty zamówienia

Otwórz zamówienie w zapleczu: panel Factur-X pojawia się na dole strony głównej. Przypomina aktywny profil i oferuje dwa przyciski: Pobierz PDF Factur-X dla kompletnego pliku hybrydowego oraz Pobierz XML dla samego XML, przydatnego w fazach testów i walidacji.

Generowanie masowe

Menu Zamówienia → Factur-X wyświetla listę zamówień z bezpośrednim dostępem do PDF i XML w każdym wierszu. Aby przetworzyć partię, zaznacz odpowiednie zamówienia i wybierz akcję zbiorczą Pobierz Factur-X (ZIP): moduł składa wszystkie faktury w jedno archiwum. Jeśli któreś zamówienie się nie powiedzie, jest pomijane, a błąd jest rejestrowany; archiwum pozostaje użyteczne.

Po stronie klienta

Jeśli opcja jest aktywna, w panelu konta pojawia się link Moje faktury Factur-X. Kontroler front sprawdza, czy klient jest zalogowany i czy zamówienie do niego należy; w przeciwnym razie przekierowuje do historii zamówień.

Co zawiera wygenerowany plik

Wyprodukowany PDF to PDF/A-3b renderowany przez TCPDF z PrestaShop. Moduł dodaje następnie, przez przyrostową aktualizację, elementy, które czynią z niego fakturę Factur-X:

• obiekt pliku osadzonego zawierający XML, nazwany factur-x.xml;
• wpis w tablicy plików powiązanych katalogu, z relacją Data;
• wpis w słowniku nazwanych plików osadzonych;
• metadane XMP opisujące typ dokumentu, nazwę pliku, wersję i poziom zgodności, wraz z odpowiadającym schematem rozszerzenia PDF/A.

Przyrostowa aktualizacja dodaje te obiekty na końcu pliku, nie zmieniając ani jednego bajta wyrenderowanego dokumentu. Czcionki, strumienie treści i profil kolorystyczny wyprodukowane przez TCPDF pozostają nietknięte, a moduł nie zależy od żadnego wewnętrznego szczegółu TCPDF, więc od żadnej konkretnej wersji.

XML to CrossIndustryInvoice UN/CEFACT. Zawiera kontekst dokumentu z identyfikatorem specyfikacji profilu, nagłówek faktury, pozycje (jeśli dotyczy), umowę handlową (sprzedawca i nabywca), dostawę oraz rozliczenie z podziałem VAT, rabatami, opłatami i podsumowaniem monetarnym.

Modelowanie księgowe

Walidatory Factur-X nie porównują Twoich sum z sumami PrestaShop: sprawdzają, czy dokument jest spójny sam ze sobą. Moduł przelicza więc wszystkie kwoty z pozycji i podziału VAT, aby spełnić reguły równowagi normy.

• Pozycje: jednostkowa cena netto jest wyprowadzana z sumy pozycji podzielonej przez ilość. Używana jednostka to generyczny kod jednostki.
• Koszty wysyłki: modelowane jako opłata na poziomie dokumentu, z własną stawką VAT.
• Rabaty: modelowane jako allowance na poziomie dokumentu, rozdzielane proporcjonalnie na poszczególne podstawy VAT.
• Podział VAT: jedno wystąpienie na każdą napotkaną stawkę, z podstawą, kwotą i kategorią.
• Kategoria VAT: kategoria standardowa przy stawce większej od zera, kategoria zerowa w przeciwnym razie.
• Zaliczka: kwota przedpłacona wynosi zero, a kwota do zapłaty równa się sumie brutto: faktura jest wystawiona, całość pozostaje należna w sensie dokumentu.

Szczególne przypadki VAT: zwolnienie, odwrotne obciążenie, dostawa wewnątrzwspólnotowa, nie są wyprowadzane automatycznie. Jeśli Twoja działalność je obejmuje, zwaliduj kilka reprezentatywnych faktur i dostosuj używaną kategorię.

Walidacja przed wdrożeniem produkcyjnym

Ten etap nie jest opcjonalny. Wygeneruj kilka faktur reprezentatywnych dla Twojej działalności: proste zamówienie, zamówienie z rabatem, zamówienie z kilkoma stawkami VAT, a następnie skontroluj je za pomocą:

• walidatora FNFE-MPE, francuskiej referencji dla Factur-X;
• Mustangproject, walidatora open source dla zgodności z EN 16931;
• veraPDF, dla zgodności kontenera PDF/A-3.

Przycisk pobierania samego XML jest stworzony do tej fazy: oszczędza Ci ręcznego wydobywania załącznika z PDF przy każdej próbie.

Zakres regulacyjny

Francuska reforma fakturowania elektronicznego przebiega dwuetapowo. Od 1 września 2026 wszystkie firmy podlegające VAT muszą być w stanie odbierać e-faktury, a duże firmy i ETI muszą je wystawiać. Od 1 września 2027 obowiązek wystawiania rozszerza się na MŚP, mikrofirmy i jednoosobowe działalności. Większość sprzedawców PrestaShop musi więc odbierać już od 2026 i wystawiać od 2027.

Należy rozróżnić trzy role:

• Generowanie zgodnych plików Factur-X: to robi ten moduł. Nie jest wymagana żadna certyfikacja ani rejestracja.
• Transmisja faktur przez Platformę Akredytowaną (dawniej PDP). Sprzedawca wybiera platformę i przekazuje jej pliki.
• Bycie Platformą Akredytowaną: działalność podlegająca rejestracji państwowej, poza zakresem modułu.

Rozwiązywanie problemów

Walidator odrzuca XML

Najpierw sprawdź tożsamość sprzedawcy, w szczególności SIREN i numer VAT: to najczęstsze przyczyny odrzucenia. Następnie skontroluj adres rozliczeniowy klienta; brakujący kraj lub kod pocztowy również może zablokować walidację.

Komunikat o niedostępności TCPDF

Moduł używa klasy TCPDF dostarczanej przez PrestaShop, a w razie jej braku próbuje załadować ją z katalogu narzędzi. Jeśli błąd się utrzymuje, biblioteka została usunięta z Twojej instalacji: przywróć ją z archiwum PrestaShop tej samej wersji.

Akcja zbiorcza ZIP jest niedostępna

Rozszerzenie PHP zip nie jest aktywne na serwerze. Pobieranie pojedyncze z każdej karty zamówienia pozostaje dostępne bez niego.

Automatyczne generowanie nic nie produkuje

Sprawdź, czy identyfikator statusu zamówienia jest uzupełniony w konfiguracji, a następnie czy katalog generated modułu ma prawa zapisu. Błędy generowania są rejestrowane w logach PrestaShop z prefiksem Factur-X.

PDF się otwiera, ale załącznik nie jest widoczny

Nie wszystkie czytniki wyświetlają domyślnie panel załączników. Otwórz dedykowany panel w swoim czytniku PDF lub użyj pobierania samego XML, aby skontrolować jego zawartość.

Architektura

Moduł ma klasyczną organizację, z ręcznym autoloaderem PSR-4, którego korzeń przestrzeni nazw DataFirefly/FacturX wskazuje na katalog src.

• src/Builder: definicja profili i budowa XML CII.
• src/Pdf: rendering PDF/A-3b i osadzanie XML.
• src/Service: ekstrakcja danych zamówienia i orkiestracja.
• src/Install: instalacja, zakładka administracyjna i hooki.
• controllers/admin i controllers/front: kontrolery pobierania w zapleczu i na froncie.

Architektura opiera się na ModuleAdminController i Smarty, identycznych w PrestaShop 8 i 9, bez osobnej gałęzi kodu i bez specyficznej zależności Symfony.

Changelog

1.0.0, 4 czerwca 2026

• Generowanie hybrydowych faktur Factur-X: PDF/A-3b z osadzonym XML CII.
• Wybieralne profile BASIC, EN 16931 i EXTENDED.
• Budowa XML CII zgodnego z UN/CEFACT z podziałem VAT według stawek.
• Autonomiczne osadzanie XML przez przyrostową aktualizację PDF.
• Wstrzykiwane metadane XMP Factur-X i schemat rozszerzenia PDF/A.
• W pełni konfigurowalna tożsamość sprzedawcy.
• Pobieranie PDF i XML z karty zamówienia, generowanie masowe do ZIP.
• Aktywowalny link pobierania w panelu klienta.
• Opcjonalne automatyczne generowanie przy przejściu w wybrany status zamówienia.
• Zgodność z PrestaShop 8.0 do 9.0 bez osobnej gałęzi kodu.