Integracja z Krajowym Systemem e-Faktur to kluczowy element przygotowania firmy na obowiązkowe e-fakturowanie. Bez sprawnego połączenia między systemami IT przedsiębiorstwa a platformą KSeF, każda faktura wymaga ręcznej obsługi – co przy dziesiątkach czy setkach dokumentów dziennie jest po prostu niewykonalne.
Integracja z KSeF oznacza dwukierunkową komunikację: wysyłkę faktur sprzedażowych do systemu rządowego oraz automatyczny odbiór faktur zakupowych od kontrahentów. Obie operacje realizowane są przez API udostępniane przez Ministerstwo Finansów.
Dobrze zaplanowana integracja pozwala firmie zachować dotychczasowe procesy pracy, jednocześnie spełniając nowe wymogi prawne. System ERP czy program księgowy staje się bramą do KSeF, a cała wymiana danych odbywa się w tle.
Architektura API KSeF
API KSeF to interfejs REST oparty na protokole HTTPS. Ministerstwo Finansów udostępnia trzy środowiska: produkcyjne, demo i testowe (sandbox). Każde wymaga osobnej autoryzacji, ale struktura wywołań jest identyczna.
Główne endpointy API obejmują: wysyłkę faktur (POST), pobieranie faktur (GET), sprawdzanie statusu (GET), pobieranie UPO (GET) i zarządzanie sesjami autoryzacyjnymi. Każda operacja wymaga ważnego tokenu sesyjnego.
Komunikacja odbywa się w formacie JSON dla metadanych i XML dla treści faktur. Schemat XML (FA(2)) definiuje strukturę faktury z ponad 300 polami, z których część jest obowiązkowa, a część opcjonalna. Szczegóły techniczne znajdziesz w naszym przewodniku po API KSeF.
Metody autoryzacji w KSeF
KSeF oferuje kilka metod autoryzacji. Najpopularniejsza w kontekście automatyzacji to token autoryzacyjny. Token generowany jest na portalu KSeF po uwierzytelnieniu właściciela firmy profilem zaufanym lub podpisem kwalifikowanym.
Token może mieć różne zakresy uprawnień: wystawianie faktur, pobieranie faktur, dostęp do statystyk. Można wygenerować osobne tokeny dla różnych systemów lub użytkowników, co zwiększa bezpieczeństwo i kontrolę.
Alternatywnie można autoryzować się podpisem kwalifikowanym lub pieczęcią elektroniczną bezpośrednio przy każdej sesji. Ta metoda jest bezpieczniejsza, ale wymaga dostępu do certyfikatu przy każdej operacji.
- Token autoryzacyjny – najwygodniejszy dla automatyzacji
- Podpis kwalifikowany – najwyższy poziom bezpieczeństwa
- Pieczęć elektroniczna – dla wysyłki masowej
- Profil zaufany – do operacji jednorazowych i konfiguracji
Integracja z systemami ERP
Większość polskich dostawców systemów ERP oferuje moduły integracji z KSeF. SAP, Comarch ERP XL i Optima, Symfonia, enova365, InsERT – wszystkie mają dedykowane rozszerzenia umożliwiające automatyczną wysyłkę i odbiór faktur.
Integracja na poziomie ERP jest najefektywniejsza, ponieważ dane fakturowe są generowane bezpośrednio w systemie. Nie ma potrzeby eksportu, konwersji i importu – faktura przechodzi z ERP do KSeF jednym kliknięciem lub automatycznie.
Dla firm korzystających z mniej popularnych systemów ERP lub własnych rozwiązań, dostępne są middleware'y – pośredniczące platformy API, które tłumaczą dane z dowolnego formatu na XML KSeF. Szczegóły integracji z systemami ERP znajdziesz na stronie o integracji z ERP.
Integracja z programami księgowymi
Programy księgowe takie jak Rachmistrz, Rewizor, SKP czy wFirma również integrują się z KSeF. W przypadku tych systemów integracja obejmuje przede wszystkim odbieranie faktur zakupowych i ich automatyczne dekretowanie.
Faktura pobrana z KSeF trafia do programu księgowego jako gotowy do zaksięgowania dokument. System rozpoznaje kontrahenta, przypisuje konto księgowe i proponuje dekret. Księgowy potrzebuje jedynie zatwierdzić operację.
Ta automatyzacja jest szczególnie wartościowa dla biur rachunkowych, które obsługują wielu klientów. Zamiast ręcznie wprowadzać setki faktur, mogą je automatycznie pobierać z KSeF i dekretować.
Scenariusze integracji – od prostych do zaawansowanych
Najprostszy scenariusz to bezpośrednia integracja jednego systemu z KSeF przez API. Firma korzysta z jednego programu do fakturowania, który wysyła faktury do KSeF i pobiera dokumenty zakupowe.
Średnio złożony scenariusz obejmuje integrację kilku systemów przez centralny hub. Firma może mieć osobne systemy do sprzedaży hurtowej, detalicznej i e-commerce. Każdy generuje faktury, które trafiają do centralnego systemu integracyjnego, a stamtąd do KSeF.
Zaawansowany scenariusz to pełna orkiestracja procesów, w której integracja KSeF jest częścią większego ekosystemu. Faktura wygenerowana w ERP trafia do KSeF, a potwierdzenie wysyłki uruchamia aktualizację statusu w CRM, powiadomienie do klienta i zapis w systemie archiwizacji.
| Scenariusz | Złożoność | Czas wdrożenia | Typowy koszt |
|---|---|---|---|
| Gotowy moduł ERP | Niska | 1-3 dni | 500-2 000 zł |
| Integracja przez middleware | Średnia | 1-4 tygodnie | 3 000-15 000 zł |
| Dedykowana integracja API | Wysoka | 4-12 tygodni | 15 000-80 000 zł |
| Pełna orkiestracja procesów | Bardzo wysoka | 3-6 miesięcy | 50 000-300 000 zł |
Obsługa błędów i monitoring integracji
Integracja z KSeF musi uwzględniać obsługę błędów. API KSeF może zwracać różne kody błędów: walidacyjne (nieprawidłowy XML), autoryzacyjne (wygasły token) czy infrastrukturalne (niedostępność systemu).
Dobrze zaprojektowany system integracyjny automatycznie klasyfikuje błędy i podejmuje odpowiednie działania. Błędy walidacyjne wymagają korekty danych i ponownej wysyłki. Błędy autoryzacyjne wymagają odświeżenia tokenu. Błędy infrastrukturalne wymagają ponowienia próby po określonym czasie.
Monitoring integracji powinien obejmować dashboardy z informacjami o liczbie wysłanych i odebranych faktur, czasie przetwarzania, wskaźniku błędów i statusie połączenia z KSeF. Alerty powinny powiadamiać odpowiednie osoby o problemach wymagających interwencji.
Testowanie integracji w środowisku sandbox
Ministerstwo Finansów udostępnia środowisko testowe KSeF, które symuluje działanie produkcyjne. Pozwala ono na testowanie wysyłki i odbioru faktur bez wpływu na realne dane podatkowe.
Testowanie powinno obejmować różne scenariusze: faktury z jedną i wieloma pozycjami, różne stawki VAT, faktury korygujące, zaliczkowe, w walutach obcych, z odwrotnym obciążeniem. Każdy scenariusz powinien być przetestowany pod kątem poprawności generowanego XML.
Warto też przetestować scenariusze awaryjne: co się stanie, gdy KSeF jest niedostępny, gdy token wygaśnie w trakcie wysyłki masowej, gdy XML zawiera błąd. System powinien poprawnie obsługiwać każdy z tych przypadków.
Podsumowanie
Integracja z KSeF to projekt technologiczny, który wymaga starannego planowania i testowania. Niezależnie od tego, czy korzystasz z gotowego modułu ERP, czy budujesz dedykowane rozwiązanie, kluczowe jest zapewnienie niezawodnej dwukierunkowej komunikacji z platformą Ministerstwa Finansów.
Nie czekaj z integracją na ostatnią chwilę. Rozpocznij od testów w środowisku sandbox, sprawdź możliwości swojego systemu ERP i zaplanuj wdrożenie z odpowiednim marginesem czasowym. Więcej informacji o automatyzacji KSeF i fakturowaniu online znajdziesz na naszych stronach.
Gotowy na zmianę?
Dołącz do setek polskich firm, które już zautomatyzowały swoje procesy. Bez zobowiązań — 30 dni za darmo.
Rozpocznij bezpłatny test →Najczęstsze pytania
Tak, jeśli Twój system ERP lub program księgowy oferuje gotowy moduł integracji z KSeF. Wystarczy go aktywować i skonfigurować token autoryzacyjny. Dedykowana integracja wymaga jednak pracy programisty.
Nie musisz posiadać własnego certyfikatu SSL. Komunikacja z API KSeF odbywa się przez HTTPS, ale certyfikat jest po stronie serwera KSeF. Twój system musi jedynie obsługiwać połączenia HTTPS.
Ministerstwo Finansów przewiduje procedurę awaryjną. W przypadku niedostępności KSeF firma może wystawić fakturę w trybie offline, a następnie przesłać ją do KSeF po przywróceniu dostępności systemu.
API KSeF obsługuje wysyłkę wsadową (batch), która pozwala przesłać wiele faktur w jednej sesji. Dokładne limity zależą od aktualnej konfiguracji systemu i mogą się zmieniać.
Tak. Komunikacja z KSeF jest szyfrowana, a autoryzacja wymaga tokenu lub podpisu kwalifikowanego. Dane przesyłane do KSeF są chronione zgodnie z przepisami o tajemnicy skarbowej.
Technicznie jest to możliwe, ale ze względów bezpieczeństwa zaleca się generowanie osobnych tokenów dla każdego systemu. Umożliwia to lepszą kontrolę dostępu i łatwiejsze zarządzanie uprawnieniami.