Integracja z KSeF: gotowa wtyczka czy własne API

Krajowy System e-Faktur ma publiczny interfejs API, więc teoretycznie każdy sklep może napisać własną integrację. Pytanie, czy warto. Właściciele sklepów słyszą czasem od zaprzyjaźnionych programistów, że to przecież tylko wysłanie pliku XML, a z drugiej strony dostawcy oprogramowania przekonują, że bez gotowego rozwiązania ani rusz. Prawda leży pośrodku i da się ją pokazać konkretnie. W tym artykule rozbieramy własną integrację na części, pokazujemy, co naprawdę trzeba zbudować i utrzymać, oraz podpowiadamy, kiedy własne API ma sens, a kiedy jest drogim błędem.

Co naprawdę obejmuje integracja z KSeF

Wysłanie faktury to ostatni i najprostszy krok całego procesu. Zanim do niego dojdzie, integracja musi obsłużyć uwierzytelnienie, które w KSeF jest kilkustopniowe. System wystawia wyzwanie, token autoryzacyjny trzeba zaszyfrować kluczem publicznym pobranym z certyfikatów systemu, a dopiero poprawnie przeprowadzona wymiana daje token dostępowy sesji, który też trzeba odświeżać. Do tego dochodzi szyfrowanie samej komunikacji i poprawne zarządzanie sesjami. Każdy z tych kroków ma swoje przypadki brzegowe i każdy potrafi się wysypać w najmniej oczekiwanym momencie.

Druga warstwa to sam dokument. Faktura ustrukturyzowana musi być zgodna ze schematem FA(3), który definiuje setki pól, ich formaty i wzajemne zależności, a dokument niezgodny ze schematem system odrzuca. Potrzebna jest więc walidacja XSD przed wysyłką i logika budowania XML z danych zamówienia, łącznie z obsługą stawek podatku, rabatów, wysyłki i walut. O tym, jak wygląda ten dokument od środka, piszemy w tekście o fakturze ustrukturyzowanej FA(3).

Warstwa, o której wszyscy zapominają, czyli tryby offline

Największa pułapka własnej integracji nie leży w szczęśliwej ścieżce, tylko w obsłudze awarii. Przepisy przewidują tryb offline24, tryb niedostępności i tryb awaryjny, każdy z innym terminem dosłania dokumentów do systemu, a od lutego 2026 roku faktury wystawiane w tych trybach wymagają dodatkowo oznaczeń kodami QR i certyfikatu KSeF. Własna integracja musi więc mieć kolejkę dokumentów, mechanizm ponawiania, rozpoznawanie rodzaju niedostępności i pilnowanie ustawowych terminów. To jest komplet funkcji, który buduje się dłużej niż całą resztę, a bez którego integracja działa tylko przy dobrej pogodzie. Szczegóły trybów opisujemy we wpisie o trybie awaryjnym i offline w KSeF.

Utrzymanie, czyli koszt, który nigdy nie znika

Integracja napisana raz nie jest napisana na zawsze. Schemat faktury już się zmieniał, obecne FA(3) zastąpiło wcześniejszą wersję, a system przeszedł na KSeF 2.0 z nowym interfejsem. Metody uwierzytelnienia też ewoluują, tokeny działają tylko do końca 2026 roku, potem zostają certyfikaty, o czym piszemy w artykule o tokenie i certyfikacie KSeF. Każda taka zmiana oznacza pracę programisty przy własnej integracji, i to pracę pilną, bo fakturowanie nie może stanąć. Przy gotowej wtyczce ta sama zmiana oznacza jedną aktualizację z kokpitu. Utrzymanie jest właśnie tym, co najbardziej różni całkowity koszt obu podejść, a które w wycenach na start bywa pomijane, co pokazujemy w zestawieniu kosztów w artykule o tym, ile kosztuje wdrożenie KSeF.

Kiedy własne API ma sens

Żeby było uczciwie, są sytuacje, w których własna integracja jest dobrą decyzją. Pierwsza to organizacja z wieloma systemami, w której faktury powstają nie tylko w sklepie, ale też w ERP, w systemie abonamentowym i w aplikacji mobilnej, a wszystko ma przechodzić przez jedną wspólną szynę dokumentów. Druga to procesy naprawdę niestandardowe, których żadne gotowe rozwiązanie nie obsłuży, na przykład nietypowe łańcuchy pośredników. Trzecia to firmy z własnym zespołem programistów, dla których utrzymanie kolejnej integracji jest naturalną częścią pracy, a pełna kontrola nad każdym bajtem ma wartość samą w sobie. W tych przypadkach koszt liczony w tysiącach złotych i ciągłe utrzymanie mają biznesowe uzasadnienie.

Kiedy wtyczka wygrywa bez dyskusji

Jeżeli Twoim źródłem faktur jest sklep na WooCommerce, rachunek wygląda inaczej. Cała logika, którą musiałby napisać programista, już istnieje, jest przetestowana na wielu sklepach i utrzymywana na bieżąco. Uwierzytelnienie, budowanie XML, walidacja XSD, kolejka offline, UPO, statusy przy zamówieniach, wszystko to dostajesz w gotowym pakiecie, który instalujesz w kilka minut zgodnie z poradnikiem integracji. Koszt to zero złotych za wersję podstawową i stała opłata roczna za automatyzację, bez płacenia za aktualizacje przy zmianach przepisów. Ryzyko projektu praktycznie nie istnieje, bo przed decyzją możesz przetestować całość w środowisku testowym KSeF na darmowej wersji.

Jest jeszcze wariant pośredni, spotykany w większych organizacjach. Sklep fakturuje przez wtyczkę, bo to najszybsza droga dla WooCommerce, a pozostałe systemy firmy korzystają z własnej integracji tam, gdzie jest naprawdę potrzebna. Te podejścia się nie wykluczają, bo każda faktura i tak trafia do tego samego systemu centralnego.

Ile pracy naprawdę wymaga własna integracja

Rozbijmy własną integrację na etapy, tak jak wyceniałby ją rzetelny wykonawca. Uwierzytelnienie i zarządzanie sesjami to pierwszy blok pracy, wraz z obsługą odświeżania tokenów i rotacji kluczy. Drugi blok to budowanie dokumentu, czyli mapowanie danych zamówienia na setki pól schematu FA(3) z obsługą stawek, rabatów, kosztów wysyłki i przypadków szczególnych, plus walidacja XSD z czytelnym raportowaniem błędów. Trzeci blok to niezawodność, kolejka dokumentów, ponawianie, tryby offline z pilnowaniem terminów, pobieranie UPO i statusów. Czwarty to testy w środowisku testowym KSeF i scenariusze awaryjne. Piąty, często pomijany w wycenach, to dokumentacja i przekazanie wiedzy, bo integracja, którą rozumie tylko jeden programista, jest ryzykiem sama w sobie.

Każdy z tych bloków to dni lub tygodnie pracy inżynierskiej, a łącznie projekt liczony w tygodniach, nie dniach. Do tego dochodzi dyżur przy każdej zmianie po stronie systemu. Gotowa wtyczka pakuje dokładnie tę samą pracę w produkt, którego koszt rozkłada się na wszystkich użytkowników, i właśnie dlatego różnica cenowa między oboma podejściami jest tak duża. Nie płacisz za mniej pracy, płacisz za pracę wykonaną raz i współdzieloną.

Jak podjąć decyzję w praktyce

Sprowadź decyzję do trzech pytań. Czy faktury powstają wyłącznie w sklepie WooCommerce? Jeśli tak, wtyczka. Czy masz zespół, który będzie utrzymywał integrację przez lata, także przy zmianach schematu i metod uwierzytelnienia? Jeśli nie, wtyczka. Czy Twoje procesy wykraczają poza to, co potrafi dobre gotowe rozwiązanie? Sprawdź to na liście kryteriów z poradnika o tym, jak wybrać wtyczkę KSeF, zanim założysz, że potrzebujesz czegoś szytego na miarę, bo w praktyce ta odpowiedź brzmi tak rzadziej, niż się wydaje.

Jeśli po tych trzech pytaniach wychodzi Ci wtyczka, zacznij od naszej darmowej wersji z katalogu WordPress.org i sprawdź cały proces na środowisku testowym. Listę wszystkiego, co dostajesz w pakiecie, znajdziesz na stronie funkcji. Własne API zawsze zdążysz napisać, ale najpierw warto sprawdzić, czy jest po co.