Why KSeF Guard Catches More Than KSeF

We built a conformance test harness that authenticates with the official KSeF test API (api-test.ksef.mf.gov.pl/v2), submits real FA(3) XML invoices, and compares KSeF's verdict with ours. Each invoice was encrypted, signed with XAdES, and submitted through the full API workflow — identical to how production invoices are processed.

256 test fixtures were submitted: PASS fixtures (invoices we consider valid) and FAIL fixtures (invoices that violate specific business rules). The question was simple: does KSeF agree with our verdict?

148 matches — KSeF and KSeF Guard agreed on the verdict. 122 valid invoices were accepted, and 26 invalid invoices were rejected by both.

95 additional catches (KSeF accepted 98 of our FAIL fixtures, including 4 for now-deactivated rules) — KSeF accepted these invoices, but they trigger rules KSeF does not check at submission. Combined with 12 rules verified offline, KSeF Guard flags 107 rules beyond KSeF — 55 legal requirements, 52 best-practice and security.

0 false negatives in conformance v9 — every invoice that KSeF rejected, KSeF Guard also rejected. We miss nothing that the government platform catches.

The data reveals that KSeF is primarily an XSD schema validator. Of the 26 rejections KSeF issued:

• ~96% were XSD errors (error code 450) — missing elements, wrong data types, invalid structure
• 3 semantic checks — future invoice dates, XML processing instructions, and NIP authorization permissions

KSeF does not check:

• VAT arithmetic (net × rate = VAT amount)
• Line total consistency (sum of lines = invoice total)
• Cross-field dependencies (e.g., exempt rate requires legal basis annotation)
• Special invoice type rules (margin, advance, correction, simplified)
• Data integrity (HTML/SQL injection, control characters)

KSeF Guard enforces 128 active validation rules. In conformance v9, we verified that 107 of these rules catch issues that the KSeF API does not check (21 rules are confirmed KSeF-enforced at submission). Of the 107: 55 are legal requirements (GOV_MANDATED, derived from Art. 106e and related regulations) and 52 are best-practice, security, and heuristic rules that improve data quality and reduce audit risk.

• 95 rules verified by API test — exercised with dedicated FAIL fixtures submitted to the official KSeF test API. KSeF accepted all 98 such invoices despite the rule violations (4 from deactivated rules). Of the 107 beyond-KSeF rules, 55 are GOV_MANDATED legal requirements and 52 are best-practice and security.
• 12 rules not testable via single-file API — verified through static analysis, unit tests, and batch testing. These include:

KSeF acceptance is not a compliance certificate. The regulations require invoices to satisfy requirements from Art. 106e of the VAT Act. KSeF is a transmission platform — it primarily validates schema structure and selected semantic checks — it does not cover the full substantive compliance surface.

Tax auditors from the National Revenue Administration (KAS) work from the regulations, not from KSeF's API behavior. An invoice that KSeF accepted but that violates Art. 106e can still be flagged during an audit.

KSeF Guard catches 55 of these legal issues — plus 52 best-practice and security checks — before submission, while the invoice is still on your machine and can be corrected at zero cost.

If you disagree with a specific rule, you can disable it. GOV_MANDATED rules that KSeF does not enforce are now individually disableable via .ksef-guard.yml or the --disable-rule CLI flag. All KSeF-enforced rules (marked with the Gov Enforced badge) cannot be disabled — those would cause actual submission rejection.

The default configuration is strict: all rules are active at their default severity. This gives maximum protection out of the box. You can relax specific rules as needed based on your business requirements.