<< 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.

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 z flagą czyKorekta=1 są importowane jako korekty (KOR) i wzbogacane danymi korygowanego dokumentu z sekcji dokumentZKorektami{}.

Konfiguracja

Parametry

Przykładowa konfiguracja

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

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).

•Pozostałe sekcje (INFO{}, Kontrahent{}, 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{}.

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).

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