KSeF w sklepie Shopware: automatyczne e-faktury (B2B i B2C)

KSeF (Krajowy System e-Faktur) przestał być tematem "na później". W 2026 roku wystawianie faktur ustrukturyzowanych stało się obowiązkowe, a sprzedawcy, którzy do tej pory generowali faktury ręcznie albo w arkuszu, muszą zautomatyzować cały proces. Dla sklepu opartego na Shopware 6 oznacza to jedno: zamówienia, dane kupującego i pozycje faktury muszą trafiać do KSeF bez udziału człowieka - poprawnie, w terminie i z możliwością obsługi korekt. Ten przewodnik wyjaśnia, jak to poukładać.

Krótka odpowiedź

Shopware nie jest programem księgowym i nie powinien samodzielnie wysyłać faktur do KSeF. W praktyce sprawdza się architektura, w której Shopware zbiera poprawne dane (faktura czy paragon, NIP, stawki VAT), a właściwą fakturę ustrukturyzowaną wystawia i wysyła do KSeF Twój system ERP lub księgowy (na przykład enova365, Comarch lub dedykowany middleware). Numer KSeF i potwierdzenie odbioru wracają następnie do zamówienia i mogą być pokazane klientowi. Sklep odpowiada za jakość danych i moment wywołania, a nie za rozmowę z API skarbówki.

Czym jest KSeF i co zmienia dla sklepu

KSeF to centralna, rządowa platforma, przez którą przechodzą faktury ustrukturyzowane - dokumenty w ustalonym formacie XML (schema FA), a nie PDF. Po wysłaniu każda faktura otrzymuje unikalny numer KSeF, a wystawca dostaje urzędowe potwierdzenie przyjęcia (UPO). To właśnie ten numer i potwierdzenie są dowodem, że faktura została skutecznie wystawiona. Konsekwencje dla sklepu są dwie: faktury muszą mieć ściśle zdefiniowaną strukturę danych, a "wystawienie" nie kończy się w momencie wygenerowania PDF - kończy się dopiero po przyjęciu dokumentu przez system.

Kto i od kiedy musi wystawiać e-faktury

Zgodnie z harmonogramem obowiązek wszedł etapami w 2026 roku: najpierw objął największe firmy (powyżej ustawowego progu obrotu z roku poprzedniego), a następnie pozostałych czynnych podatników VAT. Najmniejsze podmioty i przypadki szczególne mają osobne, późniejsze terminy. Daty i progi bywają korygowane, dlatego dokładny moment swojego obowiązku potwierdź z księgowością lub doradcą podatkowym - to decyzja podatkowa, nie techniczna. Z perspektywy wdrożenia ważne jest, że jeśli sprzedajesz do firm, integracja z KSeF nie jest opcją "na przyszłość", tylko warunkiem działania sklepu.

B2B i B2C - co właściwie musi obsłużyć sklep

To rozróżnienie decyduje o tym, jak zaprojektujesz checkout:

• Sprzedaż B2B - faktury między przedsiębiorcami przechodzą przez KSeF. Sklep musi rzetelnie zebrać dane nabywcy, przede wszystkim poprawny NIP, i jednoznacznie oznaczyć, że zamówienie wymaga faktury.
• Sprzedaż B2C - faktury dla konsumentów rządzą się odrębnymi zasadami, a paragony i faktury uproszczone mają własną ścieżkę. Część sprzedawców i tak chce wystawiać faktury konsumenckie spójnie z resztą obiegu. Sposób ich traktowania ustal z księgowością i odwzoruj tę decyzję w logice sklepu.

Kluczowy wniosek projektowy: checkout musi czytelnie rozdzielać "chcę fakturę" od "wystarczy paragon" oraz walidować NIP w momencie zakupu, a nie dopiero w ERP.

Gdzie w architekturze powstaje faktura

Najczęstszy błąd to próba wystawiania faktur bezpośrednio z Shopware. Faktura to dokument księgowy - jej numeracja, archiwizacja i wysyłka do KSeF powinny żyć w systemie, który już prowadzi Twoją księgowość. Sprawdzony podział ról wygląda tak:

• Shopware - źródło zamówienia i danych kupującego, miejsce decyzji "faktura czy paragon" oraz prezentacji statusu klientowi.
• ERP lub system księgowy - nadaje numer, generuje fakturę ustrukturyzowaną i wysyła ją do KSeF, a następnie odbiera numer KSeF i UPO.
• KSeF - przyjmuje dokument, nadaje numer i zwraca potwierdzenie.

Jeśli korzystasz już z polskiego ERP, najprawdopodobniej obsłuży on KSeF natywnie - wtedy zadaniem integracji jest niezawodne przekazanie zamówień. Zobacz nasze przewodniki po integracji z enova365 i Comarch ERP, bo to ten sam kanał wymiany danych, który posłuży do fakturowania.

Jak działa integracja krok po kroku

• 1. Zamówienie w Shopware - klient wybiera fakturę, podaje NIP, składa zamówienie.
• 2. Przekazanie do ERP - zamówienie wraz z danymi do faktury trafia do ERP przez API, najlepiej zdarzeniowo (webhook), z gwarancją, że każde zamówienie dotrze dokładnie raz.
• 3. Wystawienie i wysyłka do KSeF - ERP buduje fakturę ustrukturyzowaną i wysyła ją do KSeF, uwierzytelniając się tokenem lub certyfikatem.
• 4. Powrót numeru KSeF i UPO - po przyjęciu dokument otrzymuje numer KSeF; ERP zapisuje go razem z potwierdzeniem.
• 5. Synchronizacja do sklepu - numer faktury i jej status wracają do zamówienia w Shopware, dzięki czemu klient widzi je na koncie i w wiadomości e-mail.

Środowisko testowe KSeF pozwala przejść całą tę ścieżkę bez wystawiania prawdziwych dokumentów - wykorzystaj je do testów end-to-end, zanim przełączysz sklep na produkcję.

Co sklep Shopware musi zebrać i przekazać

Jakość faktury zaczyna się w koszyku. Sklep powinien zadbać o:

• Walidację NIP w checkoucie, najlepiej z weryfikacją formatu i statusu kontrahenta.
• Jednoznaczny wybór dokumentu - faktura czy paragon - zapisany przy zamówieniu.
• Poprawne stawki i kwoty VAT, spójne z tym, czego oczekuje ERP, łącznie z cenami dla kontrahentów B2B.
• Komplet danych nabywcy i adresów wymaganych przez schemę faktury.

Im czystsze dane wychodzą z Shopware, tym mniej odrzuceń i korekt po stronie KSeF.

Korekty, błędy i sytuacje awaryjne

Realne wdrożenie to nie tylko "szczęśliwa ścieżka". Zaplanuj z góry: faktury korygujące (zwroty, zmiany ilości, rabaty potransakcyjne), ponawianie wysyłki przy chwilowej niedostępności KSeF, idempotencję, by awaria nie wystawiła tej samej faktury dwa razy, oraz czytelną obsługę odrzuceń, gdy dane nie przejdą walidacji. Zadbaj też o archiwizację numerów KSeF i UPO - to one są dowodem wystawienia.

Najczęstsze pułapki wdrożenia

• Fakturowanie bezpośrednio z Shopware zamiast z systemu księgowego - prowadzi do problemów z numeracją i archiwizacją.
• Brak walidacji NIP w checkoucie - błędny numer blokuje fakturę dopiero w ERP, po fakcie.
• Pominięcie środowiska testowego - pierwsze błędy wychodzą wtedy na produkcji.
• Brak idempotencji i ponawiania - duplikaty albo "gubione" faktury przy chwilowej awarii.
• Niespójne mapowanie VAT między sklepem a ERP - najczęstsza przyczyna odrzuceń.

Od czego zacząć

Najlepszy pierwszy krok to uporządkowanie przepływu zamówień do ERP - bo to właśnie tym kanałem popłyną dane do faktur. Jeśli integracja z systemem księgowym już działa i jest niezawodna, dołożenie KSeF jest naturalnym rozszerzeniem, a nie nowym projektem od zera. Poznaj nasze usługi programowania Shopware oraz integracji z enova365 i Comarch ERP, albo skontaktuj się z nami, by omówić wdrożenie KSeF w Twoim sklepie.