1Jak działa automat

Łańcuch zdarzeń wygląda tak:

1. Zamówienie WooCommerce zmienia status na jeden z zaznaczonych w ustawieniach.
2. Wtyczka sprawdza, czy faktura już istnieje (nie duplikuje) i czy w ogóle ma ją wystawić — dla klienta prywatnego decyduje polityka B2C.
3. Zadanie trafia do kolejki (Action Scheduler, grupa ksef; bez niego — zdarzenie WP-Cron za 5 s), więc klient nie czeka na odpowiedź KSeF przy zakupie.
4. Faktura zostaje wystawiona. To, czy od razu poleci do KSeF, zależy od polityki auto-wysyłki. Gdy polityka nie obejmuje danego nabywcy — dokument zostaje lokalnie ze statusem „Wystawiona lokalnie — niewysłana do KSeF”.
5. Po wysyłce wtyczka odpytuje KSeF o status od razu oraz po 60, 180, 300 i 600 sekundach, a niezależnie od tego co 15 minut chodzi cykliczny cron. Po potwierdzeniu zapisuje numer KSeF i UPO.
6. Jeśli włączona jest auto-wysyłka PDF — klient dostaje fakturę mailem; przy błędzie automatu administrator dostaje powiadomienie.

2Licencja Pro

Automatyczne wystawianie z WooCommerce to funkcja Pro. Bez ważnej licencji wtyczka w ogóle nie rejestruje wyzwalaczy statusów — zmiana statusu zamówienia nic nie uruchamia i nie zostawia żadnej notatki (brak notatki nie oznacza więc, że z licencją jest wszystko w porządku). W wersji darmowej zostaje ręczne wystawienie z metaboksa zamówienia i formularz faktury; w wersji Pro bez aktywnej licencji każdy ekran wtyczki przekierowuje na stronę Licencja, a przycisk w metaboksie kończy się cichym przeładowaniem strony.

Klucz aktywujesz w e-Faktura KSeF → Licencja.

3Konto KSeF i domyślny sprzedawca

Automat musi wiedzieć, z którego konta KSeF wystawiać. Kolejność wyboru: konto przypisane do zamówienia → domyślne konto z ustawień → pierwsze skonfigurowane. Przy jednym koncie nie musisz nic robić; przy kilku (np. kilka NIP-ów) ustaw domyślne:

W tej samej zakładce dodasz konta bankowe (domyślny rachunek podpowiada się na fakturze) oraz zestawy danych kontaktowych (e-mail, telefon, miejsce wystawienia).

4Statusy wyzwalające wystawienie

Wejdź w e-Faktura KSeF → Ustawienia → Ogólne. Pierwsza pozycja to lista statusów zamówienia — zaznacz te, po przejściu w które faktura ma powstać. Można wybrać kilka.

Zalecenie: „W trakcie realizacji (processing)” — status nadawany po opłaceniu zamówienia, więc faktura powstaje razem z e-mailem o zamówieniu. „Zrealizowane (completed)” wybierz, jeśli fakturujesz dopiero po wysyłce towaru.

5Auto-wysyłka do KSeF (co faktycznie leci do MF)

To jest przełącznik oddzielający wystawienie od wysyłki. Wystawienie następuje zawsze, gdy zadziała trigger; wysyłka do KSeF — tylko dla wskazanego typu nabywcy:

• Wyłączone (domyślnie) — faktury powstają lokalnie, do KSeF wysyłasz je ręcznie (metabox zamówienia albo lista faktur). Dobry wariant na start.
• Tylko faktury dla firm (z NIP) — automat wysyła B2B, faktury imienne zostają lokalnie.
• Tylko faktury dla osób fizycznych (B2C — bez NIP).
• Wszystkie faktury — pełna automatyzacja.

Zmiana polityki działa też wstecz w prosty sposób: gdy faktura czeka lokalnie (status „issued”), a zamówienie ponownie wejdzie w wyzwalający status, wtyczka wyśle istniejący dokument — bez duplikatu i bez nowego numeru.

6Polityka dla klientów prywatnych (B2C)

Decyduje, czy w ogóle wystawiać fakturę klientowi bez NIP:

Faktury dla firm (poprawny 10-cyfrowy NIP w zamówieniu) są wystawiane zawsze, niezależnie od tego ustawienia.

7Auto-wysyłka PDF do klienta i powiadomienia administratora

Auto-wysyłka PDF do nabywcy (w tej samej zakładce Ogólne, domyślnie włączona) wysyła po wystawieniu maila z fakturą PDF na adres e-mail z zamówienia. To ona odpowiada za faktury z zamówień; drugi przełącznik — Ustawienia → Email → „Wysyłaj fakturę na email klienta automatycznie po wystawieniu” — dotyczy faktur wystawianych ręcznie z formularza. Wysyłka idzie przez wp_mail(), więc korzysta z Twojego SMTP/Resend, jeśli jest skonfigurowany. Wynik trafia do notatek zamówienia („KSeF: PDF faktury wysłany na …”).

Treść wiadomości ustawisz w Ustawienia → Email: temat i body ze zmiennymi {numer}, {kwota}, {termin}, {ksef}, {data}, {nabywca}, {sprzedawca}. Tam też włączysz powiadomienia dla administratora:

• o błędach synchronizacji i nieudanej automatycznej wysyłce faktury,
• o otwarciu bezpiecznika (circuit breaker),
• o potwierdzeniu faktur (domyślnie wyłączone),
• z limitem częstotliwości (domyślnie 10 minut), żeby nie zalać skrzynki.

Niezależnie od tego wtyczka pilnuje terminu ważności tokenu/certyfikatu KSeF i ostrzega mailem 14, 7 i 1 dzień przed wygaśnięciem.

8Pola faktury w koszyku (skąd bierze się NIP)

Automat rozpoznaje firmę po poprawnym, 10-cyfrowym NIP w zamówieniu. Wtyczka dokłada w koszyku trzy pola:

Dla faktury imiennej klient może zaznaczyć „Faktura na inne dane niż dane zamówienia” i podać imię i nazwisko oraz adres — te dane mają pierwszeństwo przed polami rozliczeniowymi. Dla firm wtyczka Pro uzupełnia nazwę i adres z GUS po numerze NIP.

9Oznaczenia KSeF na produktach

Żeby faktury z automatu były od razu poprawne podatkowo, uzupełnij oznaczenia raz na karcie produktu: Produkty → edycja produktu → Dane produktu → Oznaczenia KSeF (faktura).

• Załącznik 15 (split payment) — pozycja zostanie oznaczona jako objęta obowiązkowym mechanizmem podzielonej płatności (P_12_Zal_15).
• Kod GTU — GTU_01 … GTU_13.
• PKWiU / CN — np. 62.01.11.0 lub 84713000.

Stawki VAT automat bierze z zamówienia (produkty, dostawa i opłaty), więc muszą być poprawnie skonfigurowane w WooCommerce — zakładka Ustawienia → Podatki we wtyczce pokazuje, czy podatki są włączone i czy ceny wprowadzasz netto czy brutto.

10Test przed produkcją

1. W Ustawienia → KSeF ustaw kredencjał na środowisko TEST (token z panelu testowego MF) i kliknij „Testuj połączenie”.
2. Zaznacz status wyzwalający, ustaw politykę wysyłki na „Wszystkie faktury” i zapisz.
3. Złóż zamówienie testowe (raz z NIP-em, raz bez) i przestaw je w wyzwalający status.
4. Otwórz zamówienie: metabox „KSeF — faktura” powinien pokazać numer i status, a notatki zamówienia — całą historię.

Stan całej integracji podejrzysz w e-Faktura KSeF → Monitoring: liczniki faktur wysyłanych/potwierdzonych, stan bezpiecznika (circuit breaker), ostatnie synchronizacje i ostatnie błędy.

Po udanym teście przełącz kredencjał na PRODUKCJA (token produkcyjny) i ponownie kliknij „Testuj połączenie”. Faktury testowe zostają w piaskownicy MF — nie są sprzedażą.

11Ściąga: co się stanie przy jakich ustawieniach

12Rozwiązywanie problemów

Automat nic nie robi

• brak zaznaczonych statusów w Ustawienia → Ogólne,
• brak ważnej licencji Pro — wtedy w zamówieniu nie pojawi się żadna notatka(wyzwalacze nie są w ogóle rejestrowane); stan licencji sprawdzisz w e-Faktura KSeF → Licencja,
• zamówienie ma już fakturę (statusy „wysłana”, „oczekuje”, „potwierdzona” blokują ponowne wystawienie),
• klient prywatny bez żądania faktury przy polityce „na żądanie”.

Faktury powstają, ale nie idą do KSeF

Sprawdź Auto-wysyłkę do KSeF — przy „Wyłączone” to zachowanie oczekiwane. Statusy faktur zobaczysz na liście Faktury sprzedaży; pojedyncze dokumenty wyślesz przyciskiem „Wyślij do KSeF”.

Faktura wystawiona lokalnie po błędzie

Gdy KSeF odrzuci wysyłkę, dokument zostaje lokalnie, a w zamówieniu pojawia się notatka z treścią błędu i mail do administratora. Popraw przyczynę i ponów wysyłkę — numer jest zarezerwowany, więc w numeracji nie powstanie dziura.

Wszystko wisi w „czeka na UPO”

Statusy dociąga cron. Jeśli WordPress ma wyłączony WP-Cron (DISABLE_WP_CRON), ustaw systemowy cron wywołujący wp-cron.php. Doraźnie kliknij „Sprawdź status / pobierz UPO” w metaboksie zamówienia.

Faktury z błędnymi danymi nabywcy

Sprawdź kolejność źródeł: dane potwierdzone na checkoucie → GUS po NIP → pola rozliczeniowe zamówienia. Jeśli klient wpisał nazwisko w polu „Firma”, ale podał NIP, faktura i tak pójdzie na firmę (decyduje NIP).

Chcę zatrzymać automat natychmiast

Odznacz wszystkie statusy w Ustawienia → Ogólne i zapisz — pusta lista oznacza wyłączony automat i wtyczka wraca do trybu wyłącznie ręcznego. Jeśli aktualizujesz z bardzo starej wersji, jednorazowe, historyczne ustawienie pojedynczego wyzwalacza jest przy aktualizacji automatycznie przenoszone na listę statusów i czyszczone — nic nie zadziała „w tle” wbrew temu, co widzisz w ustawieniach.