Faktury WooCommerce – KSeF

Instalacja

Instrukcja instalacji →

Aktywacja subskrypcji

Instrukcja aktywacji →

Aktualizacja

Instrukcja aktualizacji →

Co robi wtyczka

Podstawową funkcją dodatku jest rozszerzenie działania wtyczki Faktury WooCommerce i WordPress lub Faktury WooCommerce PRO o opcję wysyłania faktur do Krajowego Systemu e-Faktur (KSeF).

Po wysłaniu dokumentu w panelu WordPressa dostępne są jego status, numer KSeF oraz komunikaty walidacji lub błędów API. Dokument można wysłać automatycznie, pojedynczo albo masowo.

Wymagania

Dodatek wymaga:

• aktywnej wtyczki Faktury WooCommerce i WordPress w wersji co najmniej 6.2.1 lub
• aktywnej wtyczki Faktury WooCommerce PRO w wersji co najmniej 5.3.1,
• PHP 7.4 lub nowszego,
• WordPress 6.4 lub nowszego,
• WooCommerce 10.8 lub nowszego.

Do uwierzytelniania certyfikatem wymagany jest aktywny moduł OpenSSL oraz stała AUTH_KEY w pliku wp-config.php.

Dodatek wysyła wyłącznie opublikowane dokumenty typu faktura lub korekta. Dokumenty nieopublikowane i proformy nie są wysyłane do KSeF.

1. Ustawienia główne

Po instalacji przejdź do Faktury → Ustawienia → KSeF. W tej zakładce skonfigurujesz połączenie, metodę uwierzytelniania, wysyłkę oraz mapowanie wybranych stawek VAT.

Połączenie

• Środowisko – wybierz środowisko KSeF:
  • Testowe – środowisko testowe pod adresem api-test.ksef.mf.gov.pl.
  • Demo – środowisko demonstracyjne pod adresem api-demo.ksef.mf.gov.pl.
  • Produkcyjne – rzeczywiste środowisko pod adresem api.ksef.mf.gov.pl. Dokumenty wysłane tutaj są dokumentami rzeczywistymi.
• NIP – wpisz NIP podmiotu, którego dotyczy certyfikat lub token. Ten sam numer jest dostępny w ustawieniach ogólnych Faktur WooCommerce.
• Metoda uwierzytelniania – wybierz Certyfikat KSeF albo Token KSeF. Dla nowych połączeń zalecane jest uwierzytelnianie certyfikatem. Działanie połączenia tokenem zależy również od jego ważności, uprawnień i obsługi tej metody przez KSeF.

Kliknij Zapisz zmiany. Wtyczka sprawdzi połączenie z wybranym środowiskiem i pokaże jego status.

2. Uwierzytelnianie certyfikatem

Certyfikat KSeF jest alternatywą dla tokena API. Wtyczka używa certyfikatu i klucza prywatnego do podpisania żądania uwierzytelnienia, a następnie nawiązuje sesję z API KSeF.

Co przygotować?

• certyfikat w pliku .crt,
• odpowiadający mu klucz prywatny w pliku .key,
• hasło do pliku, jeśli certyfikat lub klucz prywatny jest zaszyfrowany,
• prawidłowy NIP podmiotu,
• środowisko KSeF zgodne z wystawionym certyfikatem.

Certyfikat i klucz prywatny muszą tworzyć parę. Wtyczka sprawdza, czy certyfikat jest prawidłowym certyfikatem X.509, czy może odczytać klucz oraz czy oba pliki do siebie pasują.

Konfiguracja

1. W polu Metoda uwierzytelniania wybierz Certyfikat KSeF.
2. W polu Certyfikat wgraj plik .crt.
3. W polu Klucz prywatny wgraj plik .key pobrany razem z certyfikatem.
4. W polu Hasło wpisz hasło, jeśli pliki są zaszyfrowane.
5. Sprawdź środowisko i NIP.
6. Kliknij Zapisz zmiany.

Jeśli chcesz zachować zapisane hasło przy wymianie plików, pozostaw pole Hasło puste. Wtyczka zapisuje pliki oraz hasło w postaci zaszyfrowanej. Do szyfrowania wykorzystywana jest stała AUTH_KEY z pliku wp-config.php.

Po zapisaniu zobaczysz nazwę bieżącego pliku oraz datę ważności certyfikatu. Wgraj jednocześnie certyfikat i odpowiadający mu klucz prywatny. Wgranie tylko jednego pliku spowoduje komunikat błędu.

Brak stałej AUTH_KEY

Jeśli w pliku wp-config.php brakuje stałej AUTH_KEY, pola certyfikatu są zablokowane. Dodaj unikalną wartość AUTH_KEY zgodnie z konfiguracją WordPressa, a następnie wróć do ustawień KSeF.

3. Token

Token KSeF jest alternatywną metodą uwierzytelniania połączenia.

• Token – wklej wartość tokena wygenerowanego w oficjalnej aplikacji KSeF. Token musi pochodzić z tego samego środowiska, które wybrano w polu Środowisko.
• Status połączenia – po zapisaniu ustawień wtyczka sprawdza NIP, token i wybrane środowisko. Jeśli połączenie nie zostanie nawiązane, sprawdź te trzy wartości.

Token traktuj jak dane logowania. Nie udostępniaj go osobom nieuprawnionym. Jeśli podejrzewasz naruszenie bezpieczeństwa, wygeneruj nowy token i usuń poprzedni.

4. Automatyczna wysyłka

W sekcji Wysyłka znajdziesz opcję Automatyczna wysyłka.

• Włączona: dokument zostanie wysłany do KSeF po jego wystawieniu.
• Wyłączona: dokument pozostanie w panelu i będzie wymagał ręcznego kliknięcia Wyślij do KSeF.

Jeśli automatyczna wysyłka zakończy się błędem sieciowym, wtyczka ponawia próbę co 8 godzin. Ponowienia dotyczą opublikowanych dokumentów, które nie zostały zaakceptowane przez KSeF i dla których zapisano błąd sieciowy. Błędy danych dokumentu wymagają ręcznej poprawy.

5. Faktury zagraniczne

Opcja Wysyłka transgraniczna decyduje o tym, czy wtyczka może wysyłać dokumenty dla klientów spoza Polski.

• Włączona: wtyczka może wysyłać faktury zagraniczne, jeśli dokument przejdzie pozostałe walidacje.
• Wyłączona: dokument z krajem klienta innym niż Polska nie zostanie wysłany.

Opcja jest domyślnie włączona. Obsługa OSS, walut obcych i przeliczeń zależy od funkcji oraz konfiguracji Faktur WooCommerce PRO. Mapowanie transakcji unijnych korzysta z walidacji VIES, jeśli jest włączona w Fakturach WooCommerce.

6. Stawki podatkowe

Wtyczka mapuje stawki VAT skonfigurowane w WooCommerce na oznaczenia wymagane przez KSeF.

• Stawka ZW – wybierz stawkę używaną dla sprzedaży zwolnionej z VAT. Lista jest pobierana z WooCommerce → Ustawienia → Podatek. Jeśli nie używasz tej stawki, wybierz Nie używam stawki ZW.
• Zwolnienie – wpisz domyślną podstawę zwolnienia, np. „Art. 113 ust. 1 ustawy o VAT”. Wartość można zmienić podczas edycji konkretnej faktury, jeśli zawiera ona stawkę ZW.
• Stawka odwrotnego obciążenia – wybierz stawkę WooCommerce używaną dla oznaczenia OO. Jeśli jej nie używasz, wybierz Nie używam stawki odwrotnego obciążenia. Stawka ZW i stawka OO nie mogą być takie same.

Pozostałe stawki 0% oraz typy NP, WDT, EX i KR są mapowane automatycznie na podstawie danych dokumentu i zamówienia.

Ustawienia na konkretnej fakturze

W metaboxie KSeF na ekranie edycji dokumentu możesz zmienić:

• Podstawę zwolnienia – wartość używaną na tej fakturze.
• Rodzaj stawki 0% – wybierz Automatycznie, 0% KR, 0% WDT, 0% EX, NP I albo NP II.

Opcja rodzaju stawki 0% pojawia się, gdy dokument zawiera odpowiednią stawkę.

Ręczna rejestracja faktur w KSeF

Faktury i korekty możesz wysłać do KSeF na trzy sposoby:

• Automatycznie – po włączeniu opcji automatycznej wysyłki.
• Ręcznie, masowo – za pomocą akcji Wyślij do KSeF na liście Faktury → Wszystkie.
• Ręcznie, pojedynczo – przez przycisk Wyślij do KSeF w metaboxie KSeF na ekranie edycji opublikowanego dokumentu.

Zapisz zmiany w dokumencie przed wysyłką. Przyciski wysyłki i pobierania XML są zablokowane, gdy dokument ma niezapisane zmiany.

Korekty danych nabywcy

Od wersji 2.5.4 dodatek uwzględnia wcześniejsze dane nabywcy w XML korekty, jeśli zmieniasz jego nazwę lub adres i zachowujesz identyfikator podatkowy.

Aby utworzyć dokument, skorzystaj z instrukcji wystawiania faktur korygujących. Popraw dane nabywcy na korekcie i opisz przyczynę w polu Uwagi. Jeśli zmieniasz wyłącznie dane nabywcy, pozostaw wartości pozycji bez zmian i sprawdź podsumowanie oraz rozliczenie płatności. Opublikuj dokument i wyślij go do KSeF zgodnie z wybraną metodą wysyłki.

Dodatek automatycznie zapisuje w XML:

• Podmiot2 — aktualne dane nabywcy z korekty,
• Podmiot2K — wcześniejsze dane nabywcy z dokumentu korygowanego.

Sekcja Podmiot2K jest dodawana tylko wtedy, gdy dane nabywcy przekazywane w XML różnią się od danych dokumentu korygowanego. Nie musisz uzupełniać jej ręcznie.

Zmiana NIP lub innego identyfikatora podatkowego

1. Wystaw korektę do zera, zachowując dane dotychczasowego nabywcy.
2. Wyślij korektę do KSeF.
3. Wystaw nową fakturę z prawidłowymi danymi nabywcy i wyślij ją do KSeF.

Sama zmiana formatowania tego samego NIP, np. usunięcie spacji lub myślników, nie jest traktowana jako zmiana identyfikatora.

Status dokumentu i numer KSeF

Na liście faktur dostępna jest kolumna Numer KSeF. W metaboxie KSeF zobaczysz również szczegóły błędów.

• Gotowe do wysłania – dokument przeszedł wstępną walidację, a połączenie jest uwierzytelnione.
• Oczekiwanie na odpowiedź – wtyczka oczekuje na potwierdzenie statusu przez KSeF.
• Wysłano do KSeF – dokument został zaakceptowany; wtyczka pokazuje numer KSeF.
• Nie można wysłać dokumentu – popraw dane wskazane w komunikacie.
• Brak autoryzacji – sprawdź środowisko, NIP i wybraną metodę uwierzytelniania.

Jeżeli dokument został wcześniej zarejestrowany w KSeF, wtyczka może rozpoznać duplikat i powiązać go z istniejącym numerem KSeF.

Pobieranie XML faktury do weryfikacji

Możesz pobrać XML generowany dla dokumentu, aby sprawdzić dane przed wysyłką lub zdiagnozować błąd walidacji.

Gdzie znaleźć przycisk pobierania XML?

1. Przejdź do listy Faktury → Wszystkie i otwórz opublikowany dokument.
2. W ekranie edycji znajdź metabox KSeF.
3. Kliknij Pobierz XML.

Przycisk jest dostępny w metaboxie dla dokumentów, które nie zostały jeszcze pomyślnie zarejestrowane w KSeF. Jeśli zmienisz dane faktury lub pola KSeF, zapisz dokument przed ponownym pobraniem XML.

Kod QR na fakturze po wysyłce do KSeF

Po poprawnym przyjęciu dokumentu przez KSeF wtyczka generuje kod QR weryfikujący dokument i pokazuje numer KSeF.

Kiedy pojawia się kod QR?
Kod QR pojawia się dopiero po poprawnym wysłaniu dokumentu do KSeF. Nie jest wyświetlany dla dokumentu niewysłanego lub zakończonego błędem.

Gdzie widoczny jest kod QR?
Kod QR jest widoczny w metaboxie KSeF. Aby wyświetlić go na fakturze, dodaj do szablonu blok Kod QR KSeF w edytorze blokowym Flexible Invoices albo użyj znacznika {KSeFDocumentQRCode} w miejscu obsługiwanym przez edytor dokumentu.

Generowanie tokena autoryzacyjnego w KSeF

Token autoryzacyjny w KSeF służy do łączenia zewnętrznych programów z kontem podatnika w KSeF. Użyj tokena dla KSeF 2.0 z właściwego środowiska. Tokeny z KSeF 1.0 nie działają w KSeF 2.0.

Wejście do systemu KSeF

1. Otwórz stronę logowania do Krajowego Systemu e-Faktur: https://ap.ksef.mf.gov.pl/web/.
2. Zaloguj się dostępną metodą uwierzytelniania.

Przejście do sekcji tokenów

1. Po zalogowaniu odszukaj Tokeny → Generuj Token.
2. W polu Nazwa tokena wpisz czytelną nazwę, np. nazwę sklepu.
3. Wybierz uprawnienia powiązane z tokenem, w szczególności wystawianie faktur. Zakres uprawnień musi umożliwiać operacje wykonywane przez integrację.

Utworzenie i zapis tokena

1. Zatwierdź ustawienia, aby wygenerować token.
2. Skopiuj jego wartość i zapisz ją przed opuszczeniem strony — token jest wyświetlany tylko raz. Wklej go do pola Token w ustawieniach KSeF i zapisz zmiany.

Najczęstsze problemy

Nie można wgrać certyfikatu

Sprawdź, czy w wp-config.php istnieje niepusta stała AUTH_KEY. Wgraj jednocześnie certyfikat .crt i klucz prywatny .key.

Certyfikat i klucz prywatny nie pasują do siebie

Użyj klucza prywatnego pobranego razem z certyfikatem. Jeśli klucz jest szyfrowany, wpisz poprawne hasło.

Nie udało się nawiązać połączenia

Sprawdź wybrane środowisko, NIP, ważność certyfikatu oraz zgodność tokena lub certyfikatu z wybranym środowiskiem. Jeśli dane są poprawne, API KSeF może być chwilowo niedostępne.

Dokument nie ma przycisku wysyłki

Upewnij się, że dokument jest opublikowaną fakturą lub korektą, połączenie jest uwierzytelnione i dokument nie ma niezapisanych zmian.

Nie można wygenerować XML korekty po zmianie NIP

Porównaj identyfikator podatkowy nabywcy na korekcie i na dokumencie korygowanym. Dodatek blokuje generowanie XML, jeśli identyfikator się zmienił, został dodany lub usunięty. Wystaw korektę do zera z dotychczasowymi danymi nabywcy, a następnie nową fakturę z prawidłowymi danymi. Ponowienie wysyłki bez zmiany dokumentów nie rozwiąże tego błędu.

Opcje dla zaawansowanych użytkowników

Poniższe możliwości wymagają znajomości PHP i modyfikowania kodu motywu lub własnej wtyczki.

Dodawanie do faktury danych z sekcji „odbiorca”

Jeśli oprócz danych klienta dodajesz do faktury dane odbiorcy, filtr fiksef_xmldata_entity3_role pozwala zmienić rolę podmiotu 3 w XML. Domyślna wartość to 2. Przykład:

add_filter( 'fiksef_xmldata_entity3_role', function ( $default, $document ) { return '6'; }, 10, 2 );

Szczegóły dostępnych ról znajdziesz w broszurze dotyczącej struktury FA(3), w tabeli 14.

Inne filtry

Wtyczka udostępnia również filtry fiksef_xml_data, fiksef_xmldata_footer, fiksef_datamapper_payment_method, fiksef_download_xml_filename, fiksef_services_initial_validation_reasons oraz fiksef_reconciliation_job_query_args. Są przeznaczone do niestandardowych integracji i nie są wymagane przy standardowej konfiguracji.