Automatyczne pobieranie faktur z KSeF co 1 godzinę — konfiguracja, limity i praktyka

Słowo „automatyczne" w kontekście KSeF ma u większości dostawców elastyczne znaczenie — jedni odświeżają dane raz dziennie, inni raz na 4-8 godzin. Różnica między „raz dziennie" a „co godzinę" wydaje się kosmetyczna, dopóki nie zaczniesz naprawdę pracować na aktualnych danych. Wtedy okazuje się, że to różnica między „dowiemy się jutro rano" a „księgowa zobaczy fakturę zanim pójdzie na obiad".

Jeśli zamykasz miesiąc ostatniego dnia, pobranie faktur raz dziennie oznacza, że te wystawione po 18:00 wpadną dopiero 1. następnego miesiąca — za późno. Jeśli ściągasz fakturę kosztową z MPP na 40 000 zł brutto i musisz ją zapłacić w terminie, opóźnienie 6-8 godzin w jej zauważeniu potrafi kosztować. W tym artykule pokazujemy, dlaczego sync co godzinę jest inaczej skonstruowany niż naiwne „co N godzin", i jak go skonfigurować bez konfliktów z API KSeF.

Problem: KSeF bez harmonogramu to chaos

Zobacz, jak wygląda typowy dzień w firmie bez automatycznego pobierania:

1. 9:45 — księgowa siada do arkusza, ale nie ma nowych faktur (nikt jeszcze nie pobrał).
2. 10:20 — właściciel dzwoni: „czy przyszła faktura od HurtPlus?". Księgowa loguje się do portalu MF, sprawdza. Jest.
3. 11:15 — kierownik zakupów pyta o fakturę za paliwo. Księgowa znowu loguje się do KSeF.
4. 14:30 — trzeba wysłać coś do księgi głównej. Księgowa eksportuje CSV z portalu MF, otwiera w Excelu, kopiuje dane.
5. 17:00 — koniec dnia. Nikt nie wie, czy wpadły jeszcze faktury po godzinach.

W firmie z 200 fakturami miesięcznie to 5-10 godzin pracy tygodniowo tylko na „sprawdzaniu KSeF-u". A przy 15 minutach rate-limiting per sesja i konieczności logowania certyfikatem — to dodatkowa frustracja.

Wartość: harmonogram godzinowy w planach Grupa i Biuro

KSeF Import daje 9 kanonicznych częstotliwości synchronizacji: 15 min, 30 min, 1h, 2h, 4h, 6h, 8h, 12h, 24h. Konkretna częstotliwość dostępna dla Ciebie zależy od planu:

Próg 1 godziny to punkt, w którym dane w arkuszu zaczynają być „na tyle aktualne, że można na nich pracować operacyjnie". Przy częstotliwości godzinowej każda nowa faktura jest w arkuszu w ciągu maksymalnie 60 minut od jej pojawienia się w KSeF — w praktyce średnio 30 minut (bo kiedy akurat trafi, nie wiesz).

Architektura: Celery Beat + jitter + backoff

Sync godzinowy to nie jest prosty „cron co 60 minut". Cron to byłby zły pomysł: wszyscy klienci odpaliliby zapytania do KSeF w tej samej sekundzie (np. :00 każdej godziny), co spowodowałoby skokowe obciążenie API MF i ryzyko HTTP 429 (rate limit exceeded). Schemat u nas:

• Celery Beat — scheduler odpalający task sync dla każdego aktywnego NIP-a z harmonogramem godzinowym.
• Jitter ±15 min — losowy offset dodany do momentu odpalenia taska. NIP A może być pobrany o 10:07, NIP B o 10:23, NIP C o 10:51. Rozkładamy obciążenie.
• Per-NIP rate limiter — każdy NIP ma niezależny limit zgodny z limitami KSeF (20 req/h dla endpoint POST /invoices/query/metadata, 600 req/h dla GET /invoices/exports/{ref}).
• Token refresh — proaktywnie co 10 minut + reaktywnie na 401. Zero przestojów z powodu wygasłego tokena.
• Retry z exponential backoff — jeśli KSeF chwilowo pada (HTTP 5xx), retry po 30s, potem 60s, 120s. Po 3 nieudanych próbach alert do Sentry + email do właściciela NIP-a.

Limity API KSeF, których musisz przestrzegać

Ministerstwo Finansów publikuje twarde limity w ksef-docs. Kluczowe dla sync godzinowego:

„20 req/h na query" oznacza: nawet gdybyś miał 25 synchronizacji dziennie, tylko ~20 zapytań typu „query metadata" na godzinę w oknie. Dla sync godzinowego 1 query + 1 export request to komfortowo w limicie. Przy 15-minutowym na planie Biuro: 4 query/h, nadal w okienku.

Co KSeF Import robi z jitterem

Rzecz techniczna, ale kluczowa: jeśli masz 100 klientów na planie Grupa (co 1h), bez jittera wszyscy odpalają się o :00. 100 × 2 zapytania = 200 req o tej samej sekundzie. KSeF to przeżyje, ale Twój Celery worker zginie, a niektóre zapytania wpadną do kolejki na kilka minut.

Z jitterem (do 25% interwału, max 5 min dla sync godzinowego): każdy klient ma pseudolosowy offset w oknie [0 min, 15 min]. 100 klientów rozłożone na 900 sekund = 0,11 klienta/s. Idealnie dla workera i API KSeF.

Konfiguracja krok po kroku

1. Krok 1: Wybierz plan Grupa lub Biuro

   Cennik → Grupa (99 zł netto/msc) lub Biuro (299 zł netto/msc). Obie opcje odblokowują sync co 1h. Plany z synchro co 1h są dostępne od razu po aktywacji.

2. Krok 2: Dodaj NIP i wgraj certyfikat

   Panel → Certyfikaty → Dodaj certyfikat KSeF (.p12, zaszyfrowany AES-256-GCM po stronie aplikacji). Każdy NIP ma niezależną kolejkę i token.

3. Krok 3: Ustaw harmonogram

   Panel → Harmonogram synchronizacji → wybierz „Co 1 godzinę". Możesz wyłączyć sync w godzinach nocnych (np. 23:00-05:00), jeśli i tak nikt nie pracuje — oszczędza to limity API.

4. Krok 4: Wskaż docelowy eksport

   Google Sheets, Excel Online lub CSV. Każda synchronizacja automatycznie dopisuje nowe faktury do arkusza (bez duplikatów — klucz po numerze KSeF).

5. Krok 5: (Opcja) Włącz powiadomienia

   Panel → Powiadomienia → email po każdej synchronizacji z podsumowaniem (N nowych faktur, wartość) albo tylko gdy znajdzie się faktura MPP-owska > 15 000 zł. Koniec z dzwonieniem do księgowej „czy coś wpadło?".

Scenariusze, w których 1h robi różnicę

• Windykacja / monitoring kontrahentów

  Klient wystawił fakturę — chcesz wiedzieć od razu, żeby zaksięgować należność. Przy sync godzinowym należność jest w systemie najpóźniej 60 min po wystawieniu, gotowa do pilnowania terminu.

• Split payment z terminem płatności

  Faktura MPP na 30 000 zł brutto z terminem 7 dni. Sync godzinowy zapewnia, że zauważysz ją w tym samym dniu, co wystawienie — masz pełne 7 dni na płatność, nie 5 dni zredukowane o opóźnienie sync. Więcej o MPP w artykule o automatycznym flagowaniu faktur MPP.

• Integracje Make / Zapier / n8n

  Jeśli automatyzacja wysyła powiadomienia Slack, wpisuje do CRM albo tworzy zadanie w Asana — częstotliwość KSeF Import wyznacza górny próg latencji Twojego workflow. Sync 6h = alerty Slack opóźnione o 6h. Sync 1h = prawie real-time. Praktyczne scenariusze w artykule o automatyzacji Make.com.

• Dashboard CFO / controller

  Power BI z odświeżaniem scheduled refresh co godzinę nie ma sensu, jeśli arkusz źródłowy aktualizuje się raz na 6h. Dashboard Power BI zasilany sync godzinowym = pełna aktualność. Kontekst w Power BI dla CFO.

Co się dzieje, gdy KSeF jest niedostępny

Ministerstwo Finansów czasem ma przerwy serwisowe albo niespodziewane padnięcia. KSeF Import obsługuje to trzema warstwami:

• Retry 3× z 30/60/120s — dla chwilowych timeoutów.
• Circuit breaker — po 10 kolejnych padach konkretnego NIP-a automatyka pauzuje go na 30 min, żeby nie eksploatować API.
• Backfill przy odzyskaniu — gdy KSeF wraca, następna synchronizacja pobiera wszystkie faktury z okresu przerwy (do 89 dni wstecz, bo takie są limity query range w KSeF v2).

W rezultacie: jeśli KSeF padł o 14:00 i wrócił o 16:30, Twój arkusz o 17:00 ma wszystkie faktury z tego okna. Zero zgubionych dokumentów.

Efekt: operacyjna świeżość danych

• 24 synchronizacje dziennie, 720 miesięcznie — zero ręcznego logowania.
• Faktury w arkuszu w ciągu godziny od wystawienia — dashboardy są aktualne, gdy księgowa pije kawę o 9:00.
• Alerty natychmiastowe na MPP, terminy płatności, faktury od nietypowych kontrahentów.
• Zgodność z limitami API KSeF — zero ryzyka HTTP 429, zero blokad.
• Niezależność od dostępności MF — retry, circuit breaker, backfill przy recoveryey.

Dla firmy, która pracuje operacyjnie na danych z KSeF (a nie tylko do rozliczenia podatkowego raz w miesiącu), różnica między sync 6h a sync 1h to różnica między „aplikacja, która czasem odświeża dane" a „aplikacja, w której dane są".