# KSeF Integrator WHMCS Addon # Opis ### 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/) ## 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 - **Automatyczna wysylka faktur do KSeF** — po oplaceniu faktury w WHMCS modul automatycznie generuje XML FA(3) i wysyla do KSeF - **Zgodnosc z formatem FA(3)** — pelna zgodnosc ze struktura e-Faktury wymagana przez KSeF - **Obsluga kompensacji salda kredytowego** — prawidlowe przetwarzanie faktur z czesciowa lub pelna kompensacja - **Automatyczne pobieranie numeru KSeF i UPO** — po przyjciu faktury przez KSeF modul pobiera numer KSeF oraz UPO - **Kody QR na fakturach PDF** — mozliwosc umieszczenia kodu QR z linkiem weryfikacyjnym KSeF na fakturze PDF - **Srodowisko testowe i produkcyjne** — obsluga obu srodowisk KSeF z osobnymi certyfikatami - **Szczegolowe logowanie komunikacji API** — tryb debugowania z rejestrowaniem kazdego kroku w dzienniku WHMCS - **Obsluga wielu walut** — automatyczne przeliczanie kursow walut dla faktur w walutach obcych - **Panel KSeF na stronie faktury** — szczegolowy panel z informacjami KSeF bezposrednio na stronie faktury w panelu administracyjnym - **Widget na dashboardzie** — statystyki faktur KSeF na stronie glownej panelu administracyjnego - **Zarzadzanie certyfikatami** — bezpieczne przechowywanie certyfikatow XAdES z szyfrowaniem - **Wielojezycznosc** — polski i angielski interfejs - - - - - - ## Wymagania systemowe
WymaganieMinimum
WHMCS8.x, 9.x
PHP8.1, 8.2+
OpenSSL>= 1.1.1
xmlsec1>= 1.2.31
shell\_execwlaczone
Rozszerzenie PHP GDwymagane (do generowania QR)
Katalog tymczasowyzapisywalny
- - - - - - ## Srodowiska KSeF
SrodowiskoAPI URLQR 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 - **Strona produktu:** [https://puqcloud.com/](https://puqcloud.com/) - **Dokumentacja:** [https://doc.puq.info/books/ksef-integrator-whmcs-addon](https://doc.puq.info/books/ksef-integrator-whmcs-addon) - **Wsparcie:** [https://puqcloud.com/submitticket.php](https://puqcloud.com/submitticket.php?step=2&deptid=1) - **Spolecznosc:** [https://community.puqcloud.com/](https://community.puqcloud.com/)# Changelog ### 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/) ## v1.1 — 2026-03-28 ### Nowe funkcje - **Pomijanie faktur AddFunds** — nowa opcja w ustawieniach pozwala automatycznie pomijac faktury za doladowanie salda klienta. Doladowania nie sa rzeczywista sprzedaza i nie powinny byc raportowane w KSeF. Domyslnie wlaczone. ### Poprawki i ulepszenia - **Poprawiona klasyfikacja nabywcy z UE** — ulepszone czyszczenie numeru EU VAT ID z niewidocznych znakow (BOM, zero-width space itp.), ktore mogly powodowac bledna klasyfikacje klientow unijnych jako osob fizycznych zamiast firm - **Lepsza walidacja danych podatkowych** — pole `tax_id` (numer VAT) jest teraz agresywniej oczyszczane ze znakow specjalnych, co eliminuje problemy z danymi importowanymi lub kopiowanymi z zewnetrznych zrodel - - - - - - ## v1.0 — 2026-02-12 Pierwsza wersja modulu. ### Nowe funkcje - Automatyczna wysylka faktur do KSeF po oplaceniu (tryb natychmiastowy) - Reczna wysylka faktur do KSeF z poziomu panelu administracyjnego (tryb reczny) - Generowanie e-Faktur w formacie FA(3) zgodnym z KSeF - Uwierzytelnianie XAdES z certyfikatem kwalifikowanym - Szyfrowanie faktur AES-256 przed wysylka - Automatyczne pobieranie numeru KSeF i UPO po przyjciu faktury - Generowanie kodow QR z linkiem weryfikacyjnym KSeF - Obsluga srodowiska testowego i produkcyjnego - Zarzadzanie certyfikatami (dodawanie, usuwanie, walidacja) - Panel KSeF na stronie szczegolowej faktury w WHMCS - Widget statystyk na dashboardzie administratora - Sprawdzanie srodowiska (shell\_exec, xmlsec1, OpenSSL, katalog tymczasowy) - Testowanie polaczenia z serwerem KSeF - Ponowna wysylka faktur odrzuconych lub z bledem - Oznaczanie faktur jako nieoplacone (cofanie do statusu Draft) - Helper PHP do umieszczania kodu QR KSeF na fakturze PDF - Obsluga wielu walut z automatycznym przeliczaniem kursow - Tryb debugowania z logowaniem do dziennika modulow WHMCS - Interfejs w jezyku polskim i angielskim - System licencjonowania z weryfikacja online/offline# Jak to dziala — ogolne zasady ### 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/) ## 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: - Pobiera dane faktury z WHMCS (numer, kwoty, pozycje, stawka VAT) - Pobiera dane klienta (nazwa firmy / osoba fizyczna, NIP, adres) - Przygotowuje dane sprzedawcy z konfiguracji modulu - Waliduje dane (stawka VAT musi byc zgodna z KSeF: 0, 3, 4, 5, 7, 8, 22, 23%) - Generuje plik XML faktury w formacie FA(3) ### 3. Zapis w kolejce Faktura jest zapisywana w tabeli `puq_ksef_invoices` ze statusem: - **oczekuje** (pending) — jesli dane sa prawidlowe - **blad** (error) — jesli walidacja nie powiodla sie (np. nieprawidlowa stawka VAT) ### 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
StatusOpis
**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: - Przypisywany jest unikalny **numer KSeF** (np. `5252834345-20260212-15321C400000-25`) - Pobierane jest **UPO** (Urzedowe Poswiadczenie Odbioru) - Generowany jest **link QR** do weryfikacji faktury - Wszystkie dane sa zapisywane w bazie danych - - - - - - ## Obslugiwane typy nabywcow Modul automatycznie rozpoznaje typ nabywcy na podstawie danych klienta:
TypWarunekStawka VAT
Firma krajowaKraj = PL, firmaStandardowa (np. 23%)
Osoba krajowaKraj = PL, osoba fizycznaStandardowa (np. 23%)
Firma UE (B2B)Kraj UE (nie PL), firmaKonfigurowalna (domyslnie 0% EX)
Osoba UE (B2C)Kraj UE (nie PL), osoba fizycznaKonfigurowalna
Poza UEKraj spoza UEKonfigurowalna (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): - Modul automatycznie pobiera oficjalny kurs waluty z **Narodowego Banku Polskiego (NBP)** za posrednictwem API: `https://api.nbp.pl/api/exchangerates/rates/A/{waluta}/last/` - Jest to oficjalny kurs sredni NBP — wymagany przez KSeF do prawidlowego przeliczenia kwot na PLN - Kurs jest zapisywany w rekordzie faktury KSeF - Na panelu KSeF wyswietlany jest kurs przeliczeniowy (np. "Kurs: 1 USD = 3.54 PLN")# Pierwsze kroki Informacje o historii zmian, instalacji, aktualizacji oraz licencji modulu PUQ KSeF Integrator. # Instalacja / Aktualizacja ### 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/) ## 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: - **Zamow / Pobierz:** [https://puqcloud.com/index.php?rp=/store/whmcs-addon-puq-ksef-integrator](https://puqcloud.com/index.php?rp=/store/whmcs-addon-puq-ksef-integrator) - **FAQ:** [https://community.puqcloud.com/](https://community.puqcloud.com/) - **Bezposredni link do pobrania najnowszej wersji:** 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/](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: - `puq_ksef_certificates` — certyfikaty do uwierzytelniania - `puq_ksef_invoices` — rejestr faktur KSeF - `puq_ksef_settings` — ustawienia modulu ### 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](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-bxcmfron.png) *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: - Bazy danych WHMCS (szczegolnie tabel `puq_ksef_*`) - Plikow modulu w `modules/addons/puq_ksef_integrator/` ### 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 # Licencja ### 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/) ## Jak dziala licencja Modul PUQ KSeF Integrator wymaga aktywnej licencji do pelnego funkcjonowania. Licencja jest weryfikowana za posrednictwem serwera licencji PUQ Cloud. ### Weryfikacja licencji - Modul okresowo sprawdza waznosc licencji na serwerze `https://license.puqcloud.com/` - Wyniki weryfikacji sa cachowane w bazie danych, dzieki czemu modul nie wymaga stalego polaczenia z serwerem licencji - Okres cachowania wynosi 5 dni — w tym czasie modul korzysta z zapisanego wyniku weryfikacji - Jesli serwer licencji jest tymczasowo niedostepny, modul korzysta z ostatniego zapisanego wyniku ### Co jest wysylane do serwera licencji Podczas weryfikacji modul wysyla: - Klucz licencyjny - Kod produktu - Nazwe serwera (System URL z konfiguracji WHMCS) --- ## Ograniczenia bez aktywnej licencji Gdy licencja jest nieaktywna lub wygasla, modul dziala w trybie ograniczonym: ### Co dziala bez licencji - **Zbieranie faktur** — faktury sa nadal automatycznie zbierane i zapisywane w kolejce ze statusem "oczekuje" (pending) po oplaceniu w WHMCS - **Przegladanie danych** — lista faktur, statystyki, podglad XML, pobieranie UPO - **Sprawdzanie srodowiska** — strona diagnostyki srodowiska - **Widget na dashboardzie** — statystyki faktur na stronie glownej ### Co jest zablokowane bez licencji - **Wysylka faktur do KSeF** — przyciski "Wyslij do KSeF" i "Wyslij teraz" sa zablokowane - **Ponowna wysylka** — przycisk "Ponow" dla faktur z bledem jest zablokowany - **Automatyczna wysylka** — nawet w trybie "natychmiast po oplaceniu" faktury nie sa automatycznie wysylane, lecz zapisywane jako "oczekujace" - **Zmiana ustawien** — zapis konfiguracji modulu jest zablokowany - **Zarzadzanie certyfikatami** — dodawanie i usuwanie certyfikatow jest zablokowane - **Oznaczanie jako nieoplacone** — przycisk "Oznacz nieoplacona" jest zablokowany ### Komunikaty - Na kazdej stronie modulu wyswietlany jest czerwony baner z informacja o braku licencji i linkiem do zakupu - Na dashboardzie WHMCS wyswietlane jest ostrzezenie - Przy probie wykonania zablokowanej akcji uzytkownik otrzymuje komunikat: *"License is not active. Please activate your license to perform this action."* --- ## 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](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](https://puqcloud.com/submitticket.php?step=2&deptid=1)** # 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. # Praca z fakturami Zarzadzanie fakturami KSeF: lista faktur, panel KSeF na stronie faktury, widget na dashboardzie oraz osadzanie kodu QR na fakturze PDF. # Lista faktur ### 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 listy faktur dostepna jest w: **Addons** > **PUQ KSeF Integrator** > **Faktury** ![Lista faktur — widok ogolny](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-k0c3r0rn.png) *16-lista-faktur-ogolna.png* ![Lista faktur z filtrami statusow i akcjami](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-f1k3imqw.png) *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" - **Pobierz UPO** (zielony) — pobiera plik UPO (Urzedowe Poswiadczenie Odbioru) w formacie XML - **XML** (niebieski) — wyswietla zawartosc XML faktury FA(3) ### Dla faktur ze statusem "Oczekuje" - **Wyslij teraz** (niebieski) — natychmiast wysyla fakture do KSeF. Operacja moze potrwac 20-30 sekund. - **Nieoplacona** (zolty) — oznacza fakture jako nieoplacona w WHMCS i usuwa rekord KSeF ### Dla faktur ze statusem "Blad" lub "Odrzucona" - **Ponow** (zielony) — ponawia probe wysylki. Modul ponownie zbiera dane, generuje XML i ustawia status na "oczekuje" - **Nieoplacona** (zolty) — oznacza fakture jako nieoplacona w WHMCS i usuwa rekord KSeF --- ## Wyszukiwanie Pole **Search** pozwala wyszukiwac faktury po: - Numerze faktury WHMCS - Numerze KSeF - Referencji KSeF --- ## Potwierdzenia akcji Przed wykonaniem destrukcyjnych akcji wyswietlane sa okna potwierdzenia: - **Wyslij teraz:** "Uwaga: Data wystawienia i termin platnosci faktury zostana zmienione na dzisiejsza date. Kontynuowac?" - **Nieoplacona:** "Oznaczyc fakture [numer] jako nieoplacona i usunac rekord KSeF?" ![Okno potwierdzenia oznaczania faktury jako nieoplaconej](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-f1k3imqw.png) *17-lista-faktur-filtry-nieoplacona.png* # Panel KSeF na stronie faktury ### 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/) 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](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-si8udpn3.png) *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](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-p36qhqvl.png) *13-panel-ksef-potwierdzenie-wysylki.png* 3. 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: - **Status KSeF:** BLAD (czerwona etykieta) - **Numer KSeF:** — - **Wyslano do KSeF:** — - **Przyjto przez KSeF:** — - **Waluta:** PLN - Opis bledu w czerwonym polu (np. "Stawka VAT 20% niezgodna z KSeF. Dozwolone: 0,3,4,5,7,8,22,23.") Dostepne akcje: - **Ponow** (zielony) — ponowna proba wysylki - **Oznacz nieoplacona** (zolty) — cofniecie faktury do statusu Draft ![Panel KSeF — faktura ze statusem Blad](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-6mvaxycb.png) *15-panel-ksef-status-blad.png* Potwierdzenie oznaczenia jako nieoplacona z poziomu panelu faktury: ![Potwierdzenie oznaczenia jako nieoplacona](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-nsqtxpqk.png) *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: - **Pobierz UPO** (zielony) — pobieranie UPO w formacie XML - **XML** (niebieski) — podglad XML faktury FA(3) ![Panel KSeF — faktura przyjeta z pelnym zestawem informacji](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-tmknqn9a.png) *19-panel-ksef-przyjeta.png* Pod panelem wyswietlany jest rowniez link: > Bezposredni link UPO z KSeF (wygasa: 2026-02-15 02:00:54) --- ## Przycisk "Odswiez" W prawym gornym rogu panelu znajduje sie przycisk **Odswiez**, ktory pozwala odswiezyc dane panelu bez przeladowania calej strony. # Widget na dashboardzie ### 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/) Modul automatycznie dodaje widget **KSeF Integrator** na stronie glownej panelu administracyjnego WHMCS (Dashboard). ![Widget KSeF Integrator na dashboardzie](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-qzhmlbfa.png) *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**. # Kod QR KSeF na fakturze PDF ### 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/) 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](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-9b0mxs0q.png) *20-faktura-pdf-qr.png* --- ## Wymagania wstpne - Modul PUQ KSeF Integrator musi byc aktywny - Faktura musi byc przyjta przez KSeF (status: accepted) - Rozszerzenie PHP GD musi byc zainstalowane (do generowania obrazu QR) --- ## 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): ```php 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: ```php 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: ```php $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: ```php // --- 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: ```php // --- 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 `@`: ```php // --- 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 - Przyklad A tworzy plik tymczasowy, poniewaz metoda `Image()` TCPDF normalnie wymaga sciezki do pliku. Plik jest usuwany natychmiast po uzyciu. - Przyklady B i C uzywaja prefiksu `@` — TCPDF akceptuje surowe dane obrazu w ten sposob, bez dostepu do systemu plikow. - Jesli modul nie jest aktywny lub faktura nie jest w KSeF, funkcja zwraca bezpieczne wartosci domyslne (`ksef_found=false`, puste stringi) — nie zostanie zgloszony zaden blad. --- ## Rozwiazywanie problemow - **Nic sie nie pojawia i brak bledow** — sprawdz, czy faktura zostala przyjeta przez KSeF (status: accepted). Funkcja zwraca dane tylko dla zaakceptowanych faktur. - **Upewnij sie, ze uzywasz prawidlowej zmiennej:** `$invoiceid` (wewnetrzny ID faktury WHMCS, dostepny w szablonach PDF). - **Aby debugowac**, tymczasowo dodaj przed blokiem `if`: ```php 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']); ```