KSeF w sklepie WooCommerce od 1 stycznia 2027: techniczna lista kontrolna integracji

Autor: Grzegorz Wojterzak. Aktualizacja: 30 listopada 2026. Czas czytania: około 12 minut.

KSeF, czyli Krajowy System e-Faktur, to system Ministerstwa Finansów, przez który firmy wystawiają i odbierają faktury w postaci pliku XML w ustalonym formacie (FA(3)). PDF, który klient dostaje mailem, jest tylko wizualizacją takiej faktury.

Ten tekst jest o technice: skąd sklep bierze dane, kto wysyła fakturę, co się dzieje przy awarii i jak to przetestować. Nie rozstrzygam tu, które sprzedaże wymagają faktury w KSeF ani jak liczyć limity. To pytania do księgowej lub doradcy podatkowego. Fakty o terminach i trybach opieram na materiałach Ministerstwa Finansów z ksef.podatki.gov.pl, stan na październik 2026. Przepisy KSeF zmieniały się już kilka razy, więc przed decyzją sprawdź aktualne komunikaty.

Terminy i dlaczego 1 stycznia 2027 dotyczy też większych sklepów

• Odbiór faktur przez KSeF: wszyscy od 1 lutego 2026.
• Wystawianie: największe firmy od 1 lutego 2026, pozostałe od 1 kwietnia 2026.
• Najmniejsi: firmy, u których sprzedaż udokumentowana fakturami nie przekracza 10 000 zł brutto miesięcznie, od 1 stycznia 2027. Po przekroczeniu limitu obowiązek zaczyna się od faktury, która go przekroczyła, bez powrotu do starych zasad.

Jest jeszcze jedna data ważna dla sklepów z kasą fiskalną. Według materiałów MF do końca 2026 roku podatnicy mogą wystawiać po staremu faktury z kas rejestrujących, a paragon do 450 zł z NIP nabywcy jest uznawany za fakturę. Od 2027 roku taki paragon nie będzie już fakturą i trzeba będzie do niego wystawić fakturę w KSeF. Jeśli Twój sklep drukuje paragony z NIP dla firm, ten proces trzeba zmienić przed styczniem. Jak dokładnie, ustal z księgową.

Dla właścicieli najmniejszych firm przygotowałem osobną listę kontrolną: logowanie, certyfikaty i uprawnienia dla biura. Znajdziesz ją na mojej stronie informatyk-sieradz.pl, we wpisie o KSeF w jednoosobowej firmie od 2027 roku. Tutaj zajmuję się samym sklepem.

Krok 1: skąd sklep bierze dane do faktury

Faktura w KSeF dla firmy potrzebuje NIP nabywcy. Problem: WooCommerce w standardzie nie ma pola NIP. Dane rozliczeniowe zamówienia to imię, nazwisko, firma, adres, e-mail i telefon.

Pole NIP dodaje się wtyczką albo własnym kodem. Na co zwrócić uwagę:

• Rodzaj kasy. Nowe sklepy WooCommerce mają kasę blokową, starsze często klasyczną. Wtyczka musi obsługiwać tę, której używasz. W kasie blokowej WooCommerce udostępnia mechanizm dodatkowych pól (funkcja woocommerce_register_additional_checkout_field), w klasycznej pola dodaje się filtrami. Wtyczka napisana tylko pod klasyczną kasę w blokowej po prostu nie pokaże pola.
• Pole „chcę fakturę na firmę”. Zaznaczenie, które pokazuje NIP i nazwę firmy, jest czytelniejsze dla klienta niż zawsze widoczne pole.
• Walidacja. NIP ma 10 cyfr i cyfrę kontrolną. Sprawdzenie sumy kontrolnej w kasie wyłapie literówki, zanim faktura zostanie odrzucona. Część integracji sprawdza też firmę w wykazie podatników VAT Ministerstwa Finansów (tzw. biała lista).
• Zapis w zamówieniu. NIP musi trafić do danych zamówienia (meta zamówienia), a nie tylko do maila. Inaczej integracja go nie znajdzie.
• Dane sprzedawcy. Nazwa, adres i NIP Twojej firmy pochodzą zwykle z programu do faktur, ale adres sklepu w WooCommerce warto mieć zgodny, bo z niego korzystają podatki i wysyłka.

Krok 2: kto wysyła fakturę do KSeF

Są trzy typowe układy. Każdy działa, różnią się tym, gdzie leży certyfikat i kto odpowiada za błędy.

Przy wyborze nie sugeruj się samą ceną. Zapytaj dostawcę wtyczki lub programu o pięć rzeczy: czy obsługuje Twoją kasę (blokową lub klasyczną), czy zapisuje numer KSeF w zamówieniu, jak działa przy awarii KSeF, jak obsługuje korekty przy zwrotach i czym się uwierzytelnia (certyfikat czy token). Według obecnych przepisów tokeny miały działać do końca 2026 roku. MF zaproponowało ich utrzymanie, ale do października 2026 nie znalazłem ostatecznej zmiany przepisów. Jeśli integracja korzysta z tokena, zapytaj o plan na 2027.

Krok 3: przepływ faktury i numer KSeF w zamówieniu

Numer KSeF to identyfikator, który system nadaje fakturze po jej przyjęciu. Według MF to inny numer niż Twój numer faktury (np. FV/2027/01/15) i nie ma go w samym pliku XML. Wraca razem z UPO, czyli urzędowym poświadczeniem odbioru. Na wizualizacji faktury przesłanej do KSeF musi być kod QR, a pod nim numer KSeF.

Dlatego integracja powinna zapisać w zamówieniu co najmniej: numer faktury, numer KSeF, datę przyjęcia i status. Najprościej jako notatkę zamówienia albo osobne pole widoczne na ekranie zamówienia. Wtedy obsługa sklepu przy reklamacji widzi od razu, czy faktura „przeszła”.

Kolejka i ponawianie

Wysyłka faktury nie powinna dziać się w chwili, gdy klient klika „Kupuję i płacę”. Jeśli KSeF lub program do faktur odpowie wolno albo wcale, klient czeka, a zamówienie może się zawiesić. Poprawnie zrobiona integracja:

• wstawia zadanie do kolejki w tle, np. przez Action Scheduler, czyli wbudowany w WooCommerce mechanizm zadań w tle (podgląd w WooCommerce → Status → Zaplanowane działania),
• ponawia próbę po błędzie połączenia, z rosnącymi przerwami, i po kilku nieudanych próbach powiadamia Ciebie mailem,
• odróżnia błąd połączenia od odrzucenia faktury: przy błędzie danych (np. zły NIP) ponawianie nic nie da, trzeba poprawić dane,
• nie wysyła tej samej faktury dwa razy. MF ostrzega przed ponownym wystawieniem w KSeF faktury już wystawionej poza systemem, bo powstają dwie faktury dla jednej sprzedaży.

Kolejka w WooCommerce działa dzięki zadaniom cyklicznym WordPressa (WP-Cron). Na sklepach z małym ruchem albo z wyłączonym WP-Cronem zadania potrafią czekać godzinami. Wtedy warto ustawić prawdziwe zadanie cron w panelu hostingu. Przez WP-CLI sprawdzisz zaległe zadania tym poleceniem, które wypisuje zadania oczekujące w kolejce:

wp action-scheduler action list --status=pending --fields=hook,scheduled_date

Krok 4: tryby awaryjne KSeF

Według MF są cztery sytuacje, które trzeba obsłużyć. Program do faktur powinien umieć każdą z nich, a sklep nie powinien w tym przeszkadzać.

Krok 5: test na środowisku testowym MF

Ministerstwo Finansów udostępnia środowisko testowe i przedprodukcyjne (Demo) KSeF, na którym wystawione faktury nie mają skutków podatkowych. Dokumentacja API dla programistów i integratorów jest w dziale Integratorzy IT na ksef.podatki.gov.pl.

1. Zrób kopię sklepu i odetnij ją od klientów

   Na kopii wyłącz maile do klientów, przełącz bramkę płatności w tryb testowy i podłącz integrację do środowiska testowego KSeF, nie produkcyjnego.

2. Przejdź typowe scenariusze

   Zamówienie na firmę z NIP, zamówienie osoby prywatnej, zamówienie z błędnym NIP, zamówienie z kilkoma stawkami VAT, z kosztem wysyłki i z kodem rabatowym.

3. Sprawdź zwroty i anulowania

   Zrób zwrot częściowy i pełny. Korekty faktur wystawionych w KSeF też trafiają do KSeF, więc integracja musi umieć je wystawić albo przynajmniej powiadomić Cię, że trzeba to zrobić ręcznie.

4. Zasymuluj awarię

   Odłącz na chwilę połączenie z KSeF (np. błędnym adresem środowiska w ustawieniach integracji na kopii) i sprawdź, czy zamówienie przechodzi, faktura czeka w kolejce, a po przywróceniu połączenia wysyła się sama, tylko raz.

5. Sprawdź, co widzi klient

   Mail z wizualizacją, kod QR, numer KSeF pod kodem i dane firmy na fakturze.

Krok 6: certyfikaty, tokeny i bezpieczeństwo sklepu

Certyfikat KSeF lub token to klucz, który pozwala wystawiać faktury w imieniu Twojej firmy. Jeśli leży w bazie danych WordPressa, każdy, kto przejmie sklep, może go skopiować. A sklepy internetowe są atakowane znacznie częściej niż programy księgowe.

• Jeśli możesz, trzymaj certyfikat w programie do faktur, a sklepowi daj tylko dostęp do API programu.
• Nadawaj integracji najwęższe uprawnienia w KSeF, jakie wystarczą do wystawiania faktur.
• Kopię klucza prywatnego i hasła trzymaj poza serwerem, w menedżerze haseł lub zaszyfrowanym archiwum.
• Ogranicz liczbę administratorów sklepu i włącz logowanie dwuskładnikowe.
• Po każdym włamaniu na stronę traktuj certyfikat i token jako wykradzione: unieważnij je w Aplikacji Podatnika KSeF (jeśli nie wiesz jak, zapytaj dostawcę programu) i wygeneruj nowe. O czyszczeniu strony piszę w poradniku Wirus na stronie WordPress.

Lista kontrolna przed 1 stycznia 2027

• Kasa ma pole NIP z walidacją, działające w Twoim rodzaju kasy (blokowej lub klasycznej).
• NIP zapisuje się w danych zamówienia, widocznych na ekranie zamówienia.
• Wiesz, kto wysyła faktury do KSeF: program, wtyczka czy człowiek.
• Numer faktury i numer KSeF wracają do zamówienia.
• Wysyłka działa w tle, z ponawianiem i powiadomieniem o błędach.
• Program obsługuje tryby offline, a certyfikat typu 2 jest wgrany.
• Znasz datę wygaśnięcia certyfikatu typu 1 i plan na tokeny po 2026 roku.
• Zwroty i korekty są obsłużone automatycznie albo masz na nie procedurę.
• Proces paragonów z NIP został zmieniony razem z księgową.
• Integracja przeszła test na środowisku testowym MF.

Kiedy nie robić tego samemu

Gotową integrację z programem do faktur skonfigurujesz sam, korzystając z instrukcji dostawcy. Pomoc przydaje się, gdy:

• sklep ma własne pola, nietypową kasę albo kilka magazynów i walut,
• wtyczka do NIP działa tylko w klasycznej kasie, a Ty masz blokową (albo odwrotnie),
• chcesz połączyć sklep z programem, do którego nie ma gotowej wtyczki,
• po wdrożeniu część faktur ginie albo dubluje się,
• certyfikat lub token leży w bazie sklepu, a strona była kiedyś zainfekowana.

Pytania o to, które sprzedaże fakturować w KSeF, jak traktować paragony i zwroty od strony podatkowej, kieruj do księgowej. Ja zajmuję się tym, żeby technicznie wszystko działało.

Najczęstsze pytania