PUQ Mautic

KSeF Integrator WHMCS Addon

Zaawansowany modul addon dla WHMCS, ktory automatyzuje komunikacje z Krajowym Systemem e-Faktur (KSeF). Modul generuje ustrukturyzowane e-Faktury FA(3), podpisuje je certyfikatem XAdES, szyfruje sesje AES-256 i wysyla bezposrednio do KSeF.

Opis

KSeF Integrator addon WHMCS

Order now | Download | FAQ

PUQ KSeF Integrator — dodatek WHMCS

PUQ KSeF Integrator to zaawansowany modul dodatkowy (addon) dla systemu WHMCS, ktory automatyzuje komunikacje z Krajowym Systemem e-Faktur (KSeF) prowadzonym przez Ministerstwo Finansow RP.

Modul automatycznie generuje i wysyla ustrukturyzowane e-Faktury w formacie FA(3) po oplaceniu faktury w WHMCS, pobiera numery KSeF oraz UPO (Urzedowe Poswiadczenie Odbioru), obsluguje kody QR i prawidlowo przetwarza kompensacje salda kredytowego.

Glowne funkcje

Wymagania systemowe

Wymaganie Minimum
WHMCS 8.x, 9.x
PHP 8.1, 8.2+
OpenSSL >= 1.1.1
xmlsec1 >= 1.2.31
shell_exec wlaczone
Rozszerzenie PHP GD wymagane (do generowania QR)
Katalog tymczasowy zapisywalny

Srodowiska KSeF

Srodowisko API URL QR URL
Testowe https://ksef-test.mf.gov.pl https://qr-test.ksef.mf.gov.pl
Produkcyjne https://ksef.mf.gov.pl https://qr.ksef.mf.gov.pl

Linki

Changelog

KSeF Integrator addon WHMCS

Order now | Download | FAQ

v1.1 — 2026-03-28

Nowe funkcje

Poprawki i ulepszenia

v1.0 — 2026-02-12

Pierwsza wersja modulu.

Nowe funkcje

Jak to dziala — ogolne zasady

KSeF Integrator addon WHMCS

Order now | Download | FAQ

Schemat dzialania modulu

PUQ KSeF Integrator automatyzuje caly proces wysylki faktur do Krajowego Systemu e-Faktur. Ponizej opisano caly cykl zycia faktury w kontekscie integracji z KSeF.

Przepyw przetwarzania faktury

1. Oplacenie faktury w WHMCS

Gdy faktura w WHMCS otrzymuje status Paid (oplacona), automatycznie uruchamiany jest hook InvoicePaid.

2. Zbieranie danych

Modul automatycznie:

3. Zapis w kolejce

Faktura jest zapisywana w tabeli puq_ksef_invoices ze statusem:

4. Wysylka do KSeF

W zaleznosci od trybu wysylki:

Tryb natychmiastowy: Modul automatycznie wysyla fakture do KSeF zaraz po oplaceniu.

Tryb reczny: Faktura czeka w kolejce ze statusem "oczekuje". Administrator moze ja wyslac recznie z poziomu listy faktur lub panelu KSeF na stronie faktury.

5. Proces wysylki (7 krokow)

  1. Uwierzytelnienie XAdES — modul uwierzytelnia sie w KSeF za pomoca certyfikatu kwalifikowanego
  2. Szyfrowanie sesji — generowanie klucza AES-256 i szyfrowanie go kluczem publicznym RSA KSeF
  3. Otwarcie sesji — otwarcie interaktywnej sesji online FA(3) w KSeF
  4. Szyfrowanie faktury — faktura XML jest szyfrowana algorytmem AES-256-CBC
  5. Wysylka — zaszyfrowana faktura jest przesylana do KSeF
  6. Sprawdzanie statusu — modul odpytuje KSeF o status przetwarzania (do 10 prob, co 2 sekundy)
  7. Pobranie UPO i zamkniecie sesji — po przyjciu faktury modul pobiera UPO i zamyka sesje

6. Statusy faktur

Status Opis
Oczekuje (pending) Faktura w kolejce, czeka na wysylke
Przetwarzanie (processing) Faktura wyslana, czeka na odpowiedz KSeF
Przyjeta (accepted) Faktura przyjeta przez KSeF, numer KSeF przypisany
Odrzucona (rejected) KSeF odrzucil fakture (blad walidacji po stronie KSeF)
Blad (error) Blad po stronie modulu (np. nieprawidlowa stawka VAT, blad polaczenia)

7. Po przyjciu faktury

Gdy KSeF przyjmie fakture:

Obslugiwane typy nabywcow

Modul automatycznie rozpoznaje typ nabywcy na podstawie danych klienta:

Typ Warunek Stawka VAT
Firma krajowa Kraj = PL, firma Standardowa (np. 23%)
Osoba krajowa Kraj = PL, osoba fizyczna Standardowa (np. 23%)
Firma UE (B2B) Kraj UE (nie PL), firma Konfigurowalna (domyslnie 0% EX)
Osoba UE (B2C) Kraj UE (nie PL), osoba fizyczna Konfigurowalna
Poza UE Kraj spoza UE Konfigurowalna (domyslnie 0% EX)

Obslugiwane stawki VAT KSeF

KSeF akceptuje tylko nastepujace stawki VAT:

0%, 3%, 4%, 5%, 7%, 8%, 22%, 23%

Jesli faktura w WHMCS ma inna stawke VAT (np. 20%), modul zglosi blad walidacji i faktura nie zostanie wyslana.

Obsluga walut obcych

Jesli faktura jest wystawiona w walucie innej niz PLN (np. USD, EUR):

Pierwsze kroki

Informacje o historii zmian, instalacji, aktualizacji oraz licencji modulu PUQ KSeF Integrator.

Pierwsze kroki

Instalacja / Aktualizacja

KSeF Integrator addon WHMCS

Order now | Download | FAQ

Wymagania systemowe

Wymaganie Minimalna wersja
PHP 8.1, 8.2 lub nowszy
WHMCS 8.x, 9.x lub nowszy
ionCube Loader v13 lub nowszy (v14, v15)
Rozszerzenie PHP OpenSSL, GD, cURL, DOM

Uwaga: Modul uzywa kodowania ionCube. Upewnij sie, ze ionCube Loader jest zainstalowany i aktywny na serwerze.

Pobieranie

Modul mozna zamowic i pobrac na stronie PUQ Cloud:

PHP 8.1:

wget https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-KSeF-Integrator/php81/PUQ_WHMCS-KSeF-Integrator-latest.zip

PHP 8.2+:

wget https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-KSeF-Integrator/php82/PUQ_WHMCS-KSeF-Integrator-latest.zip

W przypadku problemow z pobraniem pliku, wszystkie wersje dostepne sa pod adresem: https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-KSeF-Integrator/

Po pobraniu rozpakuj archiwum:

unzip PUQ_WHMCS-KSeF-Integrator-latest.zip

Instalacja

Krok 1: Przesylanie plikow

Rozpakuj archiwum modulu i przeslij katalog puq_ksef_integrator do katalogu modulow dodatkowych WHMCS:

/twoj-whmcs/modules/addons/puq_ksef_integrator/

Struktura katalogu po przeslaniu:

modules/addons/puq_ksef_integrator/
    puq_ksef_integrator.php
    hooks.php
    whmcs.json
    version
    logo.png
    lib/
        puqKSeFIntegrator.php
        puqKSeFClient.php
        puqKSeFIntegratorQrCode.php
        puqKSeFIntegratorPdfHelper.php
    lang/
        english.php
        polish.php
    templates/
        ...

Krok 2: Aktywacja modulu

  1. Zaloguj sie do panelu administracyjnego WHMCS
  2. Przejdz do Setup > Addon Modules
  3. Znajdz PUQ KSeF Integrator na liscie
  4. Kliknij Activate

Podczas aktywacji modul automatycznie tworzy trzy tabele w bazie danych:

Krok 3: Konfiguracja klucza licencyjnego

  1. Po aktywacji kliknij Configure obok modulu
  2. Wpisz klucz licencyjny w polu License key
  3. Wybierz grupy administratorow, ktore maja miec dostep do modulu
  4. Kliknij Save Changes

Po zapisaniu, pod polem klucza licencyjnego pojawi sie status weryfikacji (np. success: 2026-03-12T18:22:48+01:00).

Konfiguracja modulu z kluczem licencyjnym i kontrola dostepu 01-whmcs-addon-config-license.png

Krok 4: Konfiguracja modulu

Przejdz do Addons > PUQ KSeF Integrator > Ustawienia > Konfiguracja i skonfiguruj dane firmy, certyfikaty oraz tryb wysylki. Szczegoly opisane sa na stronie Konfiguracja.

Aktualizacja

Krok 1: Kopia zapasowa

Przed aktualizacja zalecamy wykonanie kopii zapasowej:

Krok 2: Przeslanie nowych plikow

Rozpakuj nowa wersje archiwum i nadpisz wszystkie pliki w katalogu:

/twoj-whmcs/modules/addons/puq_ksef_integrator/

Krok 3: Weryfikacja

  1. Zaloguj sie do panelu administracyjnego WHMCS
  2. Przejdz do Addons > PUQ KSeF Integrator
  3. Sprawdz numer wersji w prawym gornym rogu nawigacji (np. v1.0)
  4. Przejdz do Ustawienia > Sprawdz srodowisko, aby upewnic sie, ze wszystkie wymagania sa spelnione

Modul automatycznie wykrywa brakujace kolumny w tabelach i dodaje je podczas pierwszego uruchomienia po aktualizacji. Nie jest wymagana ponowna aktywacja.

Dezaktywacja

Uwaga: Dezaktywacja modulu trwale usuwa wszystkie tabele modulu z bazy danych (puq_ksef_certificates, puq_ksef_invoices, puq_ksef_settings). Wszystkie dane o certyfikatach, fakturach KSeF i ustawieniach zostana utracone.

  1. Przejdz do Setup > Addon Modules
  2. Kliknij Deactivate obok PUQ KSeF Integrator
  3. Potwierdz dezaktywacje
Pierwsze kroki

Licencja

KSeF Integrator addon WHMCS

Order now | Download | FAQ

Jak dziala licencja

Modul PUQ KSeF Integrator wymaga aktywnej licencji do pelnego funkcjonowania. Licencja jest weryfikowana za posrednictwem serwera licencji PUQ Cloud.

Weryfikacja licencji

Co jest wysylane do serwera licencji

Podczas weryfikacji modul wysyla:

Ograniczenia bez aktywnej licencji

Gdy licencja jest nieaktywna lub wygasla, modul dziala w trybie ograniczonym:

Co dziala bez licencji

Co jest zablokowane bez licencji

Komunikaty

Po aktywacji licencji

Po wpisaniu prawidlowego klucza licencyjnego i zapisaniu konfiguracji:

  1. Baner z ostrzezeniem znika
  2. Wszystkie funkcje modulu sa dostepne
  3. Faktury ze statusem "oczekuje" (pending), ktore zebraly sie podczas okresu bez licencji, moga byc wyslane recznie przyciskiem "Wyslij teraz" lub ponownie przetworzone

Zakup licencji

Licencje mozna zakupic na stronie:

https://panel.puqcloud.com/index.php/store/whmcs-addon/ksef-integrator

W razie pytan dotyczacych licencji prosimy o kontakt przez system zgloszeniowy:

https://puqcloud.com/submitticket.php

Konfiguracja i ustawienia

Konfiguracja modulu, zarzadzanie certyfikatami, sprawdzenie srodowiska oraz testowanie polaczenia z KSeF.

Konfiguracja i ustawienia

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.

Konfiguracja i ustawienia

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
Konfiguracja i 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.

Konfiguracja i ustawienia

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.

Praca z fakturami

Zarzadzanie fakturami KSeF: lista faktur, panel KSeF na stronie faktury, widget na dashboardzie oraz osadzanie kodu QR na fakturze PDF.

Praca z fakturami

Lista faktur

KSeF Integrator addon WHMCS

Order now | Download | FAQ

Strona listy faktur dostepna jest w: Addons > PUQ KSeF Integrator > Faktury

Lista faktur — widok ogolny 16-lista-faktur-ogolna.png

Lista faktur z filtrami statusow i akcjami 17-lista-faktur-filtry-nieoplacona.png

Filtry statusow

Na gorze strony znajduja sie przyciski filtrowania wedlug statusu:

Filtr Opis
Wszystkie Wszystkie faktury
Oczekuje Faktury czekajace na wysylke
Przetwarzanie Faktury w trakcie przetwarzania przez KSeF
Przyjeta Faktury pomyslnie przyjete przez KSeF
Odrzucona Faktury odrzucone przez KSeF
Blad Faktury z bledem

Przy kazdym filtrze wyswietlana jest liczba faktur o danym statusie (badge z liczba).

Tabela faktur

Kolumna Opis
# ID rekordu w tabeli KSeF
Faktura Numer faktury WHMCS, kwota netto, podatek, stawka VAT, suma brutto, waluta
Klient Typ klienta (Firma / Osoba)
Status Status KSeF (kolorowa etykieta)
Numer KSeF / Blad Numer KSeF (jesli przyjeta) lub opis bledu (jesli blad/odrzucona)
Daty (Wyst / KSeF) Data wystawienia i data przyjcia przez KSeF
Akcje Przyciski akcji dostepne dla danego statusu

Akcje

Dla faktur ze statusem "Przyjeta"

Dla faktur ze statusem "Oczekuje"

Dla faktur ze statusem "Blad" lub "Odrzucona"

Wyszukiwanie

Pole Search pozwala wyszukiwac faktury po:

Potwierdzenia akcji

Przed wykonaniem destrukcyjnych akcji wyswietlane sa okna potwierdzenia:

Okno potwierdzenia oznaczania faktury jako nieoplaconej 17-lista-faktur-filtry-nieoplacona.png

Praca z fakturami

Panel KSeF na stronie faktury

KSeF Integrator addon WHMCS

Order now | Download | FAQ

Modul automatycznie dodaje panel PUQ KSeF Integrator na kazdej stronie szczegolowej faktury w panelu administracyjnym WHMCS (Billing > Invoices > [faktura]).

Panel jest wyswietlany na gorze strony faktury i zawiera wszystkie informacje dotyczace statusu KSeF danej faktury.

Faktura nie wyslana do KSeF

Jesli faktura nie zostala jeszcze wyslana do KSeF, panel wyswietla komunikat:

Ta faktura nie zostala wyslana do KSeF.

Wraz z przyciskiem Wyslij do KSeF.

Panel KSeF — faktura nie wyslana, przycisk Wyslij do KSeF 12-panel-ksef-nie-wyslana.png

Akcja "Wyslij do KSeF"

  1. Kliknij przycisk Wyslij do KSeF
  2. Pojawi sie okno potwierdzenia: "Uwaga: Data wystawienia i termin platnosci faktury zostana zmienione na dzisiejsza date. Kontynuowac?"

Potwierdzenie wysylki do KSeF 13-panel-ksef-potwierdzenie-wysylki.png

  1. Po potwierdzeniu modul zbierze dane, wygeneruje XML i doda fakture do kolejki KSeF ze statusem "oczekuje"

Uwaga: Ta akcja jest dostepna tylko dla faktur ze statusem Paid (oplacona) w WHMCS.

Faktura ze statusem "Blad"

Gdy faktura ma status Blad, panel wyswietla:

Dostepne akcje:

Panel KSeF — faktura ze statusem Blad 15-panel-ksef-status-blad.png

Potwierdzenie oznaczenia jako nieoplacona z poziomu panelu faktury:

Potwierdzenie oznaczenia jako nieoplacona 18-panel-ksef-potwierdzenie-nieoplacona.png

Faktura przyjta przez KSeF

Gdy faktura zostanie pomyslnie przyjta przez KSeF, panel wyswietla pelne informacje:

Pole Opis Przyklad
Status KSeF PRZYJETA (zielona etykieta)
Numer KSeF Unikalny numer faktury w KSeF (klikalny link) 5252834345-20260212-15321C400000-25
Wyslano do KSeF Data i godzina wysylki 2026-02-12 03:00:54
Przyjto przez KSeF Data i godzina przyjcia 2026-02-12 02:00:52
Waluta Waluta faktury z kursem (dla walut obcych) USD / Kurs: 1 USD = 3.54 PLN
Referencja KSeF Numer referencyjny sesji 20260212-EE-06EA8A5000-479472F8D4-3D
Hash faktury Hash SHA-256 faktury mGSkbTBEmkasYPglPl/3AWTumEXLjv/...
Data fakturowania KSeF Data fakturowania przypisana przez KSeF 2026-02-12 02:00:52

Dostepne akcje:

Panel KSeF — faktura przyjeta z pelnym zestawem informacji 19-panel-ksef-przyjeta.png

Pod panelem wyswietlany jest rowniez link:

Przycisk "Odswiez"

W prawym gornym rogu panelu znajduje sie przycisk Odswiez, ktory pozwala odswiezyc dane panelu bez przeladowania calej strony.

Praca z fakturami

Widget na dashboardzie

KSeF Integrator addon WHMCS

Order now | Download | FAQ

Modul automatycznie dodaje widget KSeF Integrator na stronie glownej panelu administracyjnego WHMCS (Dashboard).

Widget KSeF Integrator na dashboardzie 02-widget-dashboard.png

Zawartosc widgetu

Widget wyswietla podsumowanie statusow wszystkich faktur KSeF:

Status Ikona Opis
PRZYJETA Zielone kolko Liczba faktur pomyslnie przyjetych przez KSeF
Przetwarzanie Niebieski spinner Liczba faktur w trakcie przetwarzania
OCZEKUJE Szary zegar Liczba faktur w kolejce do wysylki
Odrzucona Czerwony krzyzyk Liczba faktur odrzuconych przez KSeF
BLAD Czerwony trojkat Liczba faktur z bledem
Lacznie Ikona faktury Calkowita liczba faktur

Dla statusow Odrzucona i BLAD, jesli liczba jest wieksza niz 0, wyswietlany jest klikalny link, ktory prowadzi do przefiltrowanej listy faktur.

Przycisk

Na dole widgetu znajduje sie przycisk Zobacz wszystkie faktury, ktory prowadzi do pelnej listy faktur modulu.

Odswiezanie

Widget posiada wbudowane cache'owanie z czasem wygasniecia 120 sekund. Dane sa automatycznie odswiezane po uplywie tego czasu.

Aby recznie odswiezyc widget, uzyj ikony odswiezania w prawym gornym rogu widgetu.

Brak faktur

Gdy w systemie nie ma jeszcze zadnych faktur KSeF, widget wyswietla komunikat:

Brak faktur

Wraz z przyciskiem Zobacz wszystkie faktury.

Praca z fakturami

Kod QR KSeF na fakturze PDF

KSeF Integrator addon WHMCS

Order now | Download | FAQ

Po przyjciu faktury przez KSeF generowany jest URL weryfikacyjny z kodem QR. Mozesz osadzic ten kod QR w swoim niestandardowym szablonie PDF faktury WHMCS, tak aby kazda wydrukowana faktura zawierala skanowalny link weryfikacyjny KSeF.

Przyklad faktury PDF z kodem QR KSeF, numerem KSeF i linkiem weryfikacyjnym 20-faktura-pdf-qr.png

Wymagania wstpne

1. Znajdz swoj szablon faktury

Szablony PDF faktur WHMCS znajduja sie zazwyczaj w:

templates/[template_name]/   (WHMCS root)
  invoicepdf.tpl      — szablon Smarty
  lub niestandardowa klasa .php PDF

2. Dolacz helper i pobierz dane

Dodaj ponizszy kod na poczatku szablonu PDF (lub w miejscu, gdzie potrzebujesz danych KSeF):

require_once ROOTDIR . '/modules/addons/puq_ksef_integrator/lib/puqKSeFIntegratorPdfHelper.php';
$ksef = puq_ksef_get_invoice_data($invoiceid);

3. Parametry funkcji

Funkcja przyjmuje opcjonalne parametry kontrolujace generowanie kodu QR:

puq_ksef_get_invoice_data(int $invoiceId, int $qrSize = 4, int $qrMargin = 2): array
Parametr Typ Domyslnie Opis
$invoiceId int — ID faktury WHMCS
$qrSize int 4 Rozmiar piksela na modul QR. Wieksza wartosc = wiekszy obraz QR.
$qrMargin int 2 Strefa ciszy wokol kodu QR w modulach (biala ramka).

Przyklad — wiekszy QR z minimalna ramka:

$ksef = puq_ksef_get_invoice_data($invoiceid, 6, 1);

4. Dostpne zmienne

Funkcja zwraca tablice asocjacyjna z nastpujacymi kluczami:

Klucz Typ Opis
ksef_found bool true jesli faktura zostala znaleziona w KSeF ze statusem accepted
ksef_number string Numer KSeF faktury (np. 5252834345-20260211-0100001BC403-59)
ksef_reference string Numer referencyjny KSeF
ksef_status string Status KSeF (zawsze accepted gdy ksef_found=true)
ksef_qr_url string Pelny URL weryfikacyjny KSeF dla kodu QR
ksef_qr_png_base64 string Obraz PNG kodu QR zakodowany jako string base64
ksef_qr_png_data_uri string Kod QR jako data URI (data:image/png;base64,...) do uzycia w HTML
ksef_invoice_hash string Hash faktury z KSeF
ksef_issue_date string Data wystawienia faktury (YYYY-MM-DD)
ksef_accepted_at string Data/godzina przyjcia faktury przez KSeF

5. Przyklad A — z plikiem tymczasowym

Zapisuje QR jako tymczasowy plik PNG, przekazuje go do TCPDF, a nastpnie usuwa:

// --- Blok kodu QR KSeF (dodaj na dole szablonu PDF) ---
require_once ROOTDIR . '/modules/addons/puq_ksef_integrator/lib/puqKSeFIntegratorPdfHelper.php';
$ksef = puq_ksef_get_invoice_data($invoiceid);

if ($ksef['ksef_found'] && $ksef['ksef_qr_png_base64']) {
    // Zapisz QR PNG do pliku tymczasowego
    $qrTmpFile = tempnam(sys_get_temp_dir(), 'ksef_qr_');
    file_put_contents($qrTmpFile, base64_decode($ksef['ksef_qr_png_base64']));

    // Wycentruj obraz QR (30x30mm) poziomo
    $pageWidth = $pdf->getPageWidth();
    $qrSize = 30;
    $qrX = ($pageWidth - $qrSize) / 2;
    $qrY = $pdf->GetY() + 5;
    $pdf->Image($qrTmpFile, $qrX, $qrY, $qrSize, $qrSize, 'PNG');

    // Numer KSeF wycentrowany pod QR
    $pdf->SetY($qrY + $qrSize + 2);
    $pdf->SetFont('', 'B', 8);
    $pdf->Cell(0, 5, 'KSeF: ' . $ksef['ksef_number'], 0, 1, 'C');

    // Bezposredni link KSeF wycentrowany pod numerem
    if (!empty($ksef['ksef_qr_url'])) {
        $pdf->SetFont('', '', 7);
        $pdf->Cell(0, 4, $ksef['ksef_qr_url'], 0, 1, 'C', false, $ksef['ksef_qr_url']);
    }

    // Usun plik tymczasowy
    @unlink($qrTmpFile);
}

6. Przyklad B — bez pliku tymczasowego (base64_decode)

Uzywa prefiksu @ TCPDF do przekazania surowych danych obrazu bezposrednio — bez pliku tymczasowego:

// --- Blok kodu QR KSeF — bez pliku tymczasowego ---
require_once ROOTDIR . '/modules/addons/puq_ksef_integrator/lib/puqKSeFIntegratorPdfHelper.php';
$ksef = puq_ksef_get_invoice_data($invoiceid);

if ($ksef['ksef_found'] && $ksef['ksef_qr_png_base64']) {
    // Przekaz surowe dane PNG bezposrednio przez prefiks '@'
    $qrRaw = '@' . base64_decode($ksef['ksef_qr_png_base64']);

    // Wycentruj obraz QR (30x30mm) poziomo
    $pageWidth = $pdf->getPageWidth();
    $qrSize = 30;
    $qrX = ($pageWidth - $qrSize) / 2;
    $qrY = $pdf->GetY() + 5;
    $pdf->Image($qrRaw, $qrX, $qrY, $qrSize, $qrSize, 'PNG');

    // Numer KSeF wycentrowany pod QR
    $pdf->SetY($qrY + $qrSize + 2);
    $pdf->SetFont('', 'B', 8);
    $pdf->Cell(0, 5, 'KSeF: ' . $ksef['ksef_number'], 0, 1, 'C');

    // Bezposredni link KSeF wycentrowany pod numerem
    if (!empty($ksef['ksef_qr_url'])) {
        $pdf->SetFont('', '', 7);
        $pdf->Cell(0, 4, $ksef['ksef_qr_url'], 0, 1, 'C', false, $ksef['ksef_qr_url']);
    }
}

7. Przyklad C — plik tymczasowy z automatycznym fallbackiem

Probuje podejscia z plikiem tymczasowym; jesli katalog tymczasowy nie jest zapisywalny, przechodzi na metode @:

// --- Blok kodu QR KSeF — plik tymczasowy z fallbackiem ---
require_once ROOTDIR . '/modules/addons/puq_ksef_integrator/lib/puqKSeFIntegratorPdfHelper.php';
$ksef = puq_ksef_get_invoice_data($invoiceid);

if ($ksef['ksef_found'] && $ksef['ksef_qr_png_base64']) {
    $qrPngData = base64_decode($ksef['ksef_qr_png_base64']);
    $qrImageArg = null;
    $qrTmpFile = null;

    // Najpierw probuj plik tymczasowy
    $qrTmpFile = @tempnam(sys_get_temp_dir(), 'ksef_qr_');
    if ($qrTmpFile && @file_put_contents($qrTmpFile, $qrPngData)) {
        $qrImageArg = $qrTmpFile;
    } else {
        // Fallback: przekaz surowe dane przez prefiks '@'
        $qrImageArg = '@' . $qrPngData;
        $qrTmpFile = null;
    }

    // Wycentruj obraz QR (30x30mm) poziomo
    $pageWidth = $pdf->getPageWidth();
    $qrSize = 30;
    $qrX = ($pageWidth - $qrSize) / 2;
    $qrY = $pdf->GetY() + 5;
    $pdf->Image($qrImageArg, $qrX, $qrY, $qrSize, $qrSize, 'PNG');

    // Numer KSeF wycentrowany pod QR
    $pdf->SetY($qrY + $qrSize + 2);
    $pdf->SetFont('', 'B', 8);
    $pdf->Cell(0, 5, 'KSeF: ' . $ksef['ksef_number'], 0, 1, 'C');

    // Bezposredni link KSeF wycentrowany pod numerem
    if (!empty($ksef['ksef_qr_url'])) {
        $pdf->SetFont('', '', 7);
        $pdf->Cell(0, 4, $ksef['ksef_qr_url'], 0, 1, 'C', false, $ksef['ksef_qr_url']);
    }

    // Usun plik tymczasowy jesli uzyty
    if ($qrTmpFile) {
        @unlink($qrTmpFile);
    }
}

Uwagi

Rozwiazywanie problemow

require_once ROOTDIR . '/modules/addons/puq_ksef_integrator/lib/puqKSeFIntegratorPdfHelper.php';
$ksef = puq_ksef_get_invoice_data($invoiceid);

// Tymczasowy debug — usun po testowaniu
error_log('PUQ KSeF PDF debug: invoiceid=' . $invoiceid . ' ksef_found=' . var_export($ksef['ksef_found'], true) . ' status=' . $ksef['ksef_status']);