Dlaczego KSeF Guard wykrywa więcej niż KSeF

Zbudowaliśmy narzędzie testujące, które uwierzytelnia się z oficjalnym API testowym KSeF (api-test.ksef.mf.gov.pl/v2), przesyła prawdziwe faktury FA(3) w formacie XML i porównuje werdykt KSeF z naszym. Każda faktura została zaszyfrowana, podpisana XAdES i przesłana przez pełny przebieg API — identycznie jak faktury produkcyjne.

Przesłano 256 testowych plików: faktury PASS (które uznajemy za poprawne) i faktury FAIL (naruszające konkretne reguły biznesowe). Pytanie było proste: czy KSeF zgadza się z naszym werdyktem?

148 zgodności — KSeF i KSeF Guard zgodziły się co do werdyktu. 122 poprawne faktury zostały zaakceptowane, a 26 nieprawidłowych odrzuconych przez obie strony.

95 dodatkowych wykryć (KSeF zaakceptował 98 naszych plików FAIL, w tym 4 dla dezaktywowanych reguł) — KSeF zaakceptował te faktury, ale naruszają one reguły, których KSeF nie sprawdza przy wysyłce. Łącznie z 12 regułami zweryfikowanymi offline, KSeF Guard wykrywa 107 reguł wykraczających poza KSeF — 55 wymogi prawne, 52 najlepsze praktyki i bezpieczeństwo.

0 fałszywych negatywów w conformance v9 — każda faktura odrzucona przez KSeF została również odrzucona przez KSeF Guard. Nie przeoczamy niczego, co wychwytuje platforma rządowa.

Dane ujawniają, że KSeF jest przede wszystkim walidatorem schematu XSD. Spośród 26 odrzuceń KSeF:

• ~96% to błędy XSD (kod 450) — brakujące elementy, błędne typy danych, nieprawidłowa struktura
• 3 kontrole semantyczne — przyszłe daty faktur, instrukcje przetwarzania XML i uprawnienia autoryzacji NIP

KSeF nie sprawdza:

• Arytmetyki VAT (netto × stawka = kwota VAT)
• Spójności sum pozycji (suma pozycji = suma faktury)
• Zależności międzypolowych (np. stawka zwolniona wymaga adnotacji podstawy prawnej)
• Reguł specjalnych typów faktur (marżowy, zaliczkowy, korygujący, uproszczony)
• Integralności danych (wstrzyknięcia HTML/SQL, znaki sterujące)

KSeF Guard egzekwuje 128 aktywnych reguł walidacji. W conformance v9 potwierdziliśmy, że 107 z tych reguł wykrywa problemy, których API KSeF nie sprawdza (21 reguły są potwierdzone jako egzekwowane przez KSeF przy wysyłce). Spośród 107: 55 to wymogi prawne (GOV_MANDATED, wywiedzione z art. 106e i powiązanych przepisów), a 52 to reguł najlepszych praktyk, bezpieczeństwa i heurystycznych, poprawiających jakość danych i zmniejszających ryzyko kontroli.

• 95 reguł zweryfikowanych testem API — sprawdzone dedykowanymi plikami FAIL przesłanymi do oficjalnego API testowego KSeF. KSeF zaakceptował wszystkie 98 takich faktur mimo naruszeń reguł (4 z dezaktywowanych reguł). Spośród 107 reguł wykraczających poza KSeF, 55 to wymogi prawne GOV_MANDATED, a 52 to najlepsze praktyki i bezpieczeństwo.
• 12 reguł nietestowalnych przez API jednoplikowe — zweryfikowane analizą statyczną, testami jednostkowymi i testami wsadowymi. Obejmują:

Akceptacja przez KSeF nie jest certyfikatem zgodności. Przepisy wymagają, aby faktury spełniały wymogi z art. 106e ustawy o VAT. KSeF jest platformą transmisyjną — przede wszystkim waliduje strukturę schematu i wybrane kontrole semantyczne — nie obejmuje pełnej powierzchni zgodności merytorycznej.

Kontrolerzy podatkowi z Krajowej Administracji Skarbowej (KAS) pracują na podstawie przepisów, a nie zachowania API KSeF. Faktura zaakceptowana przez KSeF, ale naruszająca art. 106e, może być zakwestionowana podczas kontroli.

KSeF Guard wychwytuje 55 z tych wymogów prawnych — plus 52 reguł najlepszych praktyk i bezpieczeństwa — przed wysłaniem, gdy faktura jest jeszcze na Twoim komputerze i może być poprawiona bezkosztowo.

Jeśli nie zgadzasz się z konkretną regułą, możesz ją wyłączyć. Reguły GOV_MANDATED, których KSeF nie egzekwuje, są teraz indywidualnie wyłączalne przez .ksef-guard.yml lub flagę CLI --disable-rule. Wszystkie reguły egzekwowane przez KSeF (oznaczone plakietką KSeF) nie mogą być wyłączone — te spowodowałyby faktyczne odrzucenie przesyłki.

Domyślna konfiguracja jest restrykcyjna: wszystkie reguły są aktywne z domyślnym poziomem poważności. To zapewnia maksymalną ochronę od razu. Możesz zluzować konkretne reguły w zależności od potrzeb biznesowych.