API systemu KSeF – pierwsze wrażenia

Wprowadzenie

Krajowy System e-Faktur (KSeF) to rozwiązanie wprowadzone przez Ministerstwo Finansów, które ma na celu usprawnienie procesu fakturowania oraz wymiany faktur w Polsce. W celu integracji systemów komputerowych z KSeF przygotowane zostało API, które pozwala na zarówno pobieranie jak i wysyłanie faktur do centralnej bazy danych systemu KSeF przez liczne systemy komputerowe działające w przedsiębiorstwach.

Program księgowy FinansNet został zintegrowany z Krajowym Systemem eFaktur, dzięki czemu biuro rachunowe lub dział księgowości przedsiębiorstwa automatycznie otrzymuje informację o wystawieniu lub odebraniu faktury w postaci czytelnej dla komputerów. Jest to istotny krok w kierunku automatyzacji procesów księgowych co znacząco usprawni i przyspieszy procesy księgowe.

W niniejszym artykule chcielibyśmy się podzielić naszymi wrażeniami po zintegrowaniu programu FinansNet się z systemem KSeF, co miało miejsce w styczniu 2025. Wszystkie wnioski i uwagi pochodzą z tego okresu czasu i należy pamiętać, że w chwili kiedy czytasz ten wpis niektóre problemy mogły zostać już rozwiązane.

Dokumentacja API

Pierwszym wyzwaniem na jakie trafili nasi programiści było dotarcie do najświeższej specyfikacji interfejsu API. Okazało się bowiem, że wpisanie w wyszukiwarkę hasła „Specyfikacja API KSeF”, co prawda zaprowadziła nas do dokumentacji, ale jej „świeżość” pozostawiała wiele do życzenia. Wyszukiwarka uparcie kierowała nas do wersji 1.1 lub 1.4 tego dokumentu. Po dłuższych poszukiwaniach okazało się jednak, że wersją najnowszą była wersja 1.9.

Zrozumieć dokumentację

Sama dokumentacja i zrozumienie zawartej w niej treści również okazało się pewnym wyzwaniem. Dokumentacja napisana jest bardzo chaotycznie, dosyć niedbale i z licznymi skrótami myślowymi.

Pierwsze kilka stron wydawało się kompletnym pseudoinformatycznym bełkotem, jednakże po przeczytaniu całego dokumentu od deski do deski, znajdujące się na początku dokumentacji, z pozoru kompletnie przypadkowe hasła, zaczęły się powoli układać w logiczną całość.

Środowisko testowe

Ministerstwo Finansów przygotowało trzy środowiska do testów platformy: „test”, „demo” oraz „produkcyjne”.

Podczas pierwszych prób okazało się niestety, że nie jesteśmy w stanie utworzyć testowego konta, a tym samym zalogować to środowiska „test”. Wszystkie prace programistyczne wykonaliśmy więc korzystając ze środowiska „demo„, które spełnia wszystkie wymogi, aby testować na nim integrację z programami zewnętrznymi. Można wystawić w nim sobie przykładowe faktury, które nie pociągają za sobą żadnych skutków skarbowych.

Wyzwanie autoryzacyjne

Sposób uzyskiwania dostępu do systemu wydał nam się mocno przekomplikowany.

Proces logowania rozpoczyna się uzyskaniem „wyzwania autoryzacyjnego”, które generuje nam unikalny i jednorazowy identyfikator procesu autoryzacji.

W drugim kroku musimy zbudować sobie token sklejając ze sobą: znacznik czasu, wspomniany już identyfikator, numer NIP oraz token dostępowy systemu KSeF. Żeby nie było za łatwo to uzyskany w ten sposób ciąg znaków musimy zaszyfrować kluczem publicznym dostarczonym nam przez Ministerstwo Finansów. Kompletnie nie rozumiemy w jakim celu zastosowano szyfrowanie tokena, skoro cała komunikacja odbywa się już szyfrowanym kanałem z użyciem protokołu HTTPS.

Na tym jednak proces logowania się nie kończy, albowiem przygotowany w ten sposób zaszyfrowany token jeszcze nic nam nie daje. Za jego pomocą musimy zainicjalizować sesję, czyli uzyskać tzw. token sesyjny. Mając taki token sesyjny już prawie jesteśmy gotowi do działania, ale…

Sesja nie jest otwierana natychmiast, lecz proces otwierania sesji trwa kilka lub kilkanaście sekund. Po odczekaniu tego czasu możemy w końcu przejść do wykonywania właściwych operacji w systemie KSeF.

Naprawdę nie dało się prościej?

Format FA(2)

Pobrane z systemu KSeF pliki zakodowane są w formacie XML, którego pełną formalną specyfikację znajdziemy tutaj. Kiedy już zaczęliśmy pracę z właściwą fakturą odczytując z niej interesujące nas informacje trafiliśmy na małą niespodziankę.

Okazuje się, że w pewnych sytuacjach (np. kiedy została wystawiona faktura zaliczkowa) na fakturze w formacie FA(2) należy wskazać numer KSeF faktury powiązanej. To zrozumiałe. Okazało się jednak, że faktura pobrana z systemu KSeF w formacie FA(2) nie posiada w swoim „wnętrzu” numeru KSeF.

Numer KSeF jest więc informacją trzymaną „obok” faktury, a nie jej integralną częścią. Może to sprawiać trudności, gdyż wymaga przechowywania tego numeru zupełnie w oddzielnej od samej faktury strukturze danych.

Prezentacja faktury w formie czytelnej

W przypadku dokumentów JPK Ministerstwo Finansów przygotowało pliki XSLT pozwalające na skonwertowanie tychże dokumentów do formatu czytelnego dla człowieka. W przypadku plików FA(2) wydawało się, że takiego pliku konwersji brakuje. Trochę czasu nam to zajęło, ale ostatecznie okazało się, że taki szablon konwersji istnieje, jednakże Ministerstwo się nim nie chwali. Znajduje się on tutaj, w lokalizacji głęboko ukrytej w gąszczu serwerów i dokumentów rządowych.

Dlaczego jest tak ukryty, zrozumieliśmy kiedy wykonaliśmy pierwszą konwersję pliki FA(2) do HTML. Rzeczywiście nie wygląda zbyt atrakcyjnie.

Podsumowanie

System KSeF wkrótce wejdzie do powszechnego użytku. Wydaje się zawierać pewne niedociągnięcia, jednakże pomimo ich obecności system działa całkiem stabilnie. Mamy nadzieję, że niedociągnięcia zostaną w najbliższych miesiącach naprawione.

Marek Malczewski