PUQ Mautic

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

Strona konfiguracji modulu 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

Lista certyfikatow z informacjami o waznosci 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/
  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/
  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
  1. Kliknij Zapisz certyfikat

Formularz dodawania certyfikatu 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

Order now | Download | FAQ

Strona sprawdzania srodowiska dostepna jest w: Addons > PUQ KSeF Integrator > Ustawienia > Sprawdz srodowisko

Wyniki sprawdzania srodowiska — wszystkie testy zaliczone 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

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

Strona glowna z statystykami faktur i przewodnikiem szybkiego startu 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 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:

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.