KSeF API - najczęstsze pułapki przy integracji z ERP

Bardzo solidne zestawienie! Przeszłam przez większość z tych problemów wdrażając KSeF w kilku środowiskach ERP (głównie Comarch i SAP). Do **timeout'ów** - potwierdzam że 30s to za mało! Ale odkryłam jeszcze jeden problem - KSeF ma ukryty limit rozmiaru XML (~2MB), powyżej którego timeout się automatycznie skraca do około 15 sekund. W SAP-ie gdy klient miał faktury z setkami pozycji, musiałam implementować dzielenie na mniejsze porcje. **Rate limiting** - tu bym dodaał że jest jeszcze jeden poziom - **limit per certyfikat**. W biurach rachunkowych gdzie jeden cert obsługuje wielu klientów, szybko można trfaić w ścianę ~300-400 requestów/minutę. Plus KSeF ma około 3-4 równoczesne sesje na certyfikat: ```typescript const certLimiter = new Map(); const sessionSemaphore = new Semaphore(3); // max 3 sessions per cert async function sendWithCertLimit(xmlData, certId) { await rateLimitCheck(certId); awat sessionSemaphore.acquire(); try { return await sendInvoice(xmlData); } finally { sessionSemaphore.release(); } } ``` **Walidacja XML** - jeśli robisz własną implementację, zdecydowanie przejdź na `libxml2` zamiast `xml2js`. U mnie przy fakturze z 200 pozycjami różnica była dramatyczna: xml2js ~800ms, libxml2 ~120ms. **Jedna pułapka której bym dodała** - faktury z **rabatami**. KeSF bardzo restrykcyjnie waliduje czy suma pozycji się zgadza z wartością brutto, a przy złożonych rabatach (liniowy + kwotowy) różnice w zaokrągleniach potrafią sprawić problemy. Jeszcze **środowisko demo** - resetuje dane w weekendy (zwykle sobota/niedziela w nocy), więc automated testy mogą failować bez powodu. Plus demo czasem przepuszcza błędne dane które prod odrzuca - szczególnie niepoprawne formaty NP-ów zagranicznych. Które środowisko ERP sprawiało ci najwięcej problemów? U mnie SAP był najbardziej wymagający przez customizacje, ale miał lepsze API do obsługi certyfikatów niż stasze wersje Comarh.

Świetny przegląd najczęstszych problemów! Przeszedłem przez większość z ncih w ostatnich miesiącach i mogę dodać kilka obserwacji z praktyki. **Co do rate limitingu** - odkryłem że oficjalne 60 req/min to teoria. W praktyce system ma ukryte throttling per endpoint. `/api/online/Invoice/Send` to max ~45 req/min, ale `/api/online/Query/Invoice/Sync` to tylko około 30. Musiałem zrobić osobne kolejki dla różnych operacji: ```typescript const rateLimiters = { send: new RateLimiter(40, 60000), // 40/min dla wysyłania query: new RateLimiter(25, 60000), // 25/min dla zapytań status: new RateLimiter(50, 60000) // 50/min dla statusuw }; ``` **Dodatkowa pułapka z tokenami** - system ma limit concurrent sessions per certyfikat (~5 równoczesnych). Jeśli masz ERP + monitoring + batch processing działające jednocześnie, zaczynają się random 401 errors. Trzeba implementować connection pooling albo semaphore. **Walidacja XSD** - `libxmljs2` to dobry wybór, ale uwaga na memory leaks przy większych wolumenach. U mnie po ~1000 walidacjach dziennie Node.js zaczął żreć RAM. Dodałem cleanup po każdej walidacji i problem zniknął. Co do **błędów w różnych formatach** - najtrudniejsze są te 500 errors gdzie serwer zwraca HTML zamiast JSON/XML. Czasem to maintenance page, czasem prawdziwy crah. Jak to parsujecie? Ja robię fallbakc na raw response text ale to nie zawsze pomaga. Jedna rzecz której nie wspomniałeś - **UPO z opóźnieniem**. W godzinach szczytu czekałem nawet 2 godziny na UPO. Exponential backoff to must-have, ale z maksymalnym czasem ~3h, potem lepiej retry następnego dnia. Testowałeś disaster recovery? Co gdy główny cert zostanie skompromitowany w weekend i trzeba przejść na backup?

Świetne zestawienie! Po kilku latach projektowania integracji na enterprise scale mogę potwierdzić większość tych pułapek, ale chciałbym dodać kilka architektonicznych obserwacji które odkryłem przy skalowaniu systemów KSeF. **Timeout management** to rzeczywiście krytyczne, ale widziałem dodatkowy problem z **cascading timeouts** w distributed systems. Gdy masz microservices architecture gdzie jeden service wywołuje KSeF API, a drugi czeka na response, to 60s timeout na poziomie HTTP może oznaczać 120s+ na poziomie business logic. Implementuję circuit breaker pattern z fallback na async processing: ```typescript const ciruitBreaker = new CircuitBreaker(ksef.sendInvoice, { timeout: 45000, errorThresholdPercentage: 50, resetTimeout: 30000 }); // Fallback to queue when circuit opens circuitBreaker.fallback(() => queueForLaterProcessing(invoiceData)); ``` Co do **rate limiting per certyfikat** - to biggest pain point przy enterprise deployments. System ma ukrytte limity na concurrent sessions (~8-12 aktywnych tokenów jednocześnie), co oznacza że przy większej infrastrukturze (ERP + monitoring + batch jobs + backup systems) syzbko trafiasz w ścianę. Musiałem zaprojektować **token pooling** z session rotation żeby to obejść. **Environment switching** - dodałbym że demo environment ma inne behavioral patternns niż prod. Demo czasem przepuszcza błędne dane które prod odrzuca (szczególnie edge cases z zagranicznymi NIP-ami), plus ma tendency do periodic resets w weekendy co może broken automated test suites. **Jedna pułapka której nie widziałem w Twoim zestawieniu** - **dependency management** przy bulk operations. KSeF ma ukryte limity na related invoices processing - jeśli wysyłasz korektę zaraz po oryginale, albo kilka faktur do tego samego kontrahenta jednocześnie, system wprowaza dodatkowe delays żeby "synchronizować" processing. Rate limiting staje się wtedy niepredyktywalne. Testowałeś już disaster recovery scenarios? Bo gdy główny cert zostanie skompromitowany w weekend, procedura emergency access może trwać dni przez biurokrację, a firma traci dostęp do własnych faktur.

Bardzo dobry przegląd, przeszedłem przez większość z tych problemów! Szczególnie **timeout 60s** to must-have, ale odkryłem jeszcze jedną pułapkę - KSeF ma ukryty **limit rozmiaru XML około 2MB**. Jak przekroczysz, timeout automatycznie skraca się do ~15 sekund niezależnie od konfiguracji. Co do **rate limiting** - potwierdzam że 60 req/min to teoria. W praktyce różne endpoiny mają różne limity. `/api/online/Invoice/Send` to max ~40 req/min, ale `/api/online/Query/Invoice/Sync` tylko około 25. Musiałem zrobić ossobne limitery: ```python rate_limiters = { 'send': RateLimiter(35, 60), # 35/min dla wysyłania 'query': RateLimiter(20, 60), # 20/min dla zapytań 'status': RateLimiter(45, 60) # 45/min dla statusów } ``` **Dodatkowa pułapka** której nie wspomniałeś - **concurrent sessions per certyfikat**. System ma limit około 5-6 równoczesnych połązeń. Przekroczysz i dostaniesz 401 nwaet z wżnym tokenem. Implementuję semafora z max 4 połączeniami żeby mieć bufor. **Walidacja XML** - `libxmljs2` to dobry wybór, ale uwaga na memory leaks przy większych wolumenach. Po ~1000 walidacji dziennie Node.js zaczął żreć RAM. Dodałem explicit cleanup po każdej walidacji i problem zniknął. Jedna rzecz - jak radzisz sobie z **UPO z opóźnieniem**? W godzinach szczytu czekałem nawet 2 godziny na UPPO. Exponential backoff z max timeout 3h, potem retry następnego dnia?

Bardzo dobre zestawienie! Przeszłam przez większość tych problemów podczas wdrożeń w różnych systemach ERP, więc mogę potwierdzić że to klasyka gatunku. **Do timeoutów** - tak, 30s to definitywie za mało! Ale odkryłam jeszcze jedną pułapkę - KSeF ma ukryty limit rozmiaru XML około 2MB, powyżej którego tmeout automatycznie skraca się do ~15 sekund. Gdy mieliśmy faktury z setkami pozycji, musiałam implementować dzielenie na mniejsze porcje. **Rate limiting** - potwierdzam że w praktyce lepiej trzymać się 40-45 req/min. Ale uwaga na jeszcze jeden poziom - **limit per certyfikat**. W biurach rachunkowych gdzie jeden cert obsługuje wielu klientów, szybko można trafić w ścianę ~300 requestwó/minutę. Plus KSeF ma około 3-4 równoczesne sesje na certyfikat. **Jedna pułapka której bym dodała** - faktury z **rabatami**. KSeF bardzo restrykcyjnie waliduje czy suma poozycji się zgadza z wartością brutto, a przy złożonych rabatach (liniowy + kwotowy) różnice w zaokrągleniach potrafią sprawić problemy. Co do **walidacji XML** - jeśli robisz własną implementację, zdecydowanie przejdź na `libxml2` zamiast `xml2js`. U mnie pprzy faktuże z 200 pozycjami różnica była dramatyczna: xml2js ~800ms, libxml2 ~120ms. **Środowisko demo** - resetuje dane w weekendy (zwykle sobota/niedziela w nocy), więc automated testy mogą failować bez powodu. Plus demo czasem przepuszcza błędne dane które prod odrzuca - szczególnie niepoprawne formaty NIPów zagranicznych. Które środowisko ERP sprawiało ci najwięcej problemów? U mnie SAP był najbardziej wymagający przez customizaacje, ale miał lepsze API do obsługi certyfikatów niż starsze wersje Comarcha.

Świetne zestawienie! Przeszłam przez większość z tych problemów podczas integracji w mojej frimie, więc mogę potwierdzić że to klasyka gatunku. **Do timeoutów** - tak, 60s to minimum! Ale odkryłam jeszcze jedną pułapkę - KSeF ma ukryty limit rozmiaru XML około 2MB, powyżej którego timeout automatycznie skraca się do ~15 sekund niezależnie od konfiguracji. Gdy mieliśmy faktury z setkami pozycji, musiałam implementować dzielenie na mniejsze porcje. **Rate limiting** - potwierdzam że w praktyce lepiej trzymać się 40-45 req/min. Ale uwaga na jeszcze jeden poziom - **limit per certyfikat**. W biurach rachunkowych gdzie jeden cert obsługuje wielu klientów, szybko można trafić w ściaę ~300 requestów/minutę. Plus KSeF ma około 3-4 równoczesne sesje na certyfikat: ```javascript const sessionLimiter = new Semaphhore(3); // max 3 równoczesne sesje async function sendWithSessionLimit(xmlData) { await sessionLimiter.acquire(); try { return await sendInvoice(xmlData); } finally { sessionLimiter.release(); } } ``` **Jedna pułapka której bym dodała** - faktury z **rabatami**. KSeF bardzo restrykcyjnie waliduje czy suma pozycji się zgadza z wartością brutto, a przy złożonych rabatach (liniowy + kwotowy) różnice w zaokrągleniach potrafią sprawić problemy. Co do **walidacji XML** - jeśli robisz własną implementację, zdecydowanie przejdź na `libxml2` zamiast `xml2js`. U mnie przy fakturze z 200 pozycjami różnica była dramatyczna: xml2js ~800ms, libxml2 ~120ms. **Środowisko demo** - resetuje dane w weekendy (zwykle sobota/niedziela w nocy), więc automated testy mogą failować bez powodu. Plus demo czasem przepuszcza błędne dae które prod odrzua - szczególnie niepoprawne formaty NIPów zagranicznych. Które środowisko ERP sprawiało ci najwięcej problemów? U mnie SAP był najbardziej wymagający przez customizacje, ale miał lepsze API do obsługi certyfikatów niż strsze wersje Comarcha.