Automatyzacja i dodatkowe funkcje
Ta strona opisuje zaplanowane zadania modułu, stronę statusu, endpointy REST API i inne funkcje, które pomagają w zarządzaniu wszystkim.
Zaplanowane zadania (Cron)
Moduł zawiera kilka zaplanowanych zadań automatyzujących rutynowe czynności KSeF. Korzystają one z wbudowanego systemu cron Dolibarr (Strona główna -> Ustawienia -> Moduły -> Zaplanowane zadania). Po włączeniu modułu KSeF zadania są rejestrowane automatycznie. Możesz konfigurować ich częstotliwość, włączać lub wyłączać poszczególne zadania i monitorować wykonanie ze strony Zaplanowanych zadań.
Sprawdź status wysyłki - odpytuje KSeF o status faktur nadal w stanie "Oczekująca", "Wysłana" lub "Timeout". Jeśli wysyłasz faktury i zamkniesz przeglądarkę przed nadejściem potwierdzenia, to zadanie pobierze wyniki później. Obsługuje również ponawianie faktur offline - gdy napotka fakturę offline oczekującą na wysyłkę online, automatycznie próbuje ją wysłać. Bez tego zadania musiałbyś ręcznie sprawdzać statusy i wysyłać każdą fakturę offline. Domyślna częstotliwość: co 30 minut. Domyślnie włączone.
Synchronizuj faktury przychodzące - pobiera nowe faktury przychodzące z KSeF, tak samo jak kliknięcie "Synchronizuj z KSeF" na stronie faktur przychodzących. Domyślna częstotliwość: co 4 godziny. Domyślnie wyłączone - włącz po zweryfikowaniu, że synchronizacja przychodzących działa poprawnie.
Pobierz zaległe potwierdzenia (UPO) - pobiera dokumenty UPO dla wysłanych faktur, które jeszcze ich nie mają. Czasem UPO nie jest dostępne natychmiast po wysyłce, więc to zadanie nadrabia później. Przetwarza do 50 faktur na uruchomienie. Domyślna częstotliwość: co 6 godzin. Domyślnie wyłączone.
Ostrzegaj o terminach offline - sprawdza faktury offline z terminami zbliżającymi się w ciągu najbliższych 24 godzin i loguje ostrzeżenia. Faktury offline muszą zostać wysłane do KSeF w określonym czasie po zakończeniu awarii - to zadanie pilnuje, żebyś nie przegapił tego terminu. Domyślna częstotliwość: co godzinę. Domyślnie włączone.
Konfiguracja zadań cron - system zaplanowanych zadań Dolibarr wymaga wyzwalacza cron na poziomie systemu. Jeśli nie konfigurowałeś tego wcześniej:
1. Przejdź do Strona główna → Ustawienia → Moduły i włącz moduł "Zaplanowane zadania", jeśli jeszcze nie jest włączony
2. Postępuj zgodnie z instrukcjami Dolibarr, aby dodać wpis do systemowego crontab, który wywołuje runner cron Dolibarr - zazwyczaj jedna linia w crontab serwera uruchamiana co 5 minut
3. Gdy systemowy cron działa, możesz zarządzać harmonogramami poszczególnych zadań z poziomu Dolibarr
Jeśli zaplanowane zadania już działają dla innych modułów Dolibarr, zadania KSeF działają automatycznie - nie jest potrzebna dodatkowa konfiguracja systemowa.
Strona statusu
Moduł dodaje stronę statusu dostępną z menu KSeF. To Twoje centrum operacyjne do zarządzania wysyłkami KSeF - pełna strona zarządzania wysyłkami, nie tylko panel podsumowań.
Strona wyświetla wszystkie wysyłki (pokazując ostatnią próbę na fakturę) z przeszukiwalnymi i sortowalnymi kolumnami: referencja faktury, numer KSeF, status, środowisko, data wysyłki, klient, kwota i liczba prób. Możesz filtrować po referencji faktury, numerze KSeF, statusie (Oczekująca/Zaakceptowana/Niepowodzenie/Odrzucona/Offline/Timeout), środowisku (Test/Demo/Produkcja) i zakresie dat.
Każdy wiersz ma przyciski akcji do sprawdzenia aktualnego statusu w KSeF, ponowienia nieudanej wysyłki, pobrania wysłanego XML lub UPO, lub wyświetlenia szczegółowych informacji o błędzie w oknie modalnym. Okno szczegółów błędu pokazuje kod błędu, opis czytelny dla człowieka, surową wiadomość błędu i szczegóły techniczne z odpowiedzi API.
Nad listą wysyłek podsumowanie częstych błędów agreguje najczęstsze kody błędów z ostatnich 30 dni. Jeśli ten sam błąd pojawia się na wielu fakturach, to zwykle problem konfiguracyjny, a nie coś złego z poszczególnymi fakturami. Strona obsługuje akcje masowe i łączy każdą wysyłkę z jej fakturą i klientem dla łatwej nawigacji.
To pierwsze miejsce do sprawdzenia, gdy coś wydaje się nie tak - daje ogólny obraz bez otwierania poszczególnych faktur i pozwala podejmować działania bezpośrednio z listy.
REST API
Moduł dodaje endpointy REST API do istniejącej infrastruktury API Dolibarr, umożliwiając zewnętrznym aplikacjom programistyczną interakcję z funkcjonalnością KSeF. Przydatne do niestandardowej automatyzacji, systemów zewnętrznych potrzebujących wyzwalania wysyłek lub budowania narzędzi monitorujących i raportujących.
Endpointy podążają za standardowymi wzorcami REST API i uwierzytelnianiem Dolibarr. Jeśli już korzystasz z API Dolibarr, endpointy KSeF działają tak samo. Obejmują wysyłki wychodzące (wysyłanie, ponawianie, sprawdzanie statusu, pobieranie XML/UPO), faktury przychodzące (synchronizacja, import, przeglądanie szczegółów) i sprawdzanie stanu systemu.
Najlepszą referencją dla dostępnych endpointów i ich parametrów jest kod źródłowy - sprawdź pliki klas API modułu, aby zobaczyć pełną listę.
Uwaga: z powodu znanego problemu Dolibarr (#32491) moduł zawiera drobne obejście dla rejestracji endpointów API. Jest to transparentne dla konsumentów API - warto o tym wiedzieć tylko przy rozwiązywaniu problemów z routingiem API.
Strona główna modułu
Strona indeksowa modułu (dostępna z głównego wpisu menu KSeF) daje operacyjny przegląd na pierwszy rzut oka:
Boxy informacyjne na górze pokazują trzy karty podsumowań: Faktury wychodzące (łączna liczba wysłanych i zaakceptowanych za ostatnie 30 dni), Faktury przychodzące (łączna liczba i nowe faktury oczekujące na przegląd) oraz Konfiguracja (aktualne środowisko i status gotowości). Jeśli Twój certyfikat uwierzytelniający zbliża się do wygaśnięcia (w ciągu 30 dni), poniżej boxów pojawia się baner ostrzegawczy. Strona pokazuje również aktualny status systemu KSeF - jeśli KSeF ma awarię lub zaplanowaną konserwację, baner pojawia się tutaj i na stronach wysyłek, abyś wiedział, zanim spróbujesz wysłać.
Alerty "Wymaga uwagi" podświetlają elementy wymagające działania - faktury offline ze zbliżającymi się terminami, nieudane/odrzucone wysyłki do ponowienia, wysyłki wciąż oczekujące na potwierdzenie, nowe faktury przychodzące do przeglądu i błędy importu. Każdy alert linkuje bezpośrednio do filtrowanego widoku, abyś mógł go natychmiast obsłużyć.
Statystyki pokazują łączną liczbę wysyłek od początku, plus zaakceptowane, oczekujące i nieudane za ostatnie 30 dni, wraz z procentem sukcesu.
Tabele ostatniej aktywności pokazują najnowsze wysyłki wychodzące i ostatnie faktury przychodzące z linkami do odpowiednich rekordów faktur i klientów. Oś czasu pokrycia synchronizacji i przyciski szybkich akcji (Utwórz fakturę, Zobacz wszystkie, Synchronizuj) uzupełniają stronę.
Dobra strona do sprawdzenia rano - mówi Ci od razu, czy wszystko jest w porządku i wyświetla wszystko, co wymaga uwagi.
Struktura menu KSeF
Moduł dodaje sekcję KSeF w menu Rozliczenia w Dolibarr:
KSeF - strona indeksowa/przeglądu opisana powyżej
Status wysyłek - pełna strona zarządzania wysyłkami
Faktury przychodzące - lista faktur przychodzących z synchronizacją i importem
Jak używać - wbudowany krótki przewodnik z przyciskami testu połączenia
Konfiguracja - ustawienia modułu (tylko dla użytkowników z uprawnieniami administratora)
Pliki, migracje i inne szczegóły
Załączone pliki - moduł generuje i załącza kilka typów plików do faktur w trakcie ich cyklu życia. Dla faktur wychodzących: XML FA(3), UPO (pobierany po zaakceptowaniu) i PDF w stylu KSeF (generowany automatycznie po wysyłce lub utworzeniu offline). Dla faktur przychodzących: PDF w stylu KSeF (załączany przy imporcie) i oryginalny XML (do pobrania z karty faktury przychodzącej). Pliki te są przechowywane w standardowym systemie dokumentów Dolibarr i pojawiają się w sekcji "Załączone pliki" odpowiedniej faktury.
System migracji - moduł zawiera wewnętrzny system migracji, który uruchamia się automatycznie przy aktualizacji (po wymaganym wyłączeniu/ponownym włączeniu). Migracje obsługują ponowne parsowanie XML faktur przychodzących po ulepszeniu parsera, aktualizację struktur bazy danych dla nowych funkcji i naprawę danych z wcześniejszych wersji. Nie musisz nic robić ręcznie - migracje uruchamiają się przy aktywacji modułu i są śledzone, aby się nie powtarzały. Jeśli migracja się nie powiedzie, błąd jest logowany w logach Dolibarr.
Ochrona CSRF - moduł respektuje ustawienie MAIN_SECURITY_CSRF_WITH_TOKEN Dolibarr. Gdy jest włączone (domyślnie w nowoczesnych instalacjach Dolibarr), wszystkie formularze i wrażliwe akcje wymagają prawidłowego tokena CSRF. Jeśli widzisz nieoczekiwane błędy tokenów, upewnij się, że sesja Dolibarr nie wygasła i że ochrona CSRF jest spójnie włączona w całej instalacji.
Aktualizacja modułu
Gdy nowa wersja zostanie wydana na GitHubie:
1. Pobierz nowy plik ZIP ze strony wydań
2. W Dolibarr przejdź do Strona główna → Ustawienia → Moduły
3. Wyłącz moduł KSeF
4. Prześlij nowy ZIP przez "Wdróż/zainstaluj moduł zewnętrzny" (nadpisuje stare pliki)
5. Ponownie włącz moduł KSeF
Wyłączenie/ponowne włączenie jest obecnie wymagane przy każdej aktualizacji. Twoja konfiguracja jest domyślnie zachowywana - tokeny, certyfikaty, ustawienia i wszystkie dane faktur pozostają nienaruszone. System migracji uruchamia się przy ponownym włączeniu, aby obsłużyć ewentualne zmiany w strukturze danych.
Jeśli chcesz zacząć całkowicie od nowa, jest ustawienie "Usuń dane konfiguracyjne przy wyłączeniu modułu", które czyści wszystko. Upewnij się, że jest wyłączone (domyślnie) przed aktualizacją, chyba że celowo chcesz rekonfigurować od zera.