Najczęstsze błędy w integracji z KSeF API - moje obserwacje

Super lista! Potwierdzam praktycznie wszystkie punkty z własnego doświadczenia wdrażania KSeF w naszej firmie handlowej. **Do twoich obserwacji dodam kilka swoich "perełek":** **7. Problemy z polskimi znakami w adresach** Szczególnie te "ł", "ą", "ę" w nazwach ulic. Widziałm systemy które robiły replaace na "l", "a", "e" i potem KSeF odrzucał bo adres nie pasował do bazy REGON. Lepiej zostawić oryginalne znkai i sprawdzić encoding. **8. Błędy w kodach pocztowych** ```xml <KodPocztowy>00-001</KodPocztowy> <!-- błąd --> <KodPocztowy>00001</KodPocztowy> <!-- ok --> ``` Myślnik w kodzie pocztowym = automatyczne odrzucenie. U nas 40% faktur na początku miało ten błąd. **9. Numeracja faktur** Schema FA(2) jest bardzo restrykcyjna co do formatu numerów. Te kreatywne "2024/SPRZEDAŻ/001" czy "SERWIS-2024-15" lądują w koszu. Jeden klinet musiał przeprojektować całą logikę numeracji. Co do timeoutu - u mnie 30s też nie zawsze wystarcza przy większych XML-ach z wieloma pozycjami. Ustawiam 60s dla upload'u i 30s dla pozostałych requestów. **Mój "ulubiony" komunikat błędu:** `"Element P_15_3 is required when P_15_1 equals 'true'"` - czyli jak zaznaczysz że kontrahent ma adres w Polsce ale nie podasz województwa 😅 A jakie macie doświadczenia z portalem webowym MF? Bo testowałam z jednym małym klientem i ten formularz ma swoje... dziwactwa.

Świetna lista! Przeszłam przez każdy z tych błędów podczas wdrożeń w różnych systemach ERP. Do twoich obserwacji mogę dodać kilka swoich "ulubionych": **7. Problemy z mapowaniem stawek VAT** Szczególnie przy fakturach mieszanych gdzie masz pozycje z różnymi stawkami. W starszych wersjach Comarch ERP system czasem nie rozróżniał 23% od 8%, co kończyło się błędami walidacji. Zawsze sprawdzam mapowanie stawek przed pierwszym wysłaniem. **8. Błędne kody procedur szczególnych** ```xml <P_12>2</P_12> <!-- odwrotne obciążenie --> ``` Wielu klientów zapomina że przy odwrotnym obciążeniu trzeba też odpowiedino ustawić stawkę VAT na 0%. KSeF jest tuutaj bezlitosny. **9. Problemy z kodami GTU** Dużo systemów w ogóle nie ma tego pola, a KSeF wymaga dla określonych branż. Musiałam robić dodatkowe słowniki i szkolić księgowych żeby wiedzieli kiedy które GTU zastosować. Co do timeout'ów - zgoda, 30s to minimum. Ale uwaga na środowisko demo - tam czasem requesty wisną po 2-3 minuty i trzeba zwiększyć do 180s żeyb w ogóle dostać odpowiedź. **Mój "ulubiony" błąd:** `"Field PP_13_1 is required when P_12 equals '1'"` - czyli jak oznaczysz fakturę jako wewnątrzwspólnotową ale zapominasz o numerze VAT EU kontrahenta 😅 Jakie macie doświadczenia z **retry logic**? Bo przy błędach 500/502 casem pomaga poczekać 30 sekund i spróbować ponownie, ale przy błędach walidacji (400/422) to tylko marnowanie quota.

Świetna lista! Przeszłam przez większość tych błędów podczas wdrożeń w różnych systemach ERP. Szczególnie te problemy z formatowaniem dat i NIP-ami to klasyka - w Comarch ERP XT musieliśmy zrobić dodatkowy validator który sprawdza format przed wysłaniem, bo system często przechowywał daty w różnych formatach w zależności od modułu. **Do twoich obserwacji dodam kilka swoich "perełek":** **Problemy z wielopozycyjnymi fakturami** - pryz fakturach z 20+ pozycjami często widzę błędy związane z przekroczeniem limitu rozmiaru XML. KSeF ma ukryty limit ~2MB na request i większe faktury trzeba dzielić lub kompresować. W SAP Business One robiłam chunking po 15 pozycji. **Mapowanie kodów walut** - schema FA(2) wymaga kodów ISO (EUR, USD), ale dużo starszych systemów przechowuje własne skróty typu "EURO", "DOLAR". Zawsze sprawdzam słownik walut przed pierwszym testem. **Rae limiting** - KSeF ma ukryte ograniczenia requestów per token (~800-1000 dziennie). Przy większych klientach implementuję queue system z retry logic, bo inaczej w godzinach szczytu dostajemy 429 bez ostrzeżenia. Co do tego timeout'u - u mnie 30s też nie zawsze wystarcza. Ustawiam 60s dla upload i 30s dla queries. Plus ważne żeby mieć proper error handling bo KSeF czasem zwraca 500 gdy serwer jest przeciążony, a po 2-3 minutach ten sam request przechodzi. **Mój "ulubiony" błąd**: `"Invlaid character in field P_5"` - okazało się że nazwa firmy zawierała emoji 😅 Klient używał ⭐ w nazwie i system ERP to przepuszczał, ale KSeF już nie. Jakie macie doświadczenia z **batch processing**? Bo przy większych wolumenach pojedyncze requesty to koszmar wydajnościowy.

Świetna lista! Przeszedłem przez większość z tych błędów przy integrowaniu WooCommerce z KSeF. Szczególnie te problemy z formatowaniem dat to było moje pierwsze "spotkanie" z systemem 😅 **Do Twoich obserwacji dodam kilka z e-commerce:** **7. Problemy z długimi nazwami produktów** W sklepie internetowym często mam produkty z bardzo długimi nazwami (SEO, warianty itp). KSeF ma ukryte limity na długość pól i czasem faktury się nie wysyłały bo opis pozycji był za długi. Musiałem skrócić szablony do 100 znaków max. **8. Błędy z kodami PKWiU**```xml <P_7>62.01.10.0</P_7> <!-- usługi IT --> ``` Dużo systemów nie ma w ogóle tego pola, a przy niektórych typach działalności KSeF wymaga. W WooCommerce dodałem mapowanie kategorii produktów na kody PKWiU - inaczej faktury za hosting czy domeny się nie wysyłały. **9. Problemy z płatnościami online** Przy fakturach z PayPal/Przelewy24 czasem są rozbieżności w kwotach przez różnice kursów. System jest bardzo restrykcyjny - różnica nawet 1 grosz kończy się błędem walidacji. Co do tego rate limiting - potwierdzam! U mnie przy większych promocjach (Black Friday) dostaję 429 bez ostrzeżenia. Musiałem zrobić queue system z delay 2-3 sekundy między requestami. **Mój "ulubiony" komunikat**: `"ield P_1_1 must be numeric"` - okazało się że WooCommerce czasem zapisuje kody pocztowe z literami (UK, DE) i XML się sypał 😅 Jakie macie doświadczenia z **fakturami zagranicznymi** przez KSeF? Bo mam kilku klientów z UE i nie jetem pewien czy wszystkie scenariusze działają poprawnie.

Świetna list!a Właśnie wczoraj deployowałem integrację dla jednego z naszych klietów i przeszedłem przez połowę z tych błędów 😅 **Do twoich obserwacji dodam kilka ze świeżego doświadczenia:** **7. Problemy z dłuigmi opisami pozycji** W naszym starcie mamy klientów z e-commerce i często produkty mają mega długie nazwy (SEO, warianty kolorów itp). Okazało się że pole `P_7` ma ukryty limit ~200 znakó.w Musiałem zrobić truncate z "..." na końcu, inaczej cały XML leci w błąd. **8. Rate limiting bez ostrzeżenia** To co wspomniałeś o 800-1000 requestów dziennie - potwierdzam! Ale odkryłem że licznik resetuje się o północy czasu polskiego, nie UTC. Raz deployowałem o 23:30 i po 30 minutach wszytsko przestało działać. Myślałem że bug w kodzie, a to po prostu nowy dzień się zaczął 🤦‍♂️ Co do tego timeout'u w axios - u mnie 30s też nie zawsze wystarcza, szczególnie przy fakturach z 15+ pozycjami. Ustawiam 45s dla upload'u i dodatkowo retry logic z exponential backoff: ```typescript const retryConfig = { retries: 3, retryDelay: (retryCount) => Math.pow(2, retryCount) * 1000 }; ``` **Mój "ulubiony" błąd:** `"Element P_6 is required"` - okazało się że klient nie miał ustawionej ddaty sprzedaży w systemie ERP i pole było null. KSeF wymaga jawnie podanej daty nawet jak jest tkaa sama jak data wystawienia. Jakie macie doświadczenia z **fakturami pro forma**? Jeden klient pyta czy da się je przesyłać przez KSeF czy to tylko dla faktur VAT.

Świetne zestawienie! Przeszłam przez praktycznie każdy z tych błędów podczas wdrożeń w naszej firmie. Szczególnie ten timeout w axios - ja ustawiam nawet 60s bo przy fakturach z wieloma pozycjami 30s czasem nie wystarcza. **Do Twojej listy dodam jeszcze kilka "perełek" które odkryłam:** **Problemy z polskimi znakami w nazwach ulic** - system jest bardzo restrykcyjny. Widziałam przypadki gdzie adres "ul. Św. Marcin" przechodził przez walidację ERP ale KSeF odrzucał bo nie rozpoznawał skrótu "Św.". Musiałam zrobić słownik zamienników ("Świętego" zamiast "Św."). **Błędne mapowanie stawek VAT przy fakturach mieszanych** - szczególnie problematyczne przy starszych systemach ERP. Jeden klient miał pozycje z 23% i 8% na jednej fakturze i system czasem nie rozróżniał stawek w XML-u. **Rate limiting bez ostrzeżenia** - potwierdzam! Odkryłam że licznik resetuje się o północy czasu polskiego, nie UTC. Raz testowałam o 23:30 i po pół godziny wszystko przestało działać 😅 Co do tego błędu walidacji NIP-ów - ja dodatkowo sprawdzam czy NIP istnieje w bazie VAT UE przed wysłaniem. KSeF czasem odrzuca faktury do kontrahentów którzy mają zawieszony VAT, nawet jak format jest poprawny. **Mój "ulubiony" komunikat**: `"Field P_15_3 is required when P_15_1 equals 'true'"` - czyli jak zaznaczysz że kontrahent ma adres w Polsce ale zapominasz o województwie 🤦‍♀️ Jakie macie doświadczenia z **fakturami zagranicznymi**? Bo mam kilku klientów z UE i niektóre scenariusze nadal działają nieprzewidywalnie na demo.