E-Invoice Finder
Menu
Kraje Oprogramowanie Terminy Przewodniki Checker Sprawdź obowiązek
ENFRDEPLNL
Polska · operacje KSeF

Monitoring API KSeF i obsługa incydentów w ERP

Monitoruj sesje API KSeF, status faktur, UPO, limity i incydenty. Wdroż procedurę uzgadniania ERP, alarmów i bezpiecznego wznowienia.

Praktyczne podsumowanie:
  • Zakres: obserwuj sesje, pojedyncze faktury, UPO, limity oraz zgodność danych z ERP.
  • Ryzyko: sukces transportu nie potwierdza skutecznego przetworzenia dokumentu.
  • Działanie: wznawiaj idempotentnie i najpierw uzgadniaj każdy wynik o niepewnym stanie.
Sprawdź raport gotowościŹródła oficjalne
Ostatnia aktualizacja: 27 lipca 2026Źródła oficjalneJasne podsumowanieInformacja praktyczna, nie porada prawna
Priorytet dla źródeł oficjalnych
Widoczne daty weryfikacji
Darmowy checker bez rejestracji

Co warto wiedzieć

Przewodnik

Model monitoringu i identyfikatory, które łączą ERP z KSeF

KSeF 2.0 przetwarza zgłoszenia asynchronicznie, dlatego warstwa integracyjna powinna traktować wysłanie jako początek śledzenia, a nie wynik końcowy. Dla każdego zadania zachowaj lokalny identyfikator ERP lub kolejki, referencję sesji, referencję każdej faktury, czas utworzenia i wysłania oraz zwrócony numer KSeF i bieżący status, jeśli są dostępne. Takie powiązanie pozwala odtworzyć drogę dokumentu bez przeszukiwania treści faktury. Dobrym przykładem jest rekord operacyjny łączący zamówienie ERP-7842 z sesją, trzema referencjami faktur i kolejnymi odpowiedziami API. Nie zakładaj jednak, że liczba dokumentów w podsumowaniu sesji dowodzi zgodności wszystkich pozycji. Agregat służy do szybkiego wykrywania rozbieżności, lecz uzgodnienie musi zejść do poziomu pojedynczej faktury. Najczęstszy błąd to zapisanie wyłącznie odpowiedzi transportowej i utrata referencji potrzebnej do późniejszego sprawdzenia. Logi powinny zawierać identyfikatory techniczne i metadane zdarzeń, ale nigdy treść faktury, dane uwierzytelniające, klucze prywatne ani tokeny.

Przewodnik

Cykl życia sesji i faktury oraz moment pobrania UPO

Oficjalny przewodnik integratora z 20 kwietnia 2026 r. opisuje sprawdzanie stanu sesji interaktywnej i wsadowej, odczyt zagregowanych liczników, listowanie faktur w sesji, sprawdzanie dokumentu po jego referencji oraz pobieranie UPO faktury lub całej sesji. Integracja powinna rozróżniać co najmniej wynik nadal oczekujący lub przetwarzany, skutecznie przetworzony i odrzucony zgodnie z aktualną odpowiedzią API, bez nadawania własnych znaczeń kodom. Sukces połączenia HTTP czy przyjęcie żądania przez transport nie uprawnia do oznaczenia faktury jako zaakceptowanej. UPO pobieraj dopiero wtedy, gdy odpowiedź udostępnia właściwą referencję UPO; wcześniej komunikat dla użytkownika powinien mówić, że potwierdzenie nie jest jeszcze dostępne. UPO sesji ułatwia obsługę całej paczki, a UPO pojedynczej faktury pozwala pracować dokument po dokumencie — wybór nie zwalnia z uzgodnienia referencji i wyników. Ryzykiem jest zamknięcie zadania po otrzymaniu jednego UPO mimo nierozpoznanych pozycji w sesji. Bieżąca specyfikacja OpenAPI i oficjalna dokumentacja powinny pozostawać źródłem prawdy w czasie działania, ponieważ endpointy i statusy mogą się zmieniać.

Przewodnik

Pola obserwowalności, metryki i pulpit operacyjny

Pulpit powinien odpowiadać na pytania: ile sesji jest otwartych, ile faktur ma wynik nierozpoznany, ile zakończyło się powodzeniem, ile odrzucono, gdzie brakuje UPO oraz czy liczby ERP zgadzają się z licznikami i listą faktur w KSeF. Rejestruj czas zdarzenia, środowisko, typ operacji, lokalny identyfikator zadania, referencję sesji i faktury, zwrócony status, numer KSeF, referencję UPO, kategorię błędu, liczbę bezpiecznych prób oraz identyfikator śladu. Wrażliwe wartości maskuj, a dostęp do logów ogranicz rolami. Wskaźniki powinny pokazywać wiek nierozpoznanych pozycji, udział odrzuceń, odpowiedzi z ograniczeniem ruchu, wielkość sesji, zaległość kolejki ręcznej i różnice w uzgodnieniu. Nie ustawiaj arbitralnego znaczenia biznesowego na podstawie samego wieku dokumentu; progi alarmowe muszą wynikać z procesu organizacji, aktualnych limitów i oficjalnych komunikatów. Praktyczny widok umożliwia przejście od licznika sesji do listy konkretnych referencji. Antywzorcem jest pulpit pokazujący wyłącznie zieloną dostępność endpointu, podczas gdy faktury pozostają nieuzgodnione.

Przewodnik

Poziomy alarmów i jednoznaczna odpowiedzialność

Klasyfikuj alarmy według wpływu, a nie według wymyślonego czasu oczekiwania. Informacyjny sygnał może dotyczyć przejściowego przetwarzania bez rozbieżności; ostrzeżenie — rosnącej kolejki, powtarzających się odpowiedzi ograniczających ruch albo braku zgodności liczników; alarm krytyczny — utraty możliwości bezpiecznego śledzenia, dużej liczby nierozpoznanych faktur lub potwierdzonego incydentu wpływającego na ciągłość procesu. Każdy alarm powinien wskazywać właściciela: zespół integracji bada komunikację i korelację, finanse ocenia skutki dla obiegu dokumentów, bezpieczeństwo reaguje na podejrzenie ujawnienia danych, a właściciel biznesowy zatwierdza decyzje procesowe. Macierz eskalacji może określać kanał, zastępstwo, wymagane dowody i warunek zamknięcia, lecz nie powinna udawać oficjalnego SLA KSeF. Na przykład seria 429 trafia najpierw do operacji integracji, natomiast odrzucone faktury z błędem danych do właściciela procesu i kolejki korekt. Częsty błąd to alarmowanie każdego timeoutu jako awarii krajowego systemu albo przeciwnie — wyciszenie wszystkich błędów jako chwilowych.

Przewodnik

HTTP 429, limity API i wznowienie bez tworzenia duplikatów

KSeF stosuje limity API i limity kontekstu. Oficjalne wskazówki dla pobierania przyrostowego wymagają obsługi HTTP 429 oraz nagłówka Retry-After, dlatego klient powinien wstrzymać odpowiednie wywołania zgodnie z otrzymaną informacją, ograniczyć współbieżność i zachować stan kursora lub zadania. Nie wpisuj na stałe liczby prób ani interwału odpytywania, jeśli nie wynikają z aktualnej odpowiedzi i dokumentacji. Domyślne limity kontekstu obejmują maksymalnie 10 000 faktur w sesji interaktywnej lub wsadowej, ale limity bieżące i indywidualne mogą być inne i należy je odczytywać dostępnym mechanizmem. Najważniejsza zasada odzyskiwania brzmi: nie wysyłaj automatycznie ponownie dokumentu o niepewnym wyniku. Najpierw użyj zapisanej referencji sesji i faktury, pobierz aktualny stan, przejrzyj listę w sesji i uzgodnij ją z ERP. Dopiero rozpoznany brak może uruchomić idempotentną ścieżkę ponowienia zgodną z projektem integracji. W przeciwnym razie timeout odpowiedzi może zakończyć się dwiema próbami tego samego dokumentu. Kolejka wznowień powinna zachować klucz idempotencji, przyczynę, historię decyzji i dowód uzgodnienia.

Przewodnik

Odrzucenia, kolejka ręczna i uzgodnienie na poziomie dokumentu

Odrzuconej faktury nie należy mieszać z dokumentem nadal przetwarzanym ani z błędem technicznym odczytu statusu. Zapisz aktualny wynik zwrócony przez API, powiąż go z referencją faktury i skieruj do odpowiedniej ścieżki: automatyczna korekta jest dopuszczalna tylko dla jednoznacznych, bezpiecznie obsługiwanych przypadków, a reszta powinna trafić do kolejki dead-letter lub przeglądu ręcznego. Operator musi widzieć źródłowy identyfikator ERP, bezpieczny opis błędu, historię wywołań, aktualny stan KSeF i dozwolone działania — bez ujawniania payloadu czy sekretów w logu. Uzgodnienie porównuje rejestr lokalny z listą faktur sesji, referencjami, numerami KSeF, statusami oraz dostępnymi UPO. Różnica między agregatem sesji a liczbą lokalnych pozycji jest sygnałem do analizy, nie automatycznym dowodem utraty faktury. Przykład: sesja raportuje inną liczbę wyników niż ERP; system blokuje masowe ponowienie, pobiera listę dokumentów i wskazuje brakującą referencję operatorowi. Błędem jest edycja i ponowna wysyłka bez zachowania śladu decyzji, ponieważ utrudnia audyt i może tworzyć duplikaty.

Przewodnik

Komunikaty o niedostępności i granica decyzji o trybie offline lub awaryjnym

Procedura incydentowa musi oddzielać problem lokalnej integracji od oficjalnie ogłoszonego stanu KSeF. Dokumentacja rozróżnia tryb offline24 wybierany przez podatnika, tryb offline podczas ogłoszonej niedostępności, tryb awaryjny podczas oficjalnie ogłoszonej awarii oraz awarię całkowitą. Przejście między tymi trybami ma skutki procesowe i powinno następować na podstawie aktualnych oficjalnych komunikatów oraz zatwierdzonych procedur organizacji, a nie na podstawie domysłu inżyniera. Sam timeout, błąd DNS czy seria nieudanych połączeń nie upoważnia do stwierdzenia, że obowiązuje oficjalny tryb awaryjny. Zespół powinien sprawdzić własną sieć, uwierzytelnienie i limity, zachować dowody techniczne, obserwować komunikaty techniczne Ministerstwa Finansów i eskalować decyzję do wskazanego właściciela. Runbook powinien opisywać osobno każdy tryb, sposób ewidencji dokumentów, warunki powrotu i późniejsze uzgodnienie. Nie jest to porada prawna ani podatkowa; szczegóły należy potwierdzać w bieżących źródłach i wewnętrznej procedurze zatwierdzonej przez właściwych specjalistów.

Przewodnik

Ćwiczenie incydentowe: timeout po wysłaniu paczki i niepewny wynik

W ćwiczeniu tabletop załóżmy, że ERP wysłał sesję, zapisał jej referencję i referencje dokumentów, po czym otrzymał timeout podczas sprawdzania wyniku. Dyżurny najpierw zabezpiecza identyfikator śladu, znaczniki czasu, zanonimizowane metadane żądań i odpowiedzi oraz stan kolejki. Nie przełącza trybu prawnego i nie ponawia całej paczki. Sprawdza oficjalne komunikaty, aktualny stan sesji, zagregowane liczniki i listę faktur, a następnie odpytuje nierozpoznane pozycje po referencji. Dla skutecznie przetworzonych zapisuje zwrócony numer KSeF i pobiera UPO dopiero po pojawieniu się referencji; odrzucone kieruje do analizy, a nadal nierozpoznane pozostawia pod kontrolowanym monitoringiem. Jeśli pojawia się 429, respektuje Retry-After i ogranicza obciążenie. Dowody końcowe obejmują oś czasu, listę korelacji ERP–sesja–faktura, komunikaty urzędowe, decyzje operatorów, wyniki uzgodnienia i przyczynę każdego ponowienia. Ćwiczenie zalicza się nie wtedy, gdy wszystko staje się zielone, lecz gdy zespół potrafi wykazać brak niekontrolowanych duplikatów, ochronę sekretów i pełne rozliczenie dokumentów.

Przewodnik

Kryteria wyboru dostawcy i następne kroki wdrożeniowe

Dostawca integracji powinien pokazać działający mechanizm korelacji sesji i faktur, obsługę asynchronicznych wyników, pobieranie obu zakresów UPO, respektowanie Retry-After, odczyt limitów, idempotentne wznowienia oraz uzgodnienie z ERP. Poproś o demonstrację scenariusza timeoutu, częściowego odrzucenia, rozbieżności licznika, 429 i oficjalnego komunikatu o niedostępności. Oceń, czy logi są pozbawione payloadów i sekretów, czy role są rozdzielone, czy kolejka ręczna ma audytowalną historię oraz czy można zmienić mapowanie statusów wraz z nową wersją OpenAPI bez przebudowy całego systemu. Ryzykowne deklaracje to „każdy status HTTP 200 oznacza przyjętą fakturę”, „UPO jest zawsze natychmiast” i „po timeoutcie po prostu wysyłamy ponownie”. Następny krok to spisanie modelu stanów, inwentaryzacja identyfikatorów, test limitów w bezpiecznym środowisku, przygotowanie pulpitów i alarmów, uruchomienie próbnego uzgodnienia oraz przeprowadzenie ćwiczenia incydentowego. Przed uruchomieniem produkcyjnym porównaj implementację z bieżącym OpenAPI, dokumentacją sesji, limitów i trybów offline oraz najnowszymi komunikatami technicznymi.

Lista kontrolna

Zapisuj lokalny identyfikator ERP, referencję sesji i referencję każdej faktury w jednym rejestrze korelacji.

Rozdziel w modelu danych stan transportu od aktualnego wyniku przetwarzania zwracanego przez KSeF.

Sprawdzaj liczniki sesji, listę jej faktur oraz wyniki pojedynczych dokumentów, zamiast polegać wyłącznie na agregacie.

Pobieraj UPO dopiero po udostępnieniu jego referencji i przypisuj je do właściwej faktury lub sesji.

Maskuj dane w logach i nigdy nie zapisuj treści faktur, tokenów, danych uwierzytelniających ani kluczy prywatnych.

Obsłuż HTTP 429 zgodnie z Retry-After oraz kontroluj współbieżność bez wpisywania arbitralnych retry.

Odczytuj aktualne limity i dziel pracę tak, aby nie przekraczać limitów kontekstu ani API.

Przed ponowieniem dokumentu o niepewnym stanie wykonaj odczyt statusu i pełne uzgodnienie, aby uniknąć duplikatu.

Skieruj odrzucenia i nierozpoznane przypadki do audytowalnej kolejki ręcznej z jasno wskazanym właścicielem.

Ćwicz scenariusze incydentowe i uzależniaj zmianę trybu offline lub awaryjnego od oficjalnych komunikatów i zatwierdzonej procedury.

Najczęstsze pytania

Jak sprawdzić status sesji KSeF?

Użyj funkcji API przewidzianej do odczytu jednej sesji, zachowując jej referencję od momentu utworzenia. Dla pełnego obrazu porównaj stan sesji, zagregowane liczniki i listę faktur z lokalnym rejestrem ERP. Sam zbiorczy wynik nie potwierdza statusu każdej faktury, dlatego rozbieżności należy wyjaśnić na poziomie referencji dokumentów.

Kiedy można pobrać UPO?

Dopiero gdy aktualna odpowiedź API wskazuje, że właściwa referencja UPO jest dostępna. Do tego czasu aplikacja powinna komunikować oczekiwanie lub przetwarzanie zgodnie z bieżącym stanem, zamiast obiecywać potwierdzenie. Po pobraniu zapisz powiązanie UPO z sesją albo fakturą oraz metadane audytowe.

Czy wystarczy UPO sesji, czy potrzebne jest UPO faktury?

API przewiduje pobieranie UPO zarówno dla faktury, jak i całej sesji, gdy odpowiedź udostępnia odpowiednią referencję. Zakres używany w procesie zależy od potrzeb operacyjnych i obowiązujących procedur, lecz UPO sesji nie zastępuje uzgodnienia każdej referencji faktury z ERP. Trzeba umieć wskazać wynik konkretnego dokumentu.

Jakie dane przechowywać do monitoringu i audytu?

Przechowuj referencję sesji, referencje faktur, lokalny identyfikator ERP lub zadania, znaczniki czasu, aktualne statusy, zwrócone numery KSeF, referencje UPO i historię decyzji. Logi nie powinny zawierać payloadów faktur, danych uwierzytelniających, tokenów ani kluczy prywatnych. Retencję i dostęp ustal zgodnie z polityką organizacji.

Co zrobić, gdy faktura długo ma stan oczekujący lub przetwarzany?

Nie przypisuj własnego znaczenia czasowi oczekiwania i nie uznawaj faktury ani za przyjętą, ani za odrzuconą bez aktualnej odpowiedzi. Kontynuuj kontrolowany odczyt z poszanowaniem limitów, sprawdź sesję i dokument po referencji oraz obserwuj oficjalne komunikaty. Eskaluj zgodnie z wewnętrzną macierzą wpływu, bez wymyślania oficjalnego SLA.

Jak reagować na HTTP 429 i Retry-After?

Potraktuj 429 jako sygnał ograniczenia ruchu i zastosuj wartość Retry-After zgodnie z aktualną dokumentacją oraz odpowiedzią serwera. Ogranicz współbieżność, zachowaj stan zadania i nie uruchamiaj niekontrolowanej pętli prób. Sprawdź również bieżące lub indywidualne limity, ponieważ mogą różnić się od wartości domyślnych.

Czy po timeoutcie można bezpiecznie wysłać fakturę ponownie?

Nie automatycznie. Timeout nie dowodzi, że pierwsza próba nie została przetworzona, więc ponowne wysłanie może utworzyć niepożądany duplikat. Najpierw odczytaj sesję i fakturę po zapisanych referencjach, porównaj listę dokumentów z ERP i udokumentuj wynik uzgodnienia; dopiero potem uruchom właściwą, idempotentną ścieżkę odzyskiwania.

Czy timeout oznacza możliwość przejścia na tryb awaryjny KSeF?

Nie. Timeout może wynikać z sieci lokalnej, uwierzytelnienia, limitu lub przejściowego problemu i sam nie stanowi oficjalnego ogłoszenia awarii. Dokumentacja odróżnia offline24, offline podczas ogłoszonej niedostępności, tryb awaryjny podczas oficjalnie ogłoszonej awarii i awarię całkowitą; decyzję należy oprzeć na oficjalnych komunikatach i zatwierdzonej procedurze.

Kluczowe przepisy, formaty i pojęcia

Komisja EuropejskaEN 16931Dyrektywa 2014/55/UEustrukturyzowana faktura elektronicznaMonitoring API KSeF i procedura obsługi incydentówPolska

Czytaj dalej

Źródła oficjalne

Priorytetowo traktujemy oficjalne źródła rządowe i UE, gdy są dostępne, oraz pokazujemy daty weryfikacji.