KSeF w sklepie internetowym - co się psuje przy integracji i jak to naprawić

Faktura przestaje być plikiem, który generujesz i wysyłasz mailem. Staje się dokumentem, który dopiero po przyjęciu przez centralny system dostaje numer i zaczyna istnieć w obrocie. Dla sklepu z kilkuset zamówieniami miesięcznie to zmiana operacyjna, nie księgowa.

Według harmonogramu Ministerstwa Finansów obowiązek wchodził etapami:

Według harmonogramu Ministerstwa Finansów pierwszy etap objął firmy, które przekroczyły 200 mln zł sprzedaży za 2025 rok, a ostatni obejmie od stycznia 2027 najmniejsze podmioty ze sprzedażą do 10 tys. zł miesięcznie.

Dwie rzeczy z tego harmonogramu bywają mylone. Po pierwsze, odbieranie faktur przez system obowiązuje niezależnie od tego, czy sam już je wystawiasz. Po drugie, do końca 2026 roku nie ma kar za błędy w KSeF ani za nieprzystąpienie - Szef Krajowej Administracji Skarbowej potwierdził to publicznie. To realne okno na poukładanie integracji, ale zamyka się z końcem roku.

Zastrzeżenie na wstępie: piszemy o mechanice integracji, bo to nasza robota. Kwestie podatkowe, korekty i to, które dokumenty w ogóle podlegają obowiązkowi, ustalaj z księgowym.

Sklep zwykle nie wysyła faktur do KSeF bezpośrednio. Robi to system, który odpowiada za numerację, strukturę dokumentu i archiwizację - najczęściej program księgowy albo ERP. Sklep dostarcza dane i pokazuje klientowi wizualizację.

Stąd trzy warianty, różniące się tym, ile pracy zostaje u Ciebie.

Pierwszy wariant odpada, jeśli masz WooCommerce albo PrestaShop, bo tam nikt nie doda wtyczki za Ciebie. Trzeci ma sens przy nietypowym procesie albo dużym wolumenie, bo kosztuje najwięcej pracy.

Najczęstszy w praktyce jest drugi. I to w nim kryje się większość problemów, o których dalej - bo dane muszą przejść przez granicę między dwoma systemami, które nazywają te same rzeczy inaczej.

To najczęstsza awaria u firm, które zdążyły się przygotować wcześniej. Sklep nic nie zmienił, a dokumenty przestały wychodzić.

Przyczyna jest po stronie systemu, nie Twojej. KSeF 2.0 to nie jest ta sama bramka co wcześniej - ma nową strukturę faktury FA(3), nowe API i inny model uwierzytelniania, oparty na certyfikatach. Poświadczenia wystawione dla poprzedniej wersji nie przenoszą się automatycznie.

Praktyczna konsekwencja: każda integracja potrzebuje nowych danych dostępowych. Dotyczy to nie tylko sklepu, ale wszystkiego, co wystawia albo pobiera dokumenty w Twoim imieniu - ERP, magazynu, narzędzi automatyzujących, integracji marketplace.

Certyfikaty wydaje Ministerstwo Finansów przez Moduł Certyfikatów i Uprawnień, uruchomiony 1 listopada 2025 roku. Jeśli dostajesz błąd uwierzytelnienia, zacznij od sprawdzenia, czy integracja w ogóle używa aktualnego poświadczenia, a nie starego z wcześniejszej konfiguracji.

Druga rzecz do sprawdzenia to uprawnienia. Certyfikat sam w sobie nie wystarczy, jeśli podmiot techniczny nie ma nadanego prawa do wystawiania dokumentów w imieniu firmy.

Drugi klasyk: uwierzytelnienie przechodzi, ale dokumenty wracają z błędem. Zwykle to seria odpowiedzi 400, czyli problem po stronie treści dokumentu, nie połączenia.

Kolejność sprawdzania, od najczęstszych przyczyn:

1. Struktura XML niezgodna ze schematem. KSeF 2.0 przyjmuje FA(3). Integracja przygotowana pod poprzedni schemat będzie odbijać się od walidacji, nawet jeśli dane są poprawne merytorycznie.
2. Dane kontrahenta. Brakujący albo błędny NIP, niepełny adres, pole wypełnione tekstem tam, gdzie system oczekuje kodu.
3. Znaki, których schemat nie przyjmuje. Nazwy produktów w e-commerce bywają kreatywne. Emoji w nazwie wariantu potrafi wywrócić dokument.
4. Kwoty i zaokrąglenia. Suma pozycji musi się zgadzać z sumą dokumentu co do grosza. Rabaty liczone procentowo na poziomie koszyka to typowe źródło rozjazdu o grosz.
5. Duplikat. Ponowna wysyłka dokumentu, który już przeszedł, kończy się odrzuceniem.

Jest też błąd projektowy, który widujemy najczęściej i który nie da się naprawić poprawką w jednym polu: generowanie faktury jako PDF, a potem przepisywanie jej do XML. To odwrócona kolejność. XML jest dokumentem, PDF tylko jego wizualizacją dla klienta. Jeśli proces zaczyna się od PDF, każda niezgodność wychodzi dopiero na bramce.

Sklep sprzedaje w nocy i w weekendy, a system centralny bywa niedostępny. Bez przygotowanej ścieżki awaryjnej stają procesy wysyłkowe, bo nie ma czym domknąć zamówienia.

Przepisy przewidują tryby offline. Kluczowy warunek jest techniczny: korzystanie z nich wymaga certyfikatu wystawcy faktury, bo to on pozwala podpisać dokument lokalnie, zanim trafi do systemu. Bez niego tryb awaryjny jest teoretyczny.

Osobno istnieje tryb offline24 - dobrowolny, pozwalający zarejestrować dokument w KSeF z opóźnieniem do końca następnego dnia roboczego, przy zachowaniu faktycznej daty wystawienia.

Dla sklepu oznacza to jedno praktyczne kryterium przy wyborze narzędzia: czy potrafi samo ponowić wysyłkę. Kolejka dokumentów czekających i automatyczne ponowienie po powrocie systemu to różnica między krótką przerwą a ręcznym odtwarzaniem dziesiątek faktur.

Warto to sprawdzić przed wdrożeniem, nie przy pierwszej awarii. Przy okazji naszego testu integratora open source zwróciliśmy uwagę, że jego moduł fakturowania ma zadeklarowaną osobną zdolność ponownej wysyłki dokumentów odrzuconych albo niewysłanych. To jest dokładnie ta funkcja, o którą trzeba pytać dostawcę.

Wtyczka albo moduł to zwykle najmniejsza pozycja w tym projekcie. Koszt siedzi gdzie indziej i warto go policzyć przed decyzją.

Dane z naszych wdrożeń pokazują, że licencja modułu rzadko przekracza 10% budżetu takiego projektu - reszta to praca nad danymi i testy.

Ostatnia pozycja zasługuje na osobne zdanie. W e-commerce zwroty są normą, nie wyjątkiem, a korekta ma własną ścieżkę w systemie. Wdrożenie, które obsługuje tylko sprzedaż, jest wdrożeniem w połowie.

Jeśli dopiero układasz fakturowanie w sklepie, zacznij od podstaw - opisaliśmy je w tekście o konfiguracji faktur w WooCommerce.

Samodzielnie da się to zrobić, jeśli masz standardowy sklep, jeden system księgowy i kogoś, kto rozumie XML i API. Wtedy praca sprowadza się do konfiguracji i testów.

Zlecenie ma sens przy jednym z trzech warunków: sprzedajesz na kilku kanałach i faktury powstają w różnych miejscach, masz nietypowy proces (subskrypcje, zestawy, sprzedaż mieszana), albo po prostu nie masz kogo oddelegować, a termin już minął.

Uczciwie: przy prostym sklepie i dobrym module księgowym to nie jest projekt na tygodnie. Powiemy to wprost, jeśli tak będzie w Twoim przypadku.

Spinamy sklepy z systemami księgowymi i kurierami w ramach wdrożeń e-commerce. Napisz przez formularz kontaktowy, podając platformę sklepu, system księgowy i przybliżoną liczbę faktur miesięcznie - odpiszemy, czy to praca na kilka dni, czy na osobny projekt.

Stan przepisów i harmonogramu opisujemy zgodnie z informacjami Ministerstwa Finansów na 8 sierpnia 2026. Terminy bywają przesuwane, więc przed decyzją potwierdź je u źródła albo u swojego księgowego.