Krajowy System e-Faktur (KSeF) 2.0 wchodzi w fazę obligatoryjną od 1 lutego 2026 r., co oznacza, że wszystkie firmy muszą zintegrować swoje systemy finansowo-księgowe z tym interfejsem. Dokumentacja API KSeF 2.0, opublikowana 30 czerwca 2025 r. przez Ministerstwo Finansów, stanowi kluczowe narzędzie dla integratorów i deweloperów, umożliwiając przygotowania do testów i wdrożenia.
API KSeF 2.0 definiuje precyzyjne zasady wymiany danych między zewnętrznymi programami fakturowymi a centralnym systemem, niezależnie od producenta oprogramowania.
Pełna integracja jest konieczna, by wystawiać, przesyłać i odbierać e-faktury w formacie FA(3), co zapewnia zgodność z nowymi wymogami prawnymi.
Opublikowana dokumentacja API KSeF 2.0 – co zawiera i jak z niej skorzystać?
Ministerstwo Finansów udostępniło kompletną dokumentację techniczną API KSeF 2.0 w standardzie OpenAPI, co znacząco ułatwia automatyzację integracji i generowanie klientów.
W interaktywnym portalu technicznym znajdziesz następujące elementy:
- Szczegółowymi opisami metod i endpointów – dla każdego zasobu systemu podane są dostępne operacje (np. GET, POST), wymagane parametry i przykładowe odpowiedzi;
- Strukturami danych – modele JSON dla faktur, tokenów, certyfikatów i innych obiektów, wraz z walidacją schematów;
- Parametrami i przykładami zastosowania – gotowymi snippetami kodu pokazującymi typowe scenariusze, takie jak wysyłka faktur w sesji interaktywnej lub wsadowej;
- Specyfikacją OpenAPI (JSON) – plikiem do generowania kodu klienckiego w narzędziach jak Swagger Codegen oraz do walidacji kontraktów API.
Dodatkowo dostępne jest porównanie kluczowych zmian między API 1.0 (faza fakultatywna) a 2.0, co przyspiesza migrację istniejących integracji.
„KSeF 2.0 – przewodnik dla integratorów” opisuje pełne scenariusze użycia, w tym uwierzytelnienie, wysyłkę faktur, pobieranie UPO (Urzędowego Poświadczenia Odbioru) i zarządzanie tokenami.
Resort finansów udostępnił także biblioteki SDK open source w językach Java i .NET, obejmujące wszystkie endpointy, modele danych i przykładowe wywołania. SDK ogranicza ryzyko błędnej interpretacji specyfikacji i przyspiesza development. Repozytoria znajdziesz na GitHubie: CIRFMF/ksef-docs, wraz z kompendium wiedzy dla deweloperów.
Dokumentacja jest dostępna na oficjalnej stronie: https://ksef.podatki.gov.pl/ksef-na-okres-obligatoryjny/wsparcie-dla-integratorow/.
Uwierzytelnianie w API KSeF 2.0 – krok po kroku
Uwierzytelnianie jest obowiązkowe przed dostępem do chronionych zasobów KSeF 2.0, zarówno w środowisku testowym (api-test.ksef.mf.gov.pl), jak i produkcyjnym (api.ksef.mf.gov.pl). Proces opiera się na certyfikatach kwalifikowanych i tokenach autoryzacyjnych, z naciskiem na bezpieczeństwo.
Podstawowe mechanizmy uwierzytelniania:
W praktyce stosowane są trzy mechanizmy:
- Generowanie i pobieranie certyfikatów – certyfikaty są dostępne od 1 lutego 2026 r. wyłącznie poprzez API KSeF 2.0; użytkownik składa wniosek o certyfikat, a system go generuje i udostępnia;
- Tokeny dostępowe – po uwierzytelnieniu certyfikatem generowany jest token JWT (JSON Web Token), ważny przez ograniczony czas; tokeny umożliwiają sesje interaktywne lub wsadowe;
- Uprawnienia i role – API obsługuje wyszukiwanie, przeglądanie faktur oraz zarządzanie dostępem na podstawie ról użytkownika.
Scenariusze uwierzytelniania w przewodniku:
W przewodniku opisano trzy główne scenariusze:
- Sesja interaktywna – idealna do pojedynczych operacji, np. wystawienie faktury z kodem QR;
- Sesja wsadowa – przeznaczona do masowego przetwarzania faktur, z tokenem o dłuższym czasie życia;
- Zarządzanie tokenami – endpointy do odświeżania, wylogowania i monitorowania sesji.
Przykładowy kod w C# i Javie dla każdego kroku znajdziesz w przewodniku integratorów oraz na GitHubie.
Niepoprawne uwierzytelnienie blokuje dostęp do API – etap ten należy gruntownie przetestować w środowisku integracyjnym otwartym od 30 września 2025 r.
Od 28 stycznia 2026 r. API 2.0 jest dostępne na produkcji do weryfikacji systemów komercyjnych, co umożliwia sprawdzenie pełnego cyklu – od certyfikatów po generowanie tokenów.
Limity zapytań i zarządzanie obciążeniem w API KSeF 2.0
API KSeF 2.0 wprowadza ścisłe limity zapytań, aby zapewnić stabilność systemu i uczciwy dostęp dla wszystkich użytkowników. Szczegóły znajdziesz w sekcji „Limity” dokumentacji GitHub oraz w przewodniku integratorów.
Kluczowe limity:
Najważniejsze limity prezentujemy poniżej:
- Rate limiting na poziomie endpointu – maksymalna liczba zapytań na minutę/godzinę dla operacji, takich jak wysyłka faktur czy pobieranie UPO; przekroczenie skutkuje błędami
HTTP 429(Too Many Requests); - Limity sesji – tokeny interaktywne mają krótszy czas życia (np. godziny), wsadowe – dłuższy, ale z limitem przetwarzanych faktur na sesję;
- Globalne ograniczenia – zależne od roli użytkownika i typu podmiotu (np. wyższe progi dla dużych firm).
Szczegóły zestawiono w tabeli:
| Typ limitu | Opis | Przykładowy próg |
|---|---|---|
| Zapytania na minutę | Endpointy wysyłki faktur | 100–500 (zależnie od sesji) |
| Sesja wsadowa | Liczba faktur na batch | Do 1000 na token |
| Pobieranie faktur | Dzienny limit | Zależny od uprawnień |
| Tokeny | Czas życia | 1–24 godziny |
W przypadku przekroczenia limitów system zwraca szczegółowe komunikaty błędów z nagłówkami Retry-After. Zaimplementuj mechanizmy backoff (opóźnione ponowne próby) oraz monitoruj wykorzystanie limitów w czasie rzeczywistym.
Publiczne testy uruchomione od 30 września 2025 r. pozwoliły zweryfikować progi w warunkach zbliżonych do produkcyjnych.
Harmonogram wdrożenia i testy API KSeF 2.0
Kluczowe daty i etapy wdrożenia wyglądają następująco:
- 30 czerwca 2025 – publikacja dokumentacji i struktury FA(3);
- 30 września 2025 – otwarcie środowiska testowego (integracyjnego);
- 28 stycznia 2026 – udostępnienie API na produkcji do weryfikacji;
- 1 lutego 2026 – start obligatoryjnego KSeF 2.0, pobieranie certyfikatów tylko via API.
Integratorzy powinni rozpocząć prace od środowiska testowego, korzystając z SDK i przewodnika, by zminimalizować ryzyko błędów w produkcji.
Korzyści integracji i rekomendacje dla firm
Integracja z API KSeF 2.0 automatyzuje obieg e-faktur, ogranicza błędy i obniża koszty operacyjne. Rozwiązania pośrednie (np. Fakturowo.pl, Ksef24.com) oferują gotowe REST API, jednak bezpośrednie połączenie z oficjalnym API daje pełną kontrolę nad bezpieczeństwem, wersjonowaniem i wydajnością.
Dla księgowych i przedsiębiorców – zweryfikuj, czy Twój dostawca oprogramowania jest gotowy; brak integracji uniemożliwi fakturowanie od lutego 2026 r. Dokumentacja i SDK znacząco upraszczają wdrożenie, także dla mniejszych zespołów.
W razie pytań oficjalne źródła na ksef.podatki.gov.pl oraz GitHubie CIRFMF to najlepsze punkty startowe.
