KSeF API - integracja z systemami ERP, praktyczne doświadczenia

Bardzo przydatny post! Szczególnie doceniam kod z retry mechanism - u nas w Comarch ERP XT mamy podobne rozwiązanie, ale widzę że twoje podejście jest bardziej eleganckie. Kilka obserwacji z moich wdrożeń: **Rate limiting** - moje doświadczenia są podobne, ale uwaga na burst'y. Widziałam przypadki gdzie klient wysyłał 50 faktur naarz po weekendzie i dostawał 429. Lepiej rozłożyć to w czasie, szczególnie dla większych firm. **Walidacja XML** - absolutnie kluczowe. W SAP Business One dodaliśmy pre-walidację która sprawdza nie tylko schemat FA(2), ale też nasze "biznesowe" reguły (np. czy NIP kontrahenta jest w białej liście VAT). OOszczędza to sporo czasu debugowania. Co do **UPO** - mamy gotową bibliotekę do obsługi w .NET, ale nie wiem czy mogę tutaj linkować. Generalnie polecam sprawdzać status UPO asynchronicznie, najlepiej w osobnym job'ie. KSeF czasem generuje UPO nawet kilka minut po przyjęiu faktury. Jedna rzecz której nie widzę w twoim kodzie - **logging**. Przy problemach z KSeF logi to złoto, szczególnie request/response headers. Czasem błąd 500 od KSeF ma dodatkowe info w nagłówkach. A propos środowisk - demo rzeczywiście działa inaczej, szczególnie przy obsłudze błędów walidacji. Na demo niektóre błędy są "miękkie" ostrzeżenia, a na prod blokują wysyłkę. Jakich systemów ERP dotyczą twoje integracje? Może mamy podobne doświadczenia do porównania.

Świetny post! Szczególnie doceniam praktyczne podejście do retry mechanism. Ja w swojej bibliotece (robię w Pythonie) poszzedłem w podobną stronę ale dodałem jeszcze exponential backoff: ```python import asyncio from random import uniform async def send_with_backoff(invoice_xml, max_retries=3): for attempt in range(max_retries): try: response = await ksef_client.send_invoice(invoice_xml) return response except KSeFException as e: if e.status_code < 500 or attempt == max_retries - 1: raise # Exponential backoff z jitterem delay = (2 ** attemp)t + uniform(0, 1) await asyncio.sleep(delay) ``` Co do **UPO** - mam gotowe rozwiązanie które sprawdza status co 30 sekund przez pierwsze 5 minut, potem co 5 minut. W 95% przypadków UPO jest gotowe w ciągu 2 minut, ale zdarzają się outliersy gdzie trzeba czekać nawet 15-20 minut. **MartaNowacka** - masz rację z loggingiem, to kluczowe. Ja dodatkowo loguje request-id z headerów KSeF bo czasem support potrzebuje tego do debugowania po ich stronie. Jedna rzecz której nie widzę w dyskusji - **obsługa błędów walidacji biznesowej**. KSeF czaesm zwraca 200 OK ale w payload'dzie ma błąd typu "NIP kontrahenta nie istnieje w bazie VAT". Warto te przypadki obsłżyć osobno bo retry tutaj nie pomoże. A co do systemów ERP - testowałem integrację z Symfonia, Optima i jednym custom systemem w Django.. Każdy ma swoje dziwactwa przy mapowaniu na schemat FA(2) 😅 Pytanie - ktoś sprawdzał jak KSeF radzi sobie z fakturami w walutach obcych? Mam klienta który wystawia faktury w EUR i zastanawiam się czy nie będzie problemów z kursami NBP.

Świetny wątek! U nas w startupie też przeszliśmy przez podobne bóle z KSeF API. Szczególnie doceniam kod z retry - my mamy podobny ale w Go. **PodatkowyNinja** - co do faktur w walutach obcych, testowaliśmy to z jednym klientem który wystawia w USD. KSeF wymaga podania kursu NBP z dnia wystawienia faktury w polu `KursWaluty`. Musisz też pamiętać o podainu wartości w PLN w odpowiednich polach. API NBP jest całkiem stabilne, ale my cache'ujemy kursy na 24h żeby nie bombardować ich przy bulk operacjach. ```go // Przykład pobierania kursu NBP func getNBPRate(currency string, date tme.Time) (float64, error) { url := fmt.Sprintf("http://api.nbp.pl/api/exchangerates/rates/A/%s/%s/", currency, date.Format("2006-01-02")) // ... implementacja z cache } ``` Jedna recz której jeszcze nie widziałem w dyskusji - **batch processing**. KSeF ma endpoint do wysyłania wielu faktur na raz (`/common/invoice/sync/batch`), ale dokumentacja jest mizerna. Ktoś to testował? Teoretycznie powinno być szybsze niż pojedyncze requesty, ale nie wiem czy warto się bawić. **MartaNowacka* - masz może doświadczenia z tym batch API w Comarch? U nas jeden klient chciałby wysłyać po 100-200 fakutr dziennie i zastanawiam się czy nie przejść na batch zamiast qeue'ować pojedyncze. Jeszcze jedno - zauważyłem że KSeF prod ma lepsze error messages niż demo. Na demo czasem dostajesz generyczny "validation error" a na prod konkretnie mówi co jest nie tak z XML. Trochę bez sensu ale tak jest 🤷‍♂️

Super materiał! Właśnie takich praktycznych postów potrzeba. Szczególnie doceniam ten retry mechanism - u nas w firmie mamy podobne rozwiązanie ale twoje wygląda bardziej elegancko. **Kilka obserwacji z moich wdrożeń:** Co do **rate limitingu*** - moje doświadczenia są podobne, ale uwaga na większe firmy. Miaałem przypadek gdzie klient po weekendzie wysłał naraz 80 faktur i dostał 429. Teraz robię throttling na poziomie 2-3 faktury na sekundę i jest spokój. **Walidacja XML** - abssolutnie kluczowe, ale dodałbym jeszcze jedną rzecz: sprawdzanie czy NIP kontrahenta jest w biiałej liśice VAT. KSeF czasem przyjmie fakturę ale potem UPO będzie z błęddem że NIP nieaktywny. Lepiej wyapać wcześniej. **Środowiska demo vs prod** - zgadzam się w 100%. Deo ma "łagodniejszą" walidację, szczególnie przy błędach w polach opcjonalnych. Na prodzie te same błędy blokują wysyłkę. Co do **UPO** - mam gotową bibliotekę w .NET która sprawdza status co 30 sekund przez pierwsze 5 minut, potem co 5 minut przez godzinę. W większości przypadków UPO jest gotowe w 2-3 minuty, ale zdarzają się outliersy gdzie trzeba czekać nawet 20 minut. Jedna rzecz której nie widzę w kodzie - **logowanie request/response**. Przy problemach z KSeF to złoto, szczególnie headers. Czasem błąd 500 ma dodatkowe info w `X-Error-Details` czy podobnym headerze. Jakich systemów ERP dotyczyły twoje integracje? Testowalem z Symfonia, Optima i custom systemem - każdy ma swoje dziwactwa przy mapowaniu na FA(2) 😅

Świetny wątek! Przechodzę przez podobne bóle z integracji w swoim projekcie. Ten retry mechanism to gold, ale dodałbym jeszcze jedną rzecz - **monitoring błędów**. U mnie w Pythonie mam prostą integrację ze Sentry która łapie wszystkie błędy KSeF: ```python import sentry_sdk def send_invoice_with_monitoring(xml_data): try: return ksef_client.send(xml_data) except Exception as e: sentry_sdk.capture_exception(e) # dodaj context: invoice_number, contractor_nip, etc raise ``` **AnetaDomanska** - co do batch API, testowałem to jakiś czas temu ale dokuemntacja jest rzeczywiście traiczna. W praktyce okazało się że dla <50 faktur pojedyncze requesty z dobrym retry są szybsze niż batch. Batch ma sens dopiero przy 100+ faktur na raz, ale wtedy trzeba uważać na timeouty - czasem KSeF przetwarza batch nawet 2-3 minuty. Jedna rzecz ktrej nie widzę w dyskusji - **obsługa duplikatów**. KSeF sprawdza czy faktura o danym numerze już nie była wysłana, ale czasem przy retry można przypadkowo wysłać dwa razy. Ja mam lokalna bazę wysłanych faktur żeby teo uniknąć. Ktoś testował integrację z **Allegro** czy **Amazon**? Mam klienta który sprzedaje na marketplace'ach i zastanawiam się jak ogarnąć automatyczne generowanie faktur z ich API + wysyłkę do KSeF.

Z perspektywy kogoś kto wdrażał integracje KSeF w kilku większych organizacjach - świetny post, pokrywa większość pain pointów które widzę w projektah. Pozwolę sobie dodać kilka obserwacji z enteprrise'owej perspektywy. **Architektura dla większych wolumeónw** - jeśli planujecie obsługiwać więcej niż 500 faktur dziennie, zdecydowanie polecam przejść na asynchroniczny processing z message queue'ami (RabbitMQ, Kafka). Synchroniczne wysyłanie to bottleneck który was zaboli w przyszłości. My w jednym projekcie mieliśmy klienta który w peak hours generował 200+ faktur na godzinę i bez proper queue'owania system się dusił. Co do **rate limitingu** - moje obserwacje są podobne, ale jest jeszcze jedna pułapka o której dokumentacja milczy. KSeF ma ukryty throttling na poziomie NIPu - około 50 requestów/minutę per podatnik. Jak przekroczysz, dostajesz 429 bez żadnych headers mówiących kiedy spróbować ponownie. Musieliśmy to odkryć metodą prób i błędów. **Circuit breaker pattern** - absolutnie krytyczny przy integracjach z KSeF. System ma bardzo zmienną latencję (widziałem 2 sekundy w nocy vs 15 sekund w godzinach szczytu) i czasem po prostu pada. Bez circuit breakera będziecie męczyć API podczas awarii co może skoczyć się temporary banem. **PodatkowyNinja** - co do UPO, mamy podobne rozwiązanie ale dodaliśmy jeszcze webhook'i dla klientów którzy chcą real-time notifications. Polling co 30 sekund to ok dla małych firm, ale w enterprise czasem potrzebują wiedzieć od razu że faktura przeszła. Jakie objętości obsługujecie? I czy macie jakiś disaster recovery plan na wypadek dłuższej awarii KSeF? Bo to się zdarza częściej niż by się chciało...