Krajowy System e-Faktur (KSeF) – oficjalne repozytoria GitHub dla integratorów
Krajowy System e-Faktur (KSeF) to obowiązkowe narzędzie dla polskich przedsiębiorców, które od 2026 roku rewolucjonizuje procesy fakturowania.
Dla deweloperów i integratorów systemów księgowych kluczowe są oficjalne repozytoria na GitHubie, publikowane przez Centrum Informatyki Resortu Finansów Ministerstwa Finansów (CIRFMF). Poniżej zebraliśmy najważniejsze zasoby, które realnie skracają czas wdrożenia:
- dokumentacja API – specyfikacje KSeF 2.0, scenariusze integracyjne i opisy błędów;
- biblioteki klienckie – gotowe SDK dla popularnych języków (np. .NET, Node.js),
- narzędzia do PDF – transformacje XSLT i generatory wizualizacji e-faktur oraz UPO,
- środowiska testowe – instancje TEST/DEMO do walidacji i próbnych wdrożeń.
W tym artykule omawiamy najważniejsze repozytoria, ich zawartość, praktyczne wskazówki implementacyjne oraz kanały wsparcia. Materiały te są niezbędne dla firm tworzących oprogramowanie księgowe, ERP czy systemy finansowe, aby zapewnić zgodność z wymogami fiskusa.
Co to jest KSeF i dlaczego GitHub jest kluczowy dla integratorów?
KSeF to centralny system Ministerstwa Finansów do wysyłania, odbierania i przechowywania ustrukturyzowanych e-faktur w formacie XML. Od kwietnia 2026 roku obowiązek korzystania z KSeF dotyczy większości przedsiębiorców (z wyjątkami dla małych podatników).
Integracja odbywa się przez API, a najczęstsze wyzwania techniczne to:
- autoryzacja i podpisywanie żądań,
- walidacja struktury XML względem XSD,
- obsługa UPO (Urzędowe Poświadczenie Odbioru),
- generowanie wizualizacji PDF dla użytkowników.
GitHub CIRFMF pełni rolę „informatycznego dziennika ustaw” – oficjalnego źródła norm technicznych KSeF. Repozytoria skupiają się na wersji 2.0 API, w tym na istotnych zmianach takich jak:
- nowe endpointy i ujednolicone odpowiedzi,
- ulepszona autoryzacja i obsługa uprawnień,
- biblioteki klienckie dla popularnych języków programowania.
Środowiska testowe dostępne są pod następującymi adresami:
- TEST – https://ksef-test.mf.gov.pl/;
- DEMO – https://ksef-demo.mf.gov.pl/;
- PROD – https://ksef.mf.gov.pl/.
Główne oficjalne repozytorium – CIRFMF/ksef-docs
Najważniejszym zasobem jest repozytorium ksef-docs – kompleksowe kompendium dla deweloperów, analityków i integratorów. Ostatnia aktualizacja: 22 grudnia 2025 roku. Zawiera przewodnik po KSeF 2.0: schematy XML, przykłady request/response, obsługę błędów oraz różnice względem wersji 1.0.
Najważniejsze działy w ksef-docs to:
- Przegląd zmian w API 2.0 – informacje o nowych bibliotekach (np. NuGet dla .NET, npm dla Node.js), pełne przykłady wysyłki i pobierania metadanych;
- Schematy i XSD – definicje struktur JPK_FA(3), e-faktur oraz UPO;
- Przykłady integracji – gotowe scenariusze: logowanie, wysyłka faktury, pobranie listy metadanych.
Repozytorium zachęca do dyskusji technicznej w sekcji Issues – skupionej na jakości API, stabilności, bezpieczeństwie i rozwoju interfejsów. Przykładowo, issue #668 precyzuje zasady korzystania z Issues (pytania administracyjne – poza zakresem, skupienie na kodzie i API).
Praktyczna wskazówka: aby pobrać listę metadanych faktur, korzystaj z metody inkrementalnej z kryteriami (np. data nadania numeru KSeF); w starszych wersjach zgłaszano nieścisłości w filtrach.
Biblioteki i narzędzia do generowania PDF
Wizualizacja faktur to obowiązek – KSeF nie dostarcza gotowych plików PDF, dlatego generowanie po stronie systemu integratora jest niezbędne.
CIRFMF/ksef-pdf-generator – oficjalna biblioteka do tworzenia PDF faktur i UPO z plików XML KSeF. Instalacja: git clone https://github.com/CIRFMF/ksef-pdf-generator, następnie budowa projektu. Narzędzie wykorzystuje transformacje XSLT do uzyskania spójnej wizualizacji.
ksef4dev/ksef-fop – otwartoźródłowa aplikacja webowa do podglądu e-faktur i pobierania PDF. Bazuje na transformacjach XSLT z ksef-docs, co czyni ją idealną do testów i QA.
Oba rozwiązania integrują się z Apache FOP (Formatting Objects Processor), zapewniając zgodność z wymaganiami MF i przewidywalny wygląd dokumentów.
KSeF Integrators – materiały dla programistów
Repozytorium ksef4dev (KSeF Integrators) gromadzi zasoby przydatne w praktyce: linki do środowisk, przykładowe kody oraz projekty powiązane, m.in. GbbKSeF2 (integracja dla .NET). To inicjatywa nieoficjalna, ale ściśle uzupełniająca dokumentację CIRFMF.
Wsparcie dla integratorów i dobre praktyki
Ministerstwo Finansów oferuje oficjalne wsparcie na ksef.podatki.gov.pl, w tym dostęp do środowisk testowych z realnymi uprawnieniami (wymagane konto w e-Urzędzie Skarbowym).
Rekomendowana ścieżka wdrożenia wygląda następująco:
- Sklonuj ksef-docs i przeanalizuj schematy oraz scenariusze integracji.
- Pobierz i zintegrowaj biblioteki klienckie KSeF 2.0 (np. dla .NET lub Node.js).
- Testuj w środowiskach TEST/DEMO, generując PDF za pomocą ksef-pdf-generator.
- Monitoruj sekcję Issues pod kątem zmian i poprawek (np. wizualizacja – #12, metadane – #29).
- Unikaj typowych błędów: zawsze waliduj XML względem XSD przed wysyłką oraz obsługuj limity zapytań API.
Najczęstsze wyzwania to opóźnione publikacje zmian oraz niejednoznaczności w niektórych metodach pobierania; najlepszą praktyką jest stałe śledzenie aktualizacji CIRFMF na GitHubie i szybkie testy regresyjne w TEST/DEMO.
