Integracja API KSeF: jak zaplanować połączenie i testy

Integracja obejmuje cały cykl dokumentu, a nie samo wywołanie endpointu. ERP lub sklep przygotowuje dane, warstwa integracyjna sprawdza wymagane pola, uwierzytelnia się i przesyła fakturę do KSeF. Następnie pobiera status operacji, zapisuje wynik i łączy go z właściwym dokumentem w systemie źródłowym.

Przepływ można opisać tak: system fakturujący -> warstwa integracyjna -> API KSeF -> warstwa integracyjna -> system fakturujący. Warstwa pośrednia może zarządzać kolejką, ponowieniami, historią operacji i alarmami, ale nie powinna samodzielnie rozstrzygać zasad księgowych.

Ministerstwo Finansów udostępnia interaktywną dokumentację opartą na kontrakcie OpenAPI. Zawiera endpointy, parametry, schematy danych, kody odpowiedzi i przykłady wywołań. Przed implementacją oraz aktualizacją sprawdzamy dokumentację API KSeF 2.0 i changelog API KSeF, aby porównać używane kontrakty i schematy z aktualną wersją. Szerszy kontekst projektowania przepływów opisuje nasz przewodnik po integracji systemów i API.

Zakres trzeba rozpisać dla każdego rodzaju dokumentu i zdarzenia, które może zmienić jego treść lub status. Faktura sprzedażowa nie opisuje jeszcze korekty, zaliczki, dokumentu w walucie ani sposobu postępowania po przyjęciu faktury przez KSeF. Przed estymacją zbieramy próbki dokumentów, wskazujemy system źródłowy i uzgadniamy, kto zatwierdza reguły.

Faktury wystawionej i przyjętej w KSeF nie można edytować, anulować ani usunąć. Ministerstwo Finansów wskazuje, że błąd poprawia się wyłącznie przez wystawienie faktury korygującej, dlatego system nie może oferować operatorowi pozornego cofnięcia przyjętego dokumentu. Reguły korekt potwierdza księgowość; szczegóły opisuje oficjalne FAQ KSeF.

Osobno ustalamy, czy system wysyła fakturę automatycznie po wystawieniu, czy dopiero po zatwierdzeniu przez pracownika. Przy sprzedaży internetowej trzeba też określić, który system tworzy dokument i gdzie obsługiwane są poprawki zamówienia. Zakres dla sklepu można oprzeć o wdrożenie KSeF w sklepie internetowym.

Uwierzytelnienie i uprawnienia to powiązane, ale odrębne elementy konfiguracji. Token KSeF zawiera uprawnienia podatnika zadeklarowane przy jego generowaniu, natomiast certyfikat KSeF jest środkiem uwierzytelnienia i sam nie nadaje takich uprawnień. Ministerstwo Finansów potwierdza, że tokeny będą utrzymane bezterminowo; certyfikaty mają inne zastosowania, w tym uwierzytelnianie i obsługę faktur w trybach szczególnych. Przed wyborem metody sprawdzamy aktualne informacje MF o certyfikatach i tokenach oraz wymagania używanego API.

Dane uwierzytelniające muszą odpowiadać środowisku i kontekstowi podmiotu. Dostęp należy ograniczyć do usług, które wykonują operacje, a tokenów, kluczy prywatnych i danych podpisu nie umieszczać w repozytorium, logach ani zgłoszeniach serwisowych. Sekrety przechowujemy w dedykowanym menedżerze sekretów lub chronionej konfiguracji serwera.

W rejestrze dostępu zapisujemy właściciela, kontekst, datę weryfikacji i procedurę odebrania dostępu. Jeśli proces księgowy obejmuje także uzgadnianie płatności, powiązanym zagadnieniem jest parowanie przelewów z fakturami po numerze KSeF.

System powinien odróżniać przyjęcie żądania od przyjęcia faktury. Najpierw przygotowuje dane w wymaganym formacie i waliduje je lokalnie, następnie inicjuje operację w KSeF, zapisuje identyfikator referencyjny i sprawdza status. Po zakończeniu zapisuje rezultat oraz numer KSeF przy niezmiennym identyfikatorze dokumentu w ERP.

Timeout po wysłaniu nie oznacza odrzucenia faktury. Żądanie mogło dotrzeć do KSeF, mimo że aplikacja nie otrzymała odpowiedzi, dlatego system powinien najpierw sprawdzić status wcześniej rozpoczętej operacji. Dopiero po jej rozstrzygnięciu operator lub automat może podjąć kolejną decyzję.

Każda operacja potrzebuje identyfikatora powiązanego z dokumentem źródłowym, znacznika czasu, środowiska i historii statusów. Ponowienie komunikatu do warstwy integracyjnej nie może tworzyć drugiego dokumentu źródłowego. Mechanizm idempotencji powinien rozpoznać ten sam identyfikator zamówienia lub faktury i zwrócić poprzedni wynik zamiast ponownie uruchamiać cały proces.

Reakcję dobieramy do typu problemu, a nie do samego faktu wystąpienia wyjątku. Błąd walidacji wymaga poprawienia danych, błąd uwierzytelnienia wymaga sprawdzenia dostępu, a chwilowy problem sieciowy może wymagać kontrolowanego wznowienia. Limity i kody odpowiedzi należy obsługiwać według bieżącej specyfikacji API, z uwzględnieniem nagłówków i wskazówek dotyczących ponowienia.

Dla dokumentu przechowujemy stan kolejki, liczbę prób i termin następnej próby. Po przekroczeniu ustalonego limitu automat powinien skierować sprawę do operatora, zamiast powtarzać ją bez końca. Logi techniczne nie powinny przechowywać tokenów, kluczy ani pełnych danych osobowych; do diagnozy zwykle wystarczą identyfikatory, statusy i bezpiecznie ograniczone komunikaty.

Środowiska TEST, DEMO i PROD mają różne przeznaczenie i nie wolno traktować ich zamiennie. TEST służy do integracji i wymaga danych zanonimizowanych; przesłane tam faktury nie wywołują skutków prawnych i po określonym czasie są usuwane. DEMO jest środowiskiem przedprodukcyjnym, wymaga rzeczywistych danych uwierzytelniających i faktycznych uprawnień, ale wystawione faktury nie wywołują skutków prawnych. W PROD faktury mają skutki prawne, a dostęp wymaga prawidłowych uprawnień produkcyjnych. Szczegóły i odnośniki do kontraktów środowisk opisuje strona wsparcia MF dla integratorów.

Plan testów powinien obejmować poprawną fakturę, korektę, odrzucenie walidacyjne, utratę dostępu, timeout po wysyłce i powrót po przerwie sieciowej. Po każdym przypadku porównujemy dokument źródłowy, stan integracji i rezultat w KSeF. Przy teście ponowienia przerywamy połączenie po wysłaniu żądania, ale przed odebraniem odpowiedzi; system ma sprawdzić istniejący identyfikator operacji i nie rozpocząć drugiej wysyłki przed ustaleniem wyniku.

Przed przejściem na PROD księgowość potwierdza reguły dokumentów, administrator potwierdza dostęp, a wykonawca przedstawia wyniki scenariuszy technicznych. Warto też przetestować bezpieczny rollback aplikacji, który przywraca poprzednią wersję integracji, ale nie próbuje cofać faktur już przyjętych przez KSeF. W razie potrzeby obsługi dokumentów w Subiekcie GT sprawdź zakres integracji KSeF z Subiektem GT.

Monitoring powinien wykrywać operacje bez rozstrzygniętego statusu oraz kolejki, które przestały się opróżniać. Dla każdej wysyłki zapisujemy identyfikator dokumentu w systemie źródłowym, identyfikator referencyjny KSeF, środowisko, czas wysyłki, czas ostatniego sprawdzenia statusu, wynik i kod błędu. Nie zapisujemy tokenów, kluczy prywatnych ani niepotrzebnej treści faktury.

Alarm powinien uruchomić się, gdy dokument pozostaje bez jednoznacznego wyniku dłużej niż ustalony próg, kolejka rośnie pomimo dostępności usługi albo dokument ma kilka aktywnych operacji. Widok dla operatora powinien pokazywać ostatni status, wiek operacji, liczbę prób i bezpieczne działanie: sprawdź ponownie, popraw dane lub przekaż do księgowości.

Perspektywa KC Mobile: w integracjach rozbieżności często powstają na granicy odpowiedzialności systemów. Jeśli ERP uznaje fakturę za wysłaną w chwili przekazania żądania, a KSeF jeszcze nie zwrócił wyniku, operator nie wie, czy czekać, czy uruchomić kolejny proces. Dlatego definiujemy widoczne stany przejściowe i przypisujemy właściciela decyzji do każdego z nich.

Nakład zależy od liczby systemów wystawiających dokumenty, wariantów faktur oraz wyjątków w procesie. Dodatkową pracę tworzą modyfikacje ERP, obsługa zaliczek i korekt, wymagania sklepu, uprawnienia, monitoring, kolejki oraz utrzymanie zmian po aktualizacjach API. Wycena zależy również od tego, czy zespół ma dostęp do kopii ERP i środowiska testowego.

Do rozmowy technicznej przygotuj przykładowe dokumenty z danymi ograniczonymi do niezbędnych, schemat obecnego przepływu i listę wyjątków. W przypadku wdrożenia w typowym sklepie internetowym cena podana w naszej ofercie zaczyna się od 2 999 zł netto; ostateczny zakres zależy od analizy systemów i procesu. Szczegóły obejmuje oferta wdrożenia KSeF w sklepie, a firmy pracujące na ERP mogą sprawdzić także integracje Optima, Subiekt GT i enova365.

• IFIRMA i KSeF: cennik, dostępne funkcje i koszty
• Data sprzedaży na fakturze: jak ustalić ją w sklepie internetowym
• Porównanie cen Sellasist i Apilo w Excelu: policz koszt dla swojego sklepu
• Program dla małej firmy produkcyjnej: jak wybrać system na obecne potrzeby