Konfiguracja i ustawienia Konfiguracja modulu, zarzadzanie certyfikatami, sprawdzenie srodowiska oraz testowanie polaczenia z KSeF. Konfiguracja KSeF Integrator addon WHMCS Order now | Download | FAQ Strona konfiguracji modulu dostepna jest w: Addons > PUQ KSeF Integrator > Ustawienia > Konfiguracja 06-konfiguracja.png Srodowisko i certyfikaty Pole Opis Tryb debugowania Wlaczony / Wylaczony. Gdy wlaczony, wszystkie wazne kroki sa zapisywane w dzienniku modulu WHMCS (Utilities > Logs > Module Log) Srodowisko pracy Testowe — faktury sa wysylane na serwer testowy KSeF (ksef-test.mf.gov.pl). Produkcyjne — faktury sa wysylane na serwer produkcyjny (ksef.mf.gov.pl). Certyfikat testowy Certyfikat uzywany do uwierzytelniania w srodowisku testowym KSeF. Wybierz z listy certyfikatow dodanych w zakladce Certyfikaty. Certyfikat produkcyjny Certyfikat uzywany do uwierzytelniania w srodowisku produkcyjnym KSeF. Wazne: Certyfikat testowy moze byc uzyty tylko w srodowisku testowym, a certyfikat produkcyjny — tylko w srodowisku produkcyjnym. Dane firmy W tej sekcji nalezy podac dane sprzedawcy, ktore beda umieszczone na kazdej e-Fakturze wystawianej do KSeF. Pole Opis Wymagane NIP 10-cyfrowy Numer Identyfikacji Podatkowej firmy Tak Nazwa firmy Pelna nazwa firmy Tak Ulica Nazwa ulicy Tak Nr budynku Numer budynku Tak Nr lokalu Numer lokalu/mieszkania Nie Kod pocztowy Kod pocztowy (format: XX-XXX) Tak Miasto Nazwa miasta Tak Kraj Kod kraju (domyslnie: PL) Tak Telefon Numer telefonu firmy Nie E-mail Adres e-mail firmy Nie Uwaga: NIP musi byc prawidlowym 10-cyfrowym polskim numerem identyfikacji podatkowej. Modul waliduje NIP przed wysylka. Ustawienia faktur Pole Opis Tryb wysylki Natychmiast po oplaceniu — faktury sa automatycznie wysylane do KSeF zaraz po oplaceniu w WHMCS. Reczny — faktury sa zapisywane w kolejce ze statusem "oczekuje", administrator musi je wyslac recznie. Pomijaj faktury AddFunds Tak (pomijaj) — faktury za doladowanie salda klienta (AddFunds) nie beda wysylane do KSeF. Nie (wysylaj do KSeF) — faktury AddFunds beda traktowane jak zwykle faktury sprzedazowe. Domyslnie: Tak. Doladowania salda nie sa rzeczywista sprzedaza towaru/uslugi, dlatego zazwyczaj nie powinny byc raportowane w KSeF. Automatyczne ponowienie przy bledzie Wlaczony / Wylaczony. Gdy wlaczony, modul automatycznie podejmie probe ponownej wysylki w przypadku bledu. Maks. liczba ponowien Maksymalna liczba prob ponownej wysylki (domyslnie: 3). Zwolnienie z VAT Nie (standardowy platnik VAT) — firma rozlicza VAT normalnie. Tak (firma zwolniona z VAT) — wszystkie pozycje faktur beda mialy stawke ZW (zwolniony). Kod VAT — EU B2B Kod stawki VAT w KSeF dla faktur do firm z UE (podatek 0%). Dostepne opcje: 0% — Eksport (0 EX), 0% — WDT (0 WDT), 0% — Kraj (0 KR), zwolniony (zw), nie podlega (np), odwrotne obciazenie (oo). Kod VAT — non-EU Kod stawki VAT w KSeF dla faktur do klientow spoza UE (podatek 0%). Te same opcje co powyzej. Zapisywanie ustawien Po wprowadzeniu wszystkich danych kliknij przycisk Zapisz ustawienia w prawym gornym rogu strony. Pomyslne zapisanie jest potwierdzane komunikatem powodzenia. Wskazowka: Po skonfigurowaniu danych firmy i certyfikatow, przejdz do strony glownej modulu i uzyj przycisku Testuj polaczenie, aby sprawdzic czy modul moze poprawnie polaczyc sie z serwerem KSeF. Certyfikaty KSeF Integrator addon WHMCS Order now | Download | FAQ Strona zarzadzania certyfikatami dostepna jest w: Addons > PUQ KSeF Integrator > Ustawienia > Certyfikaty 08-certyfikaty-lista.png Modul wymaga certyfikatow do uwierzytelniania w systemie KSeF za pomoca podpisu XAdES. Kazde srodowisko (testowe i produkcyjne) wymaga osobnego certyfikatu. Typy certyfikatow Certyfikat testowy Certyfikat testowy sluzy do pracy w srodowisku testowym KSeF (ksef-test.mf.gov.pl). Jest wydawany przez Ministerstwo Finansow i mozna go wygenerowac w aplikacji testowej KSeF. Gdzie uzyskac certyfikat testowy: Przejdz do strony aplikacji testowej KSeF: https://ap-test.ksef.mf.gov.pl/web/ Zaloguj sie lub utworz konto testowe W ustawieniach konta wygeneruj certyfikat testowy Pobierz plik certyfikatu (PEM) i klucz prywatny (PEM) Certyfikat produkcyjny Certyfikat produkcyjny to kwalifikowany certyfikat elektroniczny uzywany w srodowisku produkcyjnym KSeF (ksef.mf.gov.pl). Gdzie uzyskac certyfikat produkcyjny: Przejdz do strony aplikacji produkcyjnej KSeF: https://ap.ksef.mf.gov.pl/web/ Zaloguj sie za pomoca profilu zaufanego lub podpisu kwalifikowanego W ustawieniach konta firmy skonfiguruj uprawnienia do wysylki faktur Uzyj certyfikatu kwalifikowanego wydanego przez certyfikowane centrum certyfikacji Dodawanie certyfikatu Na stronie certyfikatow kliknij przycisk + Dodaj certyfikat Wypelnij formularz: Pole Opis Wymagane Nazwa Dowolna nazwa identyfikujaca certyfikat (np. "TEST", "Produkcja 2026") Tak Typ Testowy lub Produkcyjny Tak Certyfikat PEM Zawartosc pliku certyfikatu w formacie PEM (zaczyna sie od -----BEGIN CERTIFICATE-----) Tak Klucz PEM Zawartosc pliku klucza prywatnego w formacie PEM (zaczyna sie od -----BEGIN PRIVATE KEY----- lub -----BEGIN RSA PRIVATE KEY----- lub -----BEGIN ENCRYPTED PRIVATE KEY-----) Tak Haslo klucza Haslo do klucza prywatnego, jesli klucz jest zaszyfrowany Nie Kliknij Zapisz certyfikat 09-certyfikaty-dodaj.png Wazne: Certyfikaty sa przechowywane w bazie danych w postaci zaszyfrowanej. Szyfrowanie odbywa sie za pomoca mechanizmu WHMCS encrypt/decrypt. Lista certyfikatow Tabela wyswietla wszystkie zapisane certyfikaty z informacjami: Kolumna Opis ID Unikalny identyfikator certyfikatu Nazwa Nazwa nadana przy dodawaniu Typ TESTOWY / PRODUKCYJNY (kolorowe etykiety) Wystawca Nazwa wystawcy certyfikatu (np. "Ministerstwo Finansow") Podmiot Nazwa podmiotu, dla ktorego wydano certyfikat Wazny od Data poczatku waznosci certyfikatu Wazny do Data konca waznosci certyfikatu Wygasly WAZNY (zielony) lub WYGASLY (czerwony) Akcje Przycisk usuwania certyfikatu Usuwanie certyfikatu Kliknij czerwony przycisk usuwania w kolumnie Akcje Potwierdz usuniecie w oknie dialogowym Uwaga: Nie mozna usunac certyfikatu, ktory jest aktualnie wybrany w konfiguracji (Certyfikat testowy lub Certyfikat produkcyjny). Najpierw zmien certyfikat w konfiguracji. Przypisanie certyfikatu do srodowiska Po dodaniu certyfikatu: Przejdz do Ustawienia > Konfiguracja W sekcji "Srodowisko i certyfikaty" wybierz odpowiedni certyfikat z listy: Certyfikat testowy — dla srodowiska testowego Certyfikat produkcyjny — dla srodowiska produkcyjnego Kliknij Zapisz ustawienia Sprawdzenie srodowiska KSeF Integrator addon WHMCS Order now | Download | FAQ Strona sprawdzania srodowiska dostepna jest w: Addons > PUQ KSeF Integrator > Ustawienia > Sprawdz srodowisko 10-sprawdzenie-srodowiska.png Ta strona diagnostyczna automatycznie sprawdza, czy serwer spelnia wszystkie wymagania techniczne niezbedne do prawidlowego dzialania modulu. Sprawdzane komponenty 1. shell_exec Parametr Opis enabled Czy funkcja shell_exec jest dostepna w PHP Funkcja shell_exec jest wymagana do wywolyywania narzedzia xmlsec1 do podpisywania XAdES. Jak naprawic: Upewnij sie, ze shell_exec nie jest wymieniony w dyrektywie disable_functions w pliku php.ini. 2. xmlsec1 Parametr Opis installed Czy narzedzie xmlsec1 jest zainstalowane version Aktualna wersja xmlsec1 required Minimalna wymagana wersja (>= 1.2.31) ok Czy wersja spelnia wymagania Narzedzie xmlsec1 jest uzywane do generowania podpisow XAdES wymaganych przez KSeF do uwierzytelniania. Jak zainstalowac: # Debian/Ubuntu apt-get install xmlsec1 # CentOS/RHEL yum install xmlsec1 xmlsec1-openssl # AlmaLinux dnf install xmlsec1 xmlsec1-openssl 3. OpenSSL Parametr Opis installed Czy OpenSSL jest zainstalowany version Aktualna wersja OpenSSL required Minimalna wymagana wersja (>= 1.1.1) ok Czy wersja spelnia wymagania OpenSSL jest uzywany do szyfrowania RSA-OAEP i AES-256-CBC. 4. Katalog tymczasowy (Temp directory) Parametr Opis path Sciezka do katalogu tymczasowego exists Czy katalog istnieje writable Czy katalog jest zapisywalny php write Czy PHP moze tworzyc pliki w katalogu xmlsec write Czy xmlsec1 moze zapisywac pliki w katalogu ok Czy wszystkie testy przeszly Katalog tymczasowy jest uzywany do przechowywania plikow tymczasowych podczas podpisywania XAdES. Jak naprawic: Upewnij sie, ze katalog tymczasowy istnieje i ma odpowiednie uprawnienia: chmod 777 /tmp # lub uzyj katalogu tymczasowego WHMCS chmod 777 /home/twoj-whmcs/tmp Interpretacja wynikow OK (zielony) — komponent dziala prawidlowo TAK (zielona etykieta) — test zaliczony NIE (czerwona etykieta) — test niezaliczony, wymaga naprawy BLAD (czerwony) — komponent nie jest dostepny Wskazowka: Wszystkie cztery komponenty musza miec status OK, aby modul mogl prawidlowo wysylac faktury do KSeF. Strona glowna i test polaczenia KSeF Integrator addon WHMCS Order now | Download | FAQ Strona glowna modulu dostepna jest w: Addons > PUQ KSeF Integrator > Strona glowna 03-strona-glowna.png Statystyki faktur Na gorze strony glownej wyswietlany jest panel ze statystykami faktur KSeF: Statystyka Opis Lacznie Calkowita liczba faktur w systemie KSeF modulu Oczekuje Faktury w kolejce czekajace na wysylke Przetwarzanie Faktury wyslane, oczekujace na odpowiedz KSeF Przyjeta Faktury pomyslnie przyjete przez KSeF Odrzucona Faktury odrzucone przez KSeF Blad Faktury z bledem walidacji lub polaczenia Szybki start Na stronie glownej wyswietlany jest przewodnik szybkiego startu z krokami konfiguracji: Przejdz do Ustawienia > Konfiguracja Skonfiguruj dane swojej firmy Wgraj certyfikaty w Ustawienia > Certyfikaty Przetestuj polaczenie za pomoca przycisku ponizej Test polaczenia Przycisk Testuj polaczenie w prawym gornym rogu strony glownej pozwala zweryfikowac, czy modul moze poprawnie polaczyc sie z serwerem KSeF. 04-test-polaczenia-sukces.png Etapy testu Test polaczenia wykonuje nastepujace kroki: Checking configuration... — sprawdzanie konfiguracji modulu (NIP, srodowisko) Loading certificate... — ladowanie certyfikatu z bazy danych Creating KSeF client... — tworzenie klienta API KSeF Authenticating with KSeF (Challenge)... — uwierzytelnianie w KSeF za pomoca podpisu XAdES Fetching KSeF public keys... — pobieranie kluczy publicznych KSeF do szyfrowania KSeF connection verified successfully! — polaczenie zostalo zweryfikowane pomyslnie Wyniki testu Polaczenie pomyslne — zielony komunikat potwierdzajacy poprawnosc konfiguracji. W sekcji Informacje debugowania wyswietlane sa szczegolowe dane: NIP i srodowisko Wystawca certyfikatu i data waznosci Data wydania tokenu uwierzytelniania Liczba pobranych kluczy publicznych Polaczenie nieudane — czerwony komunikat z opisem bledu. Najczestsze przyczyny: Blad Rozwiazanie Certificate not found Dodaj certyfikat w Ustawienia > Certyfikaty Certificate expired Wgraj nowy, wazny certyfikat Authentication failed Sprawdz, czy certyfikat jest prawidlowy i odpowiada srodowisku NIP not configured Wypelnij NIP w Ustawienia > Konfiguracja xmlsec1 not available Zainstaluj xmlsec1 (patrz: Sprawdzenie srodowiska) Tryb testowy Gdy srodowisko jest ustawione na Testowe, na gorze kazdej strony modulu wyswietlany jest zolty baner: TRYB TESTOWY — Pracujesz w srodowisku testowym. Faktury wysylane sa na testowy serwer KSeF. API: https://ksef-test.mf.gov.pl Zaleca sie rozpoczecie pracy w trybie testowym, a po pomyslnym przetestowaniu przelaczenie na srodowisko produkcyjne.