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