Integracja z KSeF

Moduł KSeF przechowuje ustawienia połączenia z Krajowym Systemem e-Faktur. Wysyłka faktur jest dziś niemożliwa, na każdym ustawieniu. Klient API w tej wersji został napisany pod KSeF 1.0, a ten system już nie istnieje: środowisko testowe KSeF 1.0 zostało wyłączone 1 września 2025, a produkcja KSeF 1.0 przestała działać 1 lutego 2026 i została wyłączona na stałe razem ze starym Modułem Certyfikatów i Uprawnień. Od 1 lutego 2026 obowiązuje wyłącznie KSeF 2.0. Ta strona opisuje to, co wtyczka faktycznie robi dzisiaj.

Czym jest KSeF

KSeF to platforma Ministerstwa Finansów do wystawiania, przechowywania i odbierania faktur ustrukturyzowanych w formacie XML. Polscy sprzedawcy składają tam faktury w schemacie FA zamiast wymieniać się dokumentami PDF. Od 1 lutego 2026 jedyną działającą wersją systemu jest KSeF 2.0 i korzystanie z niego jest obowiązkowe.

Co robi ta wersja

Funkcja	Stan
Ustawienia połączenia z KSeF i zapis danych dostępowych	Dostępne
Oznaczanie zamówień wymagających KSeF (wtyczka FREE)	Dostępne
Wysyłka faktury do KSeF, w jakikolwiek sposób	Niemożliwa, klient sięga po wyłączone hosty KSeF 1.0
Przycisk, akcja masowa lub zadanie cykliczne, które wysyła	Brak w tej wersji
Statusy i numery referencyjne zwracane przez Ministerstwo	Brak, żadne żądanie nie dociera do serwera
Pobranie XML w schemacie FA z panelu	Brak w tej wersji
Pobranie faktury jako UBL / PEPPOL	Dostępne, działa niezależnie od KSeF
Raport JPK_FA	Dostępny, działa niezależnie od KSeF

Dlaczego wysyłka nie działa

Klient API zna dokładnie dwa adresy, https://ksef-test.mf.gov.pl/api oraz https://ksef.mf.gov.pl/api, i jeden endpoint sesji, /online/Session/InitSigned. To kształt KSeF 1.0. Obie te bramki zostały wyłączone przez Ministerstwo Finansów, więc żądania kończą się błędem już na poziomie sieci. Nie ma ustawienia, które to obejdzie, i nie ma środowiska testowego, do którego można się w ten sposób dostać.

POST /wp-json/polski-pro/v1/invoices/{id}/ksef nadal istnieje, wymaga uprawnienia manage_woocommerce i kolejkuje zadanie w Action Scheduler. Zadanie się wykona i zakończy niepowodzeniem, bo host, do którego próbuje się połączyć, nie odpowiada. Ta trasa to jedyne wejście: nie wywołuje jej żaden ekran w panelu, przycisk, akcja masowa, zmiana statusu zamówienia ani zadanie cykliczne.

KSeF 2.0 to inny interfejs, nie inna wersja tego samego. Ma inną bazę adresową (https://api-test.ksef.mf.gov.pl/v2 dla środowiska testowego i https://api.ksef.mf.gov.pl/v2 dla produkcji), inne uwierzytelnianie (POST /auth/challenge, następnie POST /auth/ksef-token z tokenem zaszyfrowanym razem ze znacznikiem czasu wyzwania, następnie POST /auth/token/redeem po token dostępowy) oraz inną wysyłkę (sesja otwierana przez POST /sessions/online z kluczem AES-256 zaszyfrowanym kluczem publicznym Ministerstwa, a sama faktura wysyłana już zaszyfrowana pod /sessions/online/{referenceNumber}/invoices, wraz z sumami SHA-256 dokumentu jawnego i zaszyfrowanego). Przepisanie modułu pod KSeF 2.0 jest zaplanowane. Nie podajemy terminu.

Do tego czasu traktuj ten moduł jako miejsce na przygotowanie danych dostępowych, a nie jako kanał składania faktur. Faktury do KSeF trzeba dziś złożyć poza wtyczką.

Konfiguracja

Dla pól KSeF nie ma wyrenderowanego ekranu ustawień. Wartości leżą w opcji polski_pro_ksef i zapisuje się je przez trasę REST ustawień PRO, tak samo jak dane dostępowe przewoźników:

PUT /wp-json/polski-pro/v1/settings
Content-Type: application/json
X-WP-Nonce: {nonce wp_rest}

{
  "ksef": {
    "enabled": true,
    "environment": "test",
    "api_token": "..."
  }
}

Trasa wymaga uprawnienia manage_woocommerce. Zapisany payload zastępuje całą opcję polski_pro_ksef, więc wyślij w tym samym żądaniu wszystkie klucze, które chcesz zachować. Zapis ustawień działa, ale nie zmienia faktu opisanego wyżej: żadna wartość nie sprawi, że wysyłka zadziała.

Ustawienia połączenia

Klucz	Opis
`enabled`	Oznacza moduł jako aktywny
`environment`	Zapisywane jako `test` albo `production`. Klient API tego nie czyta, a adresy, które zna, i tak są wyłączone.
`api_token`	Token autoryzacyjny KSeF. Przechowywany, ale nieużywany przez nic, co dziś działa.
`auto_send`	Zapisywane, ale nic tego nie czyta. Włączenie tej opcji niczego nie wysyła.

NIP wystawcy nie należy do tej opcji. Pochodzi z danych sprzedawcy w ustawieniach Faktury i trafia na faktury, które wtyczka już wystawia.

Token API

Zostaw api_token pusty do czasu przepisania modułu. Nie ma tokenu, który by tu zadziałał: token pasujący do tego kodu wydawał stary Moduł Certyfikatów i Uprawnień, wyłączony razem z KSeF 1.0 w lutym 2026, a token z KSeF 2.0 trafiłby do klienta, który mówi innym protokołem i do nieistniejącego hosta.

Kroki generowania tokenu były tu wcześniej opisane i zostały usunięte celowo, żeby nie wysyłać nikogo po poświadczenie do systemu, którego nie ma.

Uwaga na termin po stronie Ministerstwa: token jako metoda uwierzytelniania działa do 31 grudnia 2026. Od 1 stycznia 2027 jedynym sposobem uwierzytelnienia w KSeF będzie certyfikat KSeF.

Wykrywanie KSeF we wtyczce FREE

Wtyczka FREE Polski ma osobny moduł Gotowość KSeF w Polski > Moduły. Nigdy nie łączy się z KSeF i nie dotyczą go opisane wyżej problemy. Pokazuje, które zamówienia wymagają faktury ustrukturyzowanej, żebyś wiedział, co złożyć w KSeF innym kanałem.

Po włączeniu modułu:

każde zamówienie złożone w checkoucie jest sprawdzane pod kątem NIP nabywcy, a meta zamówienia _polski_ksef_required przyjmuje wartość yes lub no
na liście zamówień pojawia się kolumna KSeF z oznaczeniem przy wykrytych zamówieniach
na ekranie zamówienia, pod adresem rozliczeniowym, widoczna jest linia KSeF czytająca meta _polski_ksef_status, która pozostaje na pending, dopóki nie zapisze jej Twój własny kod

Jedyne ustawienie modułu, Automatycznie wykrywaj na podstawie NIP, steruje opisanym wyżej wykrywaniem.

Punkty rozszerzeń

polski/ksef/is_required filtruje wynik wykrywania przed zapisem.

add_filter('polski/ksef/is_required', function (bool $required, WC_Order $order): bool {
    // Nie oznaczaj zamówień poniżej 100 PLN.
    if ($order->get_total() < 100) {
        return false;
    }

    return $required;
}, 10, 2);

polski/ksef/invoice_ready uruchamia się z obiektem WC_Order zaraz po oznaczeniu zamówienia jako wymagającego faktury KSeF. To hook do wykorzystania, jeśli składasz faktury przez własny system księgowy albo własną integrację z KSeF 2.0.

Jak dziś wyciągnąć dane faktury

Wysyłka do KSeF nie działa, ale PRO nadal udostępnia dokumenty faktur w formacie maszynowym. Te dwie funkcje nie korzystają z API KSeF i działają normalnie:

meta box PEPPOL / UBL (XML) na ekranie zamówienia pobiera pojedynczą fakturę jako plik UBL zgodny z EN 16931 / PEPPOL
strona Raport JPK_FA w panelu buduje XML JPK_FA(3) dla wszystkich faktur wystawionych w wybranym zakresie dat

Żadne z tych rozwiązań nie jest złożeniem faktury w KSeF, ale oba pokrywają typowy przypadek przeniesienia danych faktur do programu księgowego lub narzędzia, które składa dokumenty za Ciebie. Zobacz Eksporty księgowe.

Powiązane zasoby

Ta strona ma wyłącznie charakter informacyjny i nie stanowi porady prawnej. Przed wdrożeniem skonsultuj się z prawnikiem. Polski for WooCommerce jest oprogramowaniem open source (GPLv2) dostarczanym bez gwarancji.