Automatyzacja KSeF przez PowerShell i Bash – wysyłka wsadowa, interaktywna i pobieranie UPO bez pisania własnego kodu
Pełna integracja API z KSeF ma sens, gdy chcesz wpiąć wysyłkę faktur bezpośrednio w swój system sprzedażowy czy księgowy. Ale nie każda firma tego potrzebuje — czasem wystarczy, żeby faktury wygenerowane w jednym miejscu (np. w programie księgowym eksportującym pliki XML) trafiały do KSeF automatycznie, o stałej porze, bez logowania się ręcznie do panelu i klikania „wyślij" przy każdym pliku. Do tego właśnie służą gotowe skrypty automatyzujące — PowerShell dla Windows i Bash dla Linux — które można podłączyć pod harmonogram zadań systemu operacyjnego.
Dwa tryby pracy: wsadowy i interaktywny
Oba skrypty (PowerShell i Bash) obsługują dwa scenariusze użycia:
- Tryb wsadowy (batch) — skrypt uruchamia się cyklicznie (np. co godzinę, raz dziennie w nocy), skanuje wskazany katalog w poszukiwaniu nowych plików faktur, wysyła je do KSeF i zapisuje wyniki bez udziału człowieka. To wariant pod harmonogram zadań (Windows) lub crona (Linux).
- Tryb interaktywny — skrypt uruchamiany ręcznie z linii poleceń, z podglądem postępu na bieżąco — przydatny przy jednorazowej wysyłce, testach czy ręcznej weryfikacji przed uruchomieniem automatyzacji na produkcji.
Jak wygląda automatyzacja w Windows (PowerShell + Harmonogram zadań)
Skrypt PowerShell (KSeFService.ps1) uruchamiany jest jako zaplanowane zadanie w Harmonogramie zadań Windows. Typowy cykl działania:
- Skrypt skanuje wskazany folder wejściowy w poszukiwaniu plików XML faktur FA(3) gotowych do wysyłki.
- Dla każdego pliku wywołuje odpowiedni endpoint API, uwzględniając obsługę limitów zapytań (rate limit) — jeśli KSeF chwilowo ogranicza liczbę wywołań, skrypt wstrzymuje się i próbuje ponownie zamiast zwracać błąd.
- Poprawnie wysłane faktury (wraz z numerem KSeF i UPO) trafiają do folderu „wysłane", z zachowaniem przejrzystej struktury katalogów (np. per data, per status).
- Faktury odrzucone lub z błędem trafiają do osobnego folderu, wraz z zapisanym komunikatem błędu — do ręcznej analizy, bez przeszukiwania logów.
Jak wygląda automatyzacja w Linux (Bash + cron)
Odpowiednik dla środowisk Linux (KSeFService.sh) działa analogicznie, ale uruchamiany jest przez wpis w crontabie zamiast Harmonogramu zadań — co ma sens dla firm hostujących swoje systemy na serwerach Linux lub chcących uruchamiać automatyzację w kontenerze/na maszynie wirtualnej działającej w tle 24/7, bez zależności od zalogowanej sesji Windows.
Pobieranie UPO — osobny, ale równie ważny proces
Wysłanie faktury do KSeF to nie koniec procesu — dopiero Urzędowe Poświadczenie Odbioru (UPO) jest dowodem, że dokument został skutecznie przyjęty przez system Ministerstwa Finansów. Skrypty automatyzujące obsługują też cykliczne pobieranie UPO:
- sprawdzanie statusu wcześniej wysłanych faktur, dla których UPO nie zostało jeszcze pobrane,
- pobranie i zapisanie UPO w ustrukturyzowanej lokalizacji, powiązanej z konkretną fakturą,
- oznaczenie faktur, dla których po określonym czasie UPO wciąż nie jest dostępne — co może sygnalizować problem po stronie KSeF wymagający sprawdzenia ręcznego.
Dzięki temu cały cykl — wysyłka, oczekiwanie, pobranie potwierdzenia — dzieje się automatycznie, a folder z fakturami staje się kompletnym archiwum: plik źródłowy, numer KSeF i UPO w jednym miejscu.
Obsługa limitów zapytań
KSeF, jak każde API publiczne, ogranicza liczbę zapytań w jednostce czasu. Skrypty działające w trybie wsadowym muszą to uwzględniać — zamiast wysyłać wszystkie pliki „naraz" i ryzykować odrzucenie części z nich, wysyłka odbywa się z kontrolowanym odstępem między żądaniami, a w razie napotkania limitu skrypt automatycznie wstrzymuje się na odpowiedni czas i wznawia wysyłkę, zamiast przerywać cały proces.
Dla kogo ma to sens
Ten sposób automatyzacji sprawdza się dla firm, które już generują poprawne pliki XML FA(3) (np. z programu księgowego, własnego systemu ERP czy generatora faktur), ale nie chcą budować pełnej integracji API — wystarczy im mechanizm „wrzuć plik do folderu, reszta dzieje się sama". To też dobre rozwiązanie przejściowe dla firm testujących proces przed docelową integracją systemową.
Podsumowanie
Nie każda automatyzacja KSeF musi zaczynać się od integracji API we własnym kodzie. Gotowe skrypty PowerShell i Bash, podpięte pod harmonogram zadań lub crona, pozwalają uzyskać pełny cykl — wysyłkę wsadową, tryb interaktywny do testów i automatyczne pobieranie UPO — bez pisania własnej logiki komunikacji z KSeF.
Chcesz pobrać gotowe skrypty i wdrożyć je u siebie? Skontaktuj się z nami lub zapoznaj się z dokumentacją API.
