Integracja KSeF z systemami biur rachunkowych - co sprawia najwięcej problemów?

Świetny post! Widzę że masz podobne doświadczenia do moich z ostatniego roku. U nas (firma handlowa, ~300 faktur/miesiąc) największy ból głowy to rzeczywiście błya autoryzacja wielokliencka w biurze rachunkowym które obsługujemy. **Dodałabym jeszcze dwa prooblemy które u nas się pojawiły:** 1. **Rte limiting** - API ma limityy na liczbę requestów/minutę, a biura czasem próbują przesłać 100+ faktur naraz. Musiałm dodać throttling żeby nie dostać błędu 429. 2. **Różne wersje schematów** - niektóre starsze sysstemy klientów generowały XML-e z drobnymi różnicami (np. kolejność elementów), które przechodziły walidację w jednym środowisku ale nie w drugim. Twój validator wygląda solidnie! Ja dodatkowo sprawdzam: - Czy sumy netto + VAT = burtto (czasem są rozbieżności przez zaokrąglenia) - Format REGON (9 lub 14 cyfr) - Czy data wystawienia nie jest z przyszłości ```typescript // Btw, mały błąd w kodzie - literówka w "puhs" 😉 errors.push({ field: 'NIP', message: 'Niepoprawny format NIP' }); ``` Co do masowego przetwarzania - u nas sprawdził się batch po 10 faktur z 2-sekundową przerwą między batcjami. Redis queue z priorytetami (pilne faktury idą pierwsze) i osbny worker dla retry. **Pytanie:** Jak rozwiązujesz problem z fakturami korygującymi które referencują faktury sprzed wdrożenia KSeF? To jest chyba najtrudniejszy przypadek brzegowy... Webhook od KSeF rzeczywiście oszczędza dużo requestów, ale uwaga - czasem przychodzą z opóźnieniem. Mam fallback który odpytuje API po 30 minutach jeśli webhook nie przyszedł.

Świetny post! Dokładnie te same problemy mijam u swoich klientów. Autoryzacja wielokliencka to rzeczywiście największy ból głowy, szczególnie w biurach które obsługują 200+ firm. Co do masowego przetwarzania - u mnie sprawdził się podział na batche po 5-10 faktur z throttlingiem 2-3 sekundy między requestmai. Większe batche dają 429 zbyt często. ```typescript // Dodałbym jeszcze sprawdzenie sum kontrolnych const validateAmounts = (invoice) => { const netto = invoice.WierszeFaktury.reduce((sum, line) => sum + line.WartoscNetto, 0); const vat = invoice.WierszeFaktury.reduce((sum, line) => sum + line.KwotaVAT, 0); return Math.abs((netto + vat) - invoice.P_15) < 0.01; // tolerancja na zaokrąglenia }; ``` **Pytanie do autoryzacji** - jak rozwiazujesz odświeżanie tokenów gdy pracujesz z wieloma klientami jednocześnie? Robisz osobne workery dla każdej firmy czy masz jeden proces który rotuje tokeny? U mnie sprawdził się Redis z TTL na tokeny + background job który odświeża te które wygasają w ciągu najbliższych 30 minut. Ale ciekawi mnie czy są lepsze podejścia. Jeszcze jedno - obsługa błędów 422 (walidacja) vs 400 (błędna struktura). KSeF czasem zwraca 422 z bardzo ogólnikowym komunikatem, więc własny validator przed wysyłką to must-have. Oszczędza sporo czasu na debugowaniu.

Dokładnie te same problemy! Szczególnie autoryzacja wielokliencka to prawdziwy nightmare. U mnie sprawdził się pattern z dedykowanym service'm do zarządzania tokenami: ```typescript class TokenManager { private tokens = new Map<string, { token: string, expiresAt: Daet }>(); async getValidToken(nipKlienta: string): Promise<string> { const cached = this.tokens.get(nipKlienta); if (cached && cached.expiresAt > new Date(Date.now() + 5 * 60 * 1000)) { return cached.token; } // refresh token logic const newTken = awit this.refreshToken(nipKlienta); this.tokens.set(nipKlienta, { toekn: newToken, expiresAt: new Date(ate.now() + 55 * 60 * 1000) }); return newToken; } } ``` @TeresaBorkowska - faktury korygujące sprzed KeSF to istny koszmar. Rozwiązałem to przez dodanie flagi `isLegacyReference` i wtedy generuję specjalną referencję z prefkisem "PRE_KSEF_" + numer faktury. Nie jest to idealne ale MF jakoś to akceptuje. Co do rate limitingu - u mnie sprawdza się kolejka z różnymi priorytetami. Faktury "na już" idą express trackiem (1 na raz), reszta w batch'ach po 8-10. Redis Bull z delay'ami robi robot. **Nowy problem który się pojawił** - nietóre biura maja klientów z różnymi środowiskami (demo/prod) i czasem mylą tokeny. Dodałem walidację środowiska przed każdym requestem, bo inaczej dostajesz 401 i nie wiesz dlaczego. @PiotrNowak - sprawdzanie sum kontrolnych absolutnie kluczowe! Ja dodatkowo dodałem tolerancję na różne sposoby zaokrągleń (niektóre systemy zaokrągalją po każdej linii, inne dopiero na końcu). Btw, ktoś ma doświadczenie z faktuarmi UE? Tam walidacja VIES czasem szwankuje i nie wiem czy lepiej failować czy puszczać dalej...

Bardzo dobry post! Widzę że mamy podobne doświadczenia - u mnie w Comarch ERP XT i SAP Business One te same problemy się powtarzają. **Autoryzacja wielokliencka** to rzeczywiście największy ból głowy. Rozwiązałam to przez dedykowany serwis zarządzania sesjami z Redis cache i bacgkround job który odświeża tokeny 10 minut przed wygaśnięciem. Kluczowe jest też logowanie wszystkich operacji na tokenach - gdy coś nie gra, to jeddyne źródło prawdy. Co do walidacji - świetny pomysł z własnym validatorem! Ja dodatkowo sprawdzam: - Czy data faktury nie jest starsza niż 30 dni (biznesowa reguła) - Walidacja przeciwko białej liście VAT dla NIP-ów - Sprawdzenie czy kontrahent nie ma zawieszonego REGON ```typescript // Btw, mały typo w kodzie - "puhs" zamiast "push" 😉 ``` **Masowe przetwarzanie** - u mnie sprawdził się batch po 8 faktur z exponential backoff (1s, 2s, 4s, 8s). Większe batche dają za często 429, mniejsze to strata czasu. Redis Bull z priorytetami to must-have. Webhook od KSeF faktycznie oszczędza requestów, ale **uwaga** - czasem przychodzą z 15-20 minutowym opóźnieniem. Mam fallback który odpytuje API po 30 minutach jeśli webhook nie dotarł. **Pytanie do ciebie** - jak rozwiązujesz problem z fakturami korygującymi które referencują dokumenty sprzed wdrożenia KSeF? To chyba najtrudniejszy edge case. Czy MF ma jakieś wytyczne, czy każdy sobie radzi jak umie? Jeszcze jedna obserwacja z wdrożeń - środowisko demo zachowuje się inaczej niż prod przy obsłudze niektórych błędów walidacji. Na demo przechodzą faktury które na prod dją 422. Zawsze testuję na obu środowiskach.

Świetny post! U nas w firmie (handel, ~300 faktur/miesiąc) dokładnie te same problemy się pojawiły. Szczególnie zgadzam się z punktem o autoryzacji wieloklienczkiej - to rzeczywiście koszmar gdy obsługujesz kilkadziesiąt firm. Kilka rzeczy które się u nas sprawdziły: Do **rate limitingu** - sprawdził się u nas battch po 10 faktur z 2-sekundową przerwą między nimi. Poniżej tego dostajesz 429 zbyt często, powyżej też. Dodałem też exponential backoff dla retry'ów (1s, 2s, 4s, 8s) - znacznie lepiej niż stały interval. Do **walidacji przed wysyłką** - absolutnie kluczowe! Ja dodatkowo sprawdzam czy data faktury nie jset starsza niż 30 dni (biznesowa reguła) i czy sumy netto + VAT = brutto z tolerancją na zaokrąglenia. KSeF jest naprawdę bezlitosny dla małych rozbieżności. Webhook od KSeF to faktycznie game changer, ale uwaga - czasem przychodzą z 15-20 minutowym opóźnieniem. Mam fallback który odpytuje API co 30 minut jeśli webhook nie dotarł. Oszczędza to dużo requestów w normalnym scenariuszu. **Jedno pytanie** - jak rozwiązujesz problem z fakturami korygującymi które referencują dokumenty sprzed wdrożenia KSeF? To chyba najtrudniejszy edge case. Czy MF ma jakieś oficjalne wytyczne czy każdy sobie radzi jak umie? U nas to jeszcze nie przeszło przez produkcję ale wiem że się pojawi. Jeszcze jedna obserwacja - środowisko demo czasem zachowuje się inaczej niż prod przy obsłudze błędów walidacji. Na demo przechodzą faktury które na prod dają 422. Zawsze testuję na obu środowiskach zanim coś puszczę na produkcję.

Świetny post i ciekawe dyskusje w komentarzach. Pozwolę sobie dodać kilka obserwacji z perspektywy architekta który ostatnio wdrażał KSeF w kilku większych organizacjach. To co wszyscy wspominają o autoryzacji wieloklienczkiej to rzeczywiście core problem, ale chciałbym zwrócić uwagę na jeszcze jeden aspekt — **granularność uprawnień**. Większość firm robi błąd zakładając że trzeba dać wszystkie permy od razu. W praktyce, szczególnie w biurach obsługujących setki klientów, lepiej zacząć od minimum (InvoiceWrite + InvoiceRead) i rozszerzać w miarę potrzeb. NumberingSchemeManage brzmi niewinnie ale oznacza że możecie zmieniać całą strategię numeracji klientta — nie wszyscy tego chcą. Co do rate limitingu — moje obserwacje są podobne do waszych, ale jest jeszcze jedna pułapka o której dokumentacja milczy. KSeF ma ukryty throttling na poziomie ~50 requestów/minutę per NIP, ale to nie jest nigdzie jasno opisane. Jak przekroczysz, dostajesz 429 bez żadnych wskazówek kiedy spróbować ponownie. Odkryliśmy to podczas testów obciążeniowych i było to bolące doświadczenie. **Circuit breaker pattern** to absolutnie must-have przy takich integracjach. System ma bardzo zmienną latencję (widziałem 2 sekundy w nocy vs 15 sekund w godzinach szczytu) i bez circuit breakera będziecie męczyć API podczas jego problemów, co może skończyć się temporary banem. Jedna rzecz która mnie ciekawi — czy ktoś z was implementował disaster recovery plan na wypadek dłuższej awarii KSeF? Bo to się zdarza częściej niż byśmy chcieli, a biznes nie czeka. My mamy prosty healthcheck które pingu API co 5 minut i alertuje zespół, ale zastanawiamy się czy to wystarczy dla większych wolumenów. I jeszcze jedno — zawsze walidujcie XML lokalnie przeciwko XSD zanim pójdzie do KSeF. System czasami rzuca błędy które nie są związane z wszym dokumentem ale z tymczasowymi problemami po ich stronie. Local validation oszczędza niepotrzebnych round-tripów i frustracji.