KSeF API integracja z ERP: najważniejsze wymagania techniczne

Integracja ERP z KSeF nie polega na „dodaniu wysyłki faktury do rządowego systemu”. To najkrótsza droga do projektu, który działa na prezentacji, ale wykłada się przy korektach, awarii połączenia, błędnym NIP-ie albo zmianie certyfikatu. KSeF API trzeba potraktować jak stały element procesu sprzedaży i księgowania: z własnym monitoringiem, logiką ponowień, obsługą statusów, kontrolą uprawnień i jasną odpowiedzialnością za dane.

Od strony technicznej najważniejsze pytanie nie brzmi: „czy ERP umie wysłać XML?”. Ważniejsze jest: czy firma wie, kto może wystawiać faktury, jak system zachowa się przy odrzuceniu dokumentu, gdzie zapisze numer KSeF, jak obsłuży pracę poza trybem standardowym i czy integracja wytrzyma realny wolumen dokumentów na koniec miesiąca.

Jakie terminy i wersje KSeF trzeba uwzględnić w projekcie ERP

Pierwsza decyzja projektowa: integracji nie należy budować pod stare API ani pod przejściowe założenia. Dla wdrożeń planowanych na 2026 rok punktem odniesienia jest KSeF 2.0 oraz struktura FA(3). To ważne, bo część firm nadal ma w dokumentacji, procedurach albo backlogu technicznym ślady wcześniejszych wersji KSeF. Takie elementy trzeba wyczyścić przed właściwym wdrożeniem, inaczej testy będą dawały fałszywe poczucie bezpieczeństwa.

Najważniejsze daty dla projektu ERP:

• 1 lutego 2026 r. — obowiązek wystawiania faktur w KSeF dla podatników, których sprzedaż brutto w 2024 r. przekroczyła 200 mln zł;
• 1 kwietnia 2026 r. — obowiązek dla pozostałych podatników;
• do 31 grudnia 2026 r. — wyjątek dla podatników, u których miesięczna wartość sprzedaży dokumentowanej fakturami nie przekracza 10 000 zł brutto;
• od 1 lutego 2026 r. — dla faktur ustrukturyzowanych stosowana jest struktura FA(3).

W praktyce oznacza to, że harmonogram wdrożenia ERP powinien być liczony wstecz od daty obowiązku, a nie od dnia, w którym dostawca oprogramowania „udostępni moduł”. Sam moduł to zwykle tylko fragment pracy. Po stronie firmy trzeba jeszcze sprawdzić:

• mapowanie pól faktury z ERP do struktury FA(3);
• obsługę faktur korygujących, zaliczkowych i rozliczeniowych;
• zgodność danych kontrahentów;
• sposób zapisu numeru KSeF w ERP;
• procedurę dla faktur odrzuconych;
• obieg dokumentów, gdy faktura jest wystawiana poza centralą albo przez kilka działów.

Największy błąd na tym etapie to testowanie wyłącznie prostego scenariusza: jedna faktura sprzedaży, jeden kontrahent, jedna stawka VAT, jeden użytkownik. Tak można potwierdzić, że połączenie działa. Nie można w ten sposób potwierdzić, że firma jest gotowa na KSeF.

Dobre testy powinny objąć przypadki brzegowe: korektę do faktury historycznej, fakturę z wieloma pozycjami, różne stawki VAT, nabywcę zagranicznego, błędne dane obowiązkowe, ponowną wysyłkę po przerwanym połączeniu i masową wysyłkę dokumentów. Dopiero wtedy widać, czy problemem jest API, konfiguracja ERP, dane podstawowe czy proces po stronie użytkowników.

Uwierzytelnianie, certyfikaty i uprawnienia: tu najłatwiej o błąd

Integracja z KSeF API musi mieć uporządkowany model dostępu. Nie wystarczy jeden „techniczny użytkownik”, którego hasło zna dział księgowości i administrator ERP. Taki skrót szybko wraca jako problem audytowy: nie wiadomo, kto faktycznie wysłał fakturę, kto miał prawo do wystawiania dokumentów i co zrobić, gdy dana osoba odchodzi z firmy.

W KSeF 2.0 trzeba zwrócić szczególną uwagę na certyfikaty KSeF, uprawnienia oraz tokeny. Certyfikat służący do uwierzytelniania może być wykorzystywany w sesjach interaktywnych i wsadowych. Jego ważność nie powinna być traktowana jako detal administracyjny — certyfikat KSeF jest ważny maksymalnie 2 lata, więc ERP musi mieć proces kontroli daty ważności i wymiany certyfikatu, zanim integracja przestanie działać.

Warto od razu ustalić trzy poziomy odpowiedzialności:

• właściciel biznesowy procesu — decyduje, kto może wystawiać i odbierać faktury;
• administrator ERP — konfiguruje integrację, role i obieg błędów;
• administrator bezpieczeństwa lub IT — pilnuje certyfikatów, dostępu technicznego, logów i rotacji uprawnień.

Osobna sprawa to tokeny KSeF 1.0. Nie należy zakładać, że stare tokeny da się przenieść do nowego środowiska. Tokeny wygenerowane dla KSeF 1.0 nie są przeznaczone do użycia w KSeF 2.0 i nie powinny być podstawą nowej integracji. Jeżeli w firmie powstały już skrypty, dodatki ERP albo automaty korzystające ze starych tokenów, trzeba je potraktować jako dług techniczny do usunięcia, nie jako punkt startowy.

Przy wdrożeniu ERP najlepiej przyjąć zasadę minimalnych uprawnień. System powinien mieć tylko te dostępy, których potrzebuje do konkretnego procesu. Innych uprawnień nie dodaje się „na zapas”, bo potem trudno ustalić, które są faktycznie używane, a które zostały po testach.

Szczególnie ryzykowne są trzy praktyki:

• używanie jednego dostępu dla kilku spółek lub oddziałów bez jasnego rozdziału odpowiedzialności;
• przechowywanie danych uwierzytelniających w konfiguracji dostępnej dla zbyt wielu administratorów;
• brak procedury awaryjnej, gdy certyfikat wygaśnie, zostanie unieważniony albo trzeba będzie szybko odebrać komuś uprawnienia.

Dobrze przygotowany ERP powinien nie tylko „łączyć się z KSeF”, ale też pokazywać użytkownikowi zrozumiały komunikat: czy problem dotyczy uprawnień, danych faktury, limitu API, niedostępności usługi czy błędu po stronie integracji. Komunikat „błąd wysyłki” jest bezużyteczny, jeśli księgowość ma zamknąć miesiąc.

Architektura integracji: walidacja, kolejki, statusy i limity API

Najlepsza integracja z KSeF to taka, która nie wymaga od użytkownika zgadywania, co stało się z fakturą. Dokument powinien mieć w ERP czytelny status: przygotowany, zwalidowany, wysłany, przyjęty, odrzucony, oczekujący na ponowienie albo wymagający poprawy. Bez tego księgowość zaczyna prowadzić równoległe rejestry w Excelu, a wtedy całe wdrożenie traci sens.

Priorytet numer jeden to walidacja przed wysyłką. ERP powinien sprawdzić dane zanim dokument trafi do KSeF. Chodzi nie tylko o poprawność XML, ale też o kompletność pól wymaganych przez strukturę FA(3), zgodność danych kontrahenta, formaty identyfikatorów, stawki VAT, daty i zależności między polami. Im później błąd zostanie wykryty, tym droższa jest jego obsługa.

Priorytet numer dwa to kolejkowanie i ponawianie wysyłki. KSeF jest systemem zewnętrznym, więc integracja musi zakładać przerwy, limity i opóźnienia. Wysyłka faktur bez kolejki, bez mechanizmu retry i bez zapisu historii komunikacji to proszenie się o chaos. Przy małej liczbie dokumentów problem może być niewidoczny. Przy setkach albo tysiącach faktur miesięcznie pojawi się szybko.

Rozsądny model integracji obejmuje:

• osobną kolejkę dokumentów do wysyłki;
• automatyczne ponowienia dla błędów technicznych;
• blokadę ponownej wysyłki tego samego dokumentu bez kontroli statusu;
• zapis identyfikatorów technicznych i numeru KSeF;
• logi dostępne dla IT oraz uproszczony widok dla księgowości;
• alerty dla dokumentów, które utknęły w procesie;
• raport faktur odrzuconych i oczekujących na działanie użytkownika.

Limity API trzeba potraktować poważnie. Ministerstwo Finansów przewidziało mechanizmy ograniczające liczbę żądań dla integracji, a zwiększenie limitów wymaga uzasadnienia rzeczywistą potrzebą operacyjną. To oznacza, że firmy z dużym wolumenem faktur nie powinny odkładać testów wydajnościowych na koniec. Jeżeli ERP wysyła faktury partiami, generuje wiele zapytań statusowych albo obsługuje kilka spółek w jednej instalacji, limit może stać się realnym ograniczeniem procesu.

Tu decyzja jest prosta: najpierw trzeba policzyć wolumen. Ile faktur firma wystawia dziennie? Ile w ostatnim dniu miesiąca? Ile korekt? Ile dokumentów generuje sprzedaż automatyczna? Czy ERP będzie pobierał także faktury zakupowe z KSeF? Dopiero po tych liczbach można ocenić, czy standardowa konfiguracja wystarczy, czy trzeba planować wniosek o zwiększenie limitów.

Nie wszystko warto automatyzować od razu. W pierwszej kolejności powinny wejść procesy, które blokują wystawianie i księgowanie faktur: sprzedaż krajowa, korekty, odbiór UPO/statusów, zapis numeru KSeF i raport błędów. Funkcje pomocnicze, takie jak rozbudowane pulpity analityczne czy automatyczne klasyfikowanie wyjątków, można wdrożyć później — pod warunkiem że podstawowy proces działa stabilnie.

Najbardziej praktyczna zasada brzmi: integracja z KSeF ma być nudna. Faktura przechodzi przez system, dostaje status, użytkownik wie, co się stało, a IT widzi logi. Jeżeli każda odmowa przyjęcia dokumentu wymaga analizy programisty, wdrożenie nie jest gotowe.

FAQ: KSeF API i integracja z ERP

Czy każdy ERP musi mieć integrację z KSeF API?
Nie zawsze technicznie musi, ale w praktyce dla firm wystawiających regularnie faktury brak integracji oznacza ręczne przepisywanie, eksporty plików i większe ryzyko błędów. Przy większej liczbie dokumentów integracja jest rozsądniejsza niż praca w aplikacji ręcznej.

Czy można używać starej integracji z KSeF 1.0?
Nie jako docelowego rozwiązania dla KSeF 2.0. Stare tokeny i mechanizmy przygotowane pod wcześniejszą wersję trzeba zweryfikować i zastąpić rozwiązaniem zgodnym z aktualnym API oraz strukturą FA(3).

Co jest ważniejsze: certyfikat czy sama wysyłka XML?
Oba elementy są konieczne, ale w praktyce najwięcej problemów organizacyjnych powodują uprawnienia, certyfikaty i odpowiedzialność za dostęp. XML można poprawić testami. Źle zaprojektowany model dostępu potrafi zablokować proces albo stworzyć problem audytowy.

Czy integracja powinna działać synchronicznie, od razu po kliknięciu „wystaw fakturę”?
Nie zawsze. Przy większym wolumenie bezpieczniejszy jest model z kolejką, statusem i ponowieniami. Użytkownik nie powinien czekać bez końca na odpowiedź systemu zewnętrznego, a ERP musi umieć obsłużyć opóźnienia i błędy techniczne.

Czy trzeba testować korekty i faktury nietypowe?
Tak. Test wyłącznie na prostej fakturze sprzedaży jest za słaby. Korekty, faktury zaliczkowe, różne stawki VAT, kontrahenci zagraniczni i błędne dane pokazują, czy integracja nadaje się do realnej pracy.

Od czego zacząć wdrożenie KSeF w ERP?
Najpierw od audytu danych i procesu: kto wystawia faktury, jakie typy dokumentów występują, ile jest faktur w szczycie miesiąca, jakie role są potrzebne i gdzie ma być zapisywany numer KSeF. Dopiero potem warto konfigurować API. Odwrotna kolejność kończy się poprawkami w ostatnim tygodniu przed startem.

Jaki błąd trzeba usunąć jako pierwszy?
Brak jednoznacznego statusu faktury w ERP. Jeżeli użytkownik nie widzi, czy dokument został wysłany, przyjęty, odrzucony czy czeka na ponowienie, firma nie ma kontroli nad procesem. To ważniejsze niż kosmetyka interfejsu i dodatkowe raporty.

Więcej: KSeF API Intergracja.