Integracja z KSeF API to kluczowy krok dla firm, które chcą zautomatyzować proces fakturowania i uniknąć ręcznej obsługi Krajowego Systemu e-Faktur. Ministerstwo Finansów udostępnia interfejs programistyczny (API), który umożliwia bezpośrednią komunikację systemów ERP, CRM i dedykowanych aplikacji z KSeF. Dzięki temu faktury mogą być wystawiane, pobierane i weryfikowane w pełni automatycznie — bez konieczności logowania się do portalu KSeF. Dla firm wystawiających setki lub tysiące faktur miesięcznie, integracja przez API to nie tyle wygoda, co konieczność operacyjna. W tym artykule szczegółowo omawiamy architekturę KSeF API, proces uwierzytelniania, strukturę żądań i odpowiedzi, a także najczęstsze problemy techniczne i sposoby ich rozwiązywania. Niezależnie od tego, czy budujesz integrację samodzielnie, czy zlecasz ją zespołowi deweloperów, ten przewodnik dostarczy Ci kompletnej wiedzy potrzebnej do skutecznego wdrożenia. Zanim zaczniesz pracę z produkcyjnym API, koniecznie poznaj środowisko testowe KSeF.
Architektura KSeF API — przegląd techniczny
KSeF API opiera się na architekturze REST i komunikuje się za pomocą protokołu HTTPS. System udostępnia kilka grup endpointów odpowiedzialnych za różne operacje: uwierzytelnianie sesji, wysyłanie faktur, pobieranie faktur, sprawdzanie statusu dokumentów oraz zarządzanie uprawnieniami. Każda operacja wymaga aktywnej sesji interaktywnej lub autoryzacji tokenem.
API obsługuje dwa główne tryby pracy: sesję interaktywną (interactive session) oraz tryb wsadowy (batch). Sesja interaktywna jest odpowiednia dla operacji w czasie rzeczywistym — np. wystawianie pojedynczych faktur z natychmiastową weryfikacją. Tryb wsadowy pozwala na przesyłanie paczek faktur, co jest wydajniejsze przy dużych wolumenach dokumentów.
- REST API z komunikacją po HTTPS
- Endpointy uwierzytelniania — inicjowanie i kończenie sesji
- Endpointy faktur — wysyłanie, pobieranie, weryfikacja statusu
- Endpointy uprawnień — zarządzanie tokenami i upoważnieniami
- Tryb interaktywny i wsadowy (batch)
Uwierzytelnianie w KSeF API — metody autoryzacji
Uwierzytelnianie to pierwszy i najważniejszy krok integracji. KSeF API obsługuje kilka metod autoryzacji, a wybór odpowiedniej zależy od scenariusza użycia. Dla integracji automatycznych (system-to-system) najczęściej stosuje się token autoryzacyjny wygenerowany wcześniej w portalu KSeF lub za pośrednictwem API.
Proces uwierzytelniania przebiega w kilku krokach: najpierw system wysyła żądanie autoryzacji (AuthorisationChallenge), otrzymuje challenge (wyzwanie), następnie podpisuje je odpowiednim kluczem i inicjuje sesję interaktywną (InitSession). Po pomyślnej autoryzacji API zwraca token sesji, który jest używany we wszystkich kolejnych żądaniach.
- Token autoryzacyjny — generowany w portalu KSeF, używany do automatycznej komunikacji
- Podpis kwalifikowany — najwyższy poziom bezpieczeństwa, wymagany przy niektórych operacjach
- Profil zaufany — alternatywa dla podpisu kwalifikowanego, dostępna przez węzeł krajowy
- Pieczęć elektroniczna — stosowana przez podmioty gospodarcze do masowego podpisywania
Inicjowanie sesji interaktywnej — krok po kroku
Inicjowanie sesji interaktywnej wymaga sekwencji precyzyjnych wywołań API. Pierwszym krokiem jest pobranie wyzwania autoryzacyjnego (AuthorisationChallenge) poprzez wysłanie żądania POST z NIP-em podmiotu. System zwraca wyzwanie (challenge) w postaci losowego ciągu znaków oraz znacznika czasu.
Następnie wyzwanie musi zostać podpisane — tokenem, podpisem kwalifikowanym lub w inny dopuszczalny sposób. Podpisane wyzwanie jest przesyłane w żądaniu InitSession wraz z identyfikatorem podmiotu. Po pozytywnej weryfikacji API zwraca token sesji (SessionToken) oraz numer referencyjny sesji. Token jest ważny przez określony czas — zwykle 2 godziny — po czym sesja wygasa i musi zostać odnowiona.
Wysyłanie faktur przez API — struktura żądania
Po ustanowieniu sesji można przystąpić do wysyłania faktur. Faktura musi być przygotowana w formacie XML zgodnym ze schematem FA(2) zdefiniowanym przez Ministerstwo Finansów. Dokument XML jest przesyłany jako treść żądania POST na odpowiedni endpoint (np. /api/online/Invoice/Send).
Żądanie musi zawierać nagłówki z tokenem sesji oraz poprawnie sformatowany dokument XML. API waliduje fakturę pod kątem zgodności ze schematem XSD — jeśli dokument jest nieprawidłowy, zostanie odrzucony z odpowiednim kodem błędu. Po pomyślnym przyjęciu faktury system zwraca numer KSeF (identyfikator faktury w systemie) oraz UPO (Urzędowe Poświadczenie Odbioru).
- Endpoint: POST /api/online/Invoice/Send
- Nagłówek: SessionToken z aktywną sesją
- Body: dokument XML zgodny ze schematem FA(2)
- Odpowiedź: numer KSeF, numer referencyjny, UPO
- Walidacja: automatyczna weryfikacja zgodności z XSD
Pobieranie faktur zakupowych — automatyzacja odbioru dokumentów
Jedną z największych zalet integracji API jest możliwość automatycznego pobierania faktur zakupowych. Zamiast czekać, aż kontrahent prześle fakturę mailem lub pocztą, system może regularnie odpytywać KSeF o nowe dokumenty. Endpoint do pobierania faktur umożliwia filtrowanie po dacie, numerze KSeF oraz NIP-ie wystawcy.
Dla firm o dużym wolumenie zakupów warto zaimplementować mechanizm periodycznego pobierania (polling) — np. co godzinę lub co kilka minut, w zależności od potrzeb biznesowych. Pobrane faktury XML mogą być automatycznie parsowane i importowane do systemu ERP, co eliminuje ręczne wprowadzanie danych i minimalizuje ryzyko błędów.
Obsługa błędów i kodów odpowiedzi API
KSeF API wykorzystuje standardowe kody HTTP do sygnalizowania statusu operacji, uzupełnione o szczegółowe kody błędów specyficzne dla systemu. Znajomość tych kodów jest niezbędna do zbudowania odpornej integracji.
Najczęstsze błędy to: 400 (nieprawidłowe żądanie — zwykle błąd w strukturze XML), 401 (brak autoryzacji — wygasła sesja lub nieprawidłowy token), 403 (brak uprawnień — podmiot nie ma prawa do danej operacji), 404 (nie znaleziono zasobu) oraz 500 (błąd wewnętrzny serwera). Każdy kod błędu jest uzupełniony o szczegółowy komunikat w odpowiedzi JSON, który ułatwia diagnostykę.
- HTTP 400 — błąd walidacji XML, nieprawidłowa struktura żądania
- HTTP 401 — wygasła sesja, nieprawidłowy token autoryzacyjny
- HTTP 403 — brak uprawnień do wykonania operacji
- HTTP 404 — faktura lub zasób nie istnieje
- HTTP 500 — błąd po stronie serwera KSeF, warto ponowić żądanie
- HTTP 503 — system tymczasowo niedostępny (przerwa techniczna)
Tryb wsadowy (batch) — wysyłanie paczek faktur
Tryb wsadowy jest przeznaczony dla podmiotów wystawiających dużą liczbę faktur. Zamiast wysyłać każdą fakturę pojedynczo, można przygotować paczkę (bundle) zawierającą wiele dokumentów i przesłać ją jednym żądaniem. Tryb batch jest bardziej wydajny i zmniejsza liczbę wywołań API.
Paczka faktur musi być podpisana pieczęcią elektroniczną lub podpisem kwalifikowanym. Po przesłaniu paczki system przetwarza ją asynchronicznie — status przetwarzania można sprawdzać za pomocą dedykowanego endpointu. Każda faktura z paczki otrzymuje indywidualny numer KSeF i UPO. Rozwiązania takie jak Finito Pro mogą znacząco uprościć zarządzanie paczkami faktur i monitorowanie ich statusu.
Bezpieczeństwo integracji — najlepsze praktyki
Integracja z KSeF API operuje na wrażliwych danych finansowych, dlatego bezpieczeństwo musi być priorytetem. Tokeny autoryzacyjne i klucze podpisów powinny być przechowywane w bezpiecznym magazynie sekretów (np. HSM, Azure Key Vault, AWS Secrets Manager), a nie w kodzie źródłowym aplikacji.
Komunikacja z API powinna odbywać się wyłącznie przez HTTPS z weryfikacją certyfikatu serwera. Warto zaimplementować logowanie wszystkich operacji (audit log) obejmujące: czas żądania, typ operacji, identyfikator faktury oraz wynik. Logi pozwalają na szybką diagnostykę problemów i stanowią dowód w przypadku sporów z kontrahentami lub organami podatkowymi.
- Przechowywanie tokenów w bezpiecznym magazynie sekretów
- Komunikacja wyłącznie przez HTTPS z weryfikacją certyfikatu
- Rotacja tokenów autoryzacyjnych co 30-90 dni
- Audit log wszystkich operacji na fakturach
- Monitoring dostępności API i alertowanie o awariach
Testowanie integracji w środowisku demo
Przed wdrożeniem integracji na produkcję absolutnie konieczne jest przeprowadzenie kompleksowych testów w środowisku testowym KSeF. Środowisko demo jest dostępne pod osobnym adresem URL i umożliwia pełną symulację wszystkich operacji bez konsekwencji prawnych i podatkowych.
Testy powinny obejmować: pełny cykl życia faktury (wystawienie, pobranie, korekta), obsługę błędów (nieprawidłowy XML, wygasła sesja), scenariusze awaryjne (timeout, przerwa techniczna) oraz testy wydajnościowe przy oczekiwanym wolumenie faktur. Warto także przetestować integrację z systemem JPK, aby upewnić się, że dane z KSeF poprawnie zasilają pliki kontrolne.
Najczęstsze problemy techniczne i ich rozwiązania
Na podstawie doświadczeń deweloperów integrujących swoje systemy z KSeF API można wskazać kilka powtarzających się problemów technicznych. Ich znajomość pozwala zaoszczędzić wiele godzin debugowania.
Typowe problemy to: nieprawidłowe kodowanie znaków w XML (system wymaga UTF-8), błędy w podpisie cyfrowym wynikające z nieprawidłowej kanonikalizacji XML, timeout sesji podczas przetwarzania dużych paczek faktur, oraz problemy z parsowaniem odpowiedzi API w różnych wersjach bibliotek HTTP. Wiele z tych problemów można wykryć wcześnie, stosując walidację XSD po stronie klienta przed wysłaniem dokumentu do API.
- Kodowanie UTF-8 — upewnij się, że XML nie zawiera znaków spoza tego kodowania
- Kanonikalizacja XML — użyj algorytmu C14N przed podpisywaniem
- Timeout sesji — zaimplementuj automatyczne odnawianie sesji
- Walidacja XSD po stronie klienta — wychwytuj błędy przed wysłaniem
- Retry z exponential backoff — obsługuj tymczasowe błędy serwera
Podsumowanie
Integracja z KSeF API to projekt techniczny, który wymaga solidnego zrozumienia architektury systemu, mechanizmów uwierzytelniania oraz struktury faktur XML. Kluczowe kroki to: wybór odpowiedniej metody autoryzacji, implementacja pełnego cyklu życia sesji, walidacja dokumentów XML przed wysłaniem oraz kompleksowe testy w środowisku demo. Dobrze zaprojektowana integracja nie tylko spełni wymogi prawne obowiązkowego KSeF, ale także zautomatyzuje procesy fakturowania i wyeliminuje ręczne operacje. Pamiętaj o bezpieczeństwie — tokeny, klucze i logi to krytyczne elementy każdej integracji. Jeśli nie masz własnego zespołu deweloperskiego, rozważ skorzystanie z gotowego programu do KSeF, który oferuje wbudowaną integrację API.