Integracja własnego systemu ERP lub sprzedażowego z API KSeF umożliwia automatyczne wysyłanie, odbieranie i walidację faktur bez ręcznego logowania do platformy rządowej.
Od 1 lutego 2026 r. obowiązek dotyczy dużych przedsiębiorstw, a od 1 kwietnia 2026 r. – wszystkich pozostałych firm.
Co to jest API KSeF i jak działa?
API KSeF to interfejs komunikacyjny oparty na zasadach REST i protokole HTTPS, który łączy systemy ERP z centralnym rejestrem KSeF.
Umożliwia bezpośrednią komunikację z serwerami Ministerstwa Finansów, eliminując ręczne wgrywanie plików XML do aplikacji webowej. Interfejs wykorzystuje standardowe metody HTTP (m.in. GET i POST), dzięki czemu jest uniwersalny dla różnych platform i języków programowania.
Krok 1 – przygotowanie i weryfikacja danych
Przed przystąpieniem do integracji przygotuj podstawowe elementy:
- zweryfikuj dane firmy – sprawdź w CEIDG/KRS, czy system posiada aktualne informacje o Twojej firmie;
- pobierz dokumentację API – zapoznaj się ze specyfikacją OpenAPI i przetestuj metody w Swagger UI z dokumentacji Ministerstwa Finansów;
- uzyskaj dostęp do środowiska testowego – skorzystaj z testowego API KSeF (ksef.podatki.gov.pl), aby przeprowadzić testy integracyjne przed wdrożeniem produkcyjnym;
- zidentyfikuj kluczowe endpointy – wysyłanie faktur, import XML oraz pobieranie UPO (Urzędowego Potwierdzenia Odbioru).
Krok 2 – uwierzytelnienie i bezpieczeństwo
Aby Twój program do fakturowania połączył się z API KSeF, wybierz jeden z dwóch mechanizmów uwierzytelnienia.
Uwierzytelnienie automatyczne
Uwierzytelnienie automatyczne to najszybsza i najbezpieczniejsza metoda. Wiele nowoczesnych systemów fakturowych automatyzuje cały proces. Po jednorazowej autoryzacji (np. podpisem kwalifikowanym) system sam generuje niezbędny certyfikat i paruje się z KSeF w tle.
Certyfikat KSeF
Jeśli Twoje oprogramowanie tego wymaga, wygeneruj certyfikat samodzielnie w Aplikacji Podatnika, a następnie wgraj go do systemu. Certyfikat służy wyłącznie do komunikacji „maszyna–maszyna”, zapewniając stabilną wymianę danych bez każdorazowego logowania właściciela.
Najczęściej wymagane są dwa elementy: certyfikat publiczny (.crt lub .pem) oraz klucz prywatny (.key) z hasłem do klucza.
W środowisku testowym możesz wygenerować token KSeF narzędziem Mój Certyfikat Urzędnika (MCU) lub użyć certyfikatu samopodpisanego. Token będzie potrzebny do autoryzacji wywołań API.
Krok 3 – schemat działania integracji
Proces integracji polega na wymianie żądań HTTP między Twoim ERP a KSeF. Poniżej znajdziesz uproszczony schemat kroków:
| Etap | Działanie w ERP | Odpowiedź API KSeF | Endpoint |
|---|---|---|---|
| Wystawienie | Generuj XML FA(3) | Weryfikacja + numer KSeF + UPO | POST /invoices |
| Odbiór | Pobierz listę faktur | Plik XML + metadane | GET /invoices |
| Walidacja | Wyślij szkic | Lista błędów lub akceptacja | POST /validate |
Aby domknąć przepływ, wykonaj trzy najważniejsze czynności:
- generowanie faktury w ERP – utwórz dokument w formacie XML zgodnym ze schematem FA(3);
- uwierzytelnienie – użyj mechanizmu podpisu/certyfikatu lub tokenu zgodnie z dokumentacją Ministerstwa Finansów;
- wysyłka – wyślij żądanie
POSTdo właściwego endpointu.
Krok 4 – implementacja autoryzacji
Proces autoryzacji przebiega przez następujące etapy:
- Zażądaj challenge (wyzwania) od serwera KSeF.
- Podpisz challenge swoim certyfikatem.
- Wyślij podpisany challenge do serwera.
- Odbierz token autoryzacyjny.
- Użyj tokenu do autoryzowania kolejnych żądań API.
Krok 5 – praca w środowisku testowym
Przed przeniesieniem rozwiązania na produkcję przeprowadź testy end-to-end:
- Otwórz sesję z KSeF.
- Wyślij testową fakturę.
- Sprawdź status faktur i pobierz UPO.
- Przetestuj różne scenariusze (faktury, korekty, obsługa błędów).
- Po pełnych testach przejdź na produkcję.
Krok 6 – konfiguracja techniczna
Podczas implementacji uwzględnij poniższe aspekty techniczne:
- konwersja do XML – automatycznie mapuj pola ERP na FA(3), w tym NIP, stawki i kwoty VAT;
- obsługa błędów – dodaj walidacje wejściowe i mechanizm ponawiania żądań (retry) z backoffem;
- weryfikacja przedwysyłkowa – zaimplementuj kontrole biznesowe i techniczne przed wysłaniem dokumentu do KSeF;
- pobieranie UPO – automatycznie pobieraj i archiwizuj urzędowe potwierdzenia odbioru.
Wdrożenie i monitoring
Po pozytywnych testach w środowisku integracyjnym uruchom produkcję i pamiętaj o stałej kontroli jakości procesu:
- regularnym monitorowaniu statusu faktur,
- archiwizowaniu UPO,
- obsłudze scenariuszy błędów (duplikaty, błędy walidacji),
- dokumentowaniu wszystkich wymienionych dokumentów.
Alternatywne podejście
Jeśli samodzielna integracja jest zbyt złożona, rozważ gotowe usługi pośredniczące. Serwis KSeFAPI.dev oferuje prosty interfejs API do KSeF – wysyłasz dane faktury w JSON, a system przejmuje walidację, generowanie XML i wysyłkę do KSeF (dostępne środowiska: test, demo, produkcja). Takie podejście przyspiesza wdrożenie, zwłaszcza w mniejszych firmach.
Zasoby dla integratorów
Ministerstwo Finansów udostępnia materiały i środowiska wspierające implementację:
- KSeF 2.0 – przewodnik dla integratorów – scenariusze użycia API, uwierzytelnianie, wysyłka w sesji interaktywnej lub wsadowej, pobieranie UPO;
- przykłady wywołań – każdy scenariusz wskazuje właściwe endpointy oraz prezentuje zapytania i odpowiedzi w C# i Javie;
- środowisko integracyjne API KSeF 2.0 – dostępne do testów i walidacji rozwiązań.
