KSeF API

API Krajowego Systemu e-Faktur (KSeF) to interfejs programistyczny typu REST, który umożliwia automatyczną komunikację systemów informatycznych z platformą Ministerstwa Finansów. Dzięki API firmy mogą programowo wystawiać faktury, pobierać dokumenty zakupowe, sprawdzać statusy przesyłek i zarządzać uprawnieniami — bez konieczności logowania się do portalu webowego. Dla średnich i dużych przedsiębiorstw integracja przez API jest jedynym sensownym sposobem obsługi KSeF przy większych wolumenach dokumentów. W tym artykule przedstawiamy kompletny przewodnik techniczny po API KSeF — od uwierzytelniania, przez kluczowe endpointy, aż po obsługę błędów i najlepsze praktyki implementacyjne. Artykuł jest skierowany zarówno do programistów, jak i do osób decyzyjnych planujących integrację systemów z KSeF.

Architektura API KSeF — przegląd techniczny

API KSeF jest zaprojektowane jako RESTful API komunikujące się za pośrednictwem protokołu HTTPS. Wymiana danych odbywa się w formacie JSON (dla metadanych i komunikatów sterujących) oraz XML (dla treści faktur w schemacie FA(2)). API udostępnia kilka grup endpointów: sesyjne (zarządzanie sesjami uwierzytelniającymi), fakturowe (wysyłanie i pobieranie faktur), statusowe (sprawdzanie statusów przesyłek) oraz administracyjne (zarządzanie uprawnieniami i tokenami).

System KSeF działa w dwóch środowiskach: produkcyjnym (do wystawiania prawnie wiążących faktur) i testowym (do testowania integracji bez skutków prawnych). Adresy bazowe różnią się — środowisko testowe jest dostępne pod adresem ksef-test.mf.gov.pl, a produkcyjne pod ksef.mf.gov.pl. Każde środowisko ma własną bazę danych — faktury wystawione w środowisku testowym nie istnieją w produkcji i odwrotnie. Więcej o testowaniu w artykule o testowym środowisku KSeF.

API obsługuje zarówno tryb interaktywny (sesja z tokenem, operacje pojedyncze), jak i tryb wsadowy (batch) do przesyłania dużej liczby faktur jednocześnie. Tryb wsadowy jest kluczowy dla firm wystawiających setki lub tysiące faktur dziennie — pozwala na przesłanie paczki dokumentów w jednym żądaniu HTTP i asynchroniczne śledzenie statusu przetwarzania każdej faktury w paczce.

Uwierzytelnianie i autoryzacja w API KSeF

Dostęp do API KSeF wymaga uwierzytelnienia, które może odbywać się na trzy sposoby: za pomocą podpisu kwalifikowanego (certyfikat kwalifikowany), za pomocą profilu zaufanego (ePUAP) lub za pomocą tokena autoryzacyjnego wygenerowanego w systemie KSeF. Dla integracji systemowych (M2M — machine-to-machine) najczęściej stosowany jest token autoryzacyjny, ponieważ nie wymaga interakcji użytkownika przy każdym żądaniu.

Proces uwierzytelnienia tokenem przebiega dwuetapowo. Najpierw wywołuje się endpoint /api/online/Session/InitToken, przesyłając zaszyfrowany challenge (wyzwanie) podpisany kluczem prywatnym powiązanym z tokenem. Klucz publiczny musi być wcześniej zarejestrowany w KSeF (przez portal webowy, z użyciem podpisu kwalifikowanego). Po pomyślnej weryfikacji system zwraca SessionToken — identyfikator sesji, który należy dołączać do każdego kolejnego żądania w nagłówku Authorization.

Sesja ma ograniczony czas życia (domyślnie 2 godziny od ostatniej aktywności) i może być jawnie zamknięta przez endpoint /api/online/Session/Terminate. Ważne jest, aby systemy integracyjne implementowały mechanizm automatycznego odnawiania sesji — jeśli sesja wygaśnie w trakcie przetwarzania paczki faktur, nieprzetworzone dokumenty nie zostaną wysłane. Token autoryzacyjny można wygenerować dla konkretnego NIP-u i zakresu uprawnień (np. tylko wystawianie, tylko odczyt, pełny dostęp).

Kluczowe endpointy API KSeF

API KSeF udostępnia kilkadziesiąt endpointów, ale w codziennej pracy najważniejsze są te związane z wystawianiem i pobieraniem faktur. Endpoint POST /api/online/Invoice/Send służy do wysłania pojedynczej faktury — w ciele żądania przesyła się plik XML faktury ustrukturyzowanej w formacie FA(2), zakodowany w Base64. Po pomyślnym przetworzeniu system zwraca numer KSeF faktury (elementReferenceNumber) oraz znacznik czasu (invoiceTimestamp).

Do pobierania faktur zakupowych służy endpoint GET /api/online/Invoice/Get/{KSeFReferenceNumber}, który zwraca pełny XML faktury na podstawie jej numeru KSeF. Endpoint POST /api/online/Query/Invoice/Sync umożliwia wyszukiwanie faktur wg kryteriów (NIP kontrahenta, zakres dat, typ dokumentu) i zwraca listę metadanych pasujących faktur. Dla dużych wolumenów zalecany jest endpoint asynchroniczny POST /api/online/Query/Invoice/Async, który uruchamia zapytanie w tle i pozwala pobrać wyniki po zakończeniu przetwarzania.

Endpoint GET /api/online/Invoice/Status/{InvoiceElementReferenceNumber} pozwala sprawdzić aktualny status faktury — czy została zaakceptowana, odrzucona, czy jest w trakcie przetwarzania. To kluczowe dla systemów, które muszą potwierdzić wystawienie faktury przed np. wygenerowaniem dokumentu WZ, wysłaniem powiadomienia do klienta czy zainicjowaniem procesu płatności.

• POST /api/online/Session/InitToken — rozpoczęcie sesji (uwierzytelnianie tokenem)
• DELETE /api/online/Session/Terminate — zakończenie sesji
• POST /api/online/Invoice/Send — wysłanie faktury
• GET /api/online/Invoice/Get/{ref} — pobranie faktury po numerze KSeF
• POST /api/online/Query/Invoice/Sync — synchroniczne wyszukiwanie faktur
• POST /api/online/Query/Invoice/Async — asynchroniczne wyszukiwanie faktur
• GET /api/online/Invoice/Status/{ref} — sprawdzenie statusu faktury
• POST /api/online/Batch/Send — wysłanie paczki faktur (tryb wsadowy)

Przykłady integracji — wysyłanie faktury przez API

Poniżej przedstawiamy uproszczony schemat integracji z API KSeF w pseudokodzie, który ilustruje typowy flow wysyłania faktury. Krok 1: Wygenerowanie pliku XML faktury zgodnego ze schematem FA(2) — na podstawie danych z systemu ERP. Krok 2: Lokalna walidacja XML względem schematu XSD — aby wykryć błędy przed wysłaniem i uniknąć odrzuceń. Krok 3: Uwierzytelnienie — wywołanie InitToken z zaszyfrowanym challengem i odebranie SessionToken.

Krok 4: Zakodowanie XML faktury w Base64 i wysłanie żądania POST na endpoint /api/online/Invoice/Send z nagłówkiem Authorization: Bearer {SessionToken}. Krok 5: Odebranie odpowiedzi — w przypadku sukcesu (HTTP 200) system zwraca numer KSeF i timestamp. W przypadku błędu (HTTP 400, 422) odpowiedź zawiera kod błędu i opis problemu. Krok 6: Zapisanie numeru KSeF w systemie ERP przy odpowiedniej fakturze — ten numer będzie potrzebny przy wystawianiu korekt i przy raportowaniu w JPK_VAT.

Warto zaimplementować mechanizm retry z exponential backoff dla błędów sieciowych (HTTP 5xx, timeout) — KSeF może być tymczasowo niedostępny z powodu obciążenia lub prac serwisowych. Jednocześnie nie należy ponawiać żądań dla błędów walidacyjnych (HTTP 4xx) bez uprzedniej naprawy danych. Cały proces powinien być logowany — zarówno żądania, jak i odpowiedzi — co ułatwia diagnozowanie problemów. Szczegóły formatu faktury ustrukturyzowanej FA(2) omawiamy w osobnym artykule.

Obsługa błędów i kody odpowiedzi API KSeF

API KSeF stosuje standardowe kody odpowiedzi HTTP uzupełnione o szczegółowe kody błędów specyficzne dla systemu. HTTP 200 oznacza sukces — faktura została przyjęta lub zapytanie zwróciło wyniki. HTTP 400 (Bad Request) sygnalizuje błąd w strukturze żądania — np. nieprawidłowy format JSON, brak wymaganych nagłówków. HTTP 401 (Unauthorized) oznacza problem z uwierzytelnieniem — wygasła sesja lub nieprawidłowy token.

HTTP 422 (Unprocessable Entity) to najczęściej spotykany błąd przy wysyłaniu faktur — oznacza, że faktura nie przeszła walidacji biznesowej. Odpowiedź zawiera szczegółowy opis problemu w polu errorMessage oraz kod w polu errorCode. Przykładowe kody to: 20201 (niezgodność NIP sprzedawcy z sesją), 20301 (nieprawidłowa suma kontrolna), 20401 (brak wymaganego pola), 20501 (nieprawidłowy numer KSeF faktury korygowanej).

HTTP 429 (Too Many Requests) oznacza przekroczenie limitu wywołań API — KSeF stosuje rate limiting, aby zapobiec przeciążeniu systemu. W nagłówku odpowiedzi Retry-After podany jest czas (w sekundach), po którym można ponowić żądanie. HTTP 503 (Service Unavailable) sygnalizuje chwilową niedostępność — np. okno serwisowe. Systemy integracyjne powinny obsługiwać wszystkie te scenariusze i informować użytkownika o statusie operacji w zrozumiały sposób.

Bezpieczeństwo integracji z API KSeF

Bezpieczeństwo komunikacji z API KSeF opiera się na kilku mechanizmach. Po pierwsze, cała komunikacja odbywa się przez HTTPS (TLS 1.2 lub nowszy), co zapewnia szyfrowanie danych w transporcie. Po drugie, uwierzytelnianie oparte na tokenach i podpisach kwalifikowanych gwarantuje, że tylko upoważnione podmioty mają dostęp do danych. Po trzecie, sesje mają ograniczony czas życia, co minimalizuje ryzyko nieautoryzowanego dostępu w przypadku przejęcia tokena sesyjnego.

Z perspektywy integrującego systemu kluczowe jest bezpieczne przechowywanie klucza prywatnego (używanego do szyfrowania challenge przy uwierzytelnianiu) oraz tokena autoryzacyjnego. Klucz prywatny powinien być przechowywany w HSM (Hardware Security Module) lub przynajmniej w zaszyfrowanym magazynie kluczy (keystore). Token sesyjny nie powinien być logowany w jawnej postaci — w logach należy zapisywać jedynie jego zamaskowaną wersję.

Warto również zaimplementować monitoring bezpieczeństwa — alertowanie o nietypowych wzorcach aktywności (np. nagły wzrost liczby wywołań API, próby uwierzytelnienia z nieznanego adresu IP, wielokrotne błędy 401). KSeF nie udostępnia publicznie listy dozwolonych adresów IP (whitelist), ale przyszłe wersje API mogą wprowadzić dodatkowe mechanizmy kontroli dostępu. Odpowiednie zabezpieczenie integracji to element szerszego przygotowania do obowiązku KSeF od 2026 roku.

Narzędzia i biblioteki do integracji z KSeF API

Na rynku dostępnych jest coraz więcej narzędzi ułatwiających integrację z API KSeF. Dla programistów .NET popularna jest biblioteka ksef-utils-dotnet (open source), która implementuje logikę uwierzytelniania, generowania XML i komunikacji z API. Dla Java istnieje ksef-java-client, a dla Pythona — ksef-python-sdk. Wszystkie te biblioteki są tworzone przez społeczność i nie są oficjalnie wspierane przez Ministerstwo Finansów, ale znacząco przyspieszają proces integracji.

Ministerstwo Finansów udostępnia oficjalną specyfikację API w formacie OpenAPI (Swagger), która pozwala na automatyczne generowanie klientów API w dowolnym języku programowania. Specyfikacja jest dostępna pod adresem ksef.mf.gov.pl/api (środowisko produkcyjne) i ksef-test.mf.gov.pl/api (środowisko testowe). Narzędzia takie jak Swagger Codegen lub OpenAPI Generator mogą na jej podstawie wygenerować gotowy kod klienta w Javie, C#, Pythonie, PHP, Go i wielu innych językach.

Dla firm, które nie chcą samodzielnie implementować integracji, jednym z rozwiązań na polskim rynku jest Finito Pro, które oferuje gotową integrację z KSeF bez konieczności pisania kodu. Alternatywnie, dostępne są platformy pośredniczące (tzw. middleware KSeF), które udostępniają uproszczone API lub integrują się bezpośrednio z popularnymi systemami ERP. Wybór odpowiedniego programu do KSeF zależy od specyfiki firmy i posiadanej infrastruktury IT.

Limity i ograniczenia API KSeF

API KSeF ma określone limity wydajnościowe, które należy uwzględnić przy projektowaniu integracji. Rate limiting ogranicza liczbę żądań z jednego tokena/sesji do kilkudziesięciu na minutę (dokładne limity mogą się zmieniać i są publikowane w dokumentacji technicznej). Maksymalny rozmiar pojedynczej faktury XML to 16 MB — w praktyce nawet bardzo rozbudowane faktury (z setkami pozycji) rzadko przekraczają kilkaset kilobajtów.

Tryb wsadowy (batch) pozwala na przesłanie do 100 faktur w jednej paczce. Czas przetwarzania paczki zależy od obciążenia systemu — w godzinach szczytu (np. ostatnie dni miesiąca, gdy firmy masowo wystawiają faktury) czas odpowiedzi może się wydłużyć. API nie gwarantuje SLA (Service Level Agreement) w formie umowy — dostępność systemu jest deklarowana na poziomie 99,5% w skali roku, ale bez formalnych zobowiązań odszkodowawczych.

Zapytania wyszukujące (Query) mogą zwrócić maksymalnie 100 rekordów na stronę — do pobrania większej liczby wyników konieczna jest paginacja. Zapytania asynchroniczne mają limit czasu przetwarzania (timeout) — jeśli zapytanie obejmuje bardzo dużą liczbę faktur, może być konieczne zawężenie kryteriów (np. krótszy zakres dat). Te ograniczenia mają istotne znaczenie dla firm przetwarzających tysiące faktur miesięcznie i powinny być uwzględnione w architekturze rozwiązania już na etapie planowania wdrożenia KSeF.

Podsumowanie

API KSeF to potężne narzędzie umożliwiające pełną automatyzację fakturowania elektronicznego w Polsce. Jego architektura REST, obsługa trybów synchronicznego i asynchronicznego oraz rozbudowany system uwierzytelniania pozwalają na budowanie elastycznych integracji dostosowanych do potrzeb zarówno małych, jak i dużych organizacji. Kluczem do udanej integracji jest dokładne zapoznanie się ze specyfikacją OpenAPI, przeprowadzenie kompleksowych testów w środowisku testowym oraz implementacja solidnej obsługi błędów i mechanizmów bezpieczeństwa. Firmy planujące integrację powinny rozpocząć prace jak najwcześniej — przepustowość środowiska testowego jest ograniczona, a doświadczenia z testów pozwalają uniknąć problemów po uruchomieniu obowiązkowego KSeF. Niezależnie od wybranej technologii, znajomość struktury faktury ustrukturyzowanej FA(2) oraz zasad rozliczeń VAT w kontekście KSeF jest niezbędna dla prawidłowej implementacji.