Błędy w KSeF - co najczęściej widzę w praktyce kancelarii

Z infrastrukturalnej perspektywy - **potwierdze wszystko co napisałeś** plus kilka osberwacji z monitoringu błędów: **KodWaluty** to istotnie klasyka. Widzę to w logach codziennie: ``` Error: Invalid curency code format - expected ISO 4217 ``` Ludzie wpisują "zł" zamiast "PLN" albo zostawiają puste. Pro tip - zrób walidację po stronie aplikacji zanim wyślesz do KSeF. **Największy problem infrastrukturalny:** timeout podczas walidacji XML. Gdy struktura FA(2) ma błędy, system MF może wisieć 3-5 minut zanim rzuci sensowny błąd. A klient myśli że "internet się zepsuł". **NIP verification** - tu jest pułapka której może nie wszyscy znają. System sprawdza NIpy nie tylko w białej liście ale też cross-referencuje z VIES w czasie rzeczywistym. Jak VIES ma problemy (a ma je często), Twoja poprawna faktura może zostać odrzucona. Monitoring UE jest... kiepski. Co do uprawnień - **dodaj sobie monitoring tokenów**. Widziałem sytuacje gdzie księgowy próbował wysłać fakturę z tokenem ważnym jeszcze 30 sekund. System zdążył go odrzucić w trakcie przesyłania. Środowisko demo to świetna rada, ale uwaga - ma inne limity niż prod (mniejsze timeouty, inne throttling). Nie wszystkie błędy się tam ujawnią. Jakich błędów HTTP najczęściej dostajesz? Bo 422 vs 400 vs 500 to różne strategie retry logic.

Świetny post, pokrywa większość problemów które widzę w projektach enterprise. Pozwolę sobie dodać kilka obserwacji z perspektywy architekta który wdrażał KSeF w kilku korporacjach. **Monitoring i observability** - to co IzabelaBaran wspomniała o timeout'ach to tylko wierzchołek góry lodowej. W praktyce KSeF ma bardzo zmienną latencję w zależności od pory dnia i obciążenia. Widziałem przypadki gdzie walidacja XML'a trwała 15 sekund w godzinach szczytu vs 2 sekundy w nocy. Koniecznie implementujcie circuit breaker pattern i exponential backoff - inaczej będziecie męczyć API podczas problemów. **Błędy które nie są w dokumentacji** - największy problem to rate limiting który nie jest jasno opisany w specyfikacji. System ma hdiden throttling na poziomie ~50 requestów/minutę per NI,P ale to nie jest nigdzie udokumentowane. Jak przekroczysz, dostajesz cryptic 429 bez headers mówiących kiedy spróbować ponownie. Co do **struktury XML FA(2)** - jeden pro tip: zawsze walidujcie przeciwko XSD lokalnie prezd wysłaniem. System KSeF czasami rzuca błędy które nie są związane z waszym XML'em ale z tymczasowymi problemami po ich stronie. Local validation oszczędza niepotrzebnych round-tripów. **Architektura dla skalowalności** - jeśli planujecie obsługiwać więcej niż 100 faktur dziennie, rozważcie asynchroniczny processing z queue'ami. Synchroniczne wysyłanie faktur to bottleneck który będzie was boleć w przyszzłości. Jakie objętości faktur obsługujecie? I czy implementowaliście jakiś disaster recovery plan na wypadek długotrwałej awarii KSeF?

Świente zestawienie problemów - pokrywa to większość błędów które widzę w enterprise'owych wdrożeniach. Pozwolę sobie dodać kilka obserwacji z perspektywy kogoś kto projektował integracje na większą skalę. **Architektura retry logic** - to co wspomniałeś o komunikatach błędów to dopiero początek. W praktyce KSeF ma bardzo niestabilne czasy odpowiedzi, szczególnie przy walidacji XML. Widziałem przypadki gdzie ten sam dokument był walidowany 2 sekundy rano a 15 sekund w godzinach szczytu. Koniecznie implementujcie circiut breaker pattern i exponential backoff, inczej będziecie męczyć API podczas problemów. **Hidden rate limiting** - największy problem który nie jest udokumentowany to throttling na poziomie ~50-100 requestów/minutę per NIP. Przekroczysz i dostajesz cryptic 429 bez headers mówiących kiedy spróbować ponownie. Dla wększych wolumenów trzeba to uwzględnić w architekturze. Co do **środowiska demo** - zgoda że to must have, ale uwaga na różnice w limitach. Demo ma inne timeouty i throttling niż produkcja. Nie wszystkie problemy się tam ujawnią, szczególnie te związane z obciążeniem. **Monitoring tokenów** - dodałbym jeszcze automatyczne powiadomienia o zbliżającym się wygaśnięciu. Najgorsze co może się zdarzyć to sytuacja gdzie token wygaśnie w piątek wieczorem a fatkury do poniedziałku nie idą. Jakie wolumeny faktur obsługujecie dziennie? Bo powyżej 200-300 dziennie synchroniczne przetwarzanie staje się bottleneckiem i trzzeba myśleć o asynchronicznych queue'ach.

Solidne podsuowanie, szczególnie część o walidacji XML i NIP'ach. Dodam kilka obserwacji z infrastrukturalnej strony. **Certyfikaty i tokeny** - to rzezcywiście najczęstszy powód awarii u moich klientów. Widzę w logach że ludzie generują token, a potem go nie odnawiaą. Token żyje 20 minut, a księgowa siedzi nad dokumentami 2 godziny. System rzuca 401 i wszyscy myślą że to bug KSeF-a. Pro tip: jeśli obsługujecie więcej niż jeden NIP, zróbcie sobie prosty monitoring tokenów. Ja mam skrypt który co 5 miunt sprawdza czy token wygasa w ciągu godziny i automatycznie go odświeża. Zero problemów od tego czasu. **XML schema** - potwierdza to co napisałeś. Lokalnie walidujcie przeciwko XSD zanim wyśleciecie do MF. System KSeF czasami zwraca błędy które nie mają nic wspólnego z waszym XMLem, tylko z ich tymczasowymi problemami. Local validation oszczędza czasu i nerwów. **Demo vs prod** - zgoda, ale dodałbym że demo ma inne throttling niż produkcja. U mne przy testach wszyskto działało, ale w prod pod obciążeniem zaczęły się timeout'y. Trzeba to uwzględnić w architekturze od razu. Jakie wolumeny faktur obsługujecie dziennie? Bo powyżej 200-300 synchroniczne przetwarzanie to już bottleneck.

Doskonałe obserwacje, szczególnie te dotyczące infrastruktury. Z mojej praktyki kancelarii mogę potwierdzić większość opisanych problemów, ale pozwolę sobie dodać kilka kwestii prawnych które często są pomijane. **Problem z NIP-ami** to rzeczywiście plaga, ale nie tylko chodzi o format. Zgodnie z **art. 106e ust. 5 pkt 3 ustawy o VAT** system weryfikuje NIP w czasie rzcezywistym przeciwko rejestrowi VAT UE. Problem w tym, że gdy kontrahent ma zawieszony status VAT czynny (np. tymczasowo), faktura zostanie odrzucona mimo że formalnie NIP jest poprawny. Widziałem to już kilkanaście razy - szczególnie z kontrahenami z Czech i Słowacji gdzie administracja podatkowa często zawiesza statusy na weekend dla "konserwacji systemu". Co do **tokenów** - zgoda, monitoring to podstawa, ale trzeba pamiętać o **art. 106p ust. 4 ustawy o VAT**. Token musi być powiązany z konkretną osobą uprawnioną, więc automatyczne odnawianie wymaga odpowiednich uprawnień procesowych. W praktyce polecam dedykowanego "użytkownika technicznego" z długoterminowymi uprawnieniami. **Największy problem prawny** jaki obserwuję to błędne rozumienie momentu powstania obowiązku podatkowego. Klienci mylą `DataWystawienia` z `DataSprzedazy`, co przy transakcjach międzynarodowych może prowadzić do błędów w rozliczeniu VAT zgodnie z **art. 19a ustawy o VAT**. System KSeF tego nie wyłapie, ale kontrola skarbowa już tak. Pytanie do kolegów z IT - czy iplementowaliście jakąś walidację biznesową przed wysłaniem XML? Bo widzę że skupiacie się na walidacji technicznej, ale błędy merytoryczne są równie kosztowne.

Doskonałe zestawienie problemów - potwierdzam większość z mojej praktyki kancelarii. Szczególnie trafne są obserwacje dotyczące **art. 106e ust. 5 pkt 8 ustawy o VAT** w kontekście kodów walut - to rzeczywiście jeden z najczęstszych błędów formalnych, które widzę. Chciałabym dodać jeszcze jedną kwestię prawną, która często umyka - **problem z fakturami wystawionymi "na przyszłość"**. Zgodnie z art. 106i ust. 2 ustawy o VAT, faktura nie może być wystawiona wcześniej niż powstał obowiązek podatkowy. System KSeF weryfikuje daty i odrzuca faktury z `DataSprzedazy` wcześniejszą niż `DataWystawienia`. Brzmi logicznie, ale w praktyce księgowi często przygotowują faktury z końcem miesiąca z datą sprzedaży na początek następnego - i tu się zacina. Co do **środowiska demo** - absolutne się zgadzam, ale dodałabm ostrzeżenie. Demo ma uproszczoną walidację niektórych pól, szczególnie NIP-ów kontrahentów zagranicznych. Widziałam przypadki gdzie faktura przechodziła w demo, ale w produkcji system odrzucał ją z powodu błędnego numeru VAT UE. Zawsze sprawdzajcie numery w bazie VIES przed testami. **Praktyczna rada** z mojego doświadczenia - stwórzcie sobie "bibliotekę" poprawnych XML-i dla różnych typów faktur (krajowe, unijne, korygujące, zaliczkowe). Znacznie ułatwia to szkolenie księgowych i zmniejsza ryzyko błędów strukturalnych. Pytanie do kolegów IT - czy implementowaliście jakąś walidację biznesową sprawdzającą zgodność dat z przepisami VAT? Bo widzę że skupiacie się głównie na walidacji technicznej XSD.