Zbiorcza wysyłka faktur do KSeF z Comarch ERP XL i w konsoli ląduje długi łańcuszek błędu: Invalid operation ‘SendBatch’: Operation failed due to component error: OpenBatchSessionAsync failed due to unauthorized access and token refresh error: Bad Request. W praktyce to komunikat z jednym prostym znaczeniem – XL próbuje otworzyć sesję zbiorczą w KSeF, dostaje 401 Unauthorized od API MF i przy próbie odnowienia tokena łapie kolejny błąd 400. Nie chodzi tu o dane faktury ani o schemę XML – problem jest po stronie sesji i tokena operatora.
Dlaczego XL zwraca ten błąd
Każda sesja KSeF w Optimie i XL bazuje na parze: token autoryzacyjny operatora + aktywna sesja API MF. Token ma swój czas życia i zakres uprawnień, sesja – jeszcze krótszy TTL. Kiedy XL próbuje uruchomić wysyłkę zbiorczą (SendBatch), otwiera nową sesję na tokenie operatora. Jeśli token wygasł, został wygenerowany dla innego środowiska (np. Demo, a wysyłka idzie na Produkcję) lub ma za wąski zakres uprawnień, MF zwróci 401. XL próbuje wtedy odnowić token (token refresh), ale endpoint refresh nie akceptuje wygasłego lub niepasującego tokena – dostaje 400 Bad Request. Efekt: często obie sesje (poprzednia i nowa) są w niespójnym stanie, a XL nie potrafi się sam z tego wygrzebać.
Krok po kroku – jak przywrócić wysyłkę
Krok 1 – zamknij aktywną sesję KSeF w XL
Z menu System → Sesja KSeF wybierz opcję zamknięcia aktywnej sesji. To wymusza porzucenie niespójnego stanu sesji, której używał SendBatch. Jeśli w oknie jest widoczna aktywna sesja – zamknij ją ręcznie, nawet jeśli status wygląda poprawnie.
<screen>
Krok 2 – zrestartuj Comarch ERP XL
Zamknij całkowicie aplikację (nie tylko okno modułu handlowego) i uruchom ją ponownie. Przy starcie XL nawiąże nową sesję na aktualnym tokenie operatora – bez śladów poprzedniej, uszkodzonej. W wielu przypadkach ten krok wystarcza, żeby wysyłka zbiorcza znowu ruszyła.
Krok 3 – jeśli błąd wraca, usuń wpis operatora z cdn.KSeFTokeny
Uruchom SQL Server Management Studio, połącz się z bazą firmową XL i sprawdź tabelę cdn.KSeFTokeny – to tam XL trzyma zapisane tokeny/uwierzytelnienia poszczególnych operatorów. Znajdź wiersz odpowiadający operatorowi, który napotkał błąd i usuń go (przed usunięciem zrób backup lub zapisz zawartość na bok). Po ponownym uwierzytelnieniu tego operatora w XL, wpis zostanie odtworzony automatycznie już na świeżym tokenie. To rozwiązuje sytuacje, w których w tabeli siedzi “martwy” token, którego XL nie potrafi odnowić.
<screen>
Krok 4 – zweryfikuj środowisko tokena (Demo vs Produkcja)
W konfiguracji KSeF w XL sprawdź, dla jakiego środowiska wygenerowano token operatora. Częsty scenariusz: token pochodzi z testowego środowiska Demo, a wysyłka celuje w Produkcję (lub odwrotnie po przełączeniu klienta z Demo na Prod). MF nie zaakceptuje takiego tokena i zwróci 401 nawet dla poprawnego formalnie żądania. Wygeneruj nowy token dla właściwego środowiska.
<screen>
Krok 5 – zweryfikuj uprawnienia tokena
Token KSeF ma zakres uprawnień (m.in. wystawianie faktur, odczyt, zarządzanie uprawnieniami, samofakturowanie). Do wysyłki zbiorczej (SendBatch) potrzebujesz przynajmniej uprawnienia do wystawiania faktur. Jeśli token był generowany “minimalistycznie” (tylko odczyt lub tylko konkretna rola) – MF odrzuci wysyłkę. W praktyce najbezpieczniej wygenerować nowy token z pełnym zestawem uprawnień dla operatora technicznego biuletynu KSeF, który będzie używany przez XL.
<screen>
Kiedy sprawa jest po stronie MF, a nie XL
Zdarza się, że cały powyższy łańcuszek jest w porządku, a XL nadal zwraca 401/400 – warto wtedy sprawdzić status środowiska KSeF na stronie MF (podatki.gov.pl → KSeF → Status środowiska). Krytyczne prace serwisowe lub incydenty po stronie MF potrafią blokować wysyłkę zbiorczą z tym samym komunikatem błędu, mimo że token i sesja są poprawne. W takich sytuacjach jedyne co pomaga to poczekać na przywrócenie usługi.
Perspektywa ELTE-S
OpenBatchSessionAsync unauthorized w 9 na 10 wdrożeń sprowadza się do jednego z trzech twórców problemu: uszkodzony stan sesji po restarcie serwera, martwy token w cdn.KSeFTokeny albo niezgodność środowiska Demo/Prod na tokenie. Dopóki nie odetnie się tych trzech możliwości, nie warto szukać problemu w schemacie faktury ani w połączeniu sieciowym. Praktyczna wskazówka na przyszłość: dokumentujcie u siebie który operator w bazie ma token na jakie środowisko i pilnujcie, żeby po zmianie z Demo na Produkcję wyczyścić cdn.KSeFTokeny lub wygenerować nowe tokeny – to eliminuje 80% przypadków tego błędu. Interwencja w tabeli KSeFTokeny wygląda mocno technicznie, ale w praktyce jest bardzo bezpieczna – wpis odtwarza się automatycznie przy następnym logowaniu operatora.
Porozmawiajmy o uporządkowaniu integracji KSeF w Twoim Comarch ERP XL.