API KSeF 2.0: jak działa integracja krok po kroku, od logowania do UPO

Integracja z KSeF to nie jedno wywołanie „wyślij fakturę”. Program musi się zalogować, otworzyć sesję, zaszyfrować fakturę, wysłać ją, odczytać status, pobrać UPO i obsłużyć błędy oraz limity. Ministerstwo Finansów publikuje do tego specyfikację OpenAPI i oficjalne biblioteki w C# i Javie. Poniżej opisuję, jak te elementy składają się w całość i gdzie najczęściej pojawiają się problemy.

1. Uwierzytelnienie: challenge, podpis albo token

Program pobiera wyzwanie ważne 10 minut i potwierdza tożsamość podpisem XAdES (np. certyfikatem KSeF, kwalifikowanym podpisem, pieczęcią firmową) albo tokenem KSeF zaszyfrowanym kluczem publicznym MF. Po sprawdzeniu statusu dostaje access token na kilkanaście minut i refresh token na maksymalnie 7 dni. Szczegóły w tekstach o błędzie uwierzytelnienia i tokenie KSeF.

2. Sesja: interaktywna albo wsadowa

3. Szyfrowanie i wysyłka faktury

Faktura nie jest wysyłana jawnym tekstem. Program szyfruje plik XML algorytmem AES-256-CBC kluczem symetrycznym, który sam jest szyfrowany algorytmem RSA-OAEP kluczem publicznym KSeF. Do tego dochodzą skróty SHA-256 i rozmiary pliku przed i po szyfrowaniu, które KSeF porównuje. Błąd w którymkolwiek z tych elementów kończy się odrzuceniem, zanim system w ogóle przeczyta treść faktury.

4. Status faktury i UPO

Wysyłka jest asynchroniczna. Program odpytuje o status faktury, aż dostanie 200 (sukces, numer KSeF) albo kod błędu, np. 440 duplikat czy 450 błąd semantyki. Dla przyjętej faktury KSeF udostępnia UPO, czyli urzędowe poświadczenie odbioru, pod adresem, który wygasa po określonym czasie. Mapę wszystkich kodów zebrałem w przeglądzie błędów KSeF.

5. Pobieranie faktur kosztowych

Druga strona integracji to odbiór faktur zakupowych. API pozwala pobrać fakturę po numerze KSeF, listę metadanych według filtrów albo zlecić asynchroniczny eksport paczki. Dla synchronizacji z systemem księgowym dokumentacja rekomenduje eksport przyrostowy w przylegających oknach czasowych. Opisuję go w tekście o pobieraniu faktur z KSeF.

6. Limity, środowiska i uprawnienia

• Limity żądań liczone na parę kontekst i adres IP, z odpowiedzią 429 i nagłówkiem Retry-After. Szczegóły w tekście o limitach API.
• Trzy środowiska: TEST, DEMO i produkcja, opisane w tekście o środowisku testowym KSeF.
• Uprawnienia do wystawiania (InvoiceWrite) i odczytu (InvoiceRead) w kontekście NIP, opisane w tekście o nadawaniu uprawnień.

Gotowa wtyczka czy integracja na zamówienie

Dla typowego sklepu na popularnej platformie gotowa wtyczka często wystarczy. Integracja na zamówienie ma sens, gdy faktury powstają w kilku systemach, gdy firma ma nietypowe procesy (np. faktury zbiorcze, sprzedaż w wielu walutach, rozbudowane korekty) albo gdy dane mają zostać w Twojej infrastrukturze.

Bezpieczeństwo integracji z KSeF

• Tokeny i klucze prywatne certyfikatów w menedżerze sekretów, a nie w kodzie, repozytorium czy bazie danych jawnym tekstem.
• Osobne dane dostępowe dla środowisk TEST, DEMO i produkcji.
• Minimalne uprawnienia: moduł sprzedaży bez prawa pobierania faktur kosztowych i odwrotnie.
• Logi z pełnymi odpowiedziami KSeF, ale bez tokenów i treści faktur w zwykłym logu aplikacji.

Jak wygląda typowy projekt integracji

1. 1.Analiza: skąd biorą się faktury, kto je wystawia, ile ich jest w szczycie, jakie są wyjątki (korekty, zaliczki, sprzedaż zagraniczna).
2. 2.Moduł KSeF na środowisku TEST: logowanie, wysyłka, statusy, pobieranie.
3. 3.Połączenie z systemem źródłowym: sklep, ERP albo CRM, z kolejką i obsługą błędów.
4. 4.Testy na DEMO z prawdziwym wolumenem i limitami produkcyjnymi.
5. 5.Start na produkcji pod kontrolą i monitoring pierwszych tygodni.

Najwięcej czasu zajmuje zwykle nie samo API KSeF, tylko dane po stronie firmy: niespójne adresy klientów, kilka numeracji faktur, korekty robione ręcznie poza systemem. Uporządkowanie ich na początku skraca resztę projektu.

Źródła: dokumentacja API KSeF 2.0 z oficjalnymi bibliotekami w C# i Javie oraz serwis KSeF.