Podłączenie KSeF

Wgrywasz certyfikat raz i działa zawsze. Dwa tryby pobierania danych: automatyczny w tle albo ręczne ściągnięcie konkretnego zakresu dat.

Co potrzebujesz przed startem

Do podłączenia bilans.ai potrzebujesz certyfikatu kwalifikowanego wygenerowanego w portalu KSeF Ministerstwa Finansów. Certyfikat jest jedynym sposobem autoryzacji — nie obsługujemy logowania hasłem, tokenów ani innych form dostępu.

Przy generowaniu certyfikatu KSeF wygeneruje Ci dwa pliki naraz:

  • .crt — sam certyfikat (publiczna część, można udostępniać).
  • .key — klucz prywatny (tajna część, zostaje tylko u Ciebie).

Zachowaj plik .key lokalnie — to jedyny moment, kiedy klucz prywatny jest dostępny do pobrania. Z portalu KSeF nie da się go potem ponownie ściągnąć. Gdy go zgubisz, musisz wygenerować nowy certyfikat od początku.

Jeśli wracasz później do listy certyfikatów w KSeF i wybierasz pobranie w formacie PEM, dostaniesz tylko plik certyfikatu (Base64, równoważnik .crt) — bez klucza prywatnego. To celowe zachowanie KSeF, nie błąd.

Format wgrywania w bilans.ai

Możesz wgrać certyfikat na dwa sposoby — wybierasz w formularzu wgrywania:

  • Dwa pliki .crt + .key — standardowy przypadek, dokładnie te dwa pliki z KSeF.
  • Jeden plik .pem — gdy samodzielnie połączyłeś oba pliki w jeden (np. cat cert.crt cert.key > combined.pem) albo używasz narzędzi openssl.

Klucz prywatny z KSeF jest zawsze zabezpieczony hasłem, które ustawiłeś w portalu przy generowaniu certyfikatu — podajesz je w trzecim polu. bilans.ai odszyfrowuje klucz lokalnie w Twojej przeglądarce, samo hasło nigdy nie opuszcza Twojego urządzenia.

Automatyczny import

Po zalogowaniu wchodzisz w Konto → Automatyczny import KSeF. To jednorazowa konfiguracja — wgrywasz certyfikat, włączasz przełącznik i od tego momentu nowe faktury wpadają same.

Przy wgrywaniu wybierasz format certyfikatu (dwa pliki .crt + .key albo jeden plik .pem) i wskazujesz odpowiednie pliki. Podajesz hasło do klucza — bilans.ai odszyfrowuje klucz lokalnie w Twojej przeglądarce, więc samo hasło nigdy nie opuszcza Twojego urządzenia.

Codziennie wcześnie rano (uruchomienie 04:17) system pobiera nowe faktury z KSeF — wszystko, co pojawiło się od ostatniego importu. Pobranie kończy się klasyfikacją AI, wykrywaniem anomalii i zaktualizowaniem dashboardu.

Status automatycznego importu (włączony / wyłączony, ostatni udany przebieg, ważność certyfikatu) widzisz na tej samej zakładce. Możesz w każdej chwili tymczasowo wyłączyć import bez usuwania certyfikatu.

Co przechowujemy

Certyfikat i klucz prywatny zapisujemy w zaszyfrowanej formie w dedykowanym magazynie kluczy, odizolowanym od głównej bazy danych. Hasło do klucza nigdy nie jest zapisywane — używamy go jednorazowo, w momencie wgrywania, do odszyfrowania klucza w przeglądarce.
Zakładka Automatyczny import KSeF — wybór formatu certyfikatu, pola na pliki, hasło do klucza i przełącznik włączenia
Konto → Automatyczny import KSeF — wgrywasz raz, działa codziennie.

Ręczne pobranie

Ręczne pobranie służy do jednorazowego ściągnięcia konkretnego zakresu dat — np. historii sprzed roku, której nie ma jeszcze w automatycznym imporcie, albo testowego pobrania na świeżym koncie zanim włączysz codzienne działanie.

Wchodzisz w Import KSeF z bocznego menu (pozycja zaraz pod „Twoja Firma"). Wybierasz:

  • Zakres dat — od kiedy do kiedy ściągnąć faktury (data wpływu do KSeF, nie data wystawienia).
  • Strumień — zakupy (koszty), sprzedaż (przychody) albo oba naraz.
  • Format certyfikatu — .crt + .key albo .pem, tak samo jak w automatycznym imporcie.
  • Pliki certyfikatu i hasło do klucza.

Przy ręcznym pobraniu certyfikat nie jest zapisywany — używamy go tylko na czas tej jednej operacji i zapominamy. Każde kolejne ręczne pobranie wymaga ponownego wgrania pliku.

Jeśli chcesz ściągać faktury raz dziennie bez ręcznego klikania, włącz automatyczny import — tam certyfikat jest przechowywany w zaszyfrowanym magazynie i dostępny dla codziennego procesu w tle.

Limity miesięczne

Każdy plan ma swój limit liczby faktur w ramach jednego ręcznego pobrania (Darmowy najmniejszy, Dedykowany bez limitu). Limit dotyczy okresu — jeśli przekroczysz, pobierzemy najnowsze faktury, a starsze pominiemy. Po wyczerpaniu limitu w danym miesiącu kolejne ręczne pobranie czeka do 1-go następnego miesiąca.

Limity są ustawione tak, żeby pokryły potrzeby zdecydowanej większości firm — od mikro do średniego biznesu. Jeśli żadna z naszych subskrypcji nie pokrywa Twojej skali (np. masz wyjątkowo wysoki wolumen faktur albo specyficzny tryb pracy), napisz do nas — wspólnie ułożymy rozwiązanie dopasowane do Twojej firmy.

Strona Import KSeF — wybór zakresu dat, strumienia, formatu certyfikatu, pola na pliki i hasło
Import KSeF — ręczne pobranie konkretnego zakresu dat, certyfikat nie jest zapisywany.

Co jeśli coś nie działa

Certyfikat wygasł

Certyfikaty KSeF mają datę ważności (zwykle 1-2 lata). Ostrzegamy mailem 14 / 7 / 1 dzień przed wygaśnięciem — generujesz nowy w portalu KSeF i wgrywasz w Konto → Automatyczny import KSeF. Stary certyfikat nadpisujemy bez utraty ustawień.

Brak nowych faktur w bilans.ai

Sprawdź status automatycznego importu w Konto → Automatyczny import KSeF. Jeśli ostatni przebieg się nie udał, zobaczysz tam komunikat błędu (najczęstsze przyczyny: certyfikat wygasł, KSeF w trakcie konserwacji, problem z siecią).

Błąd „Brak uprawnień"

Certyfikat nie ma uprawnień do odczytu faktur w KSeF — bilans.ai tylko pobiera dane (faktury otrzymane i wystawione), nie potrzebuje uprawnień do wystawiania ani modyfikacji. Wygeneruj nowy certyfikat w portalu KSeF z zakresem odczytu faktur otrzymanych i wystawionych, a następnie wgraj go ponownie.

Plik .pem nie zawiera klucza prywatnego

Pobranie z listy certyfikatów w KSeF (opcja „format PEM") daje sam certyfikat — bez klucza prywatnego. Klucz dostajesz tylko raz, w momencie generowania certyfikatu, jako osobny plik .key. Wybierz wariant .crt + .key i wgraj oba pliki osobno (klucz musisz mieć z chwili generacji).

Zgubiłem plik .key

Klucza prywatnego z KSeF nie można odzyskać — to celowe zachowanie systemu (klucz nigdy nie wraca do portalu po wygenerowaniu). Wygeneruj nowy certyfikat w portalu KSeF (stary możesz zostawić — wygaśnie sam) i tym razem zachowaj plik .key lokalnie zaraz po pobraniu.