Jak zintegrować HRappkę z Krajowym Systemem e-Faktur (KSeF)

Opcja wprowadzenia integracji pojawi się w systemie dopiero po wdrożeniu funkcjonalności. O kolejnych etapach prac i dostępności nowych ustawień będziemy informować na bieżąco. W tym artykule skupiamy się na integracji HRappki z KSeF. Szczegółowy opis planowanych funkcjonalności dostępny jest pod linkiem.

1. Wprowadzenie #

W związku z dużym zainteresowaniem dostosowaniem systemu HRappka do wymogów Krajowego Systemu e-Faktur (KSeF) informujemy, że wdrożenie integracji HRappki z KSeF planowane jest na styczeń 2026 roku.

Integracja umożliwi automatyczne wystawianie oraz przesyłanie faktur ustrukturyzowanych bezpośrednio do systemu Ministerstwa Finansów.

Aby integracja mogła działać poprawnie i bezpiecznie, wymagane jest zastosowanie odpowiednich mechanizmów uwierzytelniania:

• tokenu KSeF (podstawowy mechanizm integracji),
• certyfikatu KSeF (wymaganego w określonych trybach, np. offline).

W dalszej części artykułu wyjaśniamy, czym są token i certyfikat KSeF, jak je uzyskać oraz jak skonfigurować je w systemie HRappka.

2. Mechanizmy uwierzytelniania w KSeF #

2.1. Czym jest token KSeF? #

Token KSeF to unikalny, 40-znakowy klucz, który służy do uwierzytelniania i autoryzacji dostępu do systemu KSeF.

Token:

• jest generowany przez podatnika po zalogowaniu się do KSeF,
• posiada określone uprawnienia nadane w momencie jego tworzenia (np. wystawianie i przeglądanie faktur),
• umożliwia korzystanie z KSeF bez konieczności każdorazowego logowania się przy użyciu podpisu kwalifikowanego lub innych metod uwierzytelniania.

W systemie HRappka token KSeF odpowiada za bezpieczną, automatyczną komunikację z KSeF i jest podstawowym elementem integracji.

2.2. Czym jest certyfikat KSeF? #

Certyfikat KSeF to certyfikat elektroniczny, który pozwala zweryfikować autentyczność wystawcy faktury. Dzięki niemu odbiorca faktury lub sam system KSeF może potwierdzić, że dokument faktycznie pochodzi od wskazanego podmiotu.

Certyfikat KSeF jest wymagany w szczególności do:

• wystawiania faktur w trybie offline,
• trybie offline24,
• trybie niedostępności systemu KSeF,
• trybie awaryjnym.

Tylko certyfikat KSeF umożliwia wygenerowanie drugiego kodu QR na fakturze, który potwierdza tożsamość wystawcy poza systemem KSeF. Certyfikat działa niezależnie od tokenu i zapewnia ciągłość fakturowania w sytuacjach wyjątkowych.

3. Co zrobić, aby uzyskać token i certyfikat KSeF? #

3.1. Uzyskaj dostęp do KSeF #

3.1.1. Jeśli prowadzisz jednoosobową działalność gospodarczą (JDG)

W przypadku JDG procedura jest najprostsza.
Możesz od razu przejść do punktu 3.2. Uwierzytelnij się w KSeF – nie ma potrzeby składania dodatkowych formularzy ani zgłoszeń do urzędu skarbowego.

3.1.2. Jeśli reprezentujesz spółkę, która nie posiada kwalifikowanej pieczęci elektronicznej

W tym przypadku konieczne jest zgłoszenie pierwszej osoby uprawnionej do korzystania z KSeF poprzez formularz ZAW-FA.

Zawiadomienie ZAW-FA możesz złożyć:

• elektronicznie – przez e-Urząd Skarbowy lub ePUAP
  (formularz musi być podpisany przez wszystkie osoby reprezentujące spółkę),
• papierowo – w urzędzie skarbowym właściwym dla siedziby spółki.

Formularz ZAW-FA:
https://www.podatki.gov.pl/media/7525/zaw-fa-01-18.pdf

Po pozytywnej weryfikacji:

• wskazana osoba uzyskuje status superadministratora KSeF,
• może samodzielnie, elektronicznie nadawać uprawnienia kolejnym użytkownikom (np. księgowej, biuru rachunkowemu),
• nie ma potrzeby składania kolejnych formularzy ZAW-FA.

3.1.3. Jeśli reprezentujesz spółkę posiadającą kwalifikowaną pieczęć elektroniczną

Jeśli spółka posiada kwalifikowaną e-pieczęć, nie ma konieczności składania formularza ZAW-FA.

E-pieczęć:

• potwierdza tożsamość organizacji (nie osoby),
• umożliwia bezpośrednie uwierzytelnienie podmiotu w KSeF.

Aby zalogować się do KSeF e-pieczęcią:

1. Przygotuj ważną kwalifikowaną e-pieczęć zawierającą numer NIP.
2. Wejdź na portal KSeF.
3. Wybierz logowanie kwalifikowanym środkiem elektronicznym.
4. Wskaż certyfikat e-pieczęci.
5. Potwierdź operację i uzyskaj dostęp do systemu.

3.2. Uwierzytelnij się w KSeF #

1. Wejdź na stronę: https://ksef.mf.gov.pl/web/login
2. Wprowadź NIP podmiotu i kliknij Uwierzytelnij.

3. Wybierz jedną z dostępnych metod logowania.

4. Po poprawnym zalogowaniu przejdziesz do ekranu głównego KSeF.

3.3. Wygeneruj token KSeF #

1. W menu po lewej stronie przejdź do zakładki Tokeny.
2. Kliknij Generuj token.
3. W formularzu:
   • nadaj tokenowi nazwę, np. HRappka,
   • zaznacz uprawnienia Wystawianie faktur oraz Przeglądanie faktur.
4. Kliknij Generuj token.
5. Skopiuj wygenerowany token.
6. Wklej go w polu Token w ustawieniach integracji KSeF w HRappce i zapisz zmiany.

Token pozostaje ważny do momentu jego unieważnienia. Możesz go w każdej chwili dezaktywować z poziomu listy tokenów w KSeF.

Zalecenia bezpieczeństwa:

• traktuj token jak dane szczególnie wrażliwe,
• nie udostępniaj go osobom nieupoważnionym,
• regularnie kontroluj aktywne tokeny w KSeF.

3.4. Konfiguracja certyfikatu KSeF dla trybu offline #

3.4.1. Krok 1 – Wygeneruj certyfikat KSeF

1. W KSeF przejdź do zakładki Certyfikaty → Wnioskuj o certyfikat.
2. Nadaj certyfikatowi nazwę (np. HRappka).
3. Ustal hasło do certyfikatu i zapisz je.
4. Kliknij Generuj – plik .key zostanie automatycznie pobrany.
5. W polu Przeznaczenie certyfikatu wybierz
   Podpis linku do weryfikacji nadawcy.
6. Wyślij wniosek o wydanie certyfikatu.

3.4.2. Krok 2 – Uzupełnij dane certyfikatu w HRappce

1. Skopiuj numer seryjny certyfikatu z listy certyfikatów w KSeF i wklej go w HRappce.
2. Otwórz plik .key, skopiuj jego zawartość i wklej ją w polu Klucz prywatny certyfikatu offline.
3. Wpisz hasło certyfikatu.
4. Zapisz zmiany.

Uwaga:

• certyfikat KSeF jest ważny przez 2 lata,
• po jego wygaśnięciu należy wygenerować nowy certyfikat i ponownie uzupełnić dane w HRappce,
• hasło i zawartość certyfikatu należy traktować jako dane wrażliwe.