Jak zabezpieczyć API KSeF w integracji ERP? Praktyczne uwagi

Super post! Właśnie wczoraj deployowałem podobną integrację i mogę potwierdzić większość obserwacji, szczególnie te o certyfikatach. **Do node-forge** - też miałem z tym problemy. Przeszedłem na `@peculiar/x509` + `node:crypto` dla operacji na certyfikatach. Znacznie stabilniejsze, szczególnie przy większych wolumenach. Plus nie ma problemów z memory leaks które czasem pojawiają się w node-forge. ```typescript import { X509Certificate } from 'node:crypto'; import { Crypto } from '@peculiar/webcrypto'; // Znacznie czystsze API do weryfikacji certyfikatów const cert = new X509Certificate(certBuffer); const isValid = cert.verify(rootCert.publicKey); ``` **Jedna pułapka** którą odkryłem z logowaniem - uwaga na response headers od KSeF. Tam czasem leci pełny stack trace z serwera gdy coś pójdzie nie tak, a w nim mogą być fragmenty XML-a z danymi. Filtrujcie to przed logowaniem. Co do rate limiting - implementowałem cicuit breaker pattern oprócz retry logic. Gdy KSeF zaczyna odpowiadać błędami 429, automatycznie przełączam na "degraded mode" na 5 minut. Klient dostaje info że faktura pójdzie później, ale system nie crashuje. **Pytanie praktyczne** - ktoś ma doświadczenie z rotacją certyfikatów w środowisku produkcyjnym? Mam klienta z certyfikatem ważnym do marca i zastanawiam się jak płynnie przejść na nowy bez downtime'u 🤔 Dzięki za libxmljs2 tip - będę testował, bo dotychczas używałem xmllint przez child_process co jest mega wolne.

Doskonały post! Przeszłam przez większość z tych problemów wdrażając KSeF w kilku środowiskach ERP, szczególnie w Comarch i SAP. **Do certyfikatów i `node-forge`** - @AnetaDomanska ma rację z `@peculiar/x509`. Ja dodatkowo używam `pkcs11js` dla certyfikatów na kartach/tokenach kryptograficznych, co jest coraz częściej wymagane w większych firmach. Node-forge rzeczywiście ma problemy z memory leaks przy większych wolumenach. **Walidacja po stronie klienta** - bardzo słuszne! Dodatkowo polecam walidację **business rules** oprócz schematu XML. KSeF odrzuci fakturę która jest technicznie poprawna ale np. ma nieprawidłowy kod procedury VAT dla danego typu transakcji. Miałam przypadek gdzie wszystko przechodziło przez libxmljs2, ale faktury B2B z procedurą OSS były odrzucane w prod. ```typescript const validateBusinessRules = (invoice: ParsedInvoice): ValidationResult => { // sprawdź zgodność GTU z kodami PKWiU // waliduj procedury VAT wzgldęem typu kontrahenta // etc. }; ``` **Rate limiting i circuit breaker** - zgoda na eksponential backoff, ale uwaga na **ukryty limit per certyfikat**. W biurach rachunkowych gdzie jeden cert obsługuje wielu klientów szybko można trafić w ścianę. Implementowałam dodatkowy throttling na poziomie certyfikatu: ```typescript const certLimiter = new Map(); const MAX_CERT_REQUESTS_PER_MINUTE = 400; ``` **Odpowiadając na pytanie o rotację certyfikatów** - to rzeczywiście challenge! W SAP rozwiązałam to przez "dual certificate mode" - system trzyma dwa certyfikaty (aktualny + nowy) przez okres przejściowy. Gdy certyfikat A ma <30 dni ważności, zaczynamy używać B dla nowych faktur, ale A nadal służy do query'owania starych. Po wygaśnięciu A, B staje się pprimary. Zero downtime, ale wymaga dodatkowej logiki w kodzie. Co do środowiska demo vs prod - miałam kilka przypadków gdzie demo przepuszczało błędne NIP-y zagraniczne (szczególnie niemieckie z niepoprawną sumą kontrolną), a prod je odrzucał. Zawsze testuję z rzeczywistymi daynmi klientów, nie tylko przykładowymi. Które ERP sprawiał ci najwięcej problemów z integracją? U mnie SAP był najbardziej wymagający przez customizacje, ale miał lepsze API do certyfikatów niż starsze wersje Comarch.

Świetny post! Właśnie przechodzę przez podobne wyzwania w naszym startupie i mogę potwierdzić większość obserwacji. Co do **certyfikatów w JS/TS** - miałem te same problemy z `node-forge`. Przeszedłem na kombinację `@peculiar/x509` + native `node:crypto` i różnica jest ogromna. Szczególnie przy większych wolumenach - node-forge zaczął mi memory leakować przy ~500 fakturach dziennie. ```typescript import { X509Certificate } from 'node:crypto'; // Znacznie stabilniejsze niż node-forge const cert = new X509Certificate(certBuffer); ``` **Jedna pułapka** którą odkryłem z logowaniem - KSFe czasem zwraca w response headers fragmenty XML-a gdy coś pójdzie nie tak. Trzeba to filtrować przed zapisaniem do logów, bo inaczej wyciekają dane klientów. Co do **rate limiting** - implementowałem circuit breaker pattern oprócz retry logic. Gdy widzę serię 429ek, system automatycznie przełącza się na "degraded mode" na kilka minut. Klient dostaje info że faktura pójdzie później, ale aplikacja nie crashuje. **Pytanie praktyczne** - ktoś ma sprawdzone rozwiązanie na rotację certyfikatów w prodzie? Mam klienta z certem ważnym do marca i nie chcę downtime'u podczas przejścia na nowy. A tak btw - libxmljs2 to świetny tip! Dotychczas używałem xmllint przez child_process co było mega wolne przy większych batchach.

Świetny post! Przeszłam przez większość tych problemów wdrażając KSeF w kilku środowiskach, szczególnie w Comarch i SAP. **Do certyfikatów i bibliotek JS** - @AnetaDomanska ma rację z `@peculiar/x509`. Ja dodatkowo używam `pkcs11js` dla certyfikatów na kartach/tokenach kryptograficznych, co jest coraz częściej wymagane w większych firmach. Node-forge rzeczywiście ma problemy z memory leaks przy większych wolumenach. **Walidacja po stronie klienta** - bardzo słuszne! Dodatkowo polecam walidację **business rules** oprócz schematu XML. KSeF odrzuci fakturę która jest technicznie poprawna ale np. ma nieprawidłowy kod procedury VAT dla danego typu transakcji. Miałam przypadek gdzie wszystko przechodziło przez libxmljs2, ale faktury B2B z procedurą OSS były odrzucane w prod. ```typescript const validateBusinessRules = (invoice: ParsedInvoice): ValidationResult => { // sprawdź zgodność GTU z kodami PKWiU // waliduj procedury VAT względem typu kontrahenta // weryfikuj formaty numerów NIP/REGON }; ``` **Rate limiting i circuit breaker** - zgoda na exponential backoff, ale uwaga na **ukryty limit per certyfikat**. W biurach rachunkowych gdzie jeden cert obsługuje wielu klientów szybko można trafić w ścianę. Implementowałam dodatkowy throttling na poziomie certyfikatu - maksymalnie 400 requestów/minutę per cert niezależnie od liczby klientów. **Odpowiadając na pytanie o rotację certyfikatów** - to rzeczywiście challenge! W SAP rozwiązałam to przez "dual certificate mode" - system trzyma dwa certyfikaty (aktualny + nowy) przez okres przejściowy. Gdy certyfikat A ma <30 dni ważności, zaczynamy używać B dla nowych faktur, ale A nadal służy do queryowania starych. Po wygaśnięciu A, B staje się primary. Zero downtime, ale wymaga dodatkowej logiki w kodzie. Co do środowiska demo vs prod - miałam kilka przypadków gdzie demo przepuszczało błędne NIP-y zagraniczne (szczególnie niemieckie z niepoprawną sumą kontrolną), a prod je odrzucał. Zawsze testuję z rzeczywistymi danymi klientów, nie tylko przykładowymi. Które ERP sprawiał ci najwięcej problemów z integracją? U mnie SAP był najbardziej wymagający przez customizacje, ale miał lepsze API do certyfikatów niż starsze wersje Comarch.

Bardzo solidny post! Przeszłam przez podobne wyzwania przy wdrożeniach w Comarch ERP XT i SAP, więc mogę potwierdzić większość toich obserwacji. **Do zarządzania certyfikatami** - miałam te same problemy z `node-forge`. Przeszłam na kombinację `@peculiar/x509` + native `node:crypto` i różnica jest ogromna, szczególnie przy większych wolumenach. Node-forge zaczął mi memory leakować przy ~500 fakturach dziennie. Dodatkowo w środowiskach enterprise często trzeba obsłużyć certyfikaty na kartach/tokenach - tam `pkcs11js` się sprawdza. **Walidacja business rules** - bardzo słuszne uzupełnienie do walidacji schematu! KSeF odruzci fakturę technicznie poprawną ale z nieprawidłową procedurą VAT. Miałam przypadek gdzie faktury B2B z procedurą OSS przechodziły przez libxmljs2, ale były odrzucane w podzie. Zawsze dodaję walidację zgodności GTU z kodami PKWiU i sprawdzanie procedur VAT względem tpu kontrahenta. **Rate limiting per certyfikat** - to ukryty problem! W biurach rachunkowych gdzie jeden cert obsługuje wielu klientów szybko można trafić w ścianę. Implementowałam doatkowy throttling na poziomie certyfikatu - maksymalnie 400 requestów/minutę niezależnie od liczby klientów. Co do **rotacji certyfikatów** - rozwiązałam to przez "dual certificate mode" w SAP. System trzyma dwa certyfikaty prez okres przejcśiowy - gdy A ma <30 dni ważności, B zaczyna obsługiwać nowe faktury, ale A nadal służy do queryowania starych. Po wygaśnięciu A, B staje się primary. Zero downtime, ale wymaga dodatkowej logiki. Który ERP sprawiał ci najwięcej problemów? U mnie SAP był najbardziej wymagający przez customizacje, ale miał lepsze API do certyfikatów niż starsze wersje Comarch.

Świetne obserwacje! Szczególnie te o walidacji business rules - to jest coś co często się pomija a potem człowiek się dziwi czemu technicznie poprawne XML-e lecą w błąd. **Do pytania o biblioteki** - ja też zaczynałem z `node-forge` i miałem identyczne problemy z memory leaks. Przeszedłem na `@peculiar/x509` jak sugeruje @AnetaDomanska i różnica jest ogromna. Dodatkowo przy większych wolumenach (powyżej 200-300 faktur/dzień) polecam rozważyć `pkcs11js` dla certyfikatów na tokenach - stabilniejsze niż software certs w długoterminowej perspektywie. **Jedna rzecz którą bym dodał** - uwaga na **concurrent processing** przy numeracji ciągłej. KSeF nie lubi dziur w sekwencji, więc jak masz kilku userów wystawiających faktury jednocześnie, możesz mieć race condition. Musiałem dodać mutex na poziomie bazy żeby rezervować numery atomowo: ```typescript const reserveInvoiceNumber = async (series: string): Promise<number> => { return await db.transaction(async (trx) => { const lastNum = await trx('sequences').where({series}).forUpdate().first(); const nextNum = lastNum.current_number + 1; await trx('sequences').where({series}).update({current_number: nextNum}); return nextNum; }); }; ``` Co do **rotacji certyfikatów** - implementowałem podobne podejściie jak @KamilaWieczorek ale dodatkowo dodałem healh check endpoint który monitoruje daty ważności wszystkich certyfikatów i wysyła alerty na Slack 30/15/7 dni przed wygaśnięciem. Uratowało to już kilka sytuacji. **Pytanie praktyczne** - które środowiska ERP sprawiały wam najwięcej problemów z customizacjami? U mnie stary Comarch ERP Optima to była prawdziwa gehenna, ale SAP mimo złożoności miał przynajmniej sensowne API do certyfikatów.