ksefik

Krajowy System e-Faktur w terminalu.
Przeglądaj, wystawiaj i wysyłaj faktury FA(3) do KSeF 2.0 - szybko, z klawiatury, bez przeglądarki.

Dlaczego ksefik?

• ⚡ Szybko. Faktury są w lokalnej bazie SQLite z wyszukiwaniem pełnotekstowym - lista i szukanie działają natychmiast, także offline. Nowa faktura dla stałego kontrahenta to kilka klawiszy.
• ✅ Bezpiecznie. Każda faktura przed wysyłką jest sprawdzana oficjalnym schematem XSD FA(3) i regułami biznesowymi (NIP, daty, kurs waluty, MPP, zwolnienia, duplikaty numerów). Widzisz ją dokładnie w takiej postaci, w jakiej trafi do KSeF.
• 🧾 Kompletnie. Faktury krajowe, UE i eksport, waluty obce, wiele stawek VAT, korekty, MPP, metoda kasowa, JST i podmioty trzecie, wysyłka gotowych plików XML (także wsadowa i offline), UPO.
• 🔐 Całe konto KSeF. Tokeny, uprawnienia, certyfikaty KSeF, sesje, limity, identyfikatory zbiorcze, Peppol - wszystko, co zwykle wymaga Aplikacji Podatnika.
• 🏠 Twoje dane zostają u Ciebie. Brak serwera pośredniczącego i telemetrii. Aplikacja łączy się tylko z API KSeF Ministerstwa Finansów (i na Twoje żądanie z Białą listą VAT). Token trafia do systemowego pęku kluczy.
• 🏢 Wiele firm. Osobny profil, baza i token dla każdej firmy i środowiska (produkcja, demo, test).

Podsumowanie przed wysyłką - faktura sprawdzona schematem FA(3)	Podgląd faktury - UPO, XML, korekta, wystaw podobną
Kreator - dane firmy pobrane po NIP z Białej listy VAT	Konto KSeF - tokeny, uprawnienia, certyfikaty, limity

Instalacja

Potrzebujesz Pythona 3.12+. ksefik jest rozwijany i testowany na Linuksie; macOS powinien działać, Windows na razie nie jest wspierany. Najprościej przez uv:

uv tool install ksefik      # albo: pipx install ksefik
ksefik

Bez instalacji: uvx ksefik. Wersja rozwojowa prosto z repozytorium:

git clone https://github.com/gacopys/ksefik.git && cd ksefik
make run                     # to samo co: uv run ksefik

Pierwsze uruchomienie

1. Kreator zapyta o dane firmy (NIP, nazwa, adres, rachunek, numeracja) i zapisze je w profilu ~/.config/ksefik/profile.toml. Przycisk „Pobierz dane” obok NIP-u uzupełni nazwę i adres z wykazu podatników VAT (Biała lista MF; bez klucza, limit ok. 100 zapytań dziennie).
2. Token KSeF wygenerujesz w Aplikacji Podatnika KSeF. Token trafia do systemowego pęku kluczy, a gdy go nie ma - do pliku ~/.config/ksefik/token-… z prawami 0600. Zamiast tokena możesz logować się certyfikatem.
3. Gotowe - faktury zsynchronizują się same.

Jak to działa

Lista faktur. Zakładki Wystawione / Otrzymane (oraz Jako podmiot 3 / Jako upoważniony, jeśli włączysz je w profilu) i Wszystkie (← → albo 1…5), wybór faktury ↑ ↓ (także podczas pisania w wyszukiwarce), wyszukiwanie pełnotekstowe (/) po numerze, kontrahencie, NIP-ie, numerze KSeF i treści faktury (polskie znaki nie są wymagane: „uslugi” znajdzie „Usługi”), filtr okresu i kontrahenta.

Podgląd faktury (Enter): c kopiuje numer KSeF, x zapisuje XML do Pobrane, o otwiera stronę weryfikacji w KSeF, u pobiera UPO, d wystawia podobną fakturę, k tworzy korektę, g pobiera treść faktury, której jeszcze nie ma w bazie.

Synchronizacja. Faktury są pobierane z KSeF do lokalnej bazy. Synchronizacja rusza sama przy starcie, jeśli ostatnia była ponad 15 minut temu, i na żądanie klawiszem r. Pobierany jest tylko przyrost od ostatniej synchronizacji (KSeF ogranicza liczbę eksportów). Dowolną fakturę ściągniesz też po numerze KSeF (g na liście).

Nowa faktura (n):

1. Wybierasz kontrahenta i pozycję (z profilu albo z historii wystawionych faktur) i wpisujesz kwotę.
2. Podsumowanie pokazuje fakturę dokładnie w takiej postaci, w jakiej trafi do KSeF - po sprawdzeniu oficjalnym schematem XSD FA(3) i regułami.
3. e przenosi do edycji: wiele pozycji z różnymi stawkami (23, 8, 5, 0% kraj/WDT/eksport, zw, np, odwrotne obciążenie, marża…), data sprzedaży albo okres, waluta i kurs, nabywca z UE/spoza UE/bez NIP, forma płatności, termin albo „zapłacono”, rachunek, adnotacje (MPP, metoda kasowa, samofakturowanie, TP), uwagi, numer zamówienia i umowy. Zmiany zapisują się same jako szkic.
4. Ctrl+S w podsumowaniu wysyła fakturę. Widać kolejne kroki, a na końcu numer KSeF. XML i UPO zapisują się w ~/.local/share/ksefik/<środowisko>/<NIP>/wystawione/.

Korekta (k w podglądzie faktury wystawionej): pozycje startują od stanu sprzed korekty - zmieniasz ilości i ceny, aplikacja wysyła wiersze „przed” i „po” oraz różnice kwot (metoda zgodna z FA(3)).

Wysyłka plików XML (i): faktury FA(3) z innego programu - plik, katalog albo wzorzec (~/faktury/*.xml). Każdy plik jest najpierw sprawdzany schematem XSD; wysyłka w jednej sesji interaktywnej albo jako paczka wsadowa (ZIP szyfrowany AES-256, dzielony na części), z opcją trybu offline.

Konto KSeF (k na liście albo Ctrl+P):

Środowisko KSeF podasz w profilu albo przy starcie: ksefik --env test (prod | demo | test). Paletę poleceń otwiera Ctrl+P - są w niej wszystkie funkcje, także zmiana motywu i wylogowanie.

Profil firmy - profile.toml

Wszystko, co dotyczy Twojej firmy i Twoich faktur, jest w profilu, a nie w kodzie:

• dane sprzedawcy (z KRS/REGON/BDO do stopki) i rachunki bankowe (także walutowe),
• kontrahenci - z NIP-em, numerem VAT UE, innym identyfikatorem albo bez identyfikatora (osoba prywatna); z własnym terminem płatności, walutą, domyślną pozycją i podmiotami trzecimi (np. odbiorca dla JST),
• katalog pozycji - nazwa, jednostka, stawka VAT, cena, GTU, PKWiU, CN, załącznik nr 15,
• numeracja według wzoru (FV/{nr}/{mm}/{rrrr}, {nr}/{m}/{rrrr}, FV/{rrrr}/{nr:4}…) - licznik miesięczny, roczny albo ciągły, osobna seria dla korekt,
• daty nowej faktury (dzisiaj / koniec miesiąca / dzisiaj za poprzedni miesiąc), termin i forma płatności, waluta, MPP, metoda kasowa, podstawa zwolnienia, procedura marży, stopka,
• logowanie - token albo certyfikat, kontekst (NIP, identyfikator wewnętrzny, NIP-VAT UE, Peppol), dozwolone adresy IP,
• synchronizacja - od kiedy i które faktury: wystawione, otrzymane, jako podmiot 3, jako upoważniony.

Opis wszystkich pól z przykładami: profile.example.toml. Profil edytujesz w dowolnym edytorze (make profile, w aplikacji Ctrl+P → „Edytuj profil”). Błędy - np. literówkę w nazwie pola albo zły NIP - aplikacja opisze wprost i podpowie poprawną nazwę. Nowych kontrahentów i pozycje możesz też zapisywać do profilu prosto z edycji faktury.

Kilka firm: każda ma własny profil - ksefik --profile ~/firmy/druga.toml (albo zmienna KSEFIK_PROFILE). Baza faktur i tokeny są osobne dla każdej firmy i środowiska (~/.local/share/ksefik/<środowisko>/<NIP>/).

Logowanie certyfikatem

Zamiast tokena możesz logować się podpisem XAdES: certyfikatem KSeF, kwalifikowaną pieczęcią firmy albo podpisem kwalifikowanym w plikach PEM/DER lub .p12:

[logowanie]
metoda = "certyfikat"
certyfikat = "~/.config/ksefik/certyfikaty/laptop.pem"
klucz = "~/.config/ksefik/certyfikaty/laptop.klucz.pem"

Obsługiwane są klucze RSA i EC (P-256). Hasło do klucza nie jest zapisywane - aplikacja zapyta o nie (albo ustaw KSEF_KEY_PASSWORD). Certyfikat KSeF możesz wygenerować w samej aplikacji: Konto KSeF → Certyfikaty KSeF → n (wymaga zalogowania podpisem; klucz powstaje lokalnie).

Zmienne środowiskowe

Bezpieczeństwo i prywatność

• ksefik nie ma żadnego serwera ani telemetrii. Łączy się wyłącznie z API KSeF (api*.ksef.mf.gov.pl) i - gdy naciśniesz „Pobierz dane” - z Białą listą VAT (wl-api.mf.gov.pl).
• Token KSeF jest w systemowym pęku kluczy (Secret Service / Keychain). Hasła do kluczy prywatnych nie są zapisywane.
• Faktury, XML i UPO leżą lokalnie w ~/.local/share/ksefik/.
• Lukę bezpieczeństwa zgłoś prywatnie - zobacz SECURITY.md.

Rozwój

make install          # zależności (uv)
make test             # testy jednostkowe i interfejsu, bez sieci (~30 s, równolegle)
make check            # lint (ruff) + testy z kontrolą pokrycia (minimum 90%)
make format           # formatowanie kodu
make                  # wszystkie komendy

Około 700 testów działa bez sieci: logika faktur i XML, klient API na udawanym transporcie oraz testy interfejsu, które sterują prawdziwą aplikacją Textual (klawisze, formularze, układ w 80×24). Pokrycie linii i gałęzi musi wynosić co najmniej 90% - inaczej CI nie przejdzie.

Testy end-to-end z testowym KSeF

make run-integration-test                      # cały zestaw, ok. 4 minut
make run-integration-test ARGS="-k test_06"    # wybrane testy (argumenty pytest)

Testy sterują prawdziwą aplikacją, a backendem jest publiczne środowisko testowe KSeF. Każde uruchomienie tworzy nowe, fikcyjne firmy (losowe NIP-y z samopodpisaną pieczęcią - KSeF akceptuje takie certyfikaty tylko na środowisku testowym). Testy działają w osobnym katalogu tymczasowym z wyłączonym pękiem kluczy - nie dotykają Twojego profilu, bazy ani tokenów. Każdy wynik jest sprawdzany także po stronie KSeF. W GitHub Actions te testy działają co noc i na żądanie (odznaka „Testy z KSeF”).

Zakres: kreator i logowanie (token, certyfikat z hasłem, wylogowanie), wystawianie (szybka faktura, edytor z wieloma stawkami, UE/spoza UE/konsument/JST, waluty z kursem, korekta, kopia, UPO, XML), synchronizacja (wystawione, otrzymane, podmiot 3) z wyszukiwaniem i filtrami, pobieranie po numerze KSeF, wysyłka plików XML (interaktywna i wsadowa, offline), sesje i UPO, tokeny, sesje logowania, limity, Peppol, identyfikatory zbiorcze, wszystkie rodzaje uprawnień, certyfikaty KSeF, dane testowe, edycja profilu i dokończenie wysyłki po ponownym uruchomieniu.

Piaskownica testowa

Na środowisko testowe KSeF nie wysyła się prawdziwych danych, dlatego służy do tego osobna piaskownica (domyślnie ~/.ksef-test, zmienisz to przez TEST_HOME=…):

make run-test-env     # za pierwszym razem: fikcyjny NIP, token i profil, potem start aplikacji
make test-env-clean   # usunięcie piaskownicy (np. żeby zacząć od nowego NIP-u)

Architektura

Zrzuty ekranów w tym README generuje make docs-screens - z fikcyjnymi danymi i udawanym KSeF.

Współtworzenie

Zgłoszenia błędów, pomysły i pull requesty są mile widziane! Zacznij od CONTRIBUTING.md. Jeśli ksefik Ci się przydaje, zostaw ⭐ - to pomaga innym go znaleźć.

Zastrzeżenia

ksefik jest niezależnym projektem open source i nie jest powiązany z Ministerstwem Finansów ani Krajową Administracją Skarbową. Oprogramowanie jest dostarczane „tak jak jest”, bez gwarancji (zob. licencja). Za treść i wysyłkę faktur odpowiada podatnik - przed pierwszym użyciem na produkcji wypróbuj aplikację na środowisku testowym KSeF.

Licencja

MIT © Paweł Borkowski