KSeF 21301 i 21304: brak autoryzacji, brak uwierzytelnienia oraz błędy 401 i 403

„Brak autoryzacji” i „brak uwierzytelnienia” brzmią jak synonimy, a w API KSeF oznaczają konkretne, różne sytuacje. Oba komunikaty to kody wyjątków zwracane razem z odpowiedzią HTTP 400 przy pobieraniu lub odświeżaniu tokenów: 21301 i 21304. Osobno istnieją odpowiedzi HTTP 401 i 403 przy zwykłych operacjach, jak wysyłka czy pobieranie faktur. Poniżej rozdzielam te cztery przypadki według dokumentacji API KSeF 2.0.

21301 brak autoryzacji: cztery przyczyny z dokumentacji

• Tokeny dla operacji uwierzytelniania zostały już pobrane. Access token i refresh token można odebrać dla danego logowania tylko raz. Program, który próbuje zrobić to drugi raz (np. po restarcie w połowie procesu), dostaje 21301.
• Status uwierzytelniania nie pozwala na pobranie tokenów. Logowanie jeszcze się nie zakończyło albo zakończyło się błędem. Najpierw trzeba odczytać status uwierzytelnienia, opisany w tekście o błędzie uwierzytelnienia.
• Status uwierzytelniania nie pozwala na odświeżenie tokenu dostępowego. Uwierzytelnienie zostało unieważnione, więc refresh token nie zadziała.
• Token KSeF został unieważniony. Ktoś wyłączył token albo stracił on ważność. Więcej w tekście o tokenie KSeF.

21304 brak uwierzytelnienia: KSeF nie zna tej operacji

Dokumentacja opisuje go jednym zdaniem: operacja uwierzytelniania o podanym numerze referencyjnym nie została znaleziona. W praktyce program pyta o status albo tokeny dla numeru, którego KSeF nie ma. Najczęściej to numer z innego środowiska (test zamiast produkcji, patrz środowisko testowe KSeF), literówka w konfiguracji albo numer z bardzo starego logowania.

HTTP 401: brak ważnego access tokena

Przy zwykłych operacjach, jak otwarcie sesji czy pobranie faktury, KSeF oczekuje access tokena w nagłówku Authorization. Gdy go brakuje albo minął jego czas z pola exp, odpowiedź to 401 Unauthorized. Access token żyje krótko, zwykle kilkanaście minut, a refresh token pozwala go odnawiać do 7 dni. Integracja, która nie odświeża tokena, przestaje działać po kilkunastu minutach. Taka, która nie loguje się ponownie po wygaśnięciu refresh tokena, przestaje działać po tygodniu.

HTTP 403: brak uprawnienia do operacji

Odpowiedź 403 Forbidden oznacza, że token jest ważny, ale osoba lub podmiot nie ma uprawnienia do tej operacji w danym kontekście. W KSeF 2.0 uprawnienia są rozdzielone: wystawianie faktur to InvoiceWrite, przeglądanie i pobieranie to InvoiceRead, zarządzanie uprawnieniami to CredentialsManage. Program z samym InvoiceWrite wyśle sprzedaż, ale nie pobierze faktur kosztowych. Dokumentacja dodaje, że access token zostaje ważny do daty exp nawet po zmianie uprawnień, więc nowe uprawnienie zadziała dopiero z nowym tokenem.

Kolejność działań przy 403

1. 1.Sprawdź, w jakim kontekście (NIP) program się zalogował.
2. 2.Pobierz listę własnych uprawnień w tym kontekście, API ma do tego osobny endpoint.
3. 3.Poproś właściciela lub administratora o brakujące uprawnienie, zgodnie z opisem w tekście o nadawaniu uprawnień.
4. 4.Zaloguj się ponownie albo poczekaj na odświeżenie tokena.

Źródło: uwierzytelnianie i tokeny w dokumentacji API KSeF 2.0.