# 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…
- Strona:
- Język: pl
- Zaktualizowano: 2026-08-06
- Inne języki: [fr](https://www.datafirefly.com/documentation/dffacturx-shopware/index.md), [en](https://www.datafirefly.com/en/documentation/dffacturx-shopware/index.md), [es](https://www.datafirefly.com/es/documentation/dffacturx-shopware/index.md), [de](https://www.datafirefly.com/de/documentation/dffacturx-shopware/index.md), [it](https://www.datafirefly.com/it/documentation/dffacturx-shopware/index.md), [nl](https://www.datafirefly.com/nl/documentation/dffacturx-shopware/index.md), [pt](https://www.datafirefly.com/pt/documentation/dffacturx-shopware/index.md)
- Indeks:
## 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
```
Aktywacja instaluje zestaw pól niestandardowych **Faktura elektroniczna (DfFacturX)** z polem `df_facturx_buyer_reference` na kliencie i zamówieniu. To tutaj wpisuje się Leitweg-ID (BT-10).
## 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.
Minimalne dane sprzedawcy: nazwa, ulica, kod pocztowy, miasto, kraj oraz numer VAT _lub_ numer podatkowy (reguła BR-CO-26). Bez nich generowanie kończy się jednoznacznym błędem w logach.
### 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ą.
Przy profilu XRechnung, jeśli nie znaleziono żadnej referencji nabywcy, wtyczka **odmawia wygenerowania** nieprawidłowego XML i rejestruje błąd. Popraw dane i uruchom ponownie z `df:facturx:generate --force`.
## 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.
W Flow Builderze dodaj akcję generowania faktury do swojego przepływu zamówienia: faktura elektroniczna powstaje automatycznie, bez dodatkowych kroków.
Z założenia błąd faktury elektronicznej nigdy nie blokuje tworzenia dokumentu: incydent jest rejestrowany, a klasyczna faktura PDF pozostaje dostępna.
## 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](https://github.com/itplr-kosit/validator) dla XRechnung, [Mustang](https://www.mustangproject.org) 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).