Ekran Zarządzanie wtyczkami importu faktur (menu: Konfiguracja → Wtyczki importu) służy do konfiguracji źródeł danych, z których aplikacja automatycznie pobiera faktury do wysłania do KSeF.
Czym są wtyczki?
Wtyczki (pluginy) to moduły odpowiedzialne za odczytywanie faktur z różnych formatów plików. Każda wtyczka monitoruje wskazany folder na dysku i automatycznie importuje znalezione faktury.
Wbudowane wtyczki
Wtyczka |
Opis |
Format plików |
JPK FA(4) XML |
Import faktur z plików JPK_FA w wersji 4 |
.xml |
Excel z pozycjami faktur |
Import faktur z arkuszy kalkulacyjnych Excel z pozycjami faktur stworzony na podstawie wzoru zamieszczonego pod adresem https://doc.ktsoft.pl/ktkonwksieg/import_excel_pozycje.htm |
.xlsx, .xls |
Sage Symfonia Handel |
Import faktur z programu Symfonia Handel |
.txt |
XML eFaktura ustrukturyzowana KSeF |
Import faktur z plików XML w strukturze KSeF Faktura. |
.xml |
CSV z pozycjami faktur |
Import faktur z pliku CSV |
.csv |
Zarządzanie wtyczkami
•Dodaj wtyczkę
•Załaduj Wszystkie - załaduj ponownie wszystkie wtyczki (przydatne po zmianie konfiguracji).
•Wyładuj Wszystkie - wyładuj wszystkie wtyczki z pamięci.
Konfiguracja wbudowanych wtyczek
W panelu zarządzania dostępne są ikony akcji, które umożliwiają kontrolę nad zainstalowanymi wtyczkami:
1.Edycja konfiguracji (ikona ołówka) – pozwala na modyfikację parametrów i ustawień wybranej wtyczki.
2.Załadowanie wtyczki (ikona strzałki odświeżania) – służy do ponownego wczytania wtyczki lub odświeżenia jej stanu w systemie.
3.Włącz/Wyłącz wtyczkę (ikona pauzy/play) – umożliwia aktywację lub czasowe dezaktywowanie działania wtyczki bez jej usuwania.
4.Usuń wtyczkę (ikona kosza) – trwale usuwa wybraną wtyczkę z panelu aplikacji.
Dodawanie wtyczki
Sytuacja |
AssemblyPath |
ClassName |
Zewnętrzna wtyczka (np. plik MojaWtyczka.dll) |
Pełna ścieżka do pliku, np.: C:\plugins\MojaWtyczka.dll |
Pełna nazwa klasy, np.: MojaFirma.Wtyczki.FakturaScanner |
Wbudowana wtyczka (już załadowana w aplikacji) |
Tylko nazwa assembly, np.: AppExpirationService |
Pełna nazwa klasy, np.: KTKsefSender.WorkerLib.Scanners.MojScanner |
1.Kliknij przycisk Dodaj wtyczkę.
2.Wprowadź Nazwę wtyczki, która pozwoli na jej łatwą identyfikację.
3.Skonfiguruj wymagane parametry:
•Priorytet – wartość określająca kolejność przetwarzania. Im niższy numer, tym wyższy priorytet (np. wtyczka z priorytetem 1 zostanie uruchomiona przed tą z priorytetem 10).
•Status – określa, czy wtyczka jest obecnie aktywna (uruchomiona).
•Ścieżka do Assembly – pełna ścieżka do pliku .dll zawierającego logikę wtyczki (zgodnie z tabelą „Dwa tryby działania”).
•Nazwa klasy – pełna nazwa klasy wraz z przestrzenią nazw (np. MyCompany.Scanners.CustomScanner).
•Konfiguracja JSON – szczegółowe ustawienia działania wtyczki zapisane w formacie JSON
4. Kliknij zapisz
Jak działa skanowanie?
Po aktywacji wtyczki aplikacja automatycznie realizuje następujący cykl pracy:
•Monitorowanie folderu źródłowego – w określonych odstępach czasu (konfigurowalnych w sekcji Procesy w tle) system sprawdza zawartość wskazanego katalogu.
•Konwersja danych – aplikacja odczytuje znalezione pliki i konwertuje je do oficjalnego formatu KSeF.
•Zapis w bazie danych – poprawnie zaimportowane faktury zostają trwale zapisane w lokalnej bazie danych aplikacji.
•Archiwizacja i obsługa błędów – po zakończeniu operacji pliki są przenoszone do odpowiednich podfolderów:
oProcessed – jeśli przetwarzanie zakończyło się sukcesem.
oFailed – jeśli wystąpił błąd uniemożliwiający poprawną konwersję lub import.
Struktura folderów
Typowa struktura folderów dla wtyczek:
C:\KSeF\Import\
├── JpkFa\ ← Folder źródłowy JPK FA
│ ├── Processed\ ← Pliki pomyślnie przetworzone
│ └── Failed\ ← Pliki z błędami
├── Excel\ ← Folder źródłowy Excel
│ ├── Processed\
│ └── Failed\
└── XML\ ← Folder źródłowy XML
├── Processed\
└── Failed\
Istotnym elementem konfiguracji wtyczek jest określenie katalogu źródłowego, w którym użytkownik będzie zapisywał pliki do wysłania. W tym celu należy utworzyć dedykowany katalog, a następnie po kliknięciu „edycja” wpisaniu do niego ścieżki.
Przycisk „testuj konfigurację” pozwala sprawdzić, czy operacja przebiegła pomyślnie.
W wersji serwerowej (Docker) użyj ścieżek w podmontowanym woluminie danych, np. /app/data/import/JpkFa.
Wykrywanie duplikatów
Każda wtyczka ma konfigurowalną opcję wykrywania duplikatów. Jeśli jest włączona, aplikacja nie zaimportuje ponownie faktury o tym samym numerze.