Problem zaczyna się od jednej faktury, która w firmie pojawia się trzy razy. Najpierw system finansowo-księgowy pobiera z KSeF jej ustrukturyzowany plik XML. Kilka minut później dostawca wysyła księgowości wizualizację PDF e-mailem. Następnego dnia pracownik działu zakupów zapisuje ten sam PDF ręcznie w DMS, bo „nie widział go w obiegu”.
Technicznie powstały trzy pliki. Biznesowo nadal istnieje jeden dokument źródłowy.
Jeżeli system traktuje każde pojawienie się pliku jako nową fakturę, konsekwencje są przewidywalne: dwa obiegi akceptacyjne, trzy pozycje w archiwum, ponowne dekretowanie, a w skrajnym przypadku nawet ryzyko podwójnego przygotowania płatności. Po wejściu KSeF nie wystarczy więc „podłączyć API”. Trzeba ustalić, jak organizacja rozpoznaje tożsamość faktury niezależnie od kanału, którym dokument dotarł.
Hash pliku nie odpowiada na pytanie, czy to ta sama faktura
Najprostsza deduplikacja polega na policzeniu skrótu kryptograficznego pliku, np. SHA-256, i sprawdzeniu, czy identyczny hash istnieje już w repozytorium. To dobra reguła, ale tylko do jednego zadania: wykrywania identycznych plików.
Jeżeli pracownik dwa razy zapisze dokładnie ten sam PDF, hash z dużym prawdopodobieństwem zatrzyma drugi import. Jeżeli ten sam XML zostanie ponownie pobrany bez jakiejkolwiek zmiany, mechanizm również zadziała.
Problem pojawia się wtedy, gdy jedna faktura występuje w różnych reprezentacjach.
Załóżmy, że spółka otrzymuje od dostawcy fakturę nr FV/1258/10/2026:
-
z KSeF pobiera XML zgodny z FA(3),
-
dostawca wysyła e-mailem wygenerowaną z niego wizualizację PDF,
-
pracownik zapisuje PDF pod nazwą „faktura_pazdziernik.pdf”.
XML i PDF będą miały zupełnie inne skróty kryptograficzne. Dwie wizualizacje tego samego dokumentu wygenerowane przez różne programy również mogą mieć różne hashe — choćby przez inne metadane PDF, czcionkę, kolejność obiektów czy datę utworzenia pliku.
Dlatego hash powinien być pierwszą, a nie jedyną warstwą deduplikacji.
W praktycznym modelu można przyjąć trzy poziomy:
-
Ten sam hash – niemal na pewno ponowny import identycznego pliku. System nie powinien tworzyć kolejnego dokumentu biznesowego.
-
Inny hash, ale ten sam mocny identyfikator faktury – pliki należy powiązać z istniejącym dokumentem jako kolejne reprezentacje albo załączniki techniczne.
-
Inny hash i brak jednoznacznego identyfikatora – potrzebne jest porównanie danych biznesowych i ewentualnie kolejka do weryfikacji.
Sam NIP sprzedawcy nie wystarczy. Kwota również nie. Firma telekomunikacyjna może wystawić jednemu nabywcy kilkanaście faktur po 123 zł w tym samym miesiącu. Tak samo numer faktury bez kontekstu podatnika jest słabym kluczem: różni wystawcy mogą legalnie używać identycznych numerów, np. „10/2026”.
Przed uzyskaniem numeru KSeF sensowniejszy jest klucz złożony, obejmujący zależnie od procesu między innymi:
-
identyfikator właściwej spółki lub jednostki odbierającej dokument,
-
NIP wystawcy,
-
numer faktury nadany przez wystawcę,
-
datę wystawienia,
-
kwotę należności ogółem,
-
walutę.
Nie należy jednak automatycznie kasować dokumentu tylko dlatego, że wszystkie te dane się zgadzają. Dwa pliki mogą ujawnić rozbieżność wymagającą wyjaśnienia. PDF otrzymany e-mailem może zawierać inną wizualizację niż dane pobrane później z KSeF albo pracownik może omyłkowo podpiąć plik do złej spółki.
Deduplikacja ma scalać pewne duplikaty, a nie usuwać dowody.
Numer KSeF powinien być głównym identyfikatorem dokumentu po jego przyjęciu przez system
Po przyjęciu faktury przez KSeF sytuacja staje się prostsza. System nadaje jej unikalny numer KSeF, jednoznacznie identyfikujący fakturę w Krajowym Systemie e-Faktur.
To istotne rozróżnienie: numer KSeF nie jest numerem faktury nadawanym przez sprzedawcę. Numer handlowy znajduje się w danych faktury, natomiast numer KSeF jest nadawany przez system po przyjęciu dokumentu i nie stanowi elementu samego XML. Jest zwracany m.in. w informacji związanej z przyjęciem dokumentu przez KSeF.
Aktualny numer KSeF ma 35 znaków. W materiałach MF jego budowę pokazano w formacie odpowiadającym schematowi:
NIP sprzedawcy – data przesłania do KSeF – 12-znakowa część techniczna – suma kontrolna.
Przykładowa konstrukcja wygląda jak:9999999999-20261006-FFFFFFFFFFFF-FF.
To właśnie numer KSeF powinien po jego uzyskaniu stać się w systemie finansowym lub DMS najmocniejszym kluczem do wykrywania kolejnych reprezentacji tej samej faktury.
Praktyczny scenariusz wygląda tak:
O godz. 8:00 konektor pobiera z KSeF XML faktury i zakłada dokument w DMS. Rekord otrzymuje numer KSeF i status „nowy”.
O godz. 9:15 na skrzynkę faktury@firma.pl przychodzi PDF od dostawcy. System odczytuje z niego numer faktury, NIP i pozostałe dane albo numer KSeF znajdujący się na prawidłowo przygotowanej wizualizacji. Zamiast zakładać drugi obieg, podpina PDF do rekordu utworzonego z XML.
O godz. 13:00 pracownik przeciąga ten sam PDF do DMS. Hash pozwala stwierdzić, że identyczny plik już znajduje się w repozytorium. Nie powstaje ani nowa faktura, ani drugi załącznik.
W rezultacie użytkownik widzi jeden dokument biznesowy, ale zachowany zostaje pełny materiał:
-
XML pobrany z KSeF,
-
wizualizacja PDF,
-
informacje o źródle każdego pliku,
-
data i godzina importu,
-
historia operacji,
-
dane o tym, który mechanizm uznał plik za duplikat.
To model jednego źródła prawdy, ale nie jednego fizycznego pliku.
Nie należy też przenosić tej zasady na faktury korygujące. Korekta nie jest kolejną kopią faktury pierwotnej. Jest odrębnym dokumentem biznesowym. W FA(3) dla korekty faktury ustrukturyzowanej przewidziano powiązanie z numerem KSeF faktury pierwotnej. System DMS powinien więc tworzyć osobny rekord korekty i łączyć go relacją z dokumentem korygowanym, zamiast scalać oba dokumenty.
Podobnie trzeba uważać przy fakturach zaliczkowych i rozliczających. Związek między dokumentami nie oznacza ich tożsamości.
Kiedy numer KSeF jako klucz ma sens? Zawsze wtedy, gdy dokument został już skutecznie przyjęty do KSeF i numer jest dostępny. Nie powinno się wtedy próbować „zgadywać” duplikatu na podstawie samej kwoty czy numeru handlowego.
Kiedy nie wystarczy? Gdy dokument znajduje się jeszcze w procesie offline, przyszedł wcześniej innym kanałem albo firma musi obsłużyć dokumenty spoza KSeF. Wtedy potrzebna jest warstwa dopasowania biznesowego.
Import musi być idempotentny: jeden dokument, jeden obieg, wiele źródeł
Najbardziej kosztowny błąd nie powstaje przy przechowywaniu dwóch plików. Powstaje wtedy, gdy ten sam dokument uruchamia dwa procesy biznesowe.
Jeżeli faktura o wartości 48 200 zł trafia o 7:30 z KSeF i rozpoczyna akceptację u kierownika działu, to późniejszy e-mail z PDF nie może uruchomić drugiej ścieżki akceptacyjnej. Import powinien być idempotentny: wielokrotne dostarczenie tej samej informacji daje ten sam stan biznesowy zamiast tworzyć kolejne rekordy.
W praktyce przed utworzeniem nowego obiegu system powinien przejść przez kolejność testów:
1. Czy istnieje już ten sam plik?
Porównanie hasha. Jeżeli tak, rejestrujemy próbę importu, ale nie tworzymy niczego drugi raz.
2. Czy istnieje już dokument z tym samym numerem KSeF?
Jeżeli tak, plik lub komunikat zostaje przypisany do istniejącego dokumentu.
3. Jeżeli numeru KSeF nie ma – czy zestaw danych wskazuje z wysokim prawdopodobieństwem na tę samą fakturę?
Porównujemy co najmniej podmiot, wystawcę, numer dokumentu i pozostałe istotne cechy. Sam NIP albo sama kwota nie powinny wystarczyć do automatycznego scalenia.
4. Czy występują rozbieżności?
Jeżeli XML wskazuje 48 200 zł, a PDF 48 020 zł, system nie powinien arbitralnie wybrać „lepszej” wersji ani kasować drugiej. Dokument trafia do kontroli.
To ostatnie jest szczególnie ważne. Automatyczna deduplikacja powinna mieć kategorię „podejrzany duplikat”, a nie tylko odpowiedź „tak/nie”.
Przykład: w DMS znajduje się PDF opisany jako faktura FV/442/2026, wystawca ma NIP 1234567890, kwota wynosi 9 840 zł. Dzień później KSeF dostarcza XML z tym samym numerem i wystawcą, ale należność ogółem wynosi 10 086 zł. Tego przypadku nie wolno bezwarunkowo scalić i uznać jednego pliku za zbędny.
Możliwych przyczyn jest kilka: błędny załącznik w e-mailu, dokument wygenerowany przed ostatecznym wystawieniem, błędne rozpoznanie danych z PDF albo zwykła pomyłka pracownika.
Najbezpieczniejsza reakcja to:
-
zablokować założenie drugiego obiegu płatniczego,
-
zachować oba pliki,
-
oznaczyć konflikt danych,
-
skierować dokument do wskazanej osoby,
-
zapisać późniejszą decyzję użytkownika w historii audytowej.
Dobrze zaprojektowany DMS nie powinien więc pytać wyłącznie: „czy ten plik już mam?”. Lepsze pytanie brzmi: „czy dokument biznesowy, którego reprezentacją jest ten plik, już istnieje?”
To również oznacza, że XML z KSeF powinien zachować status oryginału danych ustrukturyzowanych, natomiast PDF nie powinien automatycznie stać się konkurencyjną „fakturą główną”. PDF bywa bardzo przydatny dla człowieka — łatwiej go przeczytać, zaakceptować czy pokazać przy kontroli wewnętrznej — ale z perspektywy integracji nie może unieważniać danych pobranych z KSeF.
Od 1 lutego 2026 r. obowiązującą strukturą faktury ustrukturyzowanej jest FA(3). Oznacza to, że systemy integracyjne powinny parsować dane właśnie według tej struktury, a nie według starszego FA(2). FA(3) obejmuje między innymi nagłówek, dane podmiotów, szczegółowe dane faktury, stopkę oraz fakultatywną strukturę załącznika. To daje znacznie lepszą podstawę do porównywania danych niż OCR wykonywany na PDF.
OCR nadal ma sens dla dokumentów spoza KSeF albo dla pomocniczego dopasowania pliku przesłanego e-mailem. Nie powinien jednak wygrywać z poprawnie odczytanym XML. OCR potrafi pomylić 8 z 3, separator dziesiętny, numer dokumentu albo NIP. To właśnie takie drobiazgi są później źródłem „prawie identycznych” faktur.
Najrozsądniejsza hierarchia wygląda więc tak: numer KSeF po przyjęciu dokumentu, dane ustrukturyzowane XML, reguły biznesowe, a dopiero później OCR i dane pomocnicze z PDF.
FAQ
Czy PDF otrzymany e-mailem i XML z KSeF są duplikatami?
Na poziomie biznesowym mogą reprezentować tę samą fakturę, ale technicznie są różnymi plikami. Powinny zostać powiązane z jednym rekordem faktury, a nie bezrefleksyjnie usunięte.
Czy wystarczy porównywać hash SHA-256?
Nie. Hash świetnie wykrywa identyczne pliki, lecz XML i PDF tej samej faktury będą miały inne skróty. Inny hash nie oznacza więc innej faktury.
Czy numer faktury nadany przez sprzedawcę jest dobrym kluczem deduplikacyjnym?
Nie samodzielnie. Numer typu 12/2026 może występować u wielu dostawców. Trzeba uwzględnić co najmniej kontekst podatnika lub spółki oraz identyfikację wystawcy.
Czy numer KSeF znajduje się wewnątrz XML faktury?
Nie. Jest nadawany przez KSeF po przyjęciu faktury i nie stanowi elementu pliku XML. Dlatego integracja musi przechowywać go jako metadane powiązane z dokumentem.
Czy fakturę korygującą można scalić z pierwotną jako duplikat?
Nie. Korekta jest odrębnym dokumentem. Powinna dostać własny rekord i własny obieg, a system powinien jednocześnie utrzymywać relację z fakturą pierwotną.
Czy po wykryciu duplikatu można automatycznie usunąć drugi plik?
To zły domyślny model. Lepiej zablokować drugi obieg i zachować plik wraz z informacją o jego źródle. W przypadku kontroli lub rozbieżności przydatny jest pełny ślad audytowy.
Co zrobić, gdy PDF i XML mają inne kwoty?
Nie scalać ich automatycznie jako zgodnego duplikatu. Należy zatrzymać drugi obieg, oznaczyć konflikt i przekazać dokument do sprawdzenia. Źródłem różnicy może być nieaktualny PDF, błędny załącznik, OCR albo niewłaściwe przypisanie dokumentu.
Od której wersji struktury powinny obecnie korzystać integracje z KSeF?
Od 1 lutego 2026 r. dla faktur ustrukturyzowanych obowiązuje FA(3). Integracja oparta nadal wyłącznie na FA(2) wymaga aktualizacji.
Pierwszą rzeczą do sprawdzenia w firmie nie jest więc interfejs DMS ani sposób wyświetlania PDF. Trzeba otworzyć konfigurację importu i odpowiedzieć na jedno pytanie: co dokładnie powoduje utworzenie nowego dokumentu i nowego obiegu?
Jeżeli odpowiedź brzmi „każdy nowy plik”, błąd jest już zlokalizowany. W pierwszej kolejności trzeba rozdzielić pojęcie pliku od dokumentu biznesowego, ustawić numer KSeF jako nadrzędny identyfikator po jego nadaniu, dodać złożone reguły dopasowania dla dokumentów bez numeru KSeF i blokować ponowne uruchamianie obiegu. Dopiero później warto poprawiać OCR, nazewnictwo załączników czy wygląd wizualizacji.
Jedna faktura może mieć kilka reprezentacji. Nie powinna mieć kilku niezależnych żyć w systemie.
