DataFirefly Factur-X SW — Faktura elektroniczna Shopware 6: kompletny przewodnik

Przegląd

DfFacturX SW generuje faktury elektroniczne zgodne z normą EN 16931 dla Shopware 6.5, 6.6 i 6.7. Przy każdym utworzeniu dokumentu faktury wtyczka buduje XML UN/CEFACT CII i, w zależności od wybranego profilu, osadza go w PDF faktury (Factur-X / ZUGFeRD) lub dostarcza jako samodzielny plik (XRechnung 3.0 dla niemieckiego sektora publicznego).

• Factur-X / ZUGFeRD EN 16931 — profil zalecany dla B2B: PDF pobierany przez klienta jest hybrydową fakturą elektroniczną.
• Factur-X BASIC — lżejszy profil dla odbiorców, którzy nie wymagają pełnego zestawu danych EN 16931.
• XRechnung 3.0 — samodzielny XML w składni CII do fakturowania niemieckich urzędów, z obowiązkowym Leitweg-ID.

Instalacja

1. Skopiuj katalog wtyczki do custom/plugins/DfFacturX (lub prześlij ZIP z panelu administracyjnego: Rozszerzenia, Moje rozszerzenia).
2. Wykonaj:

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

Konfiguracja

Panel administracyjny, Rozszerzenia, DfFacturX, Konfiguracja. Wszystkie ustawienia działają w zakresie kanału sprzedaży.

Ogólne

• Włącz generowanie — tworzy XML przy każdym nowym dokumencie faktury.
• Profil — Factur-X EN 16931, Factur-X BASIC lub XRechnung 3.0.
• Osadź XML w PDF — dla profili Factur-X; medium dokumentu zostaje zastąpione hybrydowym PDF.
• Dołącz XML do e-maili — dodaje factur-x.xml (lub numer-xrechnung.xml) do e-maili zamówienia.
• Tylko B2B — generuje wyłącznie, gdy zamówienie zawiera nazwę firmy lub numer VAT.

Sprzedawca

Nazwa firmy, ulica, kod pocztowy, miasto, kraj (ISO-2), numer VAT (BT-31), numer podatkowy (BT-32), e-mail (BT-34), telefon i osoba kontaktowa (BG-6). E-mail i kontakt są wymagane przez XRechnung.

Płatność

IBAN i BIC (przelew SEPA, kod 58), tekst warunków płatności (BT-20) i termin płatności w dniach (BT-9). Bez IBAN środek płatności jest deklarowany jako kod 1 (niezdefiniowany).

Obsługa VAT

Dla stawek 0 % tryb Automatyczny stosuje: K dostawa wewnątrzwspólnotowa (nabywca z numerem VAT w innym kraju UE), G eksport poza UE, Z w pozostałych przypadkach. Można wymusić stałą kategorię (Z, E, K, G) i dostosować powód zwolnienia (BT-120).

XRechnung

Techniczna nazwa pola niestandardowego z referencją nabywcy (domyślnie df_facturx_buyer_reference) oraz wartość zapasowa, gdy żadne pole nie jest wypełnione.

Leitweg-ID i referencja nabywcy (BT-10)

Wpisz Leitweg-ID raz na karcie klienta (zakładka pól niestandardowych): będzie używany na wszystkich jego fakturach. W jednostkowym przypadku wypełnij go bezpośrednio na zamówieniu — wartość zamówienia ma pierwszeństwo przed wartością klienta, a ta przed wartością zapasową.

Jak to działa

1. Przy tworzeniu dokumentu faktury (panel administracyjny, Flow Builder lub API) wtyczka ładuje zamówienie w jego dokładnej wersji.
2. XML CII jest budowany i zapisywany w polach niestandardowych dokumentu (df_facturx_xml, df_facturx_profile, df_facturx_generated_at).
3. Przy profilu Factur-X XML jest osadzany w PDF poprzez aktualizację przyrostową: załączony plik factur-x.xml, metadane XMP PDF A-3 i schemat rozszerzenia Factur-X. Medium dokumentu jest zastępowane w miejscu.
4. Jeśli opcja jest aktywna, XML jest dołączany do e-maili zamówienia.

Model księgowy EN 16931

• Model netto — zamówienia brutto są przeliczane za pomocą podatków obliczonych przez Shopware.
• Promocje — przekształcane w rabaty na poziomie dokumentu (BG-20), jeden wpis na stawkę VAT, ponieważ norma zabrania ujemnych pozycji (BR-27).
• Koszty wysyłki — deklarowane jako opłaty na poziomie dokumentu (BG-21), jeden wpis na stawkę.
• RoundingAmount (BT-114) — pochłania wszelkie odchylenia zaokrągleń: GrandTotal w XML jest dokładnie równy sumie zamówienia w Shopware.
• Płatność SEPA — przelew kod 58 z IBAN/BIC, termin płatności liczony od daty faktury.

Polecenie konsoli

# Ponowne wygenerowanie e-faktury dla ostatniej faktury zamówienia
bin/console df:facturx:generate 10042 --force

# Eksport XML do pliku (dla walidatora)
bin/console df:facturx:generate 10042 --output=/tmp/10042.xml

# Jednorazowe wymuszenie profilu (oznacza ponowne wygenerowanie)
bin/console df:facturx:generate 10042 --profile=xrechnung-30

Lista kontrolna walidacji przed produkcją

1. Utwórz zamówienia testowe obejmujące realne przypadki: kanał brutto i netto, promocja, koszty wysyłki, sprzedaż wewnątrzwspólnotowa z numerem VAT, eksport poza UE.
2. Wygeneruj fakturę dla każdego z nich, następnie wyeksportuj XML z --output.
3. Zweryfikuj: walidator KOSIT dla XRechnung, Mustang dla Factur-X / ZUGFeRD.
4. Otwórz hybrydowy PDF w Adobe Acrobat i sprawdź obecność załącznika factur-x.xml.

Rozwiązywanie problemów

• Brak wygenerowanego XML — sprawdź, czy wtyczka jest aktywna dla kanału sprzedaży, czy typ dokumentu to faktura i czy tryb tylko B2B nie filtruje zamówienia. Zajrzyj do logów (var/log).
• Błąd „Missing seller configuration” — uzupełnij kartę Sprzedawca (minimalne pola powyżej).
• Ostrzeżenie „PDF embedding skipped” — struktura PDF nie pozwoliła na osadzenie; XML pozostaje dostępny jako załącznik e-mail i przez konsolę. Typowy przypadek: PDF wygenerowany przez silnik zewnętrzny.
• XRechnung odrzucony — brak referencji nabywcy: wypełnij pole niestandardowe lub wartość zapasową, następnie --force.
• Ponowne generowanie po zmianach konfiguracji — już przetworzone dokumenty nie są przetwarzane ponownie automatycznie; użyj df:facturx:generate --force.

Znane ograniczenia i plan rozwoju

• Wersja 1.0: tylko faktury (kod 380). Noty kredytowe (381) i faktury korygujące (384) zaplanowane na 1.1.
• Ścisła zgodność z PDF/A-3B zależy również od właściwości źródłowego PDF generowanego przez silnik dompdf Shopware (osadzone czcionki, output intent). Odbiorcy i narzędzia księgowe w każdym przypadku przetwarzają osadzony XML; przy ścisłym wymogu PDF/A-3B użyj profilu XRechnung lub załącznika XML.
• Jedna linia VAT na pozycję zamówienia (standardowe zachowanie Shopware).