KSeF w WooCommerce: integracja krok po kroku i środowisko testowe przed 2026

Masz sklep WooCommerce, wystawiasz faktury dla firm i zaczynasz słyszeć o KSeF z każdej strony. Może już dostałeś pytanie od księgowej, może klient B2B zapytał, czy twój sklep jest gotowy. Jeśli nadal nie wiesz, od czego technicznie zacząć, ten artykuł jest właśnie dla Ciebie: przejdziemy przez całą ścieżkę krok po kroku, od tokena autoryzacyjnego, przez środowisko testowe, aż po wybór konkretnego rozwiązania dla WooCommerce.

Na wstępie jedno ważne zastrzeżenie: jestem webdeveloperem, nie księgowym ani doradcą podatkowym. Opisuję techniczną stronę integracji, natomiast kwestie prawne i podatkowe warto skonsultować z biurem rachunkowym, które obsługuje twój sklep.

Co to jest KSeF i kogo dotyczy w e-commerce

KSeF, czyli Krajowy System e-Faktur, to rządowa platforma Ministerstwa Finansów, przez którą mają przechodzić wszystkie faktury VAT wystawiane między firmami. Nie jest to kolejna aplikacja do fakturowania - to centralny rejestr, do którego każda faktura B2B trafia w postaci pliku XML i otrzymuje unikalny numer KSeF potwierdzający jej legalność.

Dla sklepów WooCommerce kluczowe terminy są dwa. Od 1 lutego 2026 obowiązek objął przedsiębiorców, których sprzedaż przekroczyła w 2024 roku 200 mln zł (z VAT). Od 1 kwietnia 2026 KSeF obejmuje wszystkich pozostałych czynnych podatników VAT, niezależnie od wielkości. Jeśli prowadzisz sklep i wystawiasz faktury firmom, dotyczy to też Ciebie. Więcej o terminach i progach piszę w artykule KSeF od kiedy i dla kogo - progi obrotu.

Sprzedaż wyłącznie konsumentom (B2C) na razie KSeF-u nie wymaga, choć można fakturować przez system dobrowolnie. Szczegóły tego wyjątku omawiam w osobnym tekście o fakturach B2C i dobrowolnym KSeF.

Dwie ścieżki integracji: przez API MF vs przez system fakturowy

Pierwsze pytanie, które musisz sobie zadać, to: czy integrujesz WooCommerce bezpośrednio z API Ministerstwa Finansów, czy robisz to przez pośrednika, czyli system fakturowy jak Fakturownia, wFirma lub iFirma?

Bezpośrednia integracja przez API MF oznacza, że budujesz własny konektor obsługujący podpisywanie żądań, kolejkowanie dokumentów XML zgodnych z FA(3), obsługę błędów i ponownych wysyłek. To poważne przedsięwzięcie programistyczne. Ma sens, jeśli masz własny dział IT lub chcesz pełnej kontroli i nie chcesz płacić za zewnętrzny SaaS. Większość właścicieli sklepów MSP wybiera jednak ścieżkę przez system fakturowy - i to z dobrego powodu.

Fakturownia, wFirma, iFirma i inFakt mają gotowe wtyczki dla WooCommerce i od dawna obsługują KSeF po swojej stronie. Twój sklep wysyła dane zamówienia do ich API, a system fakturowy zamienia je na poprawny XML, podpisuje, wysyła do KSeF i zwraca numer potwierdzenia. Ty nie musisz znać szczegółów schematu FA(3).

Token autoryzacyjny: jak go wygenerować i gdzie wkleić

Niezależnie od wybranej ścieżki, wszystko zaczyna się od tokena autoryzacyjnego. Jest to długi ciąg znaków (kilkaset liter i cyfr), który pełni rolę klucza API do KSeF. Generuje się go jednorazowo i - o ile go nie unieważnisz - używasz przez długi czas.

Jak to zrobić krok po kroku:

1. Wejdź na ksef.podatki.gov.pl.
2. Zaloguj się przez Profil Zaufany lub podpis kwalifikowany (nie hasłem do e-Deklaracji).
3. Przejdź do sekcji zarządzania dostępem i tokenami.
4. Wygeneruj token z odpowiednimi uprawnieniami (wystawianie faktur, odczyt).
5. Skopiuj go natychmiast - po zamknięciu okna token nie jest ponownie wyświetlany.

Ten token wklejasz nie do WooCommerce bezpośrednio, ale do ustawień systemu fakturowego (np. w panelu Fakturowni w sekcji integracji z KSeF). Wtyczka WooCommerce komunikuje się z Fakturownią, a Fakturownia z kolei używa tokena do komunikacji z MF.

Od 2026 roku KSeF 2.0 wprowadził też uwierzytelnianie przez certyfikaty generowane bezpośrednio w systemie KSeF przez sam system fakturowy - Fakturownia obsługuje ten tryb automatycznie bez konieczności ręcznego pobierania certyfikatu.

Środowisko testowe: jak i dlaczego z niego skorzystać

Środowisko testowe KSeF działa pod adresem ksef-test.mf.gov.pl. To oficjalna kopia produkcyjnego systemu MF, na której możesz wysyłać faktury bez żadnych skutków prawnych i podatkowych. API 2.0 jest tam dostępne od września 2025.

Możesz używać dowolnego testowego NIP-u - nie musi to być twój prawdziwy numer. To wygodne, bo możesz przetestować scenariusz nieznanego kontrahenta, błędnego NIP-u albo niepoprawnej stawki VAT.

W praktyce: przy jednym z wdrożeń dla klienta sprzedającego hurtowo na rynek polski spędziliśmy na testach dwa pełne dni robocze. Okazało się, że adresy zagranicznych kontrahentów (brak kodu pocztowego w formacie XX-XXX) były mapowane niepoprawnie i XML był odrzucany. Bez środowiska testowego odkrylibyśmy to na produkcji, przy prawdziwych fakturach.

Schemat FA(3): jak zamówienie WooCommerce trafia do XML

FA(3) to aktualny standard XML faktur ustrukturyzowanych, obowiązujący od 1 lutego 2026. Zastąpił wcześniejszy FA(2) i wprowadził kilka ważnych zmian w strukturze pliku.

Kluczowe pola, które muszą być poprawnie zmapowane z danych zamówienia WooCommerce:

• NIP nabywcy (pole NIP w sekcji Podmiot2) - musi być wprowadzony przez klienta na etapie kasy. Tu przydaje się plugin do obsługi pola NIP na checkout, który opisuję przy okazji bloku kasy WooCommerce.
• Adres nabywcy - w FA(3) adres jest rozbity na oddzielne pola: ulica, numer domu, miejscowość, kod pocztowy, kraj. WooCommerce standardowo trzyma je razem w jednym polu adresowym, więc wtyczka musi to rozdzielić.
• Stawki VAT (sekcja StawkiVAT) - każda pozycja w koszyku musi mieć przypisaną konkretną stawkę. W WooCommerce konfiguruje się ją przy produkcie lub kategorii.
• Typ dokumentu - faktura zwykła, zaliczkowa, korygująca lub do paragonu mają różne kody w XML.
• Data wystawienia i data sprzedaży - w e-commerce zwykle tożsame z datą zamówienia, ale przy wysyłce towarów może być różnica.

Korekty i faktury do paragonu w WooCommerce

Dwa scenariusze, które najczęściej są pomijane w planowaniu integracji: korekty i faktury do paragonu.

Korekta w KSeF to osobny dokument XML, który wskazuje numer KSeF faktury korygowanej. Jeśli klient zwróci towar i wystawisz korektę przez Fakturownię lub wFirmę, system automatycznie pobiera numer KSeF pierwotnej faktury i generuje poprawny XML korekty. Ważne: korekta musi być wysłana przez KSeF, nawet jeśli pierwotna faktura też tam była.

Faktura do paragonu (FP) dotyczy sytuacji, gdy klient przy kasie wystawił paragon fiskalny, a potem prosi o fakturę. W KSeF taki dokument wymaga podania numeru paragonu fiskalnego. W praktyce dla e-commerce ten przypadek pojawia się rzadko (sklepy internetowe zwykle od razu wystawiają faktury lub same paragony), ale warto sprawdzić, czy twoje rozwiązanie obsługuje go, jeśli masz też sprzedaż stacjonarną.

Które wtyczki działają: przegląd gotowych rozwiązań

Dla WooCommerce masz kilka sprawdzonych opcji:

Fakturownia + wtyczka WooCommerce - Fakturownia ma oficjalną wtyczkę integrującą WooCommerce z ich systemem. Integracja z KSeF 2.0 działa przez certyfikat generowany automatycznie w KSeF przez Fakturownię - nie musisz pobierać go ręcznie. Abonament Fakturowni zaczyna się od kilkudziesięciu złotych miesięcznie, zależnie od liczby faktur.

wFirma + wtyczka WooCommerce - wFirma obsługuje KSeF od marca 2023 i oferuje pełną integrację z WooCommerce. Faktury generowane z zamówień trafiają do KSeF automatycznie. Dobry wybór, jeśli już używasz wFirmy do bookkeepingu.

iFirma - podobne możliwości jak wFirma, z własną wtyczką do WooCommerce. Środowisko testowe obsługiwane.

WP Desk Faktury WooCommerce - wtyczka WP Desk pozwala na bezpośrednią integrację z KSeF (bez pośrednika SaaS), ale wymaga więcej konfiguracji technicznej. Dla zaawansowanych użytkowników lub tych, którzy nie chcą wiązać się z konkretnym systemem fakturowym.

Studio Kalmus / inne agencje - kilka agencji WP/WooCommerce oferuje kompleksowe wdrożenia KSeF na zamówienie, z własnym konektorem lub konfiguracją wtyczek.

Plan wdrożenia: ile to zajmuje i od czego zacząć

Z mojego doświadczenia przy kilku wdrożeniach dla sklepów MSP: realistyczny harmonogram to 2-3 tygodnie od decyzji do startu produkcyjnego. Tydzień na wybór i konfigurację systemu fakturowego, tydzień na testy na środowisku testowym MF i weryfikację mapowania pól, kilka dni na poprawki i szkolenie osoby, która będzie obsługiwać faktury.

Nie zostawiaj tego na ostatni moment. Jeśli coś pójdzie nie tak z certyfikatem, tokenem lub strukturą XML, biuro rachunkowe ani support wtyczki nie zawsze odpowiada w dniu wdrożenia.

Jeśli budujesz sklep od podstaw lub planujesz większy remont techniczny, możesz połączyć to z wdrożeniem KSeF w jednym projekcie. Jak wygląda budowa sklepu WooCommerce gotowego na 2026 rok opisuję szerzej na stronie sklepy internetowe.