KSeF API – jak zacząć
Co musisz wiedzieć
Krajowy System e-Faktur (KSeF) jest centralnym systemem administracji skarbowej do wystawiania i otrzymywania faktur ustrukturyzowanych w formacie XML.
Na tej stronie znajdziesz uporządkowane informacje dotyczące tematu: KSeF API – jak zacząć. Opis koncentruje się na aktualnych przepisach oraz komunikatach Ministerstwa Finansów.
Instrukcja krok po kroku
1. Zapoznaj się z dokumentacją API 2.0
Pobierz dokumentację ze strony ksef.podatki.gov.pl/ksef-na-okres-obligatoryjny/wsparcie-dla-integratorow. Znajdziesz tam specyfikację OpenAPI, podręcznik integratora, SDK dla Javy i .NET oraz przykładowe kody.
2. Załóż konto w środowisku testowym
Zarejestruj się w środowisku testowym KSeF (ksef-test.mf.gov.pl). Środowisko testowe pozwala na bezpieczne testowanie bez skutków prawnych. Możesz używać certyfikatów self-signed zamiast kwalifikowanych.
3. Wygeneruj token lub certyfikat testowy
W środowisku testowym wygeneruj token KSeF przez MCU lub użyj certyfikatu self-signed. Token będzie potrzebny do autoryzacji wywołań API.
4. Skonfiguruj środowisko deweloperskie
Pobierz SDK dla swojego języka programowania (Java, .NET). Skonfiguruj projekt zgodnie z dokumentacją, ustaw bazowy URL API na środowisko testowe i zaimplementuj proces autoryzacji.
5. Przetestuj podstawowe operacje
Wykonaj pierwszy test: uwierzytelnienie, otwarcie sesji, wysłanie testowej faktury i sprawdzenie jej statusu. Użyj przykładowych plików XML z dokumentacji MF, aby uniknąć błędów walidacji.
Najczęstsze problemy i rozwiązania
Nie wiem, od czego zacząć integrację z API KSeF
Zacznij od dokumentacji API 2.0 na ksef.podatki.gov.pl. Zarejestruj się w środowisku testowym, pobierz SDK dla swojego języka (Java/.NET) i przetestuj podstawowe operacje autoryzacji i wysyłki faktury.
Nie mogę uzyskać dostępu do środowiska testowego
Środowisko testowe API KSeF 2.0 jest dostępne od września 2025 r. Sprawdź, czy używasz poprawnych adresów URL i czy masz wygenerowany token testowy przez MCU w środowisku testowym.
SDK nie działa z moim projektem
Sprawdź wymagania wersji środowiska (Java/Node/.NET). Upewnij się, że używasz najnowszej wersji SDK z repozytorium GitHub CIRFMF/ksef-docs. Przejrzyj przykładowe kody w dokumentacji.
Wymagania wstępne
Przed rozpoczęciem integracji z API KSeF potrzebujesz: znajomości protokołu REST i formatu JSON/XML, środowiska deweloperskiego (Java 11+ lub .NET 6+), dostępu do internetu dla środowiska testowego, podstawowej wiedzy o podpisach elektronicznych i certyfikatach.
Materiały od Ministerstwa Finansów
MF udostępnia komplet materiałów dla integratorów: specyfikację OpenAPI (Swagger), podręcznik integratora w formacie PDF, biblioteki SDK dla Javy i .NET, przykładowe kody źródłowe, schematy XSD dla struktur FA(2) i FA(3). Wszystkie materiały dostępne są na stronie ksef.podatki.gov.pl.
Środowiska API KSeF
Dostępne są trzy środowiska: testowe (TE) – dla deweloperów, pozwala na testy z certyfikatami self-signed; demo (TR) – odzwierciedla produkcję, ale bez skutków prawnych; produkcyjne (PRD) – realne dokumenty, skutki prawne. Rozpocznij od środowiska testowego.
Proces integracji krok po kroku
- Pobierz dokumentację i SDK. 2. Skonfiguruj środowisko testowe. 3. Zaimplementuj autoryzację (challenge → podpis → token). 4. Otwórz sesję i wyślij testową fakturę. 5. Sprawdź status i pobierz UPO. 6. Przetestuj różne scenariusze (korekty, błędy). 7. Przejdź na produkcję po pełnych testach.
FAQ
Jak zacząć korzystać z API KSeF?
Rozpocznij od zapoznania się z dokumentacją API KSeF 2.0 na stronie Ministerstwa Finansów. Następnie zarejestruj się w środowisku testowym, uzyskaj token autoryzacyjny i przetestuj podstawowe operacje wysyłania i pobierania faktur.
Jakie narzędzia są dostępne dla programistów KSeF?
Ministerstwo Finansów udostępnia: dokumentację w formacie OpenAPI, biblioteki SDK dla Javy i .NET, przykładowe kody źródłowe oraz środowisko testowe. Materiały dostępne są na stronie ksef.podatki.gov.pl oraz w repozytorium GitHub CIRFMF.
Czy muszę mieć certyfikat kwalifikowany do korzystania z API KSeF?
Do autoryzacji w API KSeF potrzebujesz tokenu autoryzacyjnego lub certyfikatu KSeF. Token można wygenerować po uwierzytelnieniu się profilem zaufanym, podpisem kwalifikowanym lub pieczęcią kwalifikowaną.
Gdzie mogę testować integrację z API KSeF?
Ministerstwo Finansów udostępnia środowisko testowe API KSeF od września 2025 r. Dokumentacja testowa i dostęp do środowiska dostępne są na stronie ksef.podatki.gov.pl/ksef-na-okres-obligatoryjny/wsparcie-dla-integratorow.