Własna integracja z KSeF opłaca się wtedy, gdy faktury powstają w Twoim systemie, a nie w programie księgowym. Jeśli sklep, panel klienta albo system B2B sam decyduje, kiedy i na jaką kwotę wystawić dokument, to on musi rozmawiać z Krajowym Systemem e-Faktur bezpośrednio przez API - uwierzytelnić się, wysłać fakturę w wymaganym formacie i odebrać numer KSeF. W każdej innej sytuacji - gdy faktury robi księgowa w swoim programie albo wystarcza gotowa wtyczka - własna integracja jest wydatkiem bez pokrycia.
KSeF już działa: od lutego 2026 obowiązuje największych podatników, od kwietnia 2026 pozostałych. Pytanie nie brzmi więc „czy”, tylko „którędy”.
Czym jest integracja z KSeF przez API
Integracja z KSeF przez API to bezpośrednie połączenie Twojego systemu z Krajowym Systemem e-Faktur, bez pośrednictwa programu księgowego ani ręcznego wgrywania plików. Twój system sam się uwierzytelnia, buduje fakturę w wymaganym formacie XML, wysyła ją, odbiera nadany numer KSeF i potwierdzenie odbioru, a potem zapisuje jedno i drugie przy zamówieniu.
Klasyczny układ wygląda inaczej: sklep generuje PDF, ktoś przepisuje dane do programu księgowego, a program księgowy wysyła dokument do KSeF. Przy własnej integracji ten środkowy człon znika.
Kiedy wystarczy gotowe rozwiązanie
Gotowa wtyczka albo integracja po stronie księgowości wystarcza w większości małych i średnich firm. Jeśli wystawiasz kilkadziesiąt faktur miesięcznie w jednym standardowym wariancie, a Twoja księgowość korzysta z programu online obsługującego KSeF od siebie - nie masz czego integrować.
To samo dotyczy sklepu, który wysyła zamówienia do ERP albo do platformy typu BaseLinker i tam wystawia faktury. Wtedy ścieżka do KSeF prowadzi przez to narzędzie, a Twoja robota kończy się na dopilnowaniu kompletności danych w zamówieniu. Jak taka droga wygląda w praktyce, rozpisałem w tekście o integracji WooCommerce z ERP i KSeF.
Kiedy własna integracja ma sens
Własna integracja z KSeF ma sens, gdy faktura jest częścią Twojego procesu, a nie osobną czynnością księgową. Sygnały, które w praktyce przesądzają sprawę:
| Sytuacja | Rekomendacja |
|---|---|
| Kilkadziesiąt faktur miesięcznie, jeden prosty wariant | Gotowa wtyczka lub księgowość online |
| Sklep wystawia faktury automatycznie po opłaceniu zamówienia | Własna integracja |
| Subskrypcje, abonamenty, cykliczne rozliczenia | Własna integracja |
| Faktury zaliczkowe, końcowe, korekty generowane przez system | Własna integracja |
| Panel klienta B2B, w którym kontrahent sam pobiera dokumenty | Własna integracja |
| Kilka spółek albo kilka kanałów sprzedaży w jednym systemie | Własna integracja |
| Faktury wystawia księgowa, system o nich nie wie | Nic nie rób po stronie systemu |
Wspólny mianownik tych „tak” jest jeden: liczba dokumentów albo złożoność reguł sprawia, że ręczne ogniwo w środku przestaje wyrabiać. Przy dwustu fakturach miesięcznie przepisywanie danych to koszt czasu i pewność, że prędzej czy później coś pojedzie z błędną kwotą.
Co musi umieć taka integracja
Dobra integracja z KSeF to nie jest „wyślij XML i gotowe”. To osiem elementów, z których każdy pominięty odzywa się później jako awaria:
- Uwierzytelnienie - system loguje się do KSeF danymi uwierzytelniającymi firmy. Poświadczenia trzymamy poza kodem, w zmiennych środowiskowych, nigdy w repozytorium
- Budowa faktury w obowiązującej schemie - faktura ustrukturyzowana to XML zgodny z opublikowaną schemą; wersje bywają zmieniane, więc musi być jedno miejsce, w którym się ją podmienia
- Mapowanie danych z Twojego systemu - pozycje zamówienia, stawki VAT, jednostki miary, rabaty, koszt dostawy, dane nabywcy. Najżmudniejsza część i źródło większości błędów
- Wysyłka i odbiór potwierdzenia - po przyjęciu dokumentu KSeF nadaje mu numer i wystawia urzędowe poświadczenie odbioru. Jedno i drugie zapisujemy przy zamówieniu, bo to dowód wystawienia
- Kolejka ponowień - odrzut albo chwilowa niedostępność systemu nie może kończyć się cichym zniknięciem faktury. Nieudane wysyłki wracają do kolejki, a Ty dostajesz powiadomienie
- Tryb awaryjny i offline - przepisy przewidują sytuacje, w których faktura powstaje poza systemem i trafia do niego z opóźnieniem. Taki dokument trzeba oznaczyć i dosłać
- Korekty i anulowania - faktura raz wysłana do KSeF nie znika, poprawia się ją korektą. Ten scenariusz obsługuje się od początku, a nie w panice przy pierwszej pomyłce
- Archiwum i podgląd - Ty i klient musicie mieć czytelną wersję dokumentu wraz z numerem KSeF, nawet jeśli oryginałem jest XML
Do tego dochodzi rzecz, o której łatwo zapomnieć przy wycenie: środowisko testowe. KSeF udostępnia je osobno i całe wdrożenie przechodzi tamtędy, zanim dotknie prawdziwych faktur.
KSeF a sklep internetowy - co się psuje najczęściej
W sklepie internetowym problemem nie jest sama wysyłka do KSeF, tylko jakość danych, które do niej trafiają. System skarbowy jest bezlitośnie dosłowny: albo dane są kompletne i poprawne, albo dokument leci odrzuceniem. Najczęstsze potknięcia w WooCommerce i podobnych sklepach:
- NIP w polu tekstowym bez walidacji - klient wpisuje ze spacjami, z myślnikami albo z przedrostkiem PL, a integracja dostaje śmieć
- Brak rozróżnienia B2B i B2C - nie każde zamówienie ma iść na fakturę; sprzedaż konsumencka rządzi się innymi regułami
- Koszt dostawy i rabaty - w sklepie to pozycje pomocnicze, w fakturze muszą mieć swoją stawkę VAT i swoje miejsce
- Zaokrąglenia - sklep liczy od brutto, faktura często od netto; różnica jednego grosza wywala cały dokument
- Zamówienia zagraniczne - inne stawki, inne oznaczenia, czasem procedura, której sklep w ogóle nie przewidział
Dlatego przy wdrożeniu w sklepie zaczynam od przeglądu danych zamówień, a nie od kodu. Jeżeli sklep zbiera dane niechlujnie, żadna integracja tego nie naprawi - naprawi to poprawiony proces zakupowy.
Wdrożenie krok po kroku
Tak wygląda kolejność, w której to robię. Jest ważna, bo problemy z KSeF zaczynają się zwykle przy danych, a nie przy samym połączeniu.
- Przegląd stanu obecnego - kto dziś wystawia faktury, w czym i ile ich jest. Tu często okazuje się, że własna integracja nie jest potrzebna
- Audyt danych - realne zamówienia z ostatnich miesięcy pod kątem kompletności: NIP-y, adresy, stawki, przypadki brzegowe. Wynikiem jest lista poprawek w sklepie
- Mapa dokumentów - jakie typy faktur system ma wystawiać i co jest wyzwalaczem (opłacenie, wysyłka, koniec okresu rozliczeniowego)
- Połączenie ze środowiskiem testowym - uwierzytelnienie, pierwszy dokument, odebranie numeru i poświadczenia
- Budowa generatora faktury - mapowanie danych na obowiązującą schemę, z testami na przypadkach brzegowych z kroku 2
- Kolejka, ponowienia, powiadomienia - to decyduje, czy integracja przetrwa pierwszą awarię
- Testy na wolumenie - kilkadziesiąt dokumentów różnego typu, łącznie z korektami, na środowisku testowym
- Przełączenie na produkcję z okresem obserwacji - przez pierwsze tygodnie patrzę na każdy odrzut i domykam luki
Etap 2 bywa dłuższy niż etapy 4-6 razem wzięte i to jest normalne. Komunikacja z API jest przewidywalna, dane w sklepie - rzadko.
Ile to kosztuje
Wdrożenie wyceniam po przeglądzie systemu, bo rozrzut jest duży. Prosty scenariusz - jeden typ faktury, jedno źródło zamówień, czyste dane - to inna robota niż panel B2B z subskrypcjami i korektami. Na cenę wpływają cztery rzeczy:
| Element | Co na to wpływa |
|---|---|
| Zakres dokumentów | Sama sprzedaż czy też zaliczki, korekty, cykliczne |
| Jakość danych w systemie | Ile trzeba poprawić w checkoucie i w bazie |
| Liczba źródeł | Jeden sklep czy sklep plus marketplace plus panel B2B |
| Utrzymanie | Schemy i wymagania się zmieniają, ktoś musi to pilnować |
Moje projekty w modelu fixed-bid mieszczą się zwykle w przedziale 5000-10000 zł netto i integracja z KSeF przy typowym sklepie wpada w te widełki. Wycenę podaję na piśmie przed startem.
Osobna pozycja to utrzymanie: wymagania po stronie systemu skarbowego bywają aktualizowane, a integracja, której nikt nie dogląda, w pewnym momencie zacznie dostawać odrzuty. Dlatego u części klientów wchodzi ona do stałej opieki technicznej - Basic 1000, Pro 2000, Premium 3500 zł netto miesięcznie.
Najczęstsze błędy przy wdrożeniu
- Start od kodu, nie od danych - integracja działa na przykładowym zamówieniu i wysypuje się na realnym ruchu
- Brak kolejki ponowień - jedna chwilowa niedostępność i część faktur po prostu nie istnieje, a nikt się o tym nie dowiaduje
- Pominięte korekty - bo „na razie nie będą potrzebne”. Będą, zwykle w pierwszym miesiącu
- Poświadczenia w kodzie repozytorium - to nie niedopatrzenie, to wyciek danych firmy
Jak to sprawdzić bez zobowiązań
Zanim cokolwiek wycenimy, robię bezpłatną diagnozę: patrzę, skąd biorą się Twoje faktury dzisiaj, ile ich jest, jak wyglądają dane w zamówieniach i czy własna integracja w ogóle jest potrzebna. Zdarza się, że kończy się to rekomendacją „zostaw jak jest, dopnij dwa pola w formularzu” - i to też jest uczciwa odpowiedź.
Jeśli integracja ma sens, dostajesz zakres i wycenę na piśmie przed startem, razem z listą poprawek po Twojej stronie. Przy większych wdrożeniach przegląd wychodzi poza faktury i dotyka całej architektury firmowego systemu B2B.
Najczęstsze pytania
Czy muszę mieć własną integrację z KSeF? Nie, jeśli faktury wystawia Twoja księgowość w swoim programie albo robi to system, którego już używasz. Własna integracja jest potrzebna dopiero wtedy, gdy dokumenty powstają automatycznie w Twoim sklepie lub panelu i nie ma sensu przepisywać ich ręcznie.
Ile trwa wdrożenie integracji z KSeF w sklepie? Przy czystych danych i jednym typie faktury to kwestia tygodni, nie miesięcy. Największą niewiadomą jest stan danych w zamówieniach - jeśli sklep zbiera NIP-y bez walidacji i ma niespójne stawki VAT, poprawki zajmują więcej czasu niż samo połączenie z API.
Czy integracja z KSeF działa z WooCommerce? Tak. WooCommerce ma pełny dostęp do danych zamówienia po stronie serwera, więc da się z niego wysyłać faktury bezpośrednio albo przez warstwę pośrednią. Wybór zależy od tego, czy sklep jest jedynym źródłem sprzedaży.
Co się dzieje, gdy KSeF nie odpowiada? Poprawnie zbudowana integracja odkłada dokument do kolejki, ponawia wysyłkę i informuje Cię, że coś czeka. Przepisy przewidują też tryb, w którym faktura powstaje poza systemem i trafia do niego z opóźnieniem - to trzeba obsłużyć w kodzie od początku, a nie dopisywać w trakcie awarii.
Powiązane: Integracja WooCommerce z ERP i KSeF · BaseLinker API - automatyzacje · Sklepy e-commerce