1. Cache potrafi zabić sesję — i nikt Ci o tym nie powie
Najdziwniejsza awaria, jaką debugowałem przy KSeF: synchronizacja padała z błędem autoryzacji (kod 21111), mimo że token był poprawny. Przyczyna? Framework po stronie mojej aplikacji cache'ował odpowiedź challenge z endpointu autoryzacji. KSeF wystawia wyzwanie kryptograficzne, które żyje krótko — a my podpisywaliśmy „świeżym" tokenem martwe, zserwowane z cache'a wyzwanie.
Lekcja: każda ścieżka HTTP w torze autoryzacji KSeF musi mieć jawnie wyłączone cache'owanie (w Next.js: cache: 'no-store' na fetchu i fetchCache = 'force-no-store' na route). „Force-dynamic" na stronie nie wystarcza — to dwie różne warstwy cache.
2. Limity zapytań są realne: planuj backoff, nie retry-sztorm
KSeF ma limity po stronie API (w naszym środowisku ok. 20 zapytań autoryzacyjnych na godzinę). Naiwny retry przy błędzie potrafi wyczerpać limit w minutę — i wtedy nawet poprawny kod nie zadziała do końca okna. U nas działa wykładniczy backoff z twardym sufitem prób i alertem raz na dobę zamiast alertu przy każdej próbie: właściciel dostaje jedną wiadomość „sync leży od 6:00", nie sto.
3. Ciągłość numeracji to Twój najtańszy audyt
Faktury z KSeF przychodzą z numeracją, która powinna być ciągła. Prosty test „czy między ostatnim a bieżącym pobraniem nie ma dziury" wykrywa więcej problemów niż monitoring statusów HTTP: złapaliśmy nim lukę, której nie pokazał żaden błąd — sesja „przechodziła", ale część dokumentów nie schodziła. Kontrola luk w numeracji plus licznik pobranych vs oczekiwanych to dwie linijki, które śpią spokojnie za Ciebie.
4. XML jest dla systemów. Ludzie potrzebują PDF w folderze z miesiącem
Księgowość nie chce „dostępu do systemu". Chce plików PDF w folderze 2026-07/, nazwanych po dostawcy i numerze. Konwersja XML→PDF i układanie w foldery miesięczne to 20% pracy, które daje 80% odczuwalnej wartości — bo zdejmuje ostatni ręczny krok. Jeśli Twoja integracja kończy się na „dane są w bazie", to nie jest skończona.
5. Terminy: odbiór już obowiązuje wszystkich. Kary czekają na styczeń
Stan prawny (weryfikowany 30.07.2026): obowiązek odbierania faktur w KSeF objął wszystkich podatników 1 lutego 2026. Wystawianie: najwięksi od lutego, MŚP od 1 kwietnia 2026, najmniejsi od 1 stycznia 2027. Okres ochronny kończy się 31 grudnia 2026 — do tego czasu urząd najpierw wzywa i daje 14 dni; od 1 stycznia 2027 sankcje idą bez uprzedzenia. Wniosek praktyczny: wdrożenie „w spokoju" jest możliwe jeszcze przez kilka miesięcy. Wdrożenie „po wezwaniu" będzie droższe i nerwowe.
Chcesz zobaczyć, jak to wygląda naprawdę? Moduł, o którym piszę, działa w produkcji — z panelem kosztów, agingiem zobowiązań i anomaliami wykrywanymi przez AI.