<< Pokaż spis treści >> Nawigacja:  Wtyczki importu faktur > Symfonia Handel

Opis

Plugin do importu faktur z plików eksportu programu Sage Symfonia Handel. Obsługuje format tekstowy z sekcjami DokumentSp oraz DokumentSp_oddział w nawiasach klamrowych { }.

Obsługiwane formaty

Plugin automatycznie rozpoznaje i parsuje oba typy sekcji dokumentów z jednego pliku eksportu.

UWAGA: Ze względu ma niejednoznaczność danych źródłowych nie są obsługiwane faktury zaliczkowe i faktury rozliczające zaliczki, a także korekty takich dokumentów, które wymagają innej struktury danych dla KSeF.

Format DokumentSp (klasyczny)

Standardowa sekcja dokumentu w eksporcie Symfonia Handel:

DokumentSp{
    numer =26-FVS/03/3355
    typDk =FVS
    nazwa =Faktura
    dataWystawienia =2026-03-02
    dataSprzedazy =2026-03-02
    czyKorekta =0
    czyAnulowany =0
    netto =98.890000000000
    vat =22.740000000000
    brutto =121.630000000000
    waluta =
    kurs =1.000000000000
   
    daneKh{
        KhNIP =8992732867
        KhNazwa =FIRMA PRZYKŁADOWA
        KhUlica =Główna
        KhDomu =10
        KhLokal =5
        KhMiasto =Warszawa
        KhKodPocz =00-001
        kraj{
            symbol =PL
        }
    }
   
    Pozycja dokumentu{
        lp =1
        kod =TOWAR001
        Nazwa_Dl{
            opis =Nazwa towaru
        }
        ilosc =1.000000000000
        jednostkaMiary =szt
        cena =25.000000000000
        netto =23.810000000000
        VAT =1.190000000000
        stVAT{
            typ =10
            wartosc =0.0500
        }
        brutto =25.000000000000
        PKWiU =
    }
}

Format DokumentSp_oddział (z obsługą oddziałów)

Sekcja dokumentu generowana przy eksporcie z oddziałami. Różni się od DokumentSp następującymi elementami:

DokumentSp_oddział{
    numer =0457/2026/FVS
    typDk =FVS
    nazwa =Faktura VAT
    dataWystawienia =2026-03-25
    dataSprzedazy =2026-03-03
    czyAnulowany =0
    waluta =
    kurs =1.000000000000
    netto =3845.290000
    vat =884.420000
    brutto =4729.710000
   
    daneKh{
        KhNIP =9661461820
        KhNazwa =FERMA DROBIU KRZYSZTOF WYSOCKI
        KhUlica =Ryboły
        KhDomu =1028/8
        KhLokal =
        KhMiasto =Zabłudów
        KhPoczta =16-080
        kraj{
            symbol =PL
        }
    }
   
    pozycja{
        lp =1
        kod =KLEIB C26 Beton B-30/25
        opis{
            opis =KLEIB C26 Beton B-30 suchą miesz. cement. do betonu...
        }
        ilosc =216.000000
        jednostkaMiary =szt
        cena =17.350000
        netto =3747.600000
        VAT =861.950000
        brutto =4609.550000
        stVAT{
            typ =10
            wartosc =0.2300
        }
        PKWiU =
    }
}

Obsługiwane typy dokumentów

Plugin importuje wszystkie typy dokumentów bez filtrowania po typie — różne firmy mogą mieć różne konfiguracje typów w Symfonia.

Dokumenty z flagą czyAnulowany=1 są pomijane. Dokumenty korygujące (RodzajFaktury=KOR) są wykrywane na podstawie flagi czyKorekta=1 (DokumentSp) lub niepustego pola kodDokKoryg albo typDk=FKS (DokumentSp_oddział) i wzbogacane danymi korygowanego dokumentu. Jeśli dokument zawiera sekcję daneOd{}, dane odbiorcy są mapowane na element Podmiot3 z rolą odbiorca.

Konfiguracja

Parametry

Wartości parametru CheckDuplicates:

Przykładowa konfiguracja

{
  "SourcePath": "C:\\Symfonia\\Export",
  "FilePattern": "export_*.txt",
  "CheckDuplicates": "Block"
}

Działanie

1.Skanowanie — Plugin szuka plików pasujących do wzorca w katalogu źródłowym

2.Parsowanie — Każdy plik jest parsowany w poszukiwaniu sekcji DokumentSp{} oraz DokumentSp_oddział{}

3.Filtrowanie — Wybierane są tylko dokumenty będące fakturami sprzedaży (pomijane anulowane)

4.Walidacja — Sprawdzanie poprawności danych i duplikatów

5.Import — Konwersja do formatu KSeF XML i zapis do bazy

6.Archiwizacja — Przeniesienie pliku do podkatalogu Processed lub Failed

Szczegółowe zasady przetwarzania danych na format KSeF XML

Rozpoznawanie sekcji

•Parser szuka sekcji DokumentSp{...} i DokumentSp_oddział{...} na najwyższym poziomie pliku — z każdej z nich powstaje jeden dokument faktury.

•Sekcje Dokument{...} są parsowane pomocniczo w celu pobrania danych płatności (forma_platnosci, terminPlatnosci, dozaplaty) i powiązane z dokumentami sprzedaży przez numer faktury (FK nazwa lub kod). Pobierany jest też identyfikator kontrahenta (khid z podsekcji Dane nabywcy{}) jako fallback do powiązania z sekcją Kontrahent{}.

•Sekcje Kontrahent{...} są parsowane w celu pobrania adresu email nabywcy — budowany jest słownik id → email, który służy do wzbogacenia danych faktury.

•Pozostałe sekcje (INFO{}, towar{}, Kraj{} itp.) są ignorowane.

•Jeden plik może zawierać wiele sekcji dokumentów — każda jest parsowana niezależnie.

Parsowanie pól klucz-wartość

•Pola mają format: klucz =wartość (spacja przed znakiem = jest opcjonalna).

•Parsowane są tylko pola na pierwszym poziomie danej sekcji — zagnieżdżone sekcje (np. daneKh{}, stVAT{}) są pomijane przy odczytywaniu pól nadrzędnych i parsowane oddzielnie.

•Wartości liczbowe są zapisywane z precyzją do 12 miejsc po przecinku (np. 98.890000000000). Przecinki i kropki są obsługiwane przy parsowaniu.

•Puste wartości (np. waluta =) traktowane są jako brak wartości — stosowana jest wartość domyślna.

•Cudzysłowy na początku/końcu wartości są usuwane.

Mapowanie nagłówka faktury → XML KSeF

Mapowanie danych nabywcy (Podmiot2) → XML KSeF

Dane nabywcy pochodzą z zagnieżdżonej sekcji daneKh{}.

Zasada pobierania adresu email nabywcy:

Sekcja daneKh{} dokumentu nie zawiera bezpośrednio adresu email. Email pobierany jest pośrednio:

1.Z sekcji daneKh{} pobierany jest identyfikator kontrahenta (pole KhID).

2.Jeśli KhID nie występuje w daneKh{}, jako fallback używane jest pole khid z podsekcji Dane nabywcy{} wewnątrz powiązanej sekcji Dokument{} (powiązanie przez numer faktury).

3.Znaleziony identyfikator jest wyszukiwany w słowniku id → email zbudowanym z sekcji Kontrahent{} całego pliku (pole id = klucz, pole email = wartość).

4.Jeśli znaleziono email — jest zapisywany w elemencie Podmiot2 > DaneKontaktowe > Email, co umożliwia automatyczne wysłanie faktury emailem do nabywcy po jej wystawieniu w KSeF.

Mapowanie pozycji faktury → XML KSeF

Pozycje pochodzą z sekcji Pozycja dokumentu{} (DokumentSp) lub pozycja{} (DokumentSp_oddział).

Obliczanie stawki VAT (fallback)

Jeśli sekcja stVAT{} jest nieobecna, stawka VAT jest obliczana ze wzoru:

StawkaVat = round(VAT / netto × 100, 0)

Jeśli netto = 0, przyjmowana jest stawka domyślna 23%.

Mapowanie stawki VAT na kody KSeF

Mapowanie płatności (Platnosc) → XML KSeF

Dane płatności pochodzą z dwóch źródeł w zależności od formatu pliku:

Zasady mapowania na element Fa > Platnosc:

Sekcja Platnosc nie jest tworzona gdy brak wszystkich trzech danych: formy płatności, terminu i informacji o zapłacie.

Mapowanie faktur korygowanych → XML KSeF

Gdy czyKorekta=1, parser szuka zagnieżdżonych sekcji dokumentZKorektami{} zawierających dane korygowanego dokumentu:

dokumentZKorektami{
    numer =26-FVS/03/3355
    data  =2026-03-02
    wartosc =121.630000
}

Dla każdej sekcji dokumentZKorektami{} tworzony jest osobny element DaneFaKorygowanej w XML. Numer KSeF korygowanej faktury ustawiany jest jako nieznany (NrKSeFN=1).

Wykrywanie korekty

Plugin rozpoznaje faktury korygujące w różny sposób, zależnie od formatu dokumentu:

Pozycje faktury korygującej — wariant przed/po

W formacie DokumentSp_oddział każda sekcja pozycja{} może zawierać podsekcje przedKorekta{} i poKorekcie{}, opisujące stan pozycji przed i po korekcie:

pozycja{
    przedKorekta{
        ilosc =192.000000
        netto =2435.120000
        VAT =560.080000
        brutto =2995.200000
    }
    poKorekcie{
        ilosc =190.000000
        netto =2409.750000
        VAT =554.250000
        brutto =2964.000000
    }
}

Gdy obie podsekcje są obecne, plugin tworzy dwa wiersze KSeF dla jednej pozycji źródłowej:

Gdy podsekcje są nieobecne, pozycja zawiera wartość różnicy bezpośrednio jako pola płaskie — tworzony jest wtedy jeden wiersz KSeF. Pozycje, w których wszystkie wartości (ilość, netto, VAT, brutto) są identyczne przed i po korekcie, są pomijane.

Przy obliczaniu sum podatkowych (P_13/P_14 i P_15) wiersze z StanPrzed=1 są odejmowane — wynik odpowiada faktycznej różnicy korekty (np. 2409,75 − 2435,12 = −25,37).

Dane odbiorcy (Podmiot3) — sekcja daneOd{}

Jeśli w dokumencie (DokumentSp lub DokumentSp_oddział) występuje sekcja daneOd{}, jej dane są mapowane na element Podmiot3 z rolą odbiorca (rola=2). Stosuje się to w przypadkach, gdy towar jest dostarczany do podmiotu innego niż nabywca (Podmiot2).

Jeśli sekcja daneOd{} jest nieobecna lub pole KhNazwa jest puste, element Podmiot3 nie jest tworzony.

Obliczanie sum podatkowych (P_13/P_14)

Są obliczane dynamicznie jako suma wartości pozycji (FaWiersz), pogrupowanych wg stawki VAT:

Kwota brutto faktury (P_15) = suma (P_11 + P_11Vat) ze wszystkich pozycji.

Mapowanie rodzaju faktury

Wyjątek: jeśli pole czyKorekta =1, rodzaj jest wymuszony na KOR niezależnie od typDk.

Mapowanie kodu waluty

•Puste pole waluta → PLN

•Wartość parsowana na enum TKodWaluty (case-insensitive)

•Nierozpoznana wartość → PLN

Mapowanie kodu kraju

•Puste pole kraj > symbol → PL

•Wartość parsowana na enum TKodKraju (case-insensitive)

•Nierozpoznana wartość → PL

Mapowanie pól — podsumowanie

Nagłówek faktury

Dane nabywcy (Podmiot2) — sekcja daneKh{}

Pozycje faktury

Obsługiwane stawki VAT

Kodowanie plików

Plugin odczytuje pliki z kodowaniem Windows-1250 (CP1250), które jest standardowym kodowaniem dla polskich aplikacji Windows.

Obsługa błędów

Przetwarzanie transakcyjne

Wszystkie faktury z jednego pliku są przetwarzane transakcyjnie:

•Jeśli którakolwiek faktura zawiera błąd, wszystkie faktury z tego pliku są odrzucane

•Plik z błędami jest przenoszony do podkatalogu Failed

Typowe błędy

Archiwizacja

Po przetworzeniu pliki są przenoszone do:

•{SourcePath}/Processed/ - pliki przetworzone pomyślnie

•{SourcePath}/Failed/ - pliki z błędami

Nazwa pliku jest uzupełniana o znacznik czasu: 20251203_143022_export.txt

Przykład użycia

1.Skonfiguruj eksport w Symfonia Handel do katalogu np. C:\Symfonia\Export

2.Włącz plugin w KT KSeF Sender

3.Ustaw SourcePath na C:\Symfonia\Export

4.Plugin automatycznie skanuje katalog i importuje nowe faktury

Wymagania

•Sage Symfonia Handel 2014 lub nowszy

•Eksport w formacie tekstowym (domyślny format Symfonia)

•Pliki z rozszerzeniem .txt