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
Panel KSeF na stronie faktury
Widget na dashboardzie
Kod QR KSeF na fakturze PDF

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"

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 17-lista-faktur-filtry-nieoplacona.png

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"

Kliknij przycisk Wyslij do KSeF
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

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 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:

Pobierz UPO (zielony) — pobieranie UPO w formacie XML
XML (niebieski) — podglad XML faktury FA(3)

Panel KSeF — faktura przyjeta z pelnym zestawem informacji 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

Order now | Download | FAQ

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

Zawartosc widgetu

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

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

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

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):

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

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:

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']);