Dokumentacja Prosta Faktura KSeF

• WordPress 6.0 lub nowszy, PHP 8.1+.
• WooCommerce 7.0+ (opcjonalnie — tylko do auto-wystawiania z zamówień).
• Konto w KSeF (Krajowy System e-Faktur) — token autoryzacyjny lub certyfikat KSeF.
• Połączenie wychodzące HTTPS do serwerów Ministerstwa Finansów (api.ksef.mf.gov.pl).

1. Pobierz wtyczkę z panelu klienta (po rejestracji / zakupie) jako plik ZIP.
2. W WordPress: Wtyczki → Dodaj nową → Wyślij wtyczkę na serwer → wybierz ZIP → Zainstaluj → Włącz.
3. W menu pojawi się sekcja KSeF. Wejdź w KSeF → Ustawienia → Licencja i wklej klucz licencyjny z panelu klienta.
4. Plan Darmowy działa od razu po instalacji (5 faktur sprzedaży / miesiąc). Plan Pro odblokowuje wszystkie funkcje po aktywacji klucza.

Aktualizacje wtyczki przychodzą automatycznie — patrz sekcja „Aktualizacje".

Wejdź w KSeF → Ustawienia → Kredencjały KSeF i dodaj konto KSeF. Możesz mieć wiele kont (per NIP / lokal) — wtyczka wybiera właściwe automatycznie.

Metoda uwierzytelniania

• Token autoryzacyjny — wygeneruj token w aplikacji e-Mikrofirma / panelu KSeF i wklej go w polu tokenu. Najprostsza metoda.
• Certyfikat KSeF (XAdES) — wgraj certyfikat i klucz prywatny (do podpisu kwalifikowanego). Stosowane przy zaawansowanych integracjach.

Środowisko

Wybierz test (piaskownica MF — do prób, faktury nie są realne i nie liczą się do limitu) albo prod (produkcja — faktury trafiają do urzędowego rejestru KSeF na stałe). Po zapisaniu kliknij „Testuj połączenie" — wtyczka wykona pełny flow autoryzacji i potwierdzi poprawność.

Uwaga: faktura wysłana do KSeF na środowisku produkcyjnym jest nieodwracalnie zapisana w rejestrze MF — można ją skorygować lub anulować, ale nie usunąć.

1. Wejdź w KSeF → Wystaw fakturę.
2. Wybierz konto KSeF (sprzedawcę) i nabywcę (firma PL / UE / spoza UE / osoba prywatna — autodetekcja po NIP).
3. Dodaj pozycje (nazwa, ilość, cena netto, stawka VAT, ewentualnie GTU, PKWiU/CN).
4. Ustaw daty (wystawienia, sprzedaży), termin i formę płatności oraz status płatności.
5. Zaznacz wymagane oznaczenia FA (patrz niżej).
6. Kliknij „Wystaw i wyślij do KSeF". Faktura zostaje zwalidowana względem schematu FA(3), wysłana, a po nadaniu numeru KSeF pobierane jest UPO.

Możesz też zapisać fakturę jako szkic i wysłać później.

• Mechanizm podzielonej płatności (P_18A) — zaznaczany automatycznie, gdy kwota brutto przekracza 15 000 zł.
• Zwolnienie z VAT — wybór stawki „zw" wymaga podania podstawy prawnej zwolnienia (np. art. 43 ust. 1 albo art. 113 ust. 1 i 9 ustawy o VAT). Wtyczka pilnuje tego i zapisuje podstawę w XML (P_19 + P_19A/B/C).
• Pozostałe oznaczenia (metoda kasowa, odwrotne obciążenie, WTT, procedura marży, faktura za okres, FP) ustawiasz checkboxami w sekcji „Oznaczenia FA".

Wejdź w KSeF → Faktury zakupu i kliknij „Pobierz z KSeF". Wtyczka pobierze faktury wystawione na Twój NIP (gdzie jesteś nabywcą) — także te wystawione przez dostawców poza wtyczką. Deduplikacja po numerze KSeF.

• Podgląd faktury otwiera pełny widok danych z XML (pozycje, strony, kwoty).
• W podglądzie ustawisz status płatności oraz kategorię wydatku (listę kategorii edytujesz w Ustawienia → Ogólne).
• Pełny XML faktury dociągany jest z KSeF przy pierwszym otwarciu podglądu (limit MF: 64 pobrania/godz.).

Z listy faktur sprzedaży lub z podglądu wybierz „Wystaw korektę". Wtyczka utworzy fakturę KOR powiązaną z oryginałem (referencja numeru KSeF faktury pierwotnej), z osobnym schematem numeracji korekt.

W Ustawienia → Ogólne → Numeracja faktur definiujesz schematy (np. FV/{Y}/{m}/{n}) — osobno dla faktur sprzedaży i korekt, z resetem licznika (nigdy / rocznie / miesięcznie) i paddingiem numeru.

W Ustawienia → Ogólne zaznacz statusy zamówienia (np. „W trakcie realizacji"), po przejściu w które faktura ma być automatycznie wystawiona i wysłana do KSeF. Możesz też włączyć auto-wysyłkę PDF na e-mail nabywcy z zamówienia.

Dla klientów prywatnych (B2C) wybierasz politykę: faktura imienna na żądanie, zawsze, albo tylko dla firm.

W Ustawienia → Email włączysz automatyczną wysyłkę faktury na e-mail nabywcy po wystawieniu (domyślnie włączona). Treść i temat są konfigurowalne ze zmiennymi ({numer}, {kwota}, {termin}, {ksef}, {sprzedawca}…); mail wychodzi jako ładny HTML + wersja tekstowa, z PDF w załączniku.

Baza kontrahentów (KSeF → Kontrahenci) wypełnia się automatycznie z pobranych faktur (z zakupu — dostawcy, ze sprzedaży — nabywcy), z deduplikacją po NIP. Na karcie kontrahenta są zakładki: Ogólne, Faktury zakupu i Faktury sprzedaży — z podglądem i raportem sum za wybrany okres.

Wtyczka aktualizuje się jak każda inna w WordPress (Wtyczki → Dostępna aktualizacja → Aktualizuj). Powiadomienie o nowej wersji pojawia się automatycznie (sprawdzane co kilka godzin). Aktualizacja nie usuwa danych ani kredencjałów.

• Tokeny i klucze są szyfrowane w bazie (AES-256-GCM).
• Załączniki trzymane są w katalogu prywatnym, poza publicznym dostępem, serwowane tylko po weryfikacji uprawnień.
• System uprawnień (capabilities) pozwala ograniczyć dostęp pracownikom (osobno sprzedaż / zakup / ustawienia).
• Odinstalowanie wtyczki czyści dane zgodnie z RODO (tabele, pliki, opcje).

„Testuj połączenie" — timeout / przekroczono czas

Najczęściej to przejściowy problem sieci/DNS między Twoim serwerem a KSeF (komunikat „środowisko KSeF mogło chwilowo nie odpowiadać"). Spróbuj ponownie za chwilę. Jeśli powtarza się — sprawdź, czy serwer ma sprawne DNS i wychodzące połączenia HTTPS do *.ksef.mf.gov.pl.

Pobieranie faktur stoi / limit

MF limituje pobrania pełnego XML do 64/godz. Wtyczka pobiera metadane przy synchronizacji, a pełen XML dociąga pojedynczo przy otwarciu podglądu — to normalne.

Plan Darmowy — 0/5 mimo wystawionych faktur

Faktury wystawione na koncie testowym (piaskownica MF) celowo nie liczą się do limitu — to nie jest realna sprzedaż. Na koncie produkcyjnym licznik działa normalnie.

Masz pytanie lub problem? Napisz na hello@prostafakturaksef.pl. Klienci Pro mają wsparcie priorytetowe. Zobacz też cennik.