KSeF Private:
how BezChmury solves 30 common errors

KSeF - what it is + phased rollout in 2026

KSeF (Krajowy System e-Faktur, Poland's National e-Invoice System) becomes mandatory in 2026 for all Polish businesses. It replaces paper invoices and existing electronic invoice formats with a single XML schema (FA(3)) submitted to a centralised government API operated by the MF. For each taxpayer this means two practical changes: invoices are no longer issued as PDFs or paper to the buyer, but submitted to KSeF, which returns an official KSeF reference number once accepted. That reference number then identifies the document throughout the entire downstream settlement chain.

The legal basis for the KSeF obligation is the Polish VAT Act of 11 March 2004, as amended by the Act of 5 August 2025 - published in the Polish Journal of Laws (Dz.U. 2025 item 1203). That amendment is what spread the mandatory rollout across three waves rather than a single date.

Phased rollout - three key dates

Verbatim quote - Article 106ga of the VAT Act

„Podatnicy są obowiązani wystawiać faktury ustrukturyzowane przy użyciu Krajowego Systemu e-Faktur."

Article 106ga(1) of the Polish VAT Act of 11 March 2004, in the wording in force from 1 February 2026 - source: SIP LEX

English translation: "Taxpayers shall be obliged to issue structured invoices using the National e-Invoice System (KSeF)." (translation by BezChmury for editorial context; the Polish text is the legally binding version.)

2026 as a "grace year" - what this means in practice

The MF communicates 2026 as a transitional period - the full sanctions regime for implementation errors is not applied during this year. Sanctions for non-compliance with the KSeF obligation only take full effect from 1 January 2027. For accounting firms, however, "no KAS sanctions" does not mean "no operational risk". Every error in a reference number, every duplicate, every authorisation problem stops the settlement process, forces a correction at the ERP layer, and delays payment from the buyer.

For a typical Polish accounting firm with 30-80 SME and sole-trader (JDG) clients (the median of the local market based on public proxies for PKD 69.20.A - accounting activities), 2026 represents a step-change in document volume processed through KSeF - from a handful per month to several hundred. That is why the first real problem is not "AI" - it is predictability of process: predictability of time, cost and error rate per invoice.

A point critical for accountants: from 1 February 2026 every client must have the infrastructure to receive KSeF invoices, even those who do not issue invoices themselves (taxpayers exempted on subject grounds, smallholder farmers, some foundations). Anna at the accounting firm cannot tell a client "you have until April" - the receipt obligation came in earlier than most issuance obligations.

FA(3) - key fields and pitfalls

The FA(3) schema applies from 1 February 2026 and replaced the earlier FA(2). Crucially for ERP integration, FA(3) also covers all corrections issued after that date, even when the underlying invoice was originally issued on FA(1) or FA(2). There is therefore no way to "keep alive" the older schema: from February 2026 production runs exclusively on FA(3), and historical referenceNumber values only serve as a pointer back to the original document.

Key FA(3) fields - where accounting firms lose the most time

From an implementation perspective the most painful field is NrVatUE. The MF information brochure explicitly states that "the Polish buyer NIP must not be entered here" - a Polish NIP belongs in the NIP field. But in real ERPs the mapping flows through a shared VatNumber object, which for Polish customers receives a value while the "country" flag is lost on the way. The result: the invoice passes XSD validation (the schema is happy - the field exists and is a string), but is rejected semantically by KSeF with code 450.

Pain-point case - Marek and the NrVatUE error

Marek runs a 12-person accounting firm in Kraków with 80 clients. In March 2026 one of his clients (an electronics retailer) migrated from FA(2) to FA(3) and lost 30 minutes on every invoice that KSeF bounced back with code 450. The team went through everything: a wrong VAT rate, a missing P_18A, a buyer-country mismatch. Two days later Marek found the cause: the ERP was automatically copying the Polish buyer NIP into the NrVatUE field because the contractor record had "export = false" but "uesie = true" - a default left over from FA(2), when this field was simply ignored.

For Marek, BezChmury delivers one specific improvement: the FA(3) semantic validator before submission to KSeF. Thirty rules covering, among others, NrVatUE containing a Polish NIP, a missing P_18A above the PLN 15,000 gross threshold, P_22 without subfields, and DataWystawienia/DataSprzedazy mismatches. Marek does not wait for the KSeF response - diagnosis appears locally, with the exact field and a suggested fix.

<!-- example: BezChmury validator detects a Polish NIP in NrVatUE -->
<Faktura>
  <Naglowek>
    <KodFormularza wersjaSchemy="1-0E">FA</KodFormularza>
    <WariantFormularza>3</WariantFormularza>
  </Naglowek>
  <Podmiot2>
    <DaneIdentyfikacyjne>
      <NIP>5252344078</NIP>
      <NrVatUE>5252344078</NrVatUE>  <!-- ERROR: Polish NIP -->
    </DaneIdentyfikacyjne>
    <Adres>
      <KodKraju>PL</KodKraju>  <!-- conflicts with NrVatUE -->
    </Adres>
  </Podmiot2>
</Faktura>

[BezChmury validator output]
ERROR semantic.nrvatue_polish_nip
  field: Faktura.Podmiot2.DaneIdentyfikacyjne.NrVatUE
  found: 5252344078 (Polish NIP, KodKraju=PL)
  fix:   remove NrVatUE (the Polish NIP already lives in NIP)
  fact_id: ksef_fa3_nrvatue_polish_nip_anti
  source: MF FA(3) brochure - section 7.3
  confidence: HIGH

BezChmury KSeF Private - architecture

BezChmury KSeF Private is a five-layer local pipeline. The customer installs an Electron application (DMG for macOS, EXE for Windows). The application then runs the Polish open-source model BezChmury 11B v3 (Apache 2.0, 11 billion parameters, APT4 tokenizer optimised for Polish) and a five-layer question router. There is no product call-home by default and no automatic telemetry; working documents are designed to stay in the customer environment.

„Bielik-PL-11B-v3.0-Instruct is a generative text model featuring 11 billion parameters [...] after replacing its tokenizer to the APT4 tokenizer optimized specifically for the Polish language."

Model card by SpeakLeash, on Hugging Face - huggingface.co/speakleash/Bielik-PL-11B-v3.0-Instruct

Pipeline components

• FA(3) validator - the XSD schema plus 30 business rules per field (for example, P_22 requires subfields if set; NrVatUE containing a Polish NIP raises a warning; sale date more than 30 days past issue date is an error).
• Error resolver - 30 entries: 20 numeric error codes plus 10 logical patterns ("help with split payment", "NIP in NrVatUE instead", "missing P_18A"). Latency 0 seconds - deterministic lookup with no LLM call.
• Critical resolver - 13 hard-coded routes with priority ordering (2026/2027 sanctions, B2C obligations, QR code, KSeF certificate, JPK_V7M timing, offline24 procedures). The router returns an answer in under 100 ms, before Bielik even finishes warming up.
• Local SSoT - 218 ZUS records (111 facts + 42 anti-facts + 17 edge cases + 15 routing rules + 30 source manifest entries) plus ~130 KSeF facts and ~95 other facts (VAT, JPK, PIT, GDPR). Every record carries a source_quote, legal_basis, as_of_date and confidence rating.
• BezChmury 11B v3 + RAG - fallback for questions outside known patterns. Q4_K_M quantisation (~6.4 GB peak memory on Apple Silicon), GGUF for llama.cpp / Ollama, FP8-Dynamic for NVIDIA Hopper / Ada Lovelace.
• Audit log - JSONL append-only. Every question is recorded with the source, timestamp, IP hash, and the fact_ids used. Retention is 5 years (per the Polish Accounting Act); medical clients can extend this to 50 years.

The architectural contrast against cloud SaaS is sharp: nothing leaves the customer's device. After the first installation the application can run without a network. The (quarterly) Update Pack arrives as a signed SSoT bundle - the customer decides when to apply the update.

KSeF API error codes - done correctly

Code 410 - authorisation scope error

Official MF definition: incorrect authorisation scope for the user authenticated to KSeF. This is NOT a substantive validation of invoice content. The most common causes: the user does not have the "Invoice Issuing" role, the authorised NIP does not yet have a KSeF token, or a permission change made in the MF panel has not been propagated to the API client.

HTTP/1.1 410 Gone
Content-Type: application/json

{
  "status": 410,
  "code": "ERR_AUTHORIZATION",
  "message": "Niewlasciwy zakres uprawnien dla operacji",
  "details": {
    "user_nip": "5252344078",
    "operation": "send-invoice",
    "required_roles": ["Wystawianie", "Dostep"]
  }
}

[BezChmury fix suggestion]
1. Check the KSeF panel: api.ksef.mf.gov.pl/web/uprawnienia
2. Does the user have the "Wystawianie" (Issuing) role assigned?
3. After a permission change - refresh the session token (TTL 60 min)
4. The local BezChmury permissions DB will detect a missing role before submission
fact_id: ksef_410_authorization
confidence: HIGH (source: KSeF 2.0 Handbook, Part II)

Code 440 - duplicate invoice

„W tym przypadku jest to kod błędu 440 'Duplikat faktury'."

KSeF 2.0 Handbook, Part II - issuing and receiving invoices, Polish Ministry of Finance - source

English translation: "In this case it is error code 440 'Duplicate invoice'."

KSeF deduplication logic: the system examines the tuple (seller NIP + P_2 invoice number + invoice type), searching for an existing match in the KSeF database 10 years back. The most common real-world causes:

• Retry after timeout - the ERP client did not record the KSeF number returned by the API on the first success and retries with the same P_2.
• Manual pipeline restart - an operator reset the queue after a failure and resubmitted the same XMLs.
• Migration from FA(2) → FA(3): "loading" historical numbers into the new register.
• A correction to a single invoice issued twice with the same correction number.

BezChmury solution: an idempotency key computed locally before submission as sha256(NIP + P_2 + type + hash_XML). If the key already exists in the local cache (no KSeF call needed) we return the cached KSeF number from the first success rather than retry with a new P_2. The offline cache grows incrementally up to a 10-year window; the first year of rollout in 2026 is roughly a few thousand entries for an average accounting firm - under 50 MB on disk.

Code 450 - semantic verification error of the invoice document

Official MF definition: "Semantic verification error of the invoice document" - a broad class of business-logic errors. This is NOT a dedicated "white list" or "split payment" code - the white list is not built into KSeF (see Section 5), and split payment has its own validation logic. Code 450 covers essentially anything that passed XSD (the schema is fine) but contains a business inconsistency inside the document.

The top eight typical causes of code 450 observed by BezChmury in probe v0.4:

1. NrVatUE containing a Polish NIP instead of a foreign EU VAT number.
2. Sale date more than 30 days past the issue date (outside the permitted window).
3. Gross totals do not equal tax + net (per-line rounding).
4. Country mismatch between supplier/buyer and VAT number (Polish counterparty without KodKraju=PL).
5. Missing P_18A on an invoice with gross > PLN 15,000 containing items from Annex 15.
6. Field P_22 is set but the required subfields are missing (production year, VIN, mileage).
7. Correction without a reference to the original invoice (empty NrFaKorygowanej).
8. Subjective VAT exemption without the correct ZW rate and legal basis.

The BezChmury validator catches all eight before submission. Average saving: one retry round-trip plus 30 minutes of diagnosis per rejected invoice. For a firm with 80 clients and five rejected invoices a day during the early rollout, that adds up to roughly six hours of accounting time per day saved.

Top 10 substantive errors - full BezChmury list

VAT White List - a separate validation step

„Aktualnie nie jest planowane wprowadzenie takiej funkcjonalności."

KSeF 2.0 FAQ, MF answer to a question about checking the VAT White List inside KSeF - ksef.podatki.gov.pl/jdg-i-msp/

English translation: "Currently no plans to introduce such functionality."

The VAT White List (officially: the Register of VAT Taxpayers) is a central register of active Polish VAT taxpayers maintained by the MF. Its legal weight comes from Article 96b of the Polish VAT Act: for payments above PLN 15,000 gross to a bank account not listed in the register, the taxpayer loses the right to deduct that expense as a tax-deductible cost (CIT/PIT) and the right to deduct VAT without additional safeguards.

How BezChmury handles the white list

• Daily flat file from 00:01. The MF publishes a daily snapshot of the register as a flat file (CSV / JSON), about 50 MB. BezChmury cron-fetches it once a day (or on demand from the operator before a batch verification).
• Local offline cache. Once downloaded, the file is indexed locally (NIP → status, registration date, bank accounts). Subsequent verification queries are in-memory lookups with zero network traffic. For a firm with 200 client NIPs the whole batch takes under a second.
• Two-stage validator: FA(3) → white list → KSeF. If a counterparty is "VAT inactive" or "struck off", the validator returns a warning before submission to KSeF - letting the operator make a conscious decision (even though KSeF itself will not check this).
• Audit log of every check. Every NIP, the status at the moment of checking, the timestamp, and the date of the last flat-file download. This is critical because Article 96b imposes a verification obligation, not just a "good faith" test - auditors look at the log.

This architectural model - where BezChmury acts as a local, daily-refreshed mirror of government data sources - is a natural complement to KSeF. KSeF governs documents; the white list governs counterparties; BezChmury captures both steps in a single local pipeline.

Audit trail - GDPR Article 22 + EU AI Act

The audit log is not a cosmetic add-on or a debug log in BezChmury. It is a hard requirement coming from three legal regimes in parallel: the GDPR (Article 22), the EU AI Act (Annex IV - technical documentation), and the Polish Accounting Act (documentation retention).

GDPR Article 22 - the right to human intervention

„The data subject shall have the right not to be subject to a decision based solely on automated processing, including profiling, which produces legal effects concerning him or her or similarly significantly affects him or her. [...] the data controller shall implement suitable measures to safeguard the data subject's rights and freedoms and legitimate interests, at least the right to obtain human intervention on the part of the controller, to express his or her point of view and to contest the decision."

Article 22(1) and (3) GDPR (Regulation 2016/679) - official EUR-Lex text

What does this mean in practice for BezChmury? Every AI answer must be replicable (reproducible from the same inputs) and interpretable (a human operator can point to the SSoT fact it was based on and identify who can challenge it). Without an audit log this is impossible.

EU AI Act Annex IV - technical documentation

The EU AI Act (Regulation 2024/1689, published 12 July 2024, in force from 1 August 2024) requires high-risk systems to maintain technical documentation aligned with Annex IV (architecture, training data, metrics, risk assessment). BezChmury is not a high-risk system per Annex III (a document assistant does not automatically qualify), but a production-grade audit log is good practice and: (a) makes defence easier in any potential dispute with the Polish DPA (UODO), (b) is the market standard for AI in finance and law, and (c) is required by most internal policies of accounting firms and law offices.

BezChmury audit log format - JSONL

{
  "ts": "2026-05-01T10:23:15.347Z",
  "session_id": "anna-firm-2026-05-01-10-22",
  "ip_hash": "sha256:9c4f2a...",
  "user_email_hash": "sha256:8b1d3f...",
  "question": "What does KSeF error code 440 mean?",
  "question_lang": "en",
  "router_decision": "critical_resolver",
  "fact_ids": ["ksef_440_dedup", "fa3_p2_field"],
  "answer_hash": "sha256:5a7e1c...",
  "answer_word_count": 87,
  "model_version": "Bielik-PL-11B-v3.0-Instruct + ssot v34",
  "ssot_snapshot_hash": "sha256:e2a8b4...",
  "latency_ms": 124,
  "confidence": "HIGH"
}

The JSONL format (one JSON object per line, append-only) is a deliberate choice over a SQL database: the file grows linearly, archives easily, exports cleanly for an auditor, and immutability is enforced by the operating system itself (chmod 0444 on closed files).

Replay capability

Every question in the audit log can be replayed: (a) ssot_snapshot_hash identifies the exact SSoT version (immutable), (b) fact_ids identifies the SSoT records that were used, (c) model_version identifies the exact BezChmury 11B tag. An operator with a second BezChmury instance can reproduce the same answer exactly, analyse a different decision branch, or compare SSoT versions after an Update Pack.

Retention

Default retention: 5 years (per Articles 71-74 of the Polish Accounting Act and the Tax Ordinance - the limitation period for tax obligations is 5 years from the end of the year in which the payment was due). For medical clients this is configurable up to 50 years (per the Act on Patients' Rights - medical documentation). When retention expires the file is automatically deleted or archived to external media (the customer decides).

Probe metrics - honest framing

Probe v0.4 methodology (150 cases)

• Number of cases: 150 Q&A pairs hand-written by the BezChmury team.
• Category distribution: 40 amounts / 30 edge cases / 20 anti-stale (detecting outdated numbers) / 10 chitchat-mixed (smalltalk + KSeF question) / 50 critical (error codes + sanctions + B2C).
• Pair format: question + expected_answer + acceptable_variants (a list of 1-5 alternative correct answers).
• Scoring: manual auditor plus auto-scoring (semantic match with a keyword boost for deterministic amounts and codes).
• Confidence distribution: 80% of pairs are "amounts/dates/error codes" (HIGH confidence - deterministic answer), 20% are "edge cases" (MEDIUM confidence - require interpretation).

Results - last three resolver versions

What "147/150" does NOT mean

• It is not an academic benchmark like MT-Bench PL or the Polish LLM Eval. BezChmury 11B v3 has those benchmarks publicly (HF leaderboards), but they are a different scale of problem - generic model quality, not pinpoint answers to KSeF questions.
• It is not an official MF test. No state benchmark for AI in KSeF exists. As of today, the MF does not certify AI tools against the system.
• It is not representative of every customer. 150 cases is a small sample compared with the real life of an accounting firm with 1,000+ questions a day. Real deployments are observed in telemetry-free production (the operator can optionally submit negative feedback - there is no automatic product call-home).

Honest framing in our communications

BezChmury's product policy is deliberately narrow: reducing hallucination risk through SSoT, citations and source metadata - not "100% accuracy on open Q&A". Goodhart's law tells us that once you exceed 95% on a targeted scope, additional points typically signal overfit to the probe rather than real-world quality. That is why we hold the line at "147/150 PASS on probe" instead of promising "100%".

Every enterprise customer also receives the per-release probe report (quarterly, alongside the Update Pack). The full 150 cases plus answers plus diff against the previous release - so the IT director can see exactly where BezChmury improves and where it regresses.

Roadmap Q2-Q4 2026

• Q2 2026 - FA(3) v2 monitoring. If the MF ships a minor schema update to FA(3) (which historically happened with FA(2) - a few iterative corrections), BezChmury releases an SSoT patch within 14 working days of the MF brochure publication. No pipeline changes - only the fact_ids layer.
• Q2 2026 - Critical resolver expansion. From 13 routes to 20-25, focusing on non-issuance sanctions, ROZ-returns, multi-line corrections (more than one item corrected within the same correction number), and JPK_V7M timing edge cases.
• Q3 2026 - BezChmury Mobile (Bielik-PL-Minitron-7B-v3.0). A 7.35B-parameter variant - BezChmury 11B compressed via the Minitron technique (33.4% reduction). Aimed at older laptops (16 GB RAM is fine; Q4_K_M needs ~5 GB peak memory). Same pipeline, smaller fallback model.
• Q3 2026 - Error resolver expansion from 30 to 50 entries. Focus on JPK_V7M edge cases (JPK_V7M vs JPK_V7K differences, quarters vs months), VAT zero-rate vs exemption (different consequences for input VAT deduction), online cash register edge cases.
• Q4 2026 - BezChmury Pro 11B v3.1. A model update if SpeakLeash ships the next BezChmury 11B release (the v1 → v2 → v3 cadence suggests a 12-month window; ETA based on the SpeakLeash GitHub roadmap). Same SSoT, newer weights, better understanding of Polish context.