1. Obsługa faktur zakupowych KSeF
2. Zalecany model integracji
3. Argumenty i kontrargumenty
4. Tematy powiązane
1. Obsługa faktur zakupowych KSeF
Wprowadzenie
Ten artykuł powstał jako odpowiedź (reakcja) na plany jeden z firm, użytkującej
Trawers ERP, aby faktury zakupu, pobrane z KSeF w zewnętrznym programie, zapisywać
bezpośrednio w zbiorze faktur w ZO. Nie pobierać tej faktury KSeF w Trawersie.
W artykule opisano ryzyka takiego bezpośredniego zapisu, wskazano poprawne
rozwiązania i opisano architekturę Trawersu zapewniają bezpieczeństwo
i spójność danych.
Trawers ERP i faktury KSeF
Rozwiązania zwiększające bezpieczeństwo i odporność procesu
Ten artykuł opisuje, jakie mechanizmy w Trawers ERP zostały przewidziane wokół obsługi
faktur KSeF w kontekście faktur zakupu w ZO, oraz dlaczego warto aby ewentualne integracje
(np. DMS/Workflow/OCR) nie omijały tych rozwiązań, tylko się do nich 'podpinały'.
Poniższe wnioski opierają się na strukturach danych ZO, które są w systemie (nagłówki i pozycje),
w szczególności na obecności pól KSeF oraz pól audytowych.
1) 'Źródło prawdy' faktury KSeF w Trawers: numer, hash, XML
W nagłówku dokumentu zakupu (ZO) przewidziano komplet pól KSeF:
* KSEFNR - numer KSeF (36)
* KSEFSHA - InvoiceHash Base64 (44)
* KSEFXML - Invoice XML UTF8 (pole memo)
* dodatkowo sterowanie/parametry procesu: KSEFTRYB, KSEFWYTNCo to daje (bezpieczeństwo)
* Jednoznaczna identyfikacja dokumentu: numer KSeF jest najlepszym, stabilnym kluczem
do wykrywania duplikatów i powiązań (np. korekt).
* Integralność treści: hash (InvoiceHash) daje możliwość wykazania, że treść dokumentu
w systemie jest zgodna z KSeF (albo że nie była zmieniana).
* Kanoniczna treść: przechowywanie XML (KSEFXML) to 'dowód źródłowy' - niezależny od tego,
jak dokument jest prezentowany w PDF/GUI i niezależny od pośredników.
Co to daje (odporność na uszkodzenia)
* Jeśli pośrednik (integracja) zmieni format, linki, sposób generowania podglądu,
albo wystąpi awaria w kanale PDF - nadal jest XML jako trwałe źródło.
2) Audyt zmian i pełna rozliczalność operacji (kto/kiedy/czym)
Zarówno nagłówki jak i pozycje mają pola audytowe:
* ADDDATE/ADDDATD/ADDTIME/ADDUSER/ADDPROC/ADDSYST
* CHGDATE/CHGDATD/CHGTIME/CHGUSER/CHGPROC/CHGSYST
* MODTIME
Co to daje (bezpieczeństwo)
* Można wykazać, kto i kiedy wprowadził lub zmienił dane dokumentu, a także z jakiego procesu/systemu.
Co to daje (odporność i diagnostyka)
* Przy problemach integracyjnych widać, czy rekord powstał z dialogu czy z integracji,
kiedy poszła modyfikacja i czy modyfikacje powtarzają się cyklicznie (np. błędna synchronizacja).
Co to daje (naprawa)
* Ułatwia odtworzenie sekwencji zdarzeń i cofnięcie błędnych zmian (lub ich automatyczne wyłapanie).
3) Spójność nagłówek-pozycje (ZO) i odporność na różnice w mapowaniu
W pozycjach ZO powtarzają się kluczowe dane z nagłówka (kontrahent, daty, waluta, termin, numer faktury obcy),
a dodatkowo jest rozbudowany zestaw pól VAT/PTU, MPP, reverse charge itd.
Co to daje (bezpieczeństwo i zgodność)
* Jeśli dokument ZO jest budowany na podstawie XML KSeF, minimalizuje się ryzyko błędów
mapowania po stronie integracji (np. VAT z linii vs VAT z podsumowania, różne zaokrąglenia).
* Rozdzielenie 'treści faktury' (XML) i 'opisu' (kategorie/wymiary) pozwala bezpiecznie
zmieniać opis bez naruszania treści dokumentu.
4) Dlaczego to jest ważne przy integracjach (Saldeo, DMS, workflow)
* Ryzyko typowe dla podejścia 'pośrednik tworzy dokument w ZO'
Jeżeli system pośredni sam 'wpisuje' fakturę KSeF do ZO jako finalny dokument, pojawiają się ryzyka:
* utrata kanonicznego źródła: do ZO trafia 'rekord z polami' a nie dowód w postaci XML + hash,
* rozjazdy przez transformację: różnice w regułach VAT, rabatów, korekt, pozycji informacyjnych, zaokrągleń,
* utrudniona naprawa: w razie sporu lub błędu trzeba 'zgadywać', co było w KSeF,
zamiast odwołać się do przechowywanego XML,
* duplikaty i reimporty: bez twardego klucza i weryfikacji integralności wzrasta ryzyko
powielenia dokumentów (ponowne wysłanie, retry integracji).
Rekomendacja architektoniczna dla integracji
Jeżeli planuje się integracje (Saldeo, inne DMS/Workflow/OCR),
najbezpieczniejszy wzorzec jest taki:
Co powinno pozostać w Trawers (nie omijać)
1. Pobieranie/utrwalanie faktury KSeF jako XML w Trawers
* wypełnienie `KSEFNR`, `KSEFXML`, (docelowo także `KSEFSHA`)
2. Idempotencja/antyduplikacja oparta o KSEFNR (i hash)
* jeden dokument KSeF = jeden rekord biznesowy w ZO
Co może dostarczać integracja (wartość dodana)
* akceptacja i opis (kategorie, rejestry, wymiary, MPK/projekty),
* komentarze, przypisanie odpowiedzialnych, SLA,
* podgląd PDF i załączniki pomocnicze,
* automatyczne sugerowanie dekretacji.
Jak to spiąć praktycznie
* Integracja przekazuje do Trawers co najmniej numer KSeF (KSEFNR) + zestaw metadanych opisu.
* Trawers na podstawie numeru KSeF pobiera XML, tworzy dokument w ZO i dopina opis (nagłówek/pozycje).
Podsumowanie
Trawers ERP ma wyraźnie zaprojektowaną warstwę KSeF w ZO: numer + hash + XML,
do tego pełny audyt zmian. To daje:
* wysokie bezpieczeństwo (dowód źródłowy i integralność),
* dużą odporność (niezależność od formatów pośredników, możliwość rekonstrukcji),
* łatwiejszą diagnozę (audyt kto/kiedy/jak),
* łatwiejszą naprawę (powtarzalny reimport, porównania, cofanie etapów).
Dlatego rekomendacja dla integracji jest prosta: nie zastępować mechanizmu KSeF w Trawers,
tylko go wykorzystać - integracja powinna być 'warstwą opisu i procesu', a nie 'twórcą prawdy'
o treści faktury.
2. Zalecany model integracji
Trawers ERP i KSeF: bezpieczna obsługa faktur zakupowych oraz zalecany model integracji
Wstęp
KSeF wprowadza ustrukturyzowaną e-fakturę jako dokument źródłowy w formacie XML.
W praktyce oznacza to, że system ERP powinien nie tylko 'zaczytać dane', ale też zapewnić:
trwały ślad źródłowy, integralność, odporność na błędy oraz możliwość łatwej diagnozy i naprawy.
Trawers ERP zawiera zestaw rozwiązań wspierających bezpieczną obsługę faktur KSeF
w obszarze zakupów (ZO). Ten artykuł opisuje te mechanizmy oraz wskazuje, jak projektować
integracje (np. DMS/workflow/OCR), aby nie osłabiały bezpieczeństwa procesu.
Architektura KSeF w Trawers ERP:
Co jest 'rdzeniem' rozwiązania
1) Kluczowe pola KSeF w nagłówku dokumentu zakupu (ZO)
W definicji nagłówka dokumentu zakupu (ZO) przewidziano komplet pól służących do utrwalenia
faktury KSeF jako dokumentu źródłowego:
* KSEFNR - numer KSeF
* KSEFSHA - InvoiceHash Base64
* KSEFXML - Invoice XML UTF8 (pole memo)
* KSEFTRYB, KSEFWYTN - pola sterujące procesem wysyłki/trybu (gdy wykorzystywane)
Znaczenie praktyczne:
* Numer KSeF zapewnia jednoznaczną identyfikację dokumentu.
* Hash zapewnia warstwę weryfikacji integralności (czy treść nie została naruszona).
* XML zapewnia przechowywanie kanonicznego źródła (niezależnego od tego,
jak dane są prezentowane w GUI lub PDF).
2) Audyt zmian i rozliczalność operacji
Nagłówki i pozycje ZO posiadają pola audytu tworzenia i modyfikacji:
* ADD (kto/kiedy/jaki proces/jaki system dodał)
* CHG (kto/kiedy/jaki proces/jaki system zmienił)
* MODTIME (czas ostatniego zapisu)
Znaczenie praktyczne:
* Łatwo ustalić, czy dokument utworzył użytkownik w GUI, czy integracja.
* W razie incydentu integracyjnego widać, kiedy nastąpiły zmiany i z jakiego procesu.
Zalety rozwiązania Trawers KSeFBezpieczeństwo
* Jednoznaczny klucz dokumentu: numer KSeF (KSEFNR) jest najlepszym identyfikatorem
do wykrywania duplikatów i korekt.
* Integralność i dowodowość: hash + XML zapewniają możliwość weryfikacji,
że treść w systemie odpowiada dokumentowi źródłowemu.
* Rozdzielenie treści od opisu: opis/dekretacja może się zmieniać (proces),
treść faktury (XML KSeF) nie powinna.
Odporność na uszkodzenia i zmiany pośredników
* Jeśli zewnętrzny system (workflow/DMS) zmieni format eksportu, linki do podglądów
albo wystąpi awaria w generowaniu PDF, Trawers nadal ma XML jako źródło.
* Możliwy jest kontrolowany reimport/rekonstrukcja dokumentu w oparciu o XML,
bez utraty spójności.
Antywzorce integracji: czego unikaćAntywzorzec: Pośrednik tworzy finalny dokument KSeF w ZO
W tym modelu system zewnętrzny pobiera fakturę z KSeF, a następnie sam tworzy rekord w ZO
i wypełnia pola 'jak umie'.
Dlaczego to jest ryzykowne:
1. Transformacja zamiast źródła
Do ZO trafia reprezentacja pośrednia (zmapowane pola), a nie kanoniczny XML KSeF.
2. Ryzyko rozjazdów
Różne algorytmy liczenia VAT (linie vs podsumowania), rabatów, zaokrągleń, korekt,
pozycji opisowych - mogą dać niezgodności.
3. Utrata integralności
Jeśli nie zostanie zapisany XML i hash, trudniej udowodnić zgodność z dokumentem źródłowym.
4. Trudniejsza naprawa i większy koszt serwisu
Każdy błąd wymaga ręcznego porównywania z KSeF i odtwarzania danych.
Rekomendowany model integracji:
Trawers trzyma źródło, integracja daje proces
Najbezpieczniejsza i najbardziej serwisowalna architektura to:
Trawers ERP (rdzeń)
* pobiera fakturę z KSeF i utrwala:
* KSEFNR
* KSEFXML
* (docelowo) KSEFSHA
* buduje dokument zakupu w ZO na bazie źródła KSeF
* utrzymuje audyt zmian
System zewnętrzny (wartość dodana)
* realizuje obieg: akceptacje, opisy, komentarze, przypisania odpowiedzialnych
* dostarcza klasyfikację: kategorie, rejestry, wymiary, MPK/projekty, MPP
* może zapewniać podglądy PDF oraz 'koszyk wpływu' dokumentów spoza KSeF
Łącznik
* numer KSeF (KSEFNR) jako twardy identyfikator, po którym Trawers:
* pobiera XML z KSeF (lub dopasowuje już pobrany),
* dopina metadane opisu do nagłówka/pozycji.
Korzyść: integracja nie bierze na siebie odpowiedzialności za 'odtworzenie treści'
faktury KSeF - odpowiada za proces, a nie za prawdę dokumentu.
FAQCzy numer KSeF w ZO nie wystarczy?
Numer KSeF jest dobrym kluczem, ale nie zastępuje przechowywania treści źródłowej.
W razie sporu lub potrzeby weryfikacji najpewniejszy jest zapis XML i możliwość
kontroli integralności.
Po co hash (InvoiceHash)?
Hash pozwala wykazać, że treść dokumentu nie została zmieniona i umożliwia
automatyczną kontrolę spójności.
A co z PDF?
PDF jest podglądem. Dla KSeF dokumentem źródłowym jest XML. PDF może być pomocny operacyjnie,
ale nie powinien być jedynym 'dowodem' faktury KSeF w ERP.
Rada końcowa dla wdrożeń i integracji
Jeżeli planuje się integrację z systemami workflow/DMS/OCR (np. Saldeo), zachować zasadę:
Integracja nie powinna tworzyć 'finalnej faktury KSeF' w ZO w miejsce mechanizmu Trawersu.
Najlepszy efekt daje model, w którym:
* Trawers utrwala źródło (XML/hash/numer) i buduje dokument zakupu,
* integracja dostarcza opis, akceptacje i klasyfikację.
To podejście maksymalizuje bezpieczeństwo, ogranicza ryzyko rozjazdów, skraca diagnozę
problemów oraz ułatwia naprawy bez eskalacji kosztów serwisowych.
3. Argumenty firmy zewnętrznej i kontrargumenty Trawers
Każdy punkt zawiera:
Co mówi firma zewnęrzna -> Riposta -> Krótki przykład ryzyka.
1) Ale my też pobieramy fakturę z KSeF, więc to jest to samoRiposta: Sam fakt pobrania nie oznacza, że do ZO trafia ten sam artefakt.
KSeF daje ustrukturyzowany XML, a Wy do ERP najczęściej zapisujecie rekord z polami
+ ewentualnie PDF podglądu. To już jest transformacja i ryzyko rozjazdu.
Przykład: różnice w zaokrągleniach VAT między pozycjami a podsumowaniem;
jedna strona liczy VAT od sum, druga od linii -> w ZO wychodzi inny VAT.
2) My przepiszemy 1:1 wszystkie pola, nic nie zgubimyRiposta: Żeby było 1:1, musicie przenieść pełną strukturę XML,
a nie tylko zestaw pól księgowych. W KSeF jest dużo elementów, które w ERP często nie
mają prostych odpowiedników albo mają zależności (korekty, referencje, oznaczenia).
Przykład: korekty i powiązania do dokumentu korygowanego; jeśli mapping nie obejmie
wszystkich referencji (numer/pozycje), to korekta w ERP 'żyje własnym życiem'.
3) Wystarczy numer KSeF w ERP, po co nam XMLRiposta: Numer KSeF jest kluczem, ale nie jest dowodem treści. W razie sporu/audytu
trzeba pokazać treść dokumentu, która jest w KSeF. Bez XML w ERP nie ma 'samowystarczalnego śladu'
Jest zależność od ponownego pobrania i od tego, że wszystko odtworzy się identycznie.
Przykład: po kilku miesiącach ktoś pyta 'na jakiej podstawie zaksięgowano pozycję X?'
Bez XML trzeba odtwarzać; przy błędzie transformacji nie udowodni się, że w ERP jest zgodnie z KSeF.
4) Przecież możemy w razie czego pobrać XML z KSeF późniejRiposta: To jest strategia 'naprawimy po fakcie'. Bez XML w momencie księgowania:
* nie ma automatycznej weryfikacji zgodności danych,
* nie ma możliwości łatwego reprocessu i porównania,
* rośnie koszt serwisu (każdy incydent = ręczna analiza).
Przykład: faktura zaksięgowana, ale po czasie okazuje się, że stawki VAT w ERP
nie zgadzają się z KSeF. Jeśli XML był zapisany od razu, porównanie jest mechaniczne.
5) Nasze dane są lepsze, bo robimy opis, kategorie, akceptacjeRiposta: Dobrze - i właśnie to jest Wasza rola. Ale opis/dekretacja # treść faktury.
Bezpieczny podział odpowiedzialności to:
* KSeF/XML -> Trawers (prawda dokumentu),
* opis/akceptacja/kategorie -> Wy (proces).
Przykład: kategoria kosztowa może się zmienić (decyzja), ale treść faktury
nie powinna być 'produktem ubocznym' procesu.
6) Jeśli wpiszemy do ZO, będzie szybciej i prościejRiposta: Szybciej na starcie, ale ryzyko kosztów eksploduje później:
* duplikaty,
* korekty,
* spory o to 'kto zawinił' przy rozjeździe,
* trudne odtwarzanie stanu.
Przykład: ponowne wysłanie tego samego dokumentu po błędzie integracji
-> dwa wpisy w ZO. Bez twardego porównania do XML/hash wyłapanie tego automatem jest trudniejsze.
7) W końcu ERP i tak przechowuje rekordy, nie XMLRiposta: U nas w ZO są pola na KSeF XML i hash (`KSEFXML`, `KSEFSHA`). To oznacza,
że projektowo ERP przewiduje przechowywanie źródła. Jeśli pośrednik omija ten mechanizm,
to działa wbrew architekturze systemu i osłabia kontrolę.
Przykład: jeśli kiedyś włączy się kontrolę zgodności, nie będzie czym jej zasilić,
bo dokumenty z pośrednika nie mają XML.
8) Możemy przekazać PDF jako dowódRiposta: PDF/podgląd to nie jest kanoniczny dokument KSeF. KSeF to ustrukturyzowana
e-faktura (XML), a PDF jest tylko wizualizacją, często generowaną przez narzędzie pośrednie.
Przykład: dwa różne systemy generują PDF z tego samego XML, ale inaczej formatują
i zaokrąglają prezentację; PDF nie jest dobrą bazą do kontroli treści i zgodności.
9) Mamy już innych klientów, którzy tak robiąRiposta: To, że 'działa', nie znaczy, że jest bezpieczne. Przy małej skali
i braku kontroli może nie wyjść, ale ryzyko ujawnia się dopiero przy:
* korektach,
* dużej liczbie dokumentów,
* kontrolach i odtworzeniach historycznych,
* problemach z duplikacją.
Przykład: dopiero po 6-12 miesiącach ktoś zaczyna porównywać JPK/VAT i wychodzą
różnice na groszach/liniach.
10) To kwestia zaufania - my gwarantujemy zgodnośćRiposta: W integracji krytycznej nie chodzi o zaufanie, tylko o mechanizm weryfikacji.
Najprościej: ERP pobiera XML z KSeF i ma możliwość porównania kluczowych sum i stawek.
To jest obiektywne i automatyzowalne.
Przykład: nawet jeśli 99.9% jest OK, to 0.1% błędów przy tysiącach faktur daje realne problemy.
Mechanizm kontroli eliminuje spory.
Krótka propozycja kompromisu, którą warto przekazać firmie zewnętrznej:
> Dostarczajcie: numer KSeF + status + opis/dekretację (kategorie, rejestry, wymiary, komentarze, akceptacje).
> Trawers musi pobierać XML bezpośrednio z KSeF i tworzyć dokument w ZO na bazie źródła,
uzupełniając go metadanymi od Was.
> Łącznikiem jest KSEFNR.
To zostawia Wam całą 'wartość biznesową' (obieg dokumentów), a minimalizuje ryzyko techniczne i audytowe.