API – autoryzacja i certyfikaty krok po kroku

Zanim jakiekolwiek żądanie do API KSeF zostanie przetworzone, system musi wiedzieć, kto je wysyła i w czyim imieniu. To właśnie robi warstwa autoryzacji — i to właśnie tutaj najczęściej pojawiają się pierwsze problemy przy budowie integracji, jeszcze zanim dojdzie do wysyłki jakiejkolwiek faktury. Podstawowym mechanizmem uwierzytelniania w integracjach programistycznych z KSeF jest certyfikat — i to na nim skupiamy się w tym artykule.

Dlaczego autoryzacja certyfikatem jest bardziej złożona niż zwykłe „logowanie"

W przeciwieństwie do typowego API, gdzie autoryzacja sprowadza się do stałego klucza API, w KSeF uwierzytelnienie musi jednoznacznie potwierdzać tożsamość podatnika (lub podmiotu działającego w jego imieniu) w sposób akceptowalny prawnie — bo od tego zależy, czy dokument wysłany przez API ma moc prawną faktury ustrukturyzowanej. Certyfikat kwalifikowany, jako elektroniczny dokument potwierdzający tożsamość podmiotu wydawany przez uprawnionego dostawcę usług zaufania, spełnia ten wymóg — dlatego jest podstawą uwierzytelniania w integracjach API.

Dwa rodzaje certyfikatów — i dwa różne zadania

W praktyce integracji z KSeF spotykasz się z dwoma rodzajami certyfikatów, które pełnią zupełnie inne funkcje:

• Certyfikat autoryzacyjny (uwierzytelniający) — służy do logowania się i uzyskiwania sesji w systemie KSeF. To on potwierdza, że dany podmiot (lub osoba działająca w jego imieniu) ma prawo wysyłać i pobierać dokumenty przez API.
• Certyfikat offline — służy do podpisywania faktur w trybie offline, czyli w sytuacji braku połączenia z KSeF w momencie wystawienia dokumentu. Faktura zostaje podpisana lokalnie i dosłana do systemu, gdy połączenie wróci.

Dla integracji API opartej na regularnej, bieżącej wysyłce dokumentów kluczowy jest certyfikat autoryzacyjny — to on jest używany przy każdym nawiązaniu sesji. Certyfikat offline ma znaczenie głównie jako zabezpieczenie na wypadek niedostępności KSeF. Różnicę między nimi opisaliśmy szerzej w artykule o zarządzaniu certyfikatami KSeF.

Konteksty autoryzacji

Jednym z elementów, które najczęściej zaskakują programistów budujących pierwszą integrację, jest pojęcie kontekstu autoryzacji. Uwierzytelnienie certyfikatem w KSeF nie sprowadza się do prostego „zalogowano/niezalogowano" — system musi wiedzieć, w imieniu jakiego podmiotu działa dana sesja. Ma to znaczenie w szczególności w scenariuszach takich jak:

• biuro rachunkowe działające w imieniu wielu obsługiwanych klientów, każdy z własnym certyfikatem,
• samofakturowanie, gdzie nabywca wystawia dokument w imieniu sprzedawcy, korzystając z własnego kontekstu uprawnień,
• delegacja uprawnień w ramach struktury organizacyjnej firmy.

Pomyłka w kontekście autoryzacji (np. próba wysłania dokumentu certyfikatem przypisanym do innego NIP-u niż podmiot, w imieniu którego wysyłane jest żądanie) to jedna z najczęstszych przyczyn odrzuceń, z którymi mierzą się integratorzy na starcie.

Proces autoryzacji certyfikatem krok po kroku

1. Przygotowanie certyfikatu. Certyfikat autoryzacyjny musi być przypisany do właściwego podmiotu (NIP) i dostępny integracji w bezpiecznej formie — nigdy jako plik przechowywany bez zabezpieczeń.
2. Nawiązanie sesji. System potwierdza tożsamość podmiotu na podstawie certyfikatu i, w razie potrzeby, kontekst, w jakim ma działać dana sesja.
3. Wykorzystanie sesji do kolejnych żądań. Po poprawnym uwierzytelnieniu kolejne operacje (wysyłka, odbiór dokumentów, sprawdzanie statusu) odbywają się w ramach tej samej, autoryzowanej sesji.
4. Obsługa wygaśnięcia sesji. Integracja powinna uwzględniać, że sesja nie jest wieczna — dobra praktyka to wykrywanie błędu autoryzacji i automatyczne ponowne uwierzytelnienie certyfikatem, zamiast twardego zatrzymania całego procesu.
5. Monitorowanie ważności certyfikatu. Certyfikaty mają określony termin ważności — integracja produkcyjna powinna sygnalizować zbliżający się koniec ważności, zanim dojdzie do sytuacji, w której wysyłka faktur zostaje nagle zablokowana.

Najczęstsze błędy autoryzacji certyfikatem

• Niezgodność certyfikatu z NIP-em podmiotu — próba uwierzytelnienia certyfikatem wystawionym dla innego podmiotu niż ten, w którego imieniu wysyłane jest żądanie.
• Wygasły certyfikat — integracja nieprzewidująca monitorowania terminu ważności, co skutkuje nagłym zablokowaniem wysyłki bez wcześniejszego ostrzeżenia.
• Pomylenie certyfikatu autoryzacyjnego z offline — użycie niewłaściwego typu certyfikatu do danej operacji.
• Błędny kontekst autoryzacji — pomylenie sesji własnej firmy z sesją działania w imieniu innego podmiotu (np. przy obsłudze wielu klientów).
• Przechowywanie certyfikatu i hasła w sposób niezabezpieczony — plik certyfikatu i hasło do niego zapisane jako zwykły tekst w kodzie czy repozytorium to poważne ryzyko bezpieczeństwa, niezależnie od tego, jak poprawnie działa reszta integracji.

Podsumowanie

Autoryzacja certyfikatem to fundament każdej integracji z API KSeF — błąd na tym etapie uniemożliwia realizację jakiejkolwiek dalszej operacji, niezależnie od tego, jak