Integracja z KSeF API — 7 błędów, które warto przewidzieć

Każde wdrożenie KSeF API przy realnym ruchu napotka podobne problemy techniczne. Ten post zbiera 7 pułapek, które widać dopiero wtedy, gdy faktury zaczynają płynąć regularnie — nie w testach na kilku dokumentach.

Oparte na: dokumentacji technicznej MF, wymaganiach procesu fakturowania i art. 106na–106nh ustawy o VAT.

1. 429 Too Many Requests — zbyt agresywna wysyłka

Najczęstsze błędy API są przewidywalne, jeśli projektujesz integrację jako przepływ z limitami, retry i kolejką.

KSeF może ograniczyć ruch, jeśli integracja wysyła lub sprawdza zbyt wiele żądań w krótkim czasie. Błąd 429 Too Many Requests nie powinien zatrzymać procesu na stałe — powinien uruchomić pauzę, ponowienie i czytelny status faktury.

Co widzi klient:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "exception": {
    "exceptionDetailList": [
      {
        "exceptionCode": 20195,
        "exceptionDescription": "Przekroczono dobowy limit wystawień faktur"
      }
    ]
  }
}

Kto to łapie: firmy z większym wolumenem faktur oraz biura rachunkowe obsługujące wielu klientów, jeśli próbują traktować KSeF jak jeden wspólny strumień bez kolejek i limitowania.

Obejście:

1. Nie używaj wspólnego kontekstu dla wielu klientów — każdy klient ma własny.
2. Wysyłaj faktury przez kolejkę, nie wszystkie naraz.
3. Rozłóż masowe operacje w czasie, nie zostawiaj ich na ostatni dzień miesiąca.
4. Obsługuj odpowiedź Retry-After i ponawiaj wysyłkę po pauzie.

2. Limity odpytywania — pętla bez pauzy

Drugi błąd to sprawdzanie statusu dokumentów zbyt często. Jeśli integracja po wysłaniu faktury odpytuje KSeF w pętli, szybko zamienia normalny proces w techniczny hałas.

Co to oznacza dla narzędzia:

• Każdy dokument powinien mieć status: wysłany, czeka na odpowiedź, zaakceptowany, odrzucony albo do ponowienia.
• Sprawdzanie statusu powinno działać przez kolejkę z opóźnieniem między próbami.
• Równoległe wysyłanie wielu paczek wymaga lokalnego limitowania per NIP i czytelnego logu zdarzeń.

W praktyce użytkownik nie musi widzieć technicznych prób połączenia. Powinien widzieć prosty komunikat: dokument czeka, został przyjęty albo wymaga reakcji.

3. Niezgodność FA(3) XSD vs walidacja biznesowa MF

Plik FA(3) może przejść walidację XSD (struktura OK), ale zostać odrzucony przez MF z powodu błędów biznesowych.

Przykład — faktura z polem P_8B (rabat post-ekspedycyjny) ale bez P_8A:

<!-- XSD OK, ale MF zwraca: -->
{
  "exceptionCode": 1021,
  "exceptionDescription": "P_8B wymaga wcześniejszego P_8A w korygowanej fakturze źródłowej"
}

Lista takich reguł biznesowych nie jest publikowana kompleksowo. Znaleziono w dokumentacji ~40 reguł, z praktyki kolejne ~80. Twoje narzędzie musi znać obie warstwy walidacji.

Które reguły biznesowe są najczęściej łamane:

• Faktura korygująca bez referencji do oryginału (IdFakturyKorygowanej)
• MPP oznaczony dobrowolnie, ale kwota < 15k (MF zwraca warning, nie error)
• NrKSeF kontrahenta w formacie starym (pre-2024)
• Rozliczenie w walucie innej niż PLN bez pola KursWaluty

4. Timeout przy sesji długiej (> 2h)

KSeF sesja API wygasa po 120 minutach bezczynności (dokumentacja MF, sekcja "Zarządzanie sesjami"). Operacje na wygasłej sesji zwracają 401 Unauthorized z komunikatem "Session expired".

Problem: niektóre narzędzia trzymają otwartą sesję zbyt długo dla wielu operacji. Potem trafiają na wygaśnięcie sesji w środku wysyłki.

Rozwiązanie:

• Trzymaj sesję krótko: otwórz, wyślij paczkę faktur, zamknij.
• Przy błędzie autoryzacji odśwież sesję i ponów ostatnią operację.
• Nie zakładaj, że sesja będzie działała cały dzień bez przerwy.

5. Bufor offline — więcej niż art. 106nc mówi

Art. 106nc UoVAT pozwala wystawić fakturę offline gdy KSeF nie działa. Ale nie mówi:

• Jak udowodnić awarię? MF może później zaprzeczyć, że była. Potrzebujesz logów.
• Co jeśli awaria trwa 25 godzin? Przepis mówi "24h od przywrócenia", nie "24h od awarii". Ale interpretacja jest ambiwalentna.
• Czy faktura offline musi być w XML czy papierowa OK? Rozporządzenie MF z 2023 pozwala na PDF + papier w tym okresie.

Praktyczna implementacja bufora offline:

interface OfflineEvent {
  timestamp: Date; // kiedy wykryłeś awarię
  httpStatus: number; // 5xx / 0 (timeout) / null (TLS error)
  retryAfter?: number; // z nagłówka, jeśli był
  invoiceIds: string[]; // faktury w buforze
  resolvedAt?: Date; // kiedy auto-resend się udał
}

Każda awaria → wpis. Każdy resend → referencja do oryginalnego wpisu. W razie kontroli US — ten log to Twoja ochrona.

6. OAuth2 vs certyfikat kwalifikowany — który wybrać

KSeF 2.0 akceptuje dwie metody uwierzytelniania:

A) Certyfikat kwalifikowany (RSA, x509)

• Działa od razu, bez zewnętrznego serwera
• Ważność 1-3 lata (trzeba monitorować)
• Koszt: ~200-400 PLN/rok
• Ryzyko: utrata pliku .pfx = utrata dostępu na godziny (wyrobienie nowego)

B) OAuth2 (Profil Zaufany ePUAP)

• Wymaga redirect flow — user loguje się przez pz.gov.pl
• Token ważny 60 minut, refresh token na 30 dni
• Koszt: 0 PLN
• Ryzyko: Profil Zaufany może być zablokowany przez MC, utrata dostępu
• Dobre dla interaktywnych app, mniej dobre dla background jobs

Dla narzędzia typu SaaS: OAuth2 dla pierwszej konfiguracji (user-friendly) + certyfikat kwalifikowany dla stabilnej produkcji. Hybrid OK.

7. Różnice środowisko Test vs Prod

MF hosts dwa środowiska:

Parametr	Test	Prod
Endpoint	api-test.ksef.mf.gov.pl	api-ksef.mf.gov.pl
Lifetime faktur	30 dni (auto-cleanup)	10 lat
Limity ruchu	inne niż produkcyjne	docelowe ograniczenia
Walidacja	Luźniejsza	Pełna
Dane testowe	Publicznie dostępne	Ściśle prywatne

Typowe błędy przy przejściu z testów na produkcję:

• Zapomniana zmiana adresu środowiska → wysyłasz faktury do testów, ale klient widzi "brak w KSeF"
• Certyfikat z Test nie działa w Prod (MF ma osobne CA)
• Walidacja strictsza w Prod — faktury, które przechodziły w Test, są odrzucane w Prod

Safe deployment:

1. Narzędzie musi mieć explicit env flag (nie NODE_ENV, własny KSEF_ENV=test|prod)
2. W Prod: blokada przez 24h przed pierwszym wysłaniem (canary check — wyślij 1 fakturę testową, sprawdź UPO, potem resztę)
3. Logowanie różnicy: jeśli KSEF_ENV=prod ale certificate cn=test, aler

Podsumowanie

Te 7 pułapek pojawi się w każdym narzędziu KSeF przy realnym ruchu. Większość nie jest problemem prawnym, tylko procesowym: czy system ma kolejkę, status, ponowienie, walidację i czytelny wyjątek dla człowieka.

Co warto sprawdzić w swoim narzędziu:

• Obsługuje Retry-After i błędy 429
• Ma lokalne limitowanie żądań per NIP
• Waliduje dane biznesowe przed wysyłką, nie tylko strukturę pliku
• Odświeża sesję po błędzie autoryzacji i ponawia ostatnią operację
• Loguje awarie i ponawia wysyłkę po powrocie KSeF
• Hybrid OAuth2 + certyfikat kwalifikowany
• Monitor wygaśnięcia certyfikatu (30 dni przed)
• Explicit flag Test vs Prod + canary check

saldomat projektujemy pod taki standard pracy: widoczne zdarzenia KSeF, kontrolę błędów i proces, w którym wyjątki nie giną w technicznych logach systemowych. Zobacz demo.

Powiązane artykuły

• KSeF 2.0 w 2026 — przepisy i praktyczne braki
• JPK_V7M w 2026 — zmiany wynikające z KSeF 2.0