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:
- 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)
- Uwierzytelnienie XAdES — modul uwierzytelnia sie w KSeF za pomoca certyfikatu kwalifikowanego
- Szyfrowanie sesji — generowanie klucza AES-256 i szyfrowanie go kluczem publicznym RSA KSeF
- Otwarcie sesji — otwarcie interaktywnej sesji online FA(3) w KSeF
- Szyfrowanie faktury — faktura XML jest szyfrowana algorytmem AES-256-CBC
- Wysylka — zaszyfrowana faktura jest przesylana do KSeF
- Sprawdzanie statusu — modul odpytuje KSeF o status przetwarzania (do 10 prob, co 2 sekundy)
- 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:
- 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:
| 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):
- 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")