Integracja KSeF w systemie, którego nie można zaktualizować
Najtrudniejsze wdrożenia KSeF nie dotyczą nowych aplikacji, tylko systemów, które działają od kilkunastu lat i których nikt nie chce ruszać. Problem zwykle nie leży w samym API — leży w środowisku uruchomieniowym, które nie potrafi nawiązać wymaganego połączenia.
- Stare systemy najczęściej nie łączą się z KSeF nie z powodu API, lecz dlatego, że ich środowisko obsługuje wyłącznie przestarzałe wersje TLS.
- Rozwiązaniem jest usługa pośrednicząca na nowoczesnym środowisku — stary system nie musi umieć niczego nowego.
- Aplikacji produkcyjnej się nie przepisuje. Zmiany po stronie KSeF dotykają wyłącznie pośrednika.
- Najwięcej czasu zabiera nie wysyłka, tylko odwzorowanie modelu faktury na strukturę wymaganą przez KSeF.
Terminy, które wyznaczają presję
Obowiązek wchodził etapami i większość firm jest już w systemie. Data, która zostaje, jest jedna — i to ona decyduje o tym, ile realnie zostało czasu.
Jednorazowe przekroczenie progu 10 tys. zł w miesiącu oznacza wejście do KSeF trwale — nie da się z niego wyjść, wracając poniżej limitu.
Jeśli terminy Cię gonią i szukasz najkrótszej drogi, a nie docelowego rozwiązania — zobacz co zrobić, gdy zostało kilka tygodni.
Dlaczego stare systemy nie łączą się z KSeF
Kiedy firma dostaje zadanie „podłączcie nasz system do KSeF", pierwsze założenie brzmi: trzeba napisać klienta API. W systemach sprzed dekady to założenie jest błędne i ujawnia się to dopiero przy pierwszym połączeniu testowym.
Standardowe wydania Javy 6 obsługują TLS w wersji 1.0. Nowoczesne API rządowe wymagają co najmniej TLS 1.2 i odrzucają wcześniejsze wersje. Połączenie kończy się niepowodzeniem na etapie uzgadniania protokołu — zanim zostanie wysłany jakikolwiek dokument. Poprawnie napisany kod integracji nic tu nie zmienia, bo ograniczenie leży poziom niżej.
Ten sam mechanizm dotyczy nie tylko Javy. Starsze wersje .NET, PHP i systemów opartych o biblioteki systemowe mają analogiczne ograniczenia. Pytanie nie brzmi „jak napisać integrację", tylko „czy to środowisko w ogóle jest w stanie się połączyć".
Usługa pośrednicząca zamiast przepisywania systemu
Zamiast podnosić wersję środowiska całej aplikacji — co przy systemie z kilkudziesięcioma tysiącami linii kodu i zależnościami sprzed dekady oznacza migrację, nie aktualizację — stawia się małą, osobną usługę na nowoczesnym środowisku.
| Warstwa | Odpowiedzialność |
|---|---|
| System sprzedażowy | Wystawia fakturę i przekazuje ją dalej. Przechowuje status i numer z KSeF. |
| Usługa pośrednicząca | Bezpieczne połączenie, sesja, uwierzytelnienie, wysyłka, odpytanie o status. |
| KSeF | Przyjmuje dokument, nadaje numer, zwraca wynik przetworzenia. |
Podział ma jeszcze jedną zaletę, która ujawnia się dopiero po wdrożeniu: zmiana wersji struktury faktury albo sposobu uwierzytelniania wymaga aktualizacji wyłącznie pośrednika. System produkcyjny zostaje nietknięty — nie trzeba go budować, testować ani wdrażać ponownie.
Najtrudniejsza część to nie wysyłka
Samo połączenie i przesłanie dokumentu udaje się zwykle w kilka dni. Reszta projektu schodzi na odwzorowaniu tego, co system trzyma w bazie, na strukturę wymaganą przez KSeF — a te dwie rzeczy prawie nigdy nie są zgodne.
Typowe punkty zapalne: dane, które w istniejącym systemie powstają dopiero na wydruku faktury i nie istnieją jako pola; kontrahenci zagraniczni i kody krajów; korekty; zaokrąglenia stawek, które muszą zgadzać się co do grosza; rabaty i pozycje o zerowej wartości. Każdy z tych przypadków ujawnia się dopiero na prawdziwych danych, nie na testowych.
Zrealizowane wdrożenie
Wdrożenie w systemie magazynowo-sprzedażowym działającym produkcyjnie od kilkunastu lat, o wielkości ponad 76 tysięcy linii kodu. Środowisko: Java 6, Spring 2.5, JSF, Hibernate, Tomcat — wersje, których nie dało się podnieść bez migracji całej aplikacji.
| Element | Zakres |
|---|---|
| Moduł integracji | 22 klasy, ok. 2 400 linii kodu |
| Wysyłka | Zadanie cykliczne: wysyłka nowych dokumentów i odpytanie o statusy wcześniejszych |
| Struktura faktury | Generowanie XML w obowiązującej strukturze FA, z osobnego modelu |
| Zmiany w systemie | Kilka kolumn przy dokumencie sprzedaży. Logika sprzedaży nietknięta. |
System działa dalej na swoim środowisku i wysyła faktury do KSeF. Nie został przepisany ani zmigrowany.
Pytania, które padają najczęściej
Do kiedy trzeba mieć gotową integrację z KSeF?
Obowiązek wystawiania faktur w KSeF objął firmy o sprzedaży powyżej 200 mln zł od 1 lutego 2026 roku, a pozostałych przedsiębiorców od 1 kwietnia 2026. Najmniejsze firmy — o sprzedaży do 10 tys. zł miesięcznie przy fakturach nieprzekraczających 450 zł — wchodzą do systemu 1 stycznia 2027.
Kluczowa jest jednak inna data: 1 stycznia 2027 uruchamiane są kary administracyjne sięgające 100% kwoty VAT z faktury wystawionej poza systemem. Do tego momentu brak integracji jest problemem operacyjnym; po nim staje się problemem finansowym.
Czy stary system trzeba przepisać, żeby wysyłał faktury do KSeF?
Nie. W większości przypadków wystarczy dołożyć warstwę, która przejmuje komunikację z KSeF, zamiast zmieniać sam system. Aplikacja nadal wystawia faktury tak jak dotąd — dochodzi jej tylko jedno miejsce, w którym oddaje gotowy dokument dalej.
Przepisanie działającego systemu magazynowo-sprzedażowego to projekt na kilkanaście miesięcy i budżet o rząd wielkości większy. Integracja przez warstwę pośredniczącą to kwestia tygodni.
Dlaczego system na starej Javie nie połączy się z KSeF?
Najczęstszą przyczyną nie jest samo API, tylko szyfrowanie połączenia. Standardowe wydania Javy 6 obsługują TLS w wersji 1.0, a nowoczesne API rządowe wymagają co najmniej TLS 1.2. Połączenie nie dochodzi do skutku na etapie uzgadniania protokołu — zanim jeszcze jakikolwiek dokument zostanie wysłany.
To dlatego problem nie znika po napisaniu poprawnego klienta HTTP. Nie chodzi o kod integracji, tylko o możliwości środowiska uruchomieniowego, w którym ten kod działa.
Czy nie da się po prostu podnieść wersji Javy?
Czasem tak i wtedy jest to najprostsza droga. Częściej nie: aplikacje z tamtego okresu korzystają z bibliotek, które nie działają na nowszych wersjach, a ich odpowiedniki wymagają przepisania znacznych fragmentów systemu. Podniesienie Javy przestaje być zmianą konfiguracji, a staje się migracją całej aplikacji.
Decyzję podejmuje się po przeglądzie zależności, nie z góry. Jeśli migracja jest realna, jest lepsza — daje efekt trwalszy niż obejście.
Na czym polega usługa pośrednicząca do KSeF?
To osobna, mała aplikacja działająca na nowoczesnym środowisku, ustawiona pomiędzy starym systemem a KSeF. Stara aplikacja przekazuje jej gotowy dokument prostym wywołaniem, którego jej runtime na pewno obsłuży. Pośrednik robi całą resztę: nawiązuje bezpieczne połączenie, zarządza sesją, wysyła dokument i odbiera odpowiedź.
Zysk jest podwójny. Stary system nie musi umieć niczego nowego, a zmiany po stronie KSeF — nowa wersja schemy, zmiana sposobu uwierzytelniania — wymagają aktualizacji wyłącznie pośrednika. Systemu produkcyjnego się przy tym nie dotyka.
Co się dzieje, gdy KSeF odrzuci fakturę?
Wysyłka jest procesem dwuetapowym: dokument najpierw trafia do systemu, a status przetworzenia przychodzi później. Integracja musi więc odpytywać o wynik i przechowywać go przy fakturze — łącznie z numerem nadanym przez KSeF, gdy dokument zostanie przyjęty.
To ważny szczegół projektowy: stan wewnętrzny dokumentu w systemie sprzedażowym i stan po stronie KSeF to dwie różne rzeczy i muszą być zapisywane osobno. Sklejenie ich w jedno pole jest najczęstszym źródłem błędów, których potem nie da się rozplątać bez ręcznego przeglądu.
Czy integracja wymaga zmian w bazie danych?
Tak, ale niewielkich. Przy dokumencie trzeba przechowywać status po stronie KSeF, identyfikator sesji, numer referencyjny wysyłki i docelowy numer nadany przez KSeF. To kilka kolumn — bez przebudowy modelu danych.
Ile trwa takie wdrożenie?
Zależy przede wszystkim od tego, jak wygląda model faktury w istniejącym systemie. Samo połączenie i wysyłka to najmniejsza część pracy. Najwięcej czasu zabiera odwzorowanie danych z systemu na strukturę wymaganą przez KSeF: stawki, korekty, przypadki zagraniczne, załączniki, zaokrąglenia.
W praktyce to najbardziej niedoszacowany element takich projektów. Wysyłka działa po kilku dniach, a kolejne tygodnie schodzą na przypadkach brzegowych, które ujawniają się dopiero na prawdziwych danych.
Jak sprawdzić, czy mój system sobie poradzi?
Trzy pytania wystarczą na start. W jakiej wersji środowiska działa aplikacja i czy potrafi nawiązać połączenie TLS 1.2. Czy model faktury zawiera wszystkie dane wymagane przez strukturę KSeF, czy część powstaje dopiero na wydruku. Czy jest miejsce, w którym da się zapiąć wysyłkę, nie przebudowując logiki sprzedaży.
Odpowiedź na te trzy pytania określa, czy mówimy o tygodniach, czy o miesiącach.
Źródła
Stan na 5 września 2026. Terminy ustawowe bywają zmieniane — przy decyzjach sprawdź datę publikacji źródła.
Masz system, którego nie chcesz ruszać?
Napisz, w czym działa i jak wystawia faktury. Odpowiem, czy w tym przypadku wystarczy warstwa pośrednicząca, czy sensowniejsza jest migracja — i z czym wiąże się jedno i drugie.