KSeF Private:
jak BezChmury rozwiązuje 30 typowych błędów

KSeF - co to + obowiązki etapowe 2026

KSeF (Krajowy System e-Faktur) to centralny rejestr faktur ustrukturyzowanych prowadzony przez MF. W ramach KSeF każda faktura jest opakowana w schemat XML zgodny z aktualną strukturą logiczną, opatrzona numerem KSeF i przechowywana centralnie. Dla podatnika oznacza to dwie rzeczy: nie wystawia już faktury w PDF/papierze do kontrahenta, tylko przesyła ją do KSeF, a po zaakceptowaniu otrzymuje numer KSeF, który identyfikuje dokument w pełnym łańcuchu rozliczeń.

Charakter prawny obowiązku KSeF reguluje ustawa o VAT z 11.03.2004 r., w brzmieniu po nowelizacji z 5 sierpnia 2025 r. - opublikowanej w Dz.U. 2025 poz. 1203. To właśnie ta ustawa rozciągnęła wdrożenie obligatoryjnego KSeF na trzy fale, zamiast jednej daty wejścia w życie.

Harmonogram etapowy - trzy daty graniczne

Cytat dosłowny - Art. 106ga ust. 1 ustawy o VAT

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

Art. 106ga ust. 1 ustawy z 11.03.2004 r. o podatku od towarów i usług, w brzmieniu obowiązującym od 01.02.2026 r. - źródło: Lex SIP

2026 jako rok „ulgowy" - co to oznacza w praktyce

MF komunikuje 2026 r. jako okres przejściowy - bez pełnego nakładania sankcji za błędy wynikające z procesu wdrożeniowego. Pełne sankcje za niewypełnienie obowiązków KSeF zaczynają obowiązywać dopiero od 01.01.2027 r. Dla biur rachunkowych ważne jest jednak, że „bez sankcji KAS" nie oznacza „bez ryzyka operacyjnego". Każdy błąd w referenceNumber, każda duplikacja, każda zła autoryzacja oznacza zatrzymany proces rozliczeniowy, korektę po stronie ERP i opóźnione płatności od kontrahenta.

Dla typowego biura rachunkowego z 30–80 klientami JDG/MŚP (mediana polskiego rynku według publicznych proxy bazowych dla PKD 69.20.A) rok 2026 to skok wolumenu dokumentów obsługiwanych w KSeF od kilkunastu do kilkuset miesięcznie. To dlatego pierwszy realny problem nie nazywa się „AI", tylko predictability of process: przewidywalność czasu, kosztu i poziomu błędów na fakturę.

Co istotne dla księgowych: od 01.02.2026 wszyscy klienci muszą mieć infrastrukturę do odbioru faktur KSeF, nawet ci, którzy sami sprzedaży nie fakturują (zwolnieni podmiotowo, drobni rolnicy, niektóre fundacje). Anna z biura rachunkowego nie może powiedzieć klientowi „masz czas do kwietnia" - odbiór wszedł obowiązkowo wcześniej niż większość obowiązków wystawiania.

FA(3) - kluczowe pola i pułapki

Wzór FA(3) obowiązuje od 01.02.2026 r. i zastąpił wcześniejszy FA(2). Co istotne dla integracji ERP - FA(3) dotyczy także wszystkich korekt wystawianych po tej dacie, nawet jeśli korygowana jest faktura wystawiona kiedyś na FA(1) lub FA(2). Nie ma więc możliwości „dożywania" starszej schemy: po lutym 2026 produkcja idzie wyłącznie na FA(3), a stare numery referenceNumber służą jedynie do wskazania referencji do oryginału.

Kluczowe pola FA(3) - gdzie biuro rachunkowe traci najwięcej czasu

Z perspektywy implementacyjnej najbardziej bolesne jest pole NrVatUE. Broszura informacyjna MF wprost pisze, że „polskiego NIP nabywcy nie należy tu wpisywać" - polski NIP powinien być w polu NIP. Ale w realnych ERP mapowanie przelatuje przez wspólny obiekt VatNumber, który dla polskich klientów dostaje wartość, a flaga „kraj" się gubi. Efekt: faktura przeszła walidację schemy (XSD się nie wywala - pole istnieje, jest typu string), ale odbita semantycznie przez KSeF z kodem 450.

Pain point case - Marek, błąd NrVatUE

Marek prowadzi biuro rachunkowe w Krakowie, 12 osób, 80 klientów. W marcu 2026 jeden z klientów (sklep z elektroniką) zmigrował z FA(2) na FA(3) i stracił 30 minut na każdej fakturze, którą KSeF odbijał z kodem 450. Biuro przeszło przez wszystko po kolei: czy zła stawka VAT, czy brak P_18A, czy kraj nabywcy się rozjechał. Po dwóch dniach Marek znalazł przyczynę: ERP automatycznie kopiował polski NIP nabywcy do pola NrVatUE, bo kontrahent miał ustawiony „export = false" ale flaga „uesie = true" - domyślnie z czasów FA(2), kiedy to pole było ignorowane.

BezChmury dla Marka znaczy jedno konkretne usprawnienie: walidator semantyczny FA(3) przed wysyłką do KSeF. 30 reguł obejmujących m.in. NrVatUE z polskim NIP, P_18A przy progu 15 000 zł brutto, P_22 bez subfields, niezgodność DataWystawienia / DataSprzedazy. Marek nie czeka na odpowiedź KSeF - diagnoza pojawia się lokalnie, z dokładnym wskazaniem pola i sugerowanym fixem.

<!-- przykład: walidator BezChmury wykrywa polski NIP w NrVatUE -->
<Faktura>
  <Naglowek>
    <KodFormularza wersjaSchemy="1-0E">FA</KodFormularza>
    <WariantFormularza>3</WariantFormularza>
  </Naglowek>
  <Podmiot2>
    <DaneIdentyfikacyjne>
      <NIP>5252344078</NIP>
      <NrVatUE>5252344078</NrVatUE>  <!-- BLAD: polski NIP! -->
    </DaneIdentyfikacyjne>
    <Adres>
      <KodKraju>PL</KodKraju>  <!-- konflikt z NrVatUE -->
    </Adres>
  </Podmiot2>
</Faktura>

[BezChmury validator output]
ERROR semantic.nrvatue_polish_nip
  field: Faktura.Podmiot2.DaneIdentyfikacyjne.NrVatUE
  found: 5252344078 (polski NIP, KodKraju=PL)
  fix:   usun NrVatUE (polski NIP juz w polu NIP)
  fact_id: ksef_fa3_nrvatue_polish_nip_anti
  source: broszura MF FA(3) - pkt 7.3
  confidence: HIGH

BezChmury KSeF Private - architektura

BezChmury KSeF Private to lokalny pipeline 5-warstwowy. Klient instaluje aplikację Electron (DMG dla macOS, EXE dla Windows), aplikacja uruchamia lokalnie polski model BezChmury 11B v3 (open-source, Apache 2.0, 11 mld parametrów, tokenizer APT4 zoptymalizowany pod polski) i 5-warstwowy router pytań. Bez domyślnego call-home produktu i bez automatycznej telemetrii; dokumenty robocze są projektowane do pozostania w środowisku klienta.

„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 SpeakLeash, Hugging Face - huggingface.co/speakleash/Bielik-PL-11B-v3.0-Instruct

Komponenty pipeline'u

• Walidator FA(3) - schemat XSD + 30 reguł biznesowych per pole (np. P_22 wymaga subfields jeśli set; NrVatUE z polskim NIP = warning; DataSprzedazy > DataWystawienia +30 dni = error).
• Error resolver - 30 wpisów: 20 numerycznych kodów błędów + 10 wzorców logicznych (np. „pomóż z MPP", „NIP w NrVatUE zamiast", „bez P_18A"). Latency 0 s - deterministyczna lookup, bez wywołania LLM.
• Critical resolver - 13 hard-coded routes z priorytetem (sankcje 2026/2027, B2C obowiązki, QR code, certyfikat KSeF, JPK_V7M timing, offline24 procedury). Routing zwraca odpowiedź w < 100 ms, zanim BezChmury 11B się rozgrzeje.
• Lokalna SSoT - 218 rekordów ZUS (111 fact + 42 anti-fact + 17 edge case + 15 routing rule + 30 source manifest) + ~130 faktów KSeF + ~95 faktów innych (VAT, JPK, PIT, RODO). Każdy rekord ma source_quote, legal_basis, as_of_date, confidence.
• BezChmury 11B v3 + RAG - fallback dla pytań poza znane wzorce. Q4_K_M kwantyzacja (~6,4 GB peak memory na Apple Silicon), GGUF dla llama.cpp / Ollama, FP8-Dynamic dla NVIDIA z architekturą Hopper / Ada Lovelace.
• Audit log - JSONL append-only, każde pytanie + źródło + timestamp + hash IP + fact_ids użyte. Retencja 5 lat (zgodnie z ustawą o rachunkowości); możliwość rozszerzenia do 50 lat dla klientów medycznych.

Architekturalny kontrast vs cloud SaaS jest jasny: nic nie wychodzi z urządzenia klienta. Po pierwszej instalacji aplikacja może działać bez sieci. Update Pack (kwartalny) jest pobierany jako podpisana paczka SSoT - klient sam decyduje, kiedy zaktualizować.

Kody błędów API KSeF - POPRAWNIE

Kod 410 - błąd uprawnień

Definicja oficjalna MF: niewłaściwy zakres uprawnień użytkownika uwierzytelnionego do KSeF. To NIE jest walidacja merytoryczna treści faktury. Najczęstsze przyczyny: brak roli „Wystawianie faktur" przypisanej do użytkownika, NIP autoryzowany nie ma jeszcze tokena KSeF, zmiana uprawnień zrobiona w panelu MF, ale nie zaaplikowana po stronie klienta API.

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. Sprawdz panel KSeF: api.ksef.mf.gov.pl/web/uprawnienia
2. Czy uzytkownik ma role "Wystawianie" przypisana?
3. Po zmianie uprawnien - odswiez token sesji (TTL 60 min)
4. Lokalna baza polityk uprawnien BezChmury wykryje brak roli przed wyslaniem
fact_id: ksef_410_authorization
confidence: HIGH (zrodlo: Podrecznik KSeF 2.0, cz. II)

Kod 440 - duplikat faktury

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

Podręcznik KSeF 2.0, cz. II - wystawianie i otrzymywanie faktur, MF - źródło

Logika deduplikacji KSeF: system bada tuple (NIP sprzedawcy + P_2 numer faktury + rodzaj faktury), szukając wystąpienia tego samego klucza w bazie KSeF 10 lat wstecz. Najczęstsze realne przyczyny:

• Retry po timeout - klient ERP nie zarejestrował numeru KSeF zwróconego przez API z pierwszego sukcesu, retryje z tym samym P_2.
• Manual restart pipeline - operator zresetował kolejkę po awarii i wysłał ponownie te same XML-e.
• Migracja z FA(2) → FA(3): „wczytanie" historycznych numerów do nowego rejestru.
• Korekta jednej faktury wystawiana dwa razy z tym samym numerem korekty.

BezChmury rozwiązanie: idempotency key liczony lokalnie przed wysyłką jako sha256(NIP + P_2 + rodzaj + hash_XML). Jeśli klucz istnieje w lokalnym cache (bez wywołania KSeF) - zwracamy cached numer KSeF z pierwszego sukcesu, NIE retry z nowym P_2. Cache offline rośnie przyrostowo do 10-letniego okna; pierwszy rok wdrożenia 2026 = ~kilka tysięcy wpisów na średnie biuro, czyli < 50 MB lokalnie.

Kod 450 - błąd weryfikacji semantyki dokumentu

Definicja oficjalna MF: „Błąd weryfikacji semantyki dokumentu faktury" - szeroka klasa błędów semantycznych. To NIE jest dedykowany kod „biała lista" ani „MPP" - biała lista nie jest wbudowana w KSeF (patrz Sekcja 5), a MPP ma własną logikę walidacyjną. Kod 450 obejmuje praktycznie wszystko, co przeszło XSD (schemat się zgadza), ale wewnątrz dokumentu jest niespójność biznesowa.

Top 8 typowych przyczyn 450 widzianych przez BezChmury w probe v0.4:

1. NrVatUE z polskim NIP zamiast zagranicznego VAT UE.
2. DataSprzedazy > DataWystawienia +30 dni (poza dopuszczalnym oknem).
3. Suma kwot brutto ≠ suma podatkowa + netto (zaokrąglenia per pozycja).
4. Niezgodność kraju dostawcy/nabywcy z numerem VAT (PL kontrahent, nieobecny KodKraju=PL).
5. Brak P_18A przy fakturze > 15 000 zł brutto z poz. z załącznika 15.
6. Pole P_22 ustawione, ale brakuje wymaganych subfields (rok produkcji, VIN, przebieg).
7. Korekta bez referencji do oryginalnej faktury (puste NrFaKorygowanej).
8. Zwolnienie podmiotowe VAT bez prawidłowej stawki ZW i podstawy prawnej.

Walidator BezChmury łapie wszystkie 8 przed wysyłką. Średnia oszczędność: 1 retry round-trip + 30 minut diagnozy per faktura odbita. Dla biura z 80 klientami × 5 faktur/dzień z błędem przedwdrożeniowym = ~6 godzin pracy księgowej dziennie zaoszczędzone.

Top 10 błędów merytorycznych - pełna lista BezChmury

Biała lista VAT - osobny krok kontrolny

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

FAQ KSeF 2.0, odpowiedź MF na pytanie o weryfikację Wykazu Podatników VAT - ksef.podatki.gov.pl/jdg-i-msp/

Biała lista VAT (oficjalnie: Wykaz Podatników VAT) to centralna lista podatników VAT aktywnych, prowadzona przez MF. Jej znaczenie prawne wynika z art. 96b ustawy o VAT: przy płatnościach > 15 000 zł brutto na rachunek niewskazany w wykazie podatnik nie ma prawa do zaliczenia takiej kwoty do kosztów uzyskania przychodu (CIT/PIT) ani do prawa do odliczenia VAT bez dodatkowych zastrzeżeń.

Architektura obsługi białej listy w BezChmury

• Plik płaski codziennie od 00:01. MF publikuje codziennie zrzut wykazu jako plik płaski (CSV / JSON), ~50 MB. BezChmury cron'uje pobieranie raz dziennie (lub na żądanie operatora przed wsadową weryfikacją).
• Lokalny cache offline. Po pobraniu plik jest indeksowany lokalnie (NIP → status, data wpisu, rachunki). Kolejne zapytania weryfikacyjne to lookup w pamięci, zero ruchu sieciowego. Dla biura z 200 NIP-ami klientów = mniej niż 1 sekunda na cały batch.
• Walidator dwustopniowy: FA(3) → biała lista → KSeF. Jeśli kontrahent jest „nieaktywny VAT" lub „skreślony", walidator zwraca warning przed wysłaniem do KSeF - pozwalając operatorowi zdecydować świadomie (mimo że KSeF sam tego nie sprawdzi).
• Audit log każdego sprawdzenia. Każdy NIP, status w momencie sprawdzenia, timestamp, data ostatniego pobrania pliku. To krytyczne, bo art. 96b nakłada obowiązek weryfikacji, nie tylko „dobrej wiary" - audytor patrzy w log.

Ten model architektoniczny - gdzie BezChmury jest lokalnym, dziennie odświeżanym lustrem rządowych źródeł danych - jest naturalnym uzupełnieniem KSeF. KSeF reguluje dokumenty; biała lista reguluje kontrahentów; BezChmury przechwytuje oba kroki w jednym pipeline lokalnym.

Audit trail - Art. 22 GDPR + AI Act

Audit log nie jest w BezChmury kosmetycznym dodatkiem ani logiem debugu. Jest to wymóg twardy, wynikający z trzech porządków prawnych równolegle: RODO (art. 22), AI Act (Annex IV - dokumentacja techniczna), i ustawy o rachunkowości (retencja dokumentacji).

Art. 22 RODO - prawo do interwencji człowieka

„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."

Art. 22 ust. 1 i ust. 3 RODO (Rozporządzenie 2016/679) - oficjalny tekst EUR-Lex

Co to znaczy w praktyce dla BezChmury? Każda odpowiedź AI musi być replicable (możliwa do odtworzenia z tych samych danych) i interpretowalna (operator-człowiek może wskazać, na jakim fakcie SSoT była oparta i kto może ją zakwestionować). Bez audit log to niemożliwe.

AI Act Annex IV - dokumentacja techniczna

AI Act (rozporządzenie 2024/1689, opublikowane 12.07.2024, weszło w życie 01.08.2024) dla systemów high-risk wymaga prowadzenia dokumentacji technicznej zgodnej z Annex IV (architektura, zbiór danych, metryki, oceny ryzyka). BezChmury nie jest systemem high-risk per Annex III (asystent dokumentowy nie kwalifikuje się tam automatycznie), ale audit log na poziomie produkcyjnym to dobre praktyki, które: (a) ułatwiają obronę przy potencjalnym sporze z UODO, (b) są standardem rynkowym dla AI w finansach/prawie, (c) wymagane są przez większość polityk wewnętrznych biur i kancelarii.

Format audit log BezChmury - JSONL

{
  "ts": "2026-05-01T10:23:15.347Z",
  "session_id": "anna-biuro-2026-05-01-10-22",
  "ip_hash": "sha256:9c4f2a...",
  "user_email_hash": "sha256:8b1d3f...",
  "question": "Co to jest blad KSeF 440?",
  "question_lang": "pl",
  "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"
}

Format JSONL (jeden JSON na linię, append-only) jest świadomym wyborem zamiast bazy SQL: plik rośnie liniowo, łatwo go archiwizować, łatwo eksportować dla audytora, a immutability gwarantuje samo systemowe write-only flag (chmod 0444 dla plików zamkniętych).

Replay capability

Każde pytanie z audit log można odtworzyć: (a) ssot_snapshot_hash wskazuje konkretną wersję bazy SSoT (immutable), (b) fact_ids wskazuje, które rekordy SSoT zostały użyte, (c) model_version wskazuje konkretny tag modelu BezChmury 11B. Operator z drugą instancją BezChmury może powtórzyć dokładnie tę samą odpowiedź, przeanalizować inny tor decyzji, lub porównać wersje SSoT po Update Pack.

Retencja

Domyślna retencja: 5 lat (zgodnie z ustawą o rachunkowości art. 71-74 oraz Ordynacją podatkową - okres przedawnienia zobowiązań podatkowych 5 lat od końca roku, w którym minął termin płatności). Dla klientów medycznych konfigurowalna do 50 lat (zgodnie z ustawą o prawach pacjenta - dokumentacja medyczna). Po wygaśnięciu retencji plik jest automatycznie kasowany lub archiwizowany na zewnętrzny nośnik (decyzja klienta).

Probe metrics - honest framing

Methodology probe v0.4 (150 par)

• Liczba par: 150 par Q&A tworzonych ręcznie przez zespół BezChmury.
• Distribution kategorii: 40 kwoty / 30 edge case / 20 anti-stale (wykrywanie nieaktualnych liczb) / 10 chitchat-mixed (smalltalk + KSeF question) / 50 critical (kody błędów + sankcje + B2C).
• Format pary: question + expected_answer + acceptable_variants (lista 1-5 alternatywnych poprawnych odpowiedzi).
• Scoring: auditor ręczny + auto scoring (semantic match z keyword boost dla deterministycznych kwot/kodów).
• Confidence distribution: 80% par „kwoty/dates/error codes" (HIGH confidence - odpowiedź deterministyczna), 20% „edge cases" (MEDIUM confidence - wymaga interpretacji).

Wyniki - ostatnie 3 wersje resolverów

Czego „147/150" NIE oznacza

• Nie jest to benchmark akademicki typu MT-Bench PL czy Polish LLM Eval. BezChmury 11B v3 ma takie benchmarki publicznie (HF leaderboards), ale to inna skala problemu - uniwersalna jakość modelu, nie celne odpowiadanie na pytania KSeF.
• Nie jest to oficjalny test MF. Państwowy benchmark dla AI w KSeF nie istnieje. Aktualnie MF nie certyfikuje narzędzi AI pod kątem zgodności z systemem.
• Nie jest to test reprezentatywny dla wszystkich klientów. Probe 150 par to mała próbka vs realne życie biura rachunkowego z 1000+ pytaniami dziennie. Realne deploymenty obserwujemy w trybie production telemetry-free (operator opcjonalnie przesyła feedback negatywny - bez automatycznego call-home).

Honest framing w komunikacji

Polityka produktowa BezChmury jest celowo wąska: ograniczanie ryzyka halucynacji przez SSoT, cytaty i metadane źródłowe - nie „100% accuracy open Q&A". Goodhart's law mówi nam, że gdy przekraczasz 95% na celowanym zakresie, kolejne punkty procentowe oznaczają overfit do probe, nie realnej jakości. Dlatego trzymamy granicę „147/150 PASS na probe" zamiast obiecywać „100%".

Każdy klient enterprise dostaje też dostęp do raportu probe per release (kwartalnie, razem z Update Pack). Pełna lista 150 par + odpowiedzi + diff vs poprzedni release - żeby IT director mógł zobaczyć, gdzie konkretnie BezChmury się poprawia, a gdzie regresuje.

Roadmap Q2-Q4 2026

• Q2 2026 - FA(3) v2 monitoring. Jeśli MF wypuszcza minor schema update do FA(3) (historycznie zdarzało się dla FA(2) - kilka korekt rozwojowych), BezChmury wydaje patch SSoT w ciągu 14 dni roboczych od publikacji broszury MF. Bez ruszania pipeline - tylko warstwa fact_ids.
• Q2 2026 - Critical resolver expansion. Z 13 routes do 20-25, focus na sankcje za niewystawienie, ROZ-zwroty, korekty multi-line (więcej niż jedna pozycja korygowana w tym samym numerze korekty), JPK_V7M timing edge cases.
• Q3 2026 - BezChmury Mobile (Bielik-PL-Minitron-7B-v3.0). Wariant 7,35B parametrów - kompresja BezChmury 11B przez Minitron technique (33,4% redukcja). Dla starszych laptopów (16 GB RAM bez problemu, przy Q4_K_M wymagane ~5 GB peak memory). Ten sam pipeline, mniejszy fallback model.
• Q3 2026 - Error resolver expansion z 30 do 50 entries. Focus na JPK_V7M edge cases (różnice JPK_V7M vs JPK_V7K, kwartały vs miesiące), VAT zero-rate vs zwolnienie (różne skutki dla prawa do odliczenia), kasy online edge cases.
• Q4 2026 - BezChmury Pro 11B v3.1. Aktualizacja modelu BezChmury 11B, jeśli SpeakLeash wypuści następną wersję (release cadence v1 → v2 → v3 wskazuje ~12-miesięczne okno; ETA na podstawie speakleash GitHub roadmap). Ten sam SSoT, nowsze weights, lepsze understanding kontekstu polskiego.