Błąd integracji to nie tylko odpowiedź HTTP 500
Integracja KSeF może działać technicznie, a mimo to pozostawiać dokumenty bez numeru KSeF, błędnie interpretować status albo przypisywać fakturę do niewłaściwej spółki. Dlatego błędy trzeba analizować na poziomie XML, procesu, autoryzacji i operacji API.
Ministerstwo Finansów publikuje dokumentację API KSeF 2.0, przykładowe scenariusze oraz odpowiedzi na zagadnienia techniczne. Poniższa lista przekłada te materiały na kontrole inżynierskie. Nie jest wykładnią prawa ani katalogiem wszystkich możliwych przypadków.
1. Wysłanie XML bez walidacji FA(3)
MF wskazuje, że faktura musi być zgodna z obowiązującą strukturą logiczną, a brak pól wymaganych przez schemat skutkuje odrzuceniem.
Jak wykrywać: walidować każdy XML lokalnie na aktualnym XSD, a zestaw testów uruchamiać również w CI.
Jak naprawiać: rozdzielić błędy danych źródłowych od błędów generatora. Użytkownik powinien dostać komunikat wskazujący pole ERP, a nie tylko techniczną ścieżkę XML.
Praktyczny sposób wersjonowania reguł i testowania XML opisuje przewodnik mapowania FA(3) do ERP.
2. Testowanie wyłącznie jednej prostej faktury
Pojedynczy dokument bez korekt, walut i dodatkowych podmiotów nie reprezentuje procesu firmy.
Jak wykrywać: zestawić listę typów faktur z ostatniego reprezentatywnego okresu i porównać ją z katalogiem testów.
Jak naprawiać: dodać przypadki graniczne, między innymi korekty, zaliczki, wiele stawek, waluty, dodatkowe role podmiotów i nietypowe terminy płatności.
3. Uznanie wysłania za przyjęcie
Samo przekazanie dokumentu do API nie oznacza nadania numeru KSeF. Faktura ustrukturyzowana jest identyfikowana numerem przydzielonym po przyjęciu jej do systemu.
Jak wykrywać: raportować dokumenty wysłane, które po ustalonym czasie nadal nie mają końcowego statusu albo numeru KSeF.
Jak naprawiać: wdrożyć maszynę stanów i osobny proces sprawdzania wyniku przetwarzania.
4. Mylenie numeru faktury z numerem KSeF
Numer w polu P_2 i numer KSeF to różne wartości. Numer KSeF nie jest elementem wejściowego pliku XML.
Jak wykrywać: przegląd modelu danych i raportów; oba identyfikatory muszą być zapisane w oddzielnych polach.
Jak naprawiać: stosować niezmienny identyfikator techniczny ERP, numer biznesowy dokumentu oraz numer KSeF jako trzy odrębne klucze.
5. Ponowienie, które tworzy drugi dokument
Automatyczne ponowienia bez idempotencji mogą powodować niepewność: integracja nie wie, czy pierwsze żądanie nie dotarło, czy tylko odpowiedź została utracona. MF informuje, że KSeF 2.0 ma reguły wykrywania zdublowanych faktur, ale aplikacja nadal powinna kontrolować własne operacje.
Jak wykrywać: alertować, gdy jeden dokument ERP jest związany z więcej niż jednym żądaniem wysyłki bez jawnej decyzji operatora.
Jak naprawiać: trwale zapisywać identyfikator operacji przed wysłaniem i przed ponowieniem najpierw sprawdzać znany status.
6. Traktowanie paczki jako wyniku „wszystko albo nic”
Według MF podczas wysyłki wsadowej błędne pliki są odrzucane, a prawidłowe mogą zostać przyjęte. System zwraca informację pozwalającą rozpoznać odrzucone pliki.
Jak wykrywać: testować paczkę zawierającą dokument poprawny i celowo błędny.
Jak naprawiać: przechowywać status każdego dokumentu oddzielnie i ponawiać wyłącznie pozycje wymagające obsługi.
7. Brak obsługi limitów API
API ma limity dla grup operacji. Dokumentacja MF rozróżnia między innymi otwieranie sesji, wysyłkę, pobieranie statusu, metadanych i eksport paczki.
Jak wykrywać: mierzyć liczbę żądań według operacji i kontekstu, rejestrować odpowiedzi ograniczające ruch oraz długość kolejki.
Jak naprawiać: stosować kontrolowane tempo, rosnący odstęp ponowień i losowe przesunięcie. Dla regularnie dużego wolumenu rozważyć sesję wsadową zgodnie z zaleceniami MF.
8. Agresywne odpytywanie o status
Odpytywanie co sekundę dla każdej faktury zwiększa ruch i może samo wywołać problem z limitem.
Jak wykrywać: porównać liczbę faktur z liczbą zapytań o status.
Jak naprawiać: użyć harmonogramu z rosnącymi odstępami, grupować pracę i zakończyć polling po stanie końcowym.
9. Jeden kontekst NIP dla wielu spółek
Pobieranie lub wystawianie dla różnych podmiotów wymaga działania w odpowiednim kontekście. MF podaje, że biuro rachunkowe musi autoryzować się osobno w kontekście NIP każdego klienta.
Jak wykrywać: w logu każdej operacji zapisywać kontekst NIP oraz wewnętrzny identyfikator spółki.
Jak naprawiać: rozdzielić kolejki, konfiguracje i uprawnienia per podmiot. Nie wybierać kontekstu na podstawie nazwy kontrahenta.
10. Nadmierne uprawnienia i brak rotacji certyfikatów
Certyfikat KSeF może służyć do uwierzytelnienia, a zakres operacji zależy od uprawnień w danym kontekście. MF ostrzega, że osoba posiadająca certyfikat może działać w imieniu jego właściciela w zakresie dostępnych czynności.
Jak wykrywać: cyklicznie porównywać macierz uprawnień z rolami pracowników, dostawców i systemów.
Jak naprawiać: stosować minimalny zakres, rejestrować właściciela poświadczenia, datę ważności i procedurę unieważnienia. Sekretów nie umieszczać w repozytorium ani logach.
11. Brak kolejki wyjątków dla człowieka
Nie każdy błąd powinien być ponawiany automatycznie. Błędny NIP, brak danych albo konflikt reguł biznesowych wymaga decyzji.
Jak wykrywać: raportować dokumenty, które przekroczyły limit automatycznych prób lub mają błąd nieprzejściowy.
Jak naprawiać: utworzyć kolejkę z właścicielem, opisem przyczyny, bezpieczną korektą danych i pełnym audytem działań.
12. Monitoring samej dostępności API
Zielony test „endpoint odpowiada” nie potwierdza, że faktury są przetwarzane. W kwietniu 2026 r. MF przeprowadziło na środowisku testowym symulację, w której API przyjmowało dokumenty, lecz czasowo nie nadawało numerów KSeF ani nie generowało UPO.
Jak wykrywać: obserwować wiek najstarszego dokumentu oczekującego, czas do numeru KSeF, liczbę odrzuceń i opóźnienie pobierania zakupów.
Jak naprawiać: alarmować na podstawie procesu, nie tylko kodu HTTP.
Minimalny dashboard operacyjny
Warto mierzyć:
- dokumenty przygotowane, wysłane, przyjęte i odrzucone,
- czas od utworzenia w ERP do numeru KSeF,
- wiek najstarszej pozycji w kolejce,
- odrzucenia według przyczyny i wersji mapowania,
- liczbę ponowień,
- wykorzystanie limitów według operacji,
- faktury zakupowe oczekujące na import lub akceptację,
- ważność certyfikatów,
- wynik per spółka i kontekst NIP.
Nie należy publikować arbitralnych progów jako uniwersalnych. Progi alertów powinny wynikać z wolumenu, harmonogramu pracy i krytyczności procesu konkretnej organizacji.
Jeżeli potrzebujesz przełożyć te sygnały na kolejkę interwencji, właścicieli i alerty, zobacz zakres monitoringu integracji KSeF.
Integracja działa, ale dokumenty zatrzymują się w procesie?
Brak numeru KSeF, duplikaty, długo oczekujące statusy i rosnąca kolejka wymagają diagnostyki całego śladu dokumentu, nie tylko sprawdzenia dostępności API. Zobacz ścieżkę diagnostyki błędów KSeF, aby uporządkować objawy, dane potrzebne do analizy i zakres naprawy.
Zgłoś problem z integracją KSeF →
Źródła oficjalne
- Zagadnienia techniczne KSeF — Ministerstwo Finansów
- Informacje dla integratorów IT — Ministerstwo Finansów
- Wsparcie i dokumentacja API KSeF 2.0 — Ministerstwo Finansów
- Dostosowanie limitów API KSeF 2.0 — Ministerstwo Finansów
- Numer KSeF i zbiorczy identyfikator — Ministerstwo Finansów
- Symulacja braku przetwarzania na środowisku testowym — Ministerstwo Finansów
Stan informacji: 31 lipca 2026 r.; źródła oficjalne zweryfikowano 2 sierpnia 2026 r. Materiał ma charakter techniczny i nie zastępuje analizy prawnej ani podatkowej.
