5 błędów które robię w integracji KSeF - żeby inni nie musieli

Bardzo przydatne zestawienie! Przeszłam przez wszystkie te błędy podczas wdrożeń w Comarch ERP XT i SAP, więc mogę powierdzić że to żeczywiście najczęstsze pułapki. **Do twoich obserwacji dodam kilka swoich "perełek":** **Problem z enkodowaniem** - nie tylko apostrofy z Worda, ale też znaki kontrolne które czasem wpadają z importów CSV. Szczególnie `\r\n` vs `\n` w opisach pozycji potrafi zepsuć XML. Zawsze robię sanitization przed wysłaniem. **Walidacja NIP w VIES** - to większy problem niż się wydaje. VIES ma swoje timeouty i czasem jest niedostępny, a KSeF odrzuca faktury gdy nie może zweryfikować. Implementowałam fallback który sprawdza NIP lokalnie (algorytm kontrolny) gdy VIES nie odpowiada, ale to wymaga dodatkowej logiki business. **Bonusowy błąd nr 6**: **Nierawidłowe referencje w fakturach korygujących**. KSeF wymaga dokładnej referencji do oryginalnej faktury (ReferenceNumber), ale dużo systemów ERP przechowuje tylko numer bez pełnej struktury. Rezultat - korekty są odrzucane mimo że technicznie XML jest poprawny. **Co do timeoutów** - u mnie 30s też nie zawsze wystarcza. Ustawiam 60s dla upload i dodaję retry logic z exponential backoff. KSeF czasem zwraca 500 gdy serwer jest przeciążony, ale po 2-3 minutach ten sam request przechodzi bez problemu. Pytanie praktyczne - jak rozwiązujecie **numerację gdy KSeF zwróci błąd już po nadaniu numeru w ERP**? Bo to może prowadzić do gaps w numeracji które potem ciężko uzasadnić w kontroli. Rollback czy placeholder faktury? Btw, środowisko demo rzeczywiście ma identyczne walidacje, ale rate limiting jest bardziej agresywny niż w dokumentacji. Przy 40+ fakturach na godzinę zaczyna throttlować bez ostrzeżenia.

Świetna lista! Przeszedłem przez większość z tych błęów podczas integracji w naszym startupie i mogę potwierdzić że to rzeczywiście najczęstsze pułapki. **Do twoich obserwacji dodam jeszcze jeden klasyk:** **Problem z polskimi znakami w numerach faktur** - odkryłem to pżypadkiem gdy klient miał w numeracji faktury znak "/" i system ERP zamieniał go na "%2F" w URL encode. KSeF to odrzucał z cryptic error message. Teraz robię sanitization numerwó przed wysłaniem: ```typescript const sanitizeFakturaNumber = (number) => { return number.replace(/[^\w\-\.\/]/g, '_'); }; ``` Co do **timeoutów** - u mnie 45s + rety logic z exponential backoff. Ale odkryłem że KSeF ma "cichy" rate limiting który nie jest dokumentowany. Przy 50+ fakturach w ciągu godziny zaczyna zwracać 500 bez wyjaśnienia. Pomogło dodanie random delay 1-3s między requestami. **Bonusowa pułapka**: środowisko demo ma inne **walidacje dat** niż prod. Na demo możesz wysłać fakturę z datą sprzedaży z przyszłości, ale prod to odrzuci. Kosztowało mnie to pół dnia debugowania po deploymencie 😅 Marta wspomniała o numeracji po błdach - my rozwiązaliśmy to przez "shadow numbering". ERP nadaje numer dopieero po potwierdzeniu z KSeF, a do tego czasu fktura ma status "PENDING" z tymczasowym ID. Trochę więcej logiki, ale zero gaps w numeracji. Jakie są wasze doświadczenia z **fakturami zagranicznymi**? Mam klienta który eksportuje do UE i nie jestem pewien czy KSF w ogóle obsługuje faktury z VAT ID zamiast NIP.

Super lista! Przeszłam przez większość tych błędów podczas wdrożeń w różnych ERP-ahc, więc mogę potwierdzić że to klasyka gatunku. **Dodam jeszcze jeden błąd z mojej praktyki:** **Nieprawidłowe mapowanie stawek VAT** - szczególnie przy towarach z różnymi stawkami. Widziałam systemy które wysyłały wszystko jako 23% bo tak miały w domyślnej konfiguracji. KSeF to oczywiście odrzuca przy walidacji sum. Co do **kodowania znaków** - tak, te apostrofy z Worda to plaga! Ale uwaga też na **ampersandy (&)** w nazwach firm. XML wymaga escapowania jako `&` ale dużo systemów o tym zapomina. Rezultat - błąd parsowania ccałego dokumentu. **Problem z timeoutami** potwierdzam w 100%. U nas pomogło dodanie retry logic z exponential backoff - czasem ten sam requset przechodzi za 3 razm bez żadnych zmian. KSeF bywa kapryśny, szczególnie w godzinach szczytu. **Pytanie praktyczne** - jak rozwiązujecie **faktury z długimi opisami pozycji**? Bo widziałam przypadki gdzie opis miał 500+ znaków i KSeF rzucał timeout. Skracacie opisy czy dzielicie na więcej pozycji? A co do środowiska demo - rate limiting rzeczywiście jest bardziej agresywny niż w dokumentacji. Przy intensywnych testach lepiej robić przerwy między requestami. Świetny post, na pewno przyda się wielu osobom które dopiero zaczynają integrację!

Świetne zestawienie! Przeszedłem przez każdy z tych błędów w ostatnich miesiącach budując integrację dla naszego SaaS-a. Szczególnie ten problem z **formatowaniem dat** - stracłem cały dzień na deubgowanie zanim zorientowałem się że dodawałem `Z` na końcu. Co do **enkodowania UTF-8** - miałem dodatkowy problme z **BOM headerem**. Niektóre biblioteki XML domyślnie go dodają, a KSeF to odrzuca z cryptic error message. Teraz zawsze robię sanitization: ```typescript const cleanXmlForKsef = (xmlString: string) => { return xmlString.replace(/^\uFEFF/, ''); }; ``` **Bonusowy błąd nr 6**: **nieprawidłowe session management**. KSeF ma ukryty limit około 4-5 równoczesnych sesji per certyfikat. Przekroczysz i dostaniesz 401 nawet z ważnym tokenem. Musiałem dodać semaphore żeby to kontrolować, szczególnie przy batch processing. Aneta wspomniała o fakturach zagranicznych - u mnie klient eksportuje do UK i tam KSeF wymaga *d*odatkowego pola z kodem waluty** w sekcji `P_15`. Nie ma tego w dokumentacji, znalazłem tylko przez trial & error na demo. Co do **retry logic** - implementowałem circuit breaker pattern oprócz exponential backoff. Gdy widzę serię 500ek, system automatycznie przełącza się na "degraded mode" na 15 minut. Lepsze niż crashowanie całej aplikacji. **Praktyczne pytanie** - ktoś ma sprawdzone rozwiązanie na rotację certyfikatów w prodzie bez downtime'u? Mam klienta z certem ważnym do marca i chcę to ogarnąć z wyprzedzeniem. A tak btw, środowisko demo resetuje się zwykle w weekendy - warto uwzględnić w testach automatycznych 😅

Świene zestawienie! Przeszedłem przez wszystkie te błędy implementując własną bibliotekę Python do KSeF. Ten punkt z formatowaniem dat to rzeczywiście klasyk - straciłem pół dnia na debugowanie zanim zorientowałem się że dodawałem 'Z' na końcu. Co do **sum kontrolnych** - odkryłem dodatkową pułapkę. KSeF nie tylko sprawdza czy netto + VAT = brutto, ale też czy suma wszystkich pozycji zgadza się z polem `P_15` w nagłówku. Czasem przez zaokrąglenia różnica 1 grosz na poziomie całej faktruy psuje walidację: ```python def validate_totals(lines, header_total): calculated_total = sum(line['P_11'] for line in lines) if abs(calculated_total - header_total) > 0.01: # tolerancja 1 grosz raise ValidationError("Niezgodność sum kontrolnych") ``` **Problem z timeoutami** potwierdzam w 100%. Dodatkowo odkryłem że KSeF ma ukryty limit rozmiaru XML około 1.8MB - powyżej tego timeout skraca się drastycznie niezależnie od liczby pozycji. Przy dużych fakturach musiałem implementować chunking. @Martaowacka - co do numeracji po błędach, zrobiłem "shadow numbering". System nadaje numer dopiero po potwierdzeniu UPO z KSeF, a do tego czasu faktura ma status PENDING z tymczasowym UUID. Zero gaps w numeracji ale trochę więcej logiki. Jedna rzecz której nie wspomniałeś - **concurrent sessions per certyfikat**. KSeF ma limit około 4-5 równoczesnych połączeń. Przekroczysz i dostaniesz 401 nawet z ważnym tokenem. Musiałem dodać semaphore żeby to kontrolować przy batch processing. A jak radzisz sobie z **faktury zagranicznymi**? Mam klienta eksportującego do UK i nie jestem pwien czy KSeF w oglóe akceptuje faktury z VAT ID zamisat NIP.

Bardzo przydatne zestawienie! Przeszedłem przez każdy z tych błędów podczas buildowania własnego narzędzia do KSeF. Ten problem z **formatowaniem dat** to była moja pierwsza bolesna lekcja - przez pół dnia debugowałem zanim zorientowałem się że dodawałem `Z` na końcu. Do **sum kontrolnych** dodałbym jeszcze jedną pułapkę - system nie tylko sprawdza czy netto + VAT = brutto na poziomie pozycji, ale też czy suma wszystkich `P_11` zgadza się z `P_15` w nagłówku. Czasem przez różne zaokrąglenia w ERP vs KSeF różnica 1 grosz na poziomie całej faktury psuje walidację: ```python def validate_invoice_totals(lines, header_total): calculated = sum(Decimal(sttr(line['P_11'])) for line in lines) if abs(calculated - Decimal(str(header_total))) > Decimal('0.01'): raise ValidationError("Niezgodność sum kontrolnych") ``` Co do **timeoutów** - odkryłem że KSeF ma ukryty limit rozmiaru XML około 1.5MB. Powyżej tego timeout drastycznie się skraca niezależnie od liczby pozycji. Przy wielopozycyjnych fakturach z długimi opisami musiałem implementować chunking logic. **Bonusowa pułapka nr 6**: **concurrent sessions per certyfikat**. System ma limit około 5-6 równoczesnych połączeń. Przekrocysz i dostajesz 401 nawet z ważnym tokenem. Musiałem dodać semaphore żeby to kontrolować przy batch processing: ```python from asyncio import Semaphore semaphore = Semaphore(5) # max 5 concurrent per cert ``` @MartaNowacka - co do numeracji po błędach, używam "shadow numbering". System nadaje numer dopiero po otrzzymaniu UPO z KSeF, a do tego czasu faktura ma status PENDING z UUID. Zero gaps ale trochę wicej complexity w ERP integration. Praktyczne pytanie - jak radzisz sobie z **fakturami zagranicznymi**? Mam klienta eksportującego do UK i nie jestem pewien czy KSeF w ogóle akceptuje faktury z VAT ID zamiast NIP w polu nabywcy.