Jak budujemy testowe dokumenty KSeF
Wersja 1.0 z 27 października 2026 r., aktualizacja 17 listopada 2026 r. Wróć do generatora · Regulamin
Zasada działania
- Wszystko w przeglądarce. Losowanie, budowa XML, walidacja sum, pakowanie ZIP, kody QR i spisy działają w JavaScript na Twoim urządzeniu. Serwer nie otrzymuje żadnego dokumentu, numeru ani NIP-u.
- Ziarno. Losowanie zaczyna się od liczby (ziarna) i jest deterministyczne (generator mulberry32, wspólny z generatorem danych testowych): te same ustawienia i to samo ziarno dają tę samą paczkę. Słowo wpisane jako ziarno zamieniamy na liczbę funkcją skrótu FNV-1a.
- Jeden model, wiele formatów. Faktura jest najpierw obiektem z kwotami w groszach; dopiero z niego powstaje XML FA(3), komunikat ECOD, plik importu enova365 i wiersz spisu. Dzięki temu każdy format pokazuje te same kwoty.
- Fikcyjność. Nazwy firm, adresy, towary i osoby pochodzą ze słowników generatora danych testowych (nazwy wymyślone, miejscowości prawdziwe, numery domów losowe). NIP-y i rachunki mają poprawne sumy kontrolne, ale są losowe i nie pochodzą z rejestrów, więc mogą przypadkiem należeć do istniejących firm. Numer KSeF ma poprawny format i sumę kontrolną, lecz nie został nadany przez KSeF.
Kwoty i podsumowanie według stawek
- Wartość wiersza liczymy w groszach: ilość × cena × (1 − rabat), zaokrąglone na wierszu; VAT od netto wiersza (albo netto z brutto, gdy faktura ma ceny brutto). Sumy P_13_x i P_14_x to sumy wierszy z daną stawką, P_15 to suma brutto – dlatego zgadzają się co do grosza, tak jak sprawdzają to programy księgowe.
- Dla waluty obcej kurs (4,20–4,45, cztery miejsca) przelicza VAT na złote do pól P_14_xW; wiersze mają P_11Vat i kurs w KursWaluty. Pole KursWalutyZ zapisujemy tylko na fakturze zaliczkowej i jej korekcie – według schematu dotyczy faktur z art. 106b ust. 1 pkt 4 ustawy o VAT.
- Nabywca z innego kraju UE: towary mają stawkę 0% WDT (P_13_6_2), a usługi „np II” (P_13_9) – miejsce świadczenia jest u nabywcy (art. 28b ustawy o VAT), więc to usługi z art. 100 ust. 1 pkt 4. Taka faktura ma adnotację „odwrotne obciążenie” (P_18 = 1).
- Stawki i pola podsumowania: 23% → P_12 „23”, P_13_1 / P_14_1; 8% → P_12 „8”, P_13_2 / P_14_2; 5% → P_12 „5”, P_13_3 / P_14_3; 0% (kraj) → P_12 „0 KR”, P_13_6_1; 0% WDT → P_12 „0 WDT”, P_13_6_2; 0% eksport → P_12 „0 EX”, P_13_6_3; zwolnione → P_12 „zw”, P_13_7; nie podlega → P_12 „np I”, P_13_8; nie podlega (art. 100 ust. 1 pkt 4) → P_12 „np II”, P_13_9; odwrotne obciążenie → P_12 „oo”, P_13_10.
- Mechanizm podzielonej płatności (P_18A) zaznaczamy automatycznie, gdy brutto faktury w PLN wynosi co najmniej 15 000 zł i jest stawka 23% – uproszczenie wobec załącznika nr 15 do ustawy o VAT.
Rodzaje faktur i scenariusze
| Rodzaj | Jak budujemy |
|---|---|
| Faktura podstawowa | 1–12 wierszy z towarami i usługami (co ósmy wiersz usługa zwolniona albo niepodlegająca), rabaty 2–15% na co czwartym wierszu, data dostawy równa dacie wystawienia lub do 6 dni wcześniej, termin 7–60 dni albo zapłata przy wystawieniu, rachunek NRB z sumą mod 97, DodatkowyOpis z numerem zamówienia, warunki transakcji (zamówienie, WZ), opcjonalnie podmiot trzeci (odbiorca z identyfikatorem wewnętrznym, faktor z własnym rachunkiem, dokonujący płatności) i załącznik z tabelą. |
| Faktura korygująca | Zawsze po fakturze pierwotnej tego samego kontrahenta, z jej numerem, datą i numerem KSeF. Scenariusze: ilość (wiersz „stan przed” i wiersz z mniejszą ilością), cena (rabat 5–20%), zwrot (wszystkie wiersze jako „stan przed”), stawka (23% → 8%), dane nabywcy (bez wierszy, P_15 = 0). TypKorekty 2, a przy zmianie nabywcy i stawki 1. |
| Faktura zaliczkowa / Faktura rozliczeniowa | Zamówienie 1–3 usług (wdrożenie, licencje, remont, konferencja) i zaliczka 20–50% rozbita na stawki zamówienia; blok Zamowienie z wartością brutto. Rozliczenie ma wiersze zamówienia i ujemne wiersze rozliczające zaliczkę oraz odwołanie FakturaZaliczkowa; suma brutto zaliczki i rozliczenia równa się wartości zamówienia. |
| Faktura uproszczona | 1–2 wiersze po 5–180 zł, razem do 450 zł brutto; nabywca tylko z NIP; płatność gotówką albo kartą przy wystawieniu. |
| Korekta faktury zaliczkowej / Korekta faktury rozliczeniowej | Stan przed i po dla wierszy zaliczki (70–90% pierwotnej kwoty) albo rozliczenia (rabat 10%); zamówienie i odwołania przepisane z dokumentu pierwotnego. |
W paczce dokumenty dostają rosnące daty z zadanego zakresu i ciągłą numerację w seriach (FV, FK, FZ, FR, FU, FKZ, FKR); korekta trafia zawsze po pierwotnej, a rozliczenie 1–12 dokumentów po zaliczce. Udziały scenariuszy to prawdopodobieństwa losowania – przy małych paczkach liczby mogą się różnić od zadanych procentów.
Schemat FA(3) i walidacja
- XML budujemy w kolejności elementów schematu (Naglowek, Podmiot1, Podmiot2, Podmiot3, Fa: KodWaluty, P_1, P_1M, P_2, WZ, P_6, P_13/P_14, P_15, KursWalutyZ, Adnotacje, RodzajFaktury, dane korekty, DodatkowyOpis, FakturaZaliczkowa, FaWiersz, Platnosc, WarunkiTransakcji, Zamowienie; Stopka, Zalacznik). Teksty skracamy do limitów schematu (256 i 512 znaków), znaki specjalne kodujemy. Datę dostawy (P_6) zapisujemy tylko wtedy, gdy różni się od daty wystawienia (P_1) – tak opisuje to pole schemat.
- Każda wersja generatora przechodzi testy: wszystkie rodzaje faktur i 100 dokumentów przykładowej paczki są walidowane narzędziem xmllint na schemacie pobranym z CRD (schemat.xsd i importowane słowniki typów, stan z 26 października 2026 r.). W przeglądarce nie uruchamiamy walidatora XSD – gwarancją są testy, a sumy i sumy kontrolne liczymy w locie.
- Adnotacje wypełniamy wartościami „nie dotyczy” (P_16, P_17, P_18, P_23 = 2; P_19N, P_22N, P_PMarzyN = 1), poza P_18A dla MPP, P_18 = 1 przy stawkach „oo” i „np II” oraz P_19 przy stawce „zw” (podstawa zwolnienia: art. 43 ust. 1 ustawy o VAT).
Numer KSeF i kod QR
- Numer ma 35 znaków w formacie opisanym w dokumentacji API KSeF 2.0 Ministerstwa Finansów (CIRFMF/ksef-api, „Numer KSeF – struktura i walidacja”) i zgodnym ze wzorcem TNumerKSeF w schemacie: NIP sprzedawcy, data (RRRRMMDD), 12 znaków szesnastkowych i dwuznakowa suma kontrolna. Sumę liczymy tak jak KSeF: CRC-8 z wielomianem 0x07 i wartością początkową 0x00 z 32 znaków przed sumą, zapis szesnastkowy wielkimi literami (przykład z dokumentacji: 5265877635-20250826-0100001AF629-AF). Numer nigdy nie istnieje w KSeF: przy każdym numerze, w spisie i w README jest nota „dokument testowy – numer KSeF fikcyjny, nie weryfikuj w KSeF”.
- Kod QR (KOD I) liczymy tak jak podgląd faktury Enology: link https://qr.ksef.mf.gov.pl/invoice/NIP/DD-MM-RRRR/skrót, gdzie skrót to SHA-256 pliku w Base64URL (dokumentacja CIRFMF/ksef-api). Weryfikacja na stronie ministerstwa zwróci „brak”, bo faktury nie ma w KSeF.
Pliki celowo błędne
| Błąd | Co robimy | Wykryje |
|---|---|---|
| Brak numeru faktury (P_2) | Element P_2 jest obowiązkowy w schemacie FA(3). Plik nie przejdzie walidacji XSD – KSeF odrzuci go od razu, program księgowy zgłosi błąd struktury. | XSD |
| Niedozwolony kod waluty | KodWaluty ma wartość „ZL” spoza listy ISO 4217 w schemacie. Błąd XSD – plik odrzucony przy walidacji struktury. | XSD |
| Znak sterujący w nazwie towaru | W nazwie pozycji (P_7) jest znak sterujący (U+0001), którego XML 1.0 nie dopuszcza. Parser XML przerwie odczyt pliku, zanim dojdzie do walidacji. | XSD |
| Stawka VAT spoza słownika | P_12 w wierszu ma wartość „13”, której nie ma w słowniku stawek schematu (23, 22, 8, 7, 5, 4, 3, 0 KR, 0 WDT, 0 EX, zw, oo, np I, np II). Błąd XSD. | XSD |
| Suma VAT nie zgadza się z wierszami | Pierwsze pole P_14_x (albo P_13_x, gdy faktura nie ma VAT) jest o 10,00 zł niższe niż suma z wierszy. Schemat tego nie sprawdza; KSeF przyjmie plik, ale program księgowy pokaże rozbieżność podsumowania z pozycjami. | ERP |
| Kwota należności (P_15) niezgodna | P_15 jest wyższe o 100,00 zł od sumy netto i VAT. Plik przechodzi XSD; ERP przy imporcie porówna P_15 z sumami i zatrzyma dokument do wyjaśnienia. | ERP |
| NIP sprzedawcy z błędną sumą kontrolną | Ostatnia cyfra NIP-u sprzedawcy jest zmieniona, więc suma kontrolna się nie zgadza. XSD sprawdza tylko format 10 cyfr. KSeF na produkcji sprawdza sumę kontrolną NIP w Podmiot1, Podmiot2, Podmiot3 i PodmiotUpowazniony i odrzuci plik; na środowisku testowym tej kontroli nie ma (plik może tam odpaść tylko przez brak uprawnień do wystawiania faktur w imieniu tego NIP-u). ERP zgłosi błędny NIP kontrahenta. | KSeF |
| Numer rachunku z błędną sumą kontrolną | NrRB ma zamienione dwie cyfry, więc nie przechodzi kontroli mod 97. XSD tego nie sprawdza; program ERP odrzuci rachunek przy zapisie płatności albo przy sprawdzeniu białej listy. | ERP |
| Data wystawienia w przyszłości | P_1 jest o rok później niż data dokumentu. Mieści się w zakresie dat schematu, ale KSeF i ERP sprawdzają datę wystawienia względem daty bieżącej. | KSeF |
| Duplikat numeru faktury | Ten sam numer P_2 co w poprawnym dokumencie, inna data. KSeF rozpoznaje duplikat po NIP-ie sprzedawcy, rodzaju faktury (RodzajFaktury) i numerze P_2 i odrzuci drugi plik z kodem 440 „Duplikat faktury” (unikalność pilnuje przez 10 lat od końca roku wystawienia). Program ERP też zgłosi duplikat numeru w serii przy imporcie. | KSeF |
Formaty dodatkowe – do sprawdzenia na pliku z programu
- ECOD (Comarch EDI / EDINet). Komunikaty Document-Invoice, Document-Order i Document-DespatchAdvice z sekcjami nagłówka, stron (ILN z prefiksem 590 i cyfrą kontrolną GS1 wyprowadzony z NIP-u, TaxID, nazwa, adres), wierszy (EAN, kod dostawcy, ilość, jednostka w kodzie UN/ECE, cena netto, stawka, kategoria podatkowa S/Z/E/AE/O) i podsumowania z liniami per stawka; InvoiceType 380/384/386, środki płatności według UNCL 4461, awizo z numerami SSCC (cyfra kontrolna mod 10). Comarch nie publikuje specyfikacji ECOD – nazwy elementów pochodzą z fragmentów mapowań w pomocy Comarch, więc układ wymaga porównania z plikiem wyeksportowanym z programu.
- XML importu enova365. Sesja
business="true"według dokumentacji importu XML enova365: kontrahenci (Kod, Nazwa, NIP, EUVAT, Adres z krajem przezwhere), towary (Kod, Nazwa, Typ, Jednostka, EAN, PKWiU, StawkaVAT) i dokumenty handlowe (Definicja i Magazyn przezwhere, Kontrahent, Data, NumerObcy, Pozycje z Towar/Ilosc/Cena, Stan „Zatwierdzony” na końcu). Nazwy pól towaru i sposób zapisu korekt nie były potwierdzone importem próbnym; korekty oznaczamy komentarzem i definicją z przyrostkiem K. - Spis CSV/XLSX. Kolumny: plik, rodzaj, scenariusz, numer, numer KSeF, data, NIP-y, nabywca, waluta, netto, VAT, brutto, dokument powiązany, uwagi. CSV ze średnikiem i BOM (polski Excel), XLSX z tym samym mechanizmem co generator danych testowych.
Źródła
- Ministerstwo Finansów – struktura logiczna e-faktury FA(3): schemat XSD (CRD, wzór 2025/06/25/13775) i broszura informacyjna – crd.gov.pl/wzor/2025/06/25/13775
- KSeF – pliki do pobrania: przykładowe pliki FA(3), podręczniki KSeF 2.0 – ksef.podatki.gov.pl/pliki-do-pobrania-ksef-20
- Ministerstwo Finansów – prezentacja „Z czego składa się numer KSeF” – ksef.podatki.gov.pl/media/4zsbiko2/prezentacja-numeru-ksef.pdf
- CIRFMF/ksef-api – dokumentacja API KSeF 2.0: numer KSeF i suma CRC-8 (faktury/numer-ksef.md), weryfikacja faktury – duplikaty, NIP, załączniki (faktury/weryfikacja-faktury.md), środowiska, kody QR, dane testowe – github.com/CIRFMF/ksef-api
- Ustawa z 11 marca 2004 r. o podatku od towarów i usług – art. 106e (elementy faktury), 106f (zaliczki), 106j (korekty), 106e ust. 5 pkt 3 (faktury uproszczone) – isap.sejm.gov.pl/isap.nsf/DocDetails.xsp?id=WDU20040540535
- Soneta – dokumentacja enova365: KSeF (pobieranie i import faktur), moduł EDI (definicje ECOD/EDINet), import danych z XML – www.enova.pl/krajowy-system-e-faktur
- Comarch – pomoc Comarch ERP Optima: Krajowy System e-Faktur, Faktury z KSeF, Comarch EDI – pomoc.comarch.pl/optima/pl/2026/index.php/dokumentacja/krajowy-system-e-faktur-ksef
- GS1 – budowa numerów GLN i SSCC (cyfra kontrolna mod 10) – www.gs1pl.org
- UN/CEFACT – kody jednostek miary (Rec. 20), kody rodzajów dokumentów (UNCL 1001) i kategorii podatkowych (UNCL 5305) używane w komunikatach ECOD – unece.org/trade/uncefact
Historia zmian
- 17 listopada 2026 r. Usługi dla firm z UE ze stawką „np II” (P_13_9) i adnotacją P_18 = 1 zamiast „np I”; KursWalutyZ tylko na fakturach zaliczkowych (kurs w pozycjach jak dotąd); P_6 tylko przy dacie dostawy innej niż data wystawienia; suma kontrolna numeru KSeF opisana według dokumentacji MF (CRC-8, wielomian 0x07); błędy „duplikat numeru” (KSeF odrzuca kodem 440) i „NIP” (kontrola sumy tylko na produkcji KSeF) z poprawionym opisem; README paczki ostrzega przed fakturami z załącznikiem.
- 27 października 2026 r. – wersja 1.0. Pierwsza wersja: jedna faktura, paczka z ziarna (VAT, KOR, ZAL, ROZ, UPR, KOR_ZAL, KOR_ROZ), pliki celowo błędne, ECOD INVOICE/ORDER/DESADV, XML importu enova365, spis CSV/XLSX, przekazanie do podglądu faktury.