Integracja ERP z KSeF: wdrożenie, testy i tryb offline w praktyce

Terminy, które wyznaczają zakres prac

KSeF jest obowiązkowy dla dużych podatników z obrotem powyżej 200 mln PLN od 1 lutego 2026 r., a od 1 kwietnia 2026 r. obejmuje wszystkich podatników zarejestrowanych jako podatnicy VAT. Od stycznia 2026 obowiązującą strukturą faktury jest schemat FA(3), który zastąpił FA(2). Fakturowanie sektora publicznego również przechodzi przez KSeF, co czyni wcześniejszą platformę PEF zbędną.

Kary finansowe za naruszenia są zawieszone do 31 grudnia 2026 r. Od 1 stycznia 2027 r. wynoszą do 100% kwoty VAT za niewystawienie faktury przez KSeF oraz do 18,7% kwoty brutto za faktury bez VAT. Mikroprzedsiębiorcy podlegają temu samemu terminowi. Obowiązek dotyczy także firm spoza Polski, które są zarejestrowane jako płatnicy polskiego VAT i wystawiają faktury polskim nabywcom będącym płatnikami VAT, co dokłada warstwę złożoności transgranicznej.

Czego wymaga API KSeF

Platforma udostępnia API RESTful, które przyjmuje ustrukturyzowane faktury XML w schemacie FA(3). Ministerstwo Finansów opublikowało szczegółowe specyfikacje API, a cztery rozporządzenia opisują wymagania techniczne: format faktury, protokoły integracji API, procedury trybu offline oraz reguły walidacji. Zanim system zacznie przesyłać faktury, firma musi zarejestrować go w Ministerstwie Finansów.

Uwierzytelnianie opiera się na kwalifikowanych pieczęciach elektronicznych lub profilach zaufanych. W logowaniu do KSeF Profil Zaufany zostaje zastąpiony uwierzytelnianiem SSO opartym na Krajowym Węźle Identyfikacji Elektronicznej. API obsługuje zarówno sesje interaktywne do przesyłania w czasie rzeczywistym, jak i sesje wsadowe do dużych wolumenów. Każda sesja wymaga tokena bezpieczeństwa, który wygasa po określonym czasie, więc integracja musi sama obsługiwać logikę odświeżania tokenów.

Minimalny zakres funkcji, który musi objąć wdrożenie:

Generowanie XML zgodnego z oficjalnym schematem FA(3)
Uwierzytelnianie i obsługę sesji wraz z odświeżaniem tokenów
Przesyłanie i pobieranie faktur przez punkty końcowe KSeF w czasie rzeczywistym
Przechowywanie numeru KSeF, który faktura otrzymuje po akceptacji i który trzeba podawać we wszystkich późniejszych komunikatach jej dotyczących
Śledzenie statusów: czy faktura została wystawiona, przesłana, zatwierdzona czy odrzucona
Pobieranie UPO, czyli oficjalnego potwierdzenia odbioru

Mapowanie danych na schemat FA(3)

FA(3) wprowadza dodatkowe pola obowiązkowe i bardziej rygorystyczne zasady walidacji niż jego poprzednik. Najważniejsze zmiany to rozszerzone wymagania identyfikacji sprzedawcy i nabywcy, bardziej szczegółowe rozbicia podatkowe pozycji oraz nowe pola dotyczące warunków płatności i informacji o dostawie. Odwzorowanie istniejącego modelu danych faktury w ERP na FA(3) wymaga analizy pole po polu, ponieważ wiele systemów przechowuje dane w formatach i strukturach, które nie są bezpośrednio zgodne z wymaganiami KSeF.

Typowe luki widać od razu. Pola adresowe często trzeba rozdzielić na ulicę, numer budynku i numer lokalu. Numery identyfikacji podatkowej muszą spełniać precyzyjne zasady formatowania. Opisy pozycji mają limity znaków, które potrafią obciąć dane używane dzisiaj. Efektem tej pracy powinien być kompletny dokument mapowania oraz warstwa transformacji między ERP a KSeF, przetestowana na setkach rzeczywistych scenariuszy fakturowych i gotowa przed 1 kwietnia.

Dlaczego KSeF odrzuca faktury

Błędne lub niekompletne dane VAT są najczęstszym powodem odrzuceń. Schemat FA(3) weryfikuje numery identyfikacji podatkowej, adresy i dane podmiotów w bazach rządowych, a każda niezgodność kończy się odrzuceniem faktury. Przed przesłaniem system powinien walidować co najmniej:

Poprawny NIP zarówno sprzedawcy, jak i nabywcy
Prawidłową kategoryzację i obliczanie stawek VAT
Wymagane pola schematu XML: daty, kwoty, opisy
Kodowanie znaków i obsługę znaków specjalnych w polskich polach tekstowych

Czyszczenie danych podstawowych warto przeprowadzić przed integracją, a nie w jej trakcie. Numery VAT klientów i dostawców należy zweryfikować z Białą Listą.

Dwie daty jednej faktury

Gdy faktura trafia do KSeF, system przypisuje jej własną datę odbioru i to ona staje się oficjalną datą wystawienia dla celów podatkowych. Może się ona różnić od daty wygenerowania faktury w ERP, zwłaszcza gdy przesyłanie odbywa się asynchronicznie albo jest opóźnione przez problemy sieciowe. ERP musi więc przechowywać obie daty, wewnętrzną datę utworzenia i datę przypisaną przez KSeF, a logika raportowania VAT musi odwoływać się do daty KSeF.

W praktyce ten wymóg podwójnej daty oznacza zmiany w schemacie bazy danych, niestandardowe pola w ERP i aktualizację zapytań raportowych. Firmy, które przeoczą tę rozbieżność, ryzykują nieprawidłowe deklaracje VAT, a po zakończeniu okresu przejściowego 1 stycznia 2027 r. także kary.

Co psuje się w praktyce

Na wczesnym etapie zawodzą najczęściej trzy rzeczy: błędna konfiguracja certyfikatów, nieprawidłowe kierowanie ruchu między środowiskiem testowym a produkcyjnym oraz zła sekwencja inicjalizacji sesji. Każda z nich wygląda jak problem z API, a jest problemem konfiguracyjnym po stronie firmy.

Testy obciążeniowe KSeF ujawniły wąskie gardła wydajnościowe, które w szczycie powodowały przekroczenia czasu i nieudane przesyłanie. Architektura integracji musi to uwzględniać. Zaimplementuj ponawianie prób z wykładniczym opóźnieniem dla nieudanych wywołań API, utrzymuj lokalną kolejkę faktur oczekujących na wysyłkę, aby przestój KSeF nie blokował operacji biznesowych, i zaprojektuj jasne alerty, które natychmiast informują zespół finansowy o fakturach, które nie zostały przesłane.

Tryb offline i tryb awaryjny

KSeF może mieć planowane przerwy konserwacyjne i nieplanowane awarie, a po stronie firmy może zawieść samo połączenie internetowe. Przepisy przewidują na to tryb offline, ale nakładają konkretne obowiązki techniczne. Faktury wystawione podczas przestoju muszą być oznaczone specjalnym wskaźnikiem offline i przesłane do KSeF w określonym oknie po przywróceniu łączności. ERP musi utrzymywać lokalną kolejkę oczekujących przesyłek oraz zachować prawidłową kolejność i numerację w okresach offline i online.

Bufor offline powinien działać automatycznie: przechowywać faktury lokalnie, śledzić te wystawione poza KSeF i przesyłać je ponownie, gdy platforma znów odpowiada. Tryb awaryjny, czyli tymczasowe wystawianie faktur poza KSeF z późniejszym retroaktywnym przesłaniem, jest dozwolony do 31 grudnia 2026 r. Od 1 stycznia 2027 r. wszystkie faktury muszą przechodzić przez KSeF w czasie rzeczywistym, dlatego udokumentowana procedura fakturowania offline jest potrzebna już teraz, żeby uniknąć luk w zgodności z przepisami.

Kolejność wdrożenia i testy

Integracja z KSeF nie jest zwykłą aktualizacją oprogramowania. Obejmuje jednocześnie generowanie faktur, walidację danych, protokoły transmisji, obsługę błędów i archiwizację, dlatego kolejność prac ma znaczenie. Zacznij od testów jednostkowych, które sprawdzają generowanie XML FA(3) względem oficjalnych plików definicji schematu. Następnie przejdź do testów integracyjnych w środowisku testowym KSeF i pokryj w nich pełny cykl życia faktury: uwierzytelnianie, przesłanie, odpytywanie statusu, pobranie UPO oraz scenariusze błędów.

Testy obciążeniowe są równie ważne. Jeśli firma wystawia setki lub tysiące faktur dziennie, ten wolumen trzeba zasymulować w środowisku testowym, żeby wąskie gardła we własnej infrastrukturze znaleźć przed startem produkcyjnym, a nie po nim. Na koniec potrzebne są testy akceptacyjne z zespołami finansowym i księgowym, które potwierdzą, że cała droga od utworzenia faktury w ERP do potwierdzenia z KSeF działa i że dane wyświetlają się poprawnie w raportach wewnętrznych. Na same testy integracyjne warto przeznaczyć co najmniej cztery do sześciu tygodni.

Procesy, systemy i kontrahenci

Większość polskich firm fakturuje w systemach takich jak SAP, Comarch ERP, Enova czy Microsoft Dynamics i to na styku tych systemów z API KSeF rozstrzyga się powodzenie wdrożenia. Jeśli sprzedaż, zakupy, księgowość i archiwizacja działają w osobnych systemach, integracja musi objąć je wszystkie. Prościej i bezpieczniej jest wyznaczyć jedną warstwę integracyjną łączącą je z KSeF niż budować oddzielne połączenie dla każdego z nich.

KSeF zmienia też same procesy. Zespoły sprzedaży nie mogą już wystawiać faktur ad hoc, księgowość potrzebuje nowych łańcuchów zatwierdzania, a controlling nowych struktur raportowania. Warto zmapować obecny obieg faktury na całej długości, wskazać punkty, które KSeF zmienia, i przeszkolić wszystkie dotknięte działy. Osobnym zadaniem jest gotowość kontrahentów: faktury od partnerów, którzy nie spełniają wymagań, zakłócają procesy, więc wymagania i terminy trzeba przekazać dostawcom oraz odbiorcom przed styczniem 2027 r.

Biura rachunkowe

Biura rachunkowe mają trudniejszy wariant tego samego zadania: zarządzają poświadczeniami i dostępem do API KSeF dla wszystkich firm klientów naraz. Każda relacja z klientem wymaga odrębnego uwierzytelnienia, a biuro musi przechowywać ścieżki audytu wszystkich operacji KSeF wykonanych w imieniu każdego z nich. Przejście z Profilu Zaufanego na SSO wymaga ponownego uwierzytelnienia każdej relacji z klientem, co w II kwartale 2026 r. oznacza znaczne obciążenie operacyjne.

Co przygotować przed terminem

Równolegle z KSeF Polska wdraża e-KPiR, czyli elektroniczną księgę przychodów i rozchodów, wprowadzając obowiązkową cyfrową księgowość. To kolejny wymóg integracyjny dla firm i biur rachunkowych, który trafia w ten sam kalendarz. Zanim nadejdzie termin, gotowe powinny być:

Dokument mapowania pól ERP na FA(3) i przetestowana warstwa transformacji
Wyczyszczone dane podstawowe kontrahentów, zweryfikowane z Białą Listą
Zarejestrowany system, poprawnie skonfigurowane certyfikaty i obsługa odświeżania tokenów sesji
Przechowywanie numeru KSeF i daty nadanej przez KSeF w ERP oraz raportowanie VAT oparte na tej dacie
Bufor offline z lokalną kolejką, ponawianiem prób i alertami dla zespołu finansowego
Udokumentowana procedura fakturowania w trybie offline i awaryjnym
Przeprowadzone testy jednostkowe, integracyjne, obciążeniowe i akceptacyjne