Integracja KSeF z ERP w 2026 roku — praktyczna checklista

Integracja KSeF z ERP jest procesem wymiany dokumentów, potwierdzeń i uprawnień, a nie pojedynczym przyciskiem „wyślij fakturę”. System finansowy musi przygotować prawidłową strukturę, uwierzytelnić podmiot, przesłać dokument, odebrać status, zapisać numer KSeF i UPO, a w razie błędu pozostawić księgowości jasną ścieżkę działania. Osobny przepływ dotyczy faktur zakupowych oraz trybów offline.

Na dzień aktualizacji tego materiału obowiązuje KSeF 2.0. Według informacji Ministerstwa Finansów odbieranie faktur przez KSeF stało się obowiązkowe 1 lutego 2026 roku. Obowiązek wystawiania wszedł od 1 lutego dla największych podatników i od 1 kwietnia dla pozostałych, z czasowym wyjątkiem dla najmniejszych firm spełniających wskazany limit. Aktualny zakres obowiązkowego KSeF zawsze powinien zostać sprawdzony przed decyzją projektową, ponieważ jest to obszar prawny i techniczny podlegający zmianom.

Ustal zakres biznesowy, zanim dotkniesz API

Pierwszy warsztat powinien odpowiedzieć, jakie dokumenty firma wystawia i odbiera. Inaczej wygląda proces zwykłej faktury sprzedaży, korekty, faktury zaliczkowej, dokumentu z załącznikiem czy faktury wystawianej poza podstawowym trybem online. Trzeba również określić liczbę podmiotów, oddziałów, systemów ERP, operatorów oraz osób i aplikacji korzystających z uprawnień.

Zakres warto opisać w macierzy:

Obszar	Pytanie kontrolne	Właściciel
sprzedaż	kto zatwierdza dokument do wysyłki	księgowość / sprzedaż
zakup	jak często pobierane są nowe faktury	księgowość
uprawnienia	kto nadaje, odbiera i audytuje dostęp	administrator / finanse
korekty	jak łączymy korektę z dokumentem pierwotnym	ERP / księgowość
offline	kto uruchamia tryb i pilnuje dosłania	właściciel procesu
awaria	kiedy przechodzimy na obsługę ręczną	IT / finanse

Bez tej analizy integrator może zbudować poprawną technicznie wysyłkę, która nie obsłuży realnych wyjątków organizacji.

Korzystaj z aktualnego kontraktu KSeF 2.0

Ministerstwo Finansów udostępnia publiczny przewodnik dla integratorów KSeF 2.0, kontrakt OpenAPI, biblioteki referencyjne i changelog. To powinno być podstawowe źródło dla zespołu technicznego. Kopia przykładowego żądania znaleziona w starszym artykule nie jest wystarczającą specyfikacją.

Po stronie ERP potrzebne są co najmniej następujące elementy:

1. mapowanie dokumentu wewnętrznego do obowiązującej struktury FA(3),
2. walidacja danych przed wysyłką,
3. uwierzytelnienie i sprawdzenie uprawnień,
4. obsługa sesji odpowiedniej do sposobu pracy,
5. szyfrowanie i transmisja zgodna z kontraktem,
6. odczyt statusu przetwarzania,
7. zapis numeru KSeF i UPO,
8. pobieranie dokumentów zakupowych oraz ich deduplikacja,
9. historia techniczna niezależna od statusu księgowego.

Ważne, aby wersja integracji była widoczna w systemie i wdrażana kontrolowanie. Zmiana schematu albo endpointu nie może zostać zauważona dopiero wtedy, gdy dokumenty zaczną wracać z błędem.

Oddziel status dokumentu od statusu transmisji

Faktura może być zatwierdzona księgowo, ale jeszcze niewysłana. Może zostać wysłana, lecz oczekiwać na przetworzenie. Może też zostać odrzucona technicznie albo otrzymać numer KSeF. Jeżeli ERP próbuje zamknąć te stany w jednym polu, użytkownik szybko traci informację, co naprawdę się wydarzyło.

Praktyczny model techniczny może zawierać stany: przygotowana, oczekuje na wysyłkę, wysłana, przetwarzana, przyjęta, odrzucona, wymaga interwencji i wystawiona offline. Przy każdej zmianie należy zapisać czas, identyfikator sesji lub operacji, wersję dokumentu oraz bezpieczny opis błędu.

Ponowienie musi być świadome duplikatów. Brak odpowiedzi nie oznacza, że KSeF nie przyjął żądania. Przed kolejną wysyłką system powinien sprawdzić znany stan i użyć mechanizmów identyfikacji opisanych w aktualnym API. Ręczny przycisk „wyślij ponownie” bez kontroli to prosta droga do niespójności.

Zaprojektuj uwierzytelnienie i certyfikaty

Uprawnienia powinny odpowiadać rolom, a nie wygodzie wdrożenia. Konto lub certyfikat używany przez integrację nie powinien otrzymywać szerszego zakresu niż potrzebny. Trzeba ustalić właściciela poświadczeń, sposób bezpiecznego przechowywania, rotację, alarm przed wygaśnięciem i procedurę natychmiastowego odebrania dostępu.

Oficjalna strona opisująca certyfikaty KSeF wskazuje, że służą one między innymi do uwierzytelnienia oraz potwierdzania tożsamości wystawcy w trybach szczególnych. Certyfikat ma ograniczony okres ważności, więc jego odnowienie nie może zależeć od pamięci jednej osoby.

W środowiskach z wieloma podmiotami trzeba dodatkowo zapobiec użyciu poświadczeń niewłaściwej spółki. Identyfikator kontekstu powinien być częścią konfiguracji, logu audytowego i testów automatycznych.

Przygotuj tryby offline i niedostępność

Oficjalny opis trybów szczególnych rozróżnia offline24, offline związany z niedostępnością KSeF oraz tryb awaryjny. Każdy ma własne przesłanki i terminy późniejszego przekazania dokumentu. Integracja powinna prowadzić użytkownika przez właściwą procedurę, a nie traktować „offline” jako ogólnego statusu.

Scenariusz offline obejmuje przygotowanie faktury zgodnie z aktualną strukturą, odpowiednią datę, kody weryfikujące, certyfikat, udostępnienie nabywcy, kolejkę dosłania i kontrolę terminu. Po odzyskaniu łączności system powinien wysłać dokument, odebrać wynik i połączyć numer KSeF z pierwotnym zapisem bez tworzenia drugiej faktury.

Warto przeprowadzić ćwiczenie awaryjne przed produkcją: odciąć dostęp do środowiska testowego, wystawić dokument offline, przywrócić połączenie i przejść całą ścieżkę aż do archiwizacji potwierdzenia.

Testy akceptacyjne przed uruchomieniem

Minimalny pakiet testów powinien zawierać poprawną fakturę, brak wymaganego pola, nieprawidłowe uprawnienie, wygaśnięte poświadczenie, timeout po wysłaniu, ponowienie, duplikat, korektę, fakturę zakupową, dużą paczkę dokumentów i każdy wykorzystywany tryb offline. Użytkownicy finansowi powinni zobaczyć zarówno szczęśliwą ścieżkę, jak i komunikaty wyjątków.

Przed startem należy też potwierdzić:

• monitoring dostępności i czasu przetwarzania,
• alerty dla dokumentów bez końcowego statusu,
• uzgodnienie liczby faktur ERP–KSeF,
• kopię i retencję UPO,
• instrukcję operacyjną dla księgowości,
• właściciela aktualizacji po zmianie API,
• procedurę eskalacji do dostawcy ERP i zespołu integracyjnego.

Wniosek

Dobra integracja KSeF z ERP daje księgowości pewność, co stało się z każdym dokumentem, a nie tylko możliwość wysłania XML. Łączy aktualny kontrakt techniczny z rolami, potwierdzeniami, obsługą zakupów i procedurą awaryjną. Ze względu na podatkowy charakter procesu ostateczny zakres i reguły powinny zostać zatwierdzone przez osobę odpowiedzialną za rozliczenia oraz sprawdzone ponownie przed publikacją lub wdrożeniem.