Większość błędów integracji z KSeF ma przypisany kod, który szybko pokazuje, czy problem dotyczy Twojej konfiguracji, czy systemu dostawcy. Najpierw zapisz pełny komunikat i kod, a następnie sprawdź, kto powinien wykonać naprawę.
Co oznacza kod błędu?
Poniższa tabela pozwala wstępnie określić źródło problemu. Błędy uprawnień, podpisu i certyfikatu zwykle można usunąć po stronie firmy. Problemy z autoryzacją API lub działaniem integracji wymagają zgłoszenia do dostawcy programu.
| Kod błędu | Opis | Kto naprawia |
|---|---|---|
| 401 | Problem z autoryzacją, nieprawidłowy token API lub komunikat „autoryzacja w trakcie” | Dostawca integracji |
| 403 | Brak uprawnień do wystawiania lub wysyłania faktur | Użytkownik, a przy problemie technicznym dostawca |
| 415 | Brak uprawnień osoby podpisującej plik autoryzacyjny | Użytkownik |
| 21111 | Nieprawidłowe, nieaktualne lub ponownie użyte wyzwanie autoryzacyjne | Użytkownik |
| 21115 | Certyfikat pochodzi z niewłaściwego środowiska albo jest nieprawidłowy | Użytkownik |
| 9103 | W dokumencie znajduje się więcej niż jeden podpis | Użytkownik |
Kiedy możesz naprawić błąd samodzielnie?
Samodzielna poprawka jest możliwa wtedy, gdy komunikat dotyczy ustawień konta, uprawnień, podpisu albo certyfikatu. Przed zmianami sprawdź też, czy KSeF nie ma przerwy technicznej lub awarii. Jeśli problem występuje wyłącznie w Twoim programie, nie powtarzaj wielokrotnie autoryzacji bez analizy komunikatu.
Przed kontaktem ze wsparciem wykonaj następujące czynności:
- Sprawdź dostępność KSeF oraz komunikaty o pracach serwisowych.
- Zweryfikuj, czy logujesz się do właściwego podmiotu i numeru NIP.
- Sprawdź uprawnienia w Aplikacji Podatnika, szczególnie prawo do wystawiania faktur.
- Upewnij się, że używasz środowiska produkcyjnego albo DEMO zgodnie z przeznaczeniem certyfikatu.
- Pobierz nowe wyzwanie autoryzacyjne i podpisz je tylko raz, bez edytowania pliku XML.
W przypadku błędu 415 plik powinien podpisać właściciel firmy albo osoba z właściwymi uprawnieniami w KSeF. W spółce znaczenie może mieć także sposób reprezentacji, formularz ZAW-FA oraz użycie podpisu kwalifikowanego lub pieczęci zawierającej NIP podmiotu.
Błąd 21115 oznacza zwykle pomieszanie środowisk. Certyfikat wygenerowany dla DEMO nie zadziała w produkcji, a produkcyjny nie służy do integracji testowej. Przy kodzie 21111 pobierz nowe wyzwanie i ponów cały proces. Kod 9103 wymaga ponownego podpisania dokumentu, tym razem tylko jednym podpisem.
Jeśli konto przekroczyło limit certyfikatów, skorzystaj z ręcznego wgrania certyfikatów wygenerowanych w Aplikacji Podatnika, zgodnie z dokumentacją dostawcy. Nie opisuję tu generowania certyfikatów krok po kroku, ponieważ szczegóły zależą od używanego programu i aktualnych zasad KSeF.
Kiedy trzeba zgłosić problem dostawcy?
Nie próbuj samodzielnie resetować integracji, gdy widzisz błąd 401, komunikat „autoryzacja w trakcie”, „AppStore and InConnector must be active” albo informację o nieprawidłowym tokenie API. Są to sygnały problemu w warstwie połączenia programu z KSeF. Dostawca musi sprawdzić konfigurację aplikacji, tokeny, sesję lub komunikację przez API.
Przygotuj komplet informacji, aby wsparcie nie musiało dopytywać o podstawowe dane:
- Adres konta lub URL widoczny w ustawieniach programu albo po zalogowaniu.
- Pełny komunikat błędu, najlepiej skopiowany, a nie przepisany z pamięci.
- Kod błędu, na przykład 401, 403, 21111 lub 21115.
- NIP podmiotu i środowisko – DEMO albo produkcja.
- Opis czynności wykonanych przed błędem, na przykład logowanie, wysyłka faktury lub podpisanie pliku.
Jak zgłosić błąd krok po kroku?
- Zatrzymaj kolejne próby autoryzacji, jeśli komunikat dotyczy tokenu, sesji lub integracji.
- Zapisz godzinę wystąpienia problemu i identyfikator dokumentu, którego dotyczy.
- Skopiuj pełny komunikat oraz zrób zrzut ekranu, jeśli błąd pojawia się tylko w interfejsie.
- Wyślij zgłoszenie przez kanał wsparcia dostawcy, podając adres konta, NIP, środowisko i opis kroków.
- Wykonuj ponowne testy dopiero po wskazaniu przez wsparcie właściwej poprawki.
Nie przesyłaj w zgłoszeniu haseł, kluczy prywatnych ani pełnych danych uwierzytelniających. Jeśli dostawca potrzebuje dodatkowych logów, przekaż je wyłącznie bezpiecznym kanałem wskazanym w jego dokumentacji.
Jak ograniczyć ryzyko kolejnych błędów?
Trzymaj osobno konfigurację DEMO i produkcji, kontroluj nadane uprawnienia oraz monitoruj komunikaty Ministerstwa Finansów. Integracja powinna też rejestrować statusy wysyłki i komunikaty API, aby można było ustalić, czy problem powstał przy podpisie, autoryzacji, przekazaniu dokumentu czy jego przetwarzaniu.
Nie generuj nowych certyfikatów tylko dlatego, że wystąpił błąd 401 lub problem z tokenem. Jeśli stare certyfikaty są aktywne, kolejne próby mogą zwiększyć chaos konfiguracyjny albo doprowadzić do limitu certyfikatów. Najpierw sprawdź kod błędu i ustal, czy naprawa należy do Ciebie, czy do dostawcy programu.
Najkrótsza ścieżka diagnozy wygląda tak: kod 401 lub błąd tokenu oznacza kontakt z dostawcą, kod 403 lub 415 wymaga sprawdzenia uprawnień, a kody 21111, 21115 i 9103 wskazują zwykle na poprawkę wyzwania, certyfikatu albo podpisu po stronie użytkownika.
