# Konfiguracja i ustawienia Konfiguracja modulu, zarzadzanie certyfikatami, sprawdzenie srodowiska oraz testowanie polaczenia z KSeF. # Konfiguracja ### KSeF Integrator addon **[WHMCS](https://puqcloud.com/link.php?id=77)** ##### [Order now](https://puqcloud.com/whmcs-addon-puq-ksef-integrator.php) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-KSeF-Integrator/) | [FAQ](https://community.puqcloud.com/) Strona konfiguracji modulu dostepna jest w: **Addons** > **PUQ KSeF Integrator** > **Ustawienia** > **Konfiguracja** ![Strona konfiguracji modulu](https://doc.puq.info/uploads/images/gallery/2026-03/embedded-image-oittqafk.png) *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](https://puqcloud.com/link.php?id=77)** ##### [Order now](https://puqcloud.com/whmcs-addon-puq-ksef-integrator.php) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-KSeF-Integrator/) | [FAQ](https://community.puqcloud.com/) Strona zarzadzania certyfikatami dostepna jest w: **Addons** > **PUQ KSeF Integrator** > **Ustawienia** > **Certyfikaty** ![Lista certyfikatow z informacjami o waznosci](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-fdkr8wbp.png) *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:** 1. Przejdz do strony aplikacji testowej KSeF: [https://ap-test.ksef.mf.gov.pl/web/](https://ap-test.ksef.mf.gov.pl/web/) 2. Zaloguj sie lub utworz konto testowe 3. W ustawieniach konta wygeneruj certyfikat testowy 4. 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:** 1. Przejdz do strony aplikacji produkcyjnej KSeF: [https://ap.ksef.mf.gov.pl/web/](https://ap.ksef.mf.gov.pl/web/) 2. Zaloguj sie za pomoca profilu zaufanego lub podpisu kwalifikowanego 3. W ustawieniach konta firmy skonfiguruj uprawnienia do wysylki faktur 4. Uzyj certyfikatu kwalifikowanego wydanego przez certyfikowane centrum certyfikacji --- ## Dodawanie certyfikatu 1. Na stronie certyfikatow kliknij przycisk **+ Dodaj certyfikat** 2. 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 | 3. Kliknij **Zapisz certyfikat** ![Formularz dodawania certyfikatu](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-lnqhvrlr.png) *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 1. Kliknij czerwony przycisk usuwania w kolumnie **Akcje** 2. 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: 1. Przejdz do **Ustawienia** > **Konfiguracja** 2. W sekcji "Srodowisko i certyfikaty" wybierz odpowiedni certyfikat z listy: - **Certyfikat testowy** — dla srodowiska testowego - **Certyfikat produkcyjny** — dla srodowiska produkcyjnego 3. Kliknij **Zapisz ustawienia** # Sprawdzenie srodowiska ### KSeF Integrator addon **[WHMCS](https://puqcloud.com/link.php?id=77)** ##### [Order now](https://puqcloud.com/whmcs-addon-puq-ksef-integrator.php) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-KSeF-Integrator/) | [FAQ](https://community.puqcloud.com/) Strona sprawdzania srodowiska dostepna jest w: **Addons** > **PUQ KSeF Integrator** > **Ustawienia** > **Sprawdz srodowisko** ![Wyniki sprawdzania srodowiska — wszystkie testy zaliczone](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-avbieur6.png) *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:** ```bash # 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: ```bash 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](https://puqcloud.com/link.php?id=77)** ##### [Order now](https://puqcloud.com/whmcs-addon-puq-ksef-integrator.php) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-KSeF-Integrator/) | [FAQ](https://community.puqcloud.com/) Strona glowna modulu dostepna jest w: **Addons** > **PUQ KSeF Integrator** > **Strona glowna** ![Strona glowna z statystykami faktur i przewodnikiem szybkiego startu](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-nhtkdjjg.png) *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: 1. Przejdz do **Ustawienia** > **Konfiguracja** 2. Skonfiguruj dane swojej firmy 3. Wgraj certyfikaty w **Ustawienia** > **Certyfikaty** 4. 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. ![Wynik pomyslnego testu polaczenia](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-m9ld8ysd.png) *04-test-polaczenia-sukces.png* ### Etapy testu Test polaczenia wykonuje nastepujace kroki: 1. **Checking configuration...** — sprawdzanie konfiguracji modulu (NIP, srodowisko) 2. **Loading certificate...** — ladowanie certyfikatu z bazy danych 3. **Creating KSeF client...** — tworzenie klienta API KSeF 4. **Authenticating with KSeF (Challenge)...** — uwierzytelnianie w KSeF za pomoca podpisu XAdES 5. **Fetching KSeF public keys...** — pobieranie kluczy publicznych KSeF do szyfrowania 6. **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.