Fakturownia WooCommerce

Najważniejsze funkcje wtyczki

• Dokumenty z zamówień – faktury VAT, proformy, także bez VAT, faktury bez VAT, rachunki, paragony, faktury walutowe i korekty faktur.
• Wystawianie ręczne lub automatyczne – wystaw dokument w edycji zamówienia albo wybierz statusy zamówienia uruchamiające automatyzację.
• Dane nabywcy i odbiorcy – wtyczka dodaje pola fakturowe do klasycznego i blokowego formularza zamówienia, w tym osobny NIP wysyłki.
• Wysyłka dokumentów e-mailem – wiadomość ze sklepu zawiera link do pobrania PDF-u i załącznik. Automatyczna wysyłka jest domyślnie planowana po 5 minutach.
• Dokumenty w Moim koncie – klient może pobrać dokument ze szczegółów zamówienia.
• Walidacja NIP i VIES – sprawdzanie formatu numeru, polskiej sumy kontrolnej i numerów VAT w rejestrze VIES.
• Sprzedaż zagraniczna – rozróżnianie OSS, WDT, eksportu towarów i odwrotnego obciążenia na podstawie danych zamówienia.
• Oznaczenia dokumentów – GTU, PKWiU, oznaczenia procedur i ryczałt.
• Synchronizacja produktów – stany magazynowe i ceny pomiędzy WooCommerce a Fakturownią.
• Automatyczne korekty – opcjonalne wystawianie korekt po zwrotach częściowych i pełnych.

Instalacja

Instrukcja instalacji →

Aktywacja subskrypcji

Aktywacja subskrypcji →

Aktualizacja

Instrukcja aktualizacji →

Konto w Fakturowni

Korzystanie z wtyczki wymaga posiadania konta w serwisie Fakturownia, jeśli jeszcze nie masz konta, zarejestruj się przez nasz link, aby otrzymać 20% rabatu na opłacenie konta!

Ważne informacje

• Wymagania deklarowane przez wtyczkę: WordPress 6.2 lub nowszy, WooCommerce 8.1 lub nowszy i PHP 7.4 lub nowszy.
• Wtyczka deklaruje zgodność z HPOS i obsługuje klasyczny oraz blokowy formularz zamówienia.
• Do połączenia potrzebujesz konta Fakturowni i tokenu API z dostępem do używanej firmy lub działu. Przy synchronizacji magazynowej skonfiguruj także magazyn i webhook.
• Aby pokazywał się podpis wystawiającego, dodaj osobę kontaktową w ustawieniach firmy lub działu w Fakturowni.
• Wtyczka uwzględnia ustawienie WooCommerce Ceny wpisywane z podatkiem. Przy rozbieżnościach porównaj sposób naliczania i zaokrąglania podatków w obu systemach. Zmiana sposobu wprowadzania cen wymaga odpowiedniego przeliczenia cen produktów.
• Wtyczka pomija pozycje, których cena po zaokrągleniu do dwóch miejsc wynosi zero. Jeśli nie pozostanie żadna pozycja o niezerowej wartości, dokument nie zostanie wystawiony.

Konfiguracja podatków w WooCommerce

Dla firm zwolnionych z VAT

Jeśli twoja firma nie jest płatnikiem VAT, wyłącz podatki w swoim sklepie.

Faktura bez VAT

Przy wyłączonych podatkach przejdź do zakładki Wystawianie faktur bez VAT i w polu Typ dokumentu wybierz Faktury bez VAT. Ustaw tryb wystawiania, statusy zamówienia i wysyłkę wiadomości. Faktura bez VAT otrzymuje stawkę zw.

Rachunek

W polu Typ dokumentu wybierz Rachunki. Skonfiguruj osobno sposób wystawiania rachunków, statusy zamówienia i automatyczną wysyłkę.

W przypadku faktur bez VAT uzupełnij pole Podstawa prawna zwolnienia. Wtyczka przekazuje je do dedykowanego pola podstawy zwolnienia w Fakturowni. Uwagi do dokumentu możesz wykorzystać na dodatkowe informacje.

Dla firm będących płatnikami VAT

Skonfiguruj podatki w swoim sklepie zgodnie z naszą dokumentacją. Wtyczka będzie wystawiać faktury.

Konfiguracja wtyczki

Aby skonfigurować wtyczkę, odwiedź menu w panelu admina WordPressa: WooCommerce → Ustawienia → Integracja → Fakturownia:

Ustawienia są podzielone na zakładki: Autoryzacja, Wystawianie paragonów, Wystawianie faktur lub Wystawianie faktur bez VAT (zależnie od włączenia podatków), Magazyn i Tryb debugowania. Kliknięcie Zapisz zmiany zapisuje ustawienia ze wszystkich zakładek integracji.

Autoryzacja

Przejdź do panelu Fakturowni, wybierz z menu opcję Ustawienia → Ustawienia konta → Integracja, a następnie skopiuj Kod autoryzacyjny API:

Skopiowany kod wklej do pola o nazwie API Token:

API Token – indywidualny kod autoryzacyjny, który pozwoli zintegrować twój sklep z systemem Fakturownia przy użyciu naszej wtyczki. Znajdziesz go w panelu Fakturowni: Ustawienia → Ustawienia konta → Integracja

Domena – pierwszy człon adresu URL wyświetlony w pasku adresu twojej przeglądarki, po zalogowaniu do systemu Fakturownia:

ID Firmy – pole opcjonalne. Domyślnie faktura jest wystawiana na firmę ustawioną jako główną w ustawieniach Fakturowni (jeśli jest dodanych więcej firm/działów):

Jeśli do twojego konta Fakturowni jest przypisanych więcej firm/działów, możesz wybrać konkretny dział/firmę, z którego danych będzie korzystać wtyczka podczas wystawiania dokumentów. W tym celu odnajdź dział/firmę na liście w Fakturowni i skopiuj ID z jej adresu URL, zgodnie z obrazkiem poglądowym:

Skopiowane ID wklej w pole ID Firmy i zapisz zmiany.

W polu Domena podaj samą nazwę konta, np. wpdesk dla adresu https://wpdesk.fakturownia.pl/. Nie wpisuj protokołu ani końcówki .fakturownia.pl.

Integracja z KSeF

Wtyczka wystawia dokument w Fakturowni. Połączenie z Krajowym Systemem e-Faktur, uprawnienia i zasady wysyłki do KSeF konfigurujesz w serwisie Fakturownia. W ustawieniach wtyczki nie ma osobnej zakładki KSeF.

Sprawdź poprawność danych przekazywanych ze sklepu: NIP-u nabywcy, danych odbiorcy, stawek podatku i podstawy zwolnienia, jeśli dokument zawiera pozycje ze stawką ZW. Utworzenie dokumentu w Fakturowni nie potwierdza jego przyjęcia przez KSeF. Status wysyłki sprawdzaj w Fakturowni.

Konfiguracja KSeF w Fakturowni →

Wystawianie paragonów

• Ręcznie – będziesz miał możliwość manualnego wystawienia paragonu w edycji zamówienia,
• Automatycznie – paragony będą wystawiane automatycznie w momencie osiągnięcia przez zamówienie określonego statusu,
• Automatycznie, jeśli kupujący nie chce faktury / rachunku – paragony będą wystawiane automatycznie w momencie osiągnięcia przez zamówienie określonego statusu, ale tylko pod warunkiem, że kupujący nie zaznaczy opcji “Chcę otrzymać fakturę” / “Chcę otrzymać rachunek” (więcej informacji poniżej).

Automatycznie wysyłaj paragon po wystawieniu – jeśli chcesz aby po wystawieniu paragonu był on automatycznie przesyłany na adres e-mail kupującego, zaznacz to pole.

Parametry paragonu

Termin płatności dla paragonów – określ termin płatności, który zostanie zapisany na paragonie wysyłkowym. Domyślna wartość to 7 dni. Przy ręcznym wystawianiu termin możesz zmienić w parametrach paragonu.

Język paragonów – jeśli obsługujesz zamówienia z zagranicy, wybierz język:

• Język kraju klienta, jeżeli dostępny lub angielski – wtyczka przekazuje kod języka na podstawie kraju w adresie rozliczeniowym. Jeżeli potrzebujesz stałego języka paragonu, wybierz jedną z poniższych opcji,
• Zawsze angielski,
• Zawsze polski.

Uwagi do dokumentu – treść która znajdzie się na paragonie w polu Uwagi. Możesz w tym miejscu użyć shortcode [order_number]. Na dokumencie zostanie zastąpiony numerem zamówienia.

Wystawianie faktur

Wystawianie faktur – wybierz tryb wystawiania faktur. Do wyboru są cztery warianty:

• Ręcznie – faktury dla zamówień będziesz mógł wystawić manualnie, za pomocą metaboksa na ekranie edycji zamówienia. Dokumenty nie będą wystawiane automatycznie.
• Pytaj kupującego i nie wystawiaj automatycznie – w formularzu zamówienia pojawi się nowe pole typu checkbox – “Chcę otrzymać fakturę VAT”. Kupujący będzie miał możliwość zaznaczenia tego pola, jeśli chciałby otrzymać dokument sprzedaży. Dokumenty nie będą wystawiane automatycznie.
• Pytaj kupującego i wystawiaj automatycznie – w formularzu zamówienia pojawi się nowe pole typu checkbox – “Chcę otrzymać fakturę VAT”. Kupujący będzie miał możliwość zaznaczenia tego pola, jeśli chciałby otrzymać dokument sprzedaży. Dokumenty będą wystawiane automatycznie w momencie spełnienia dwóch warunków: jeżeli kupujący zaznaczy to pole oraz jeżeli zamówienie osiągnie status wybrany w polu Status zamówienia.
• Zawsze, automatycznie – faktury będą wystawiane automatycznie w momencie kiedy zamówienie osiągnie status wybrany w polu Status zamówienia.

Wtyczka samodzielnie obsługuje pola fakturowe i ich widoczność. Flexible Checkout Fields możesz wykorzystać do dodatkowego dopasowania klasycznego formularza. Zachowaj nazwy pól opisane w części dla zaawansowanych.

Status zamówienia – wybierz status lub statusy zamówienia, przy którym faktura zostanie automatycznie wystawiona. Jest to pole typu multi-select, więc masz możliwość wyboru kilku statusów.

Automatycznie wysyłaj faktury po wystawieniu – jeśli chcesz aby po wystawieniu faktury była ona automatycznie przesyłana na adres e-mail kupującego, zaznacz to pole.

Automatycznie wystawiaj korekty po zwrocie – zaznacz, aby zwroty WooCommerce uruchamiały wystawianie korekt faktur. Domyślnie opcja jest wyłączona. Sprawdź warunki wystawiania korekt →

Automatyczna wysyłka dokumentu jest domyślnie planowana po 5 minutach. Zasady wysyłki →

Parametry faktury

Klasa podatkowa dla stawki ZW – wybierz klasę podatkową produktów, które mają być oznaczane jako zwolnione z VAT na fakturze.

PKWiU – wpisz nazwę atrybutu produktu, z którego wtyczka pobierze kod PKWiU. Pole jest dostępne także przy fakturach bez VAT, a jego działanie nie jest ograniczone do stawki ZW. W serwisie Fakturownia.pl, w Ustawienia → Konfiguracja → Faktury i Dokumenty, wśród pozycji faktury odnajdź „Dodatkowe pole”, wybierz „PKWiU”, a następnie zaznacz „Zawsze umieszczaj na fakturze”.

Podstawa prawna zwolnienia – wpisz podstawę zwolnienia właściwą dla wystawianego dokumentu, np. numer artykułu. Wtyczka przekazuje wartość do pola exempt_tax_kind, gdy faktura zawiera stawkę ZW, oraz dla faktur bez VAT.

Poprawność numeru NIP – włącz sprawdzanie poprawności NIP na stronie zamówienia.

Termin płatności dla faktur wysyłkowych – określ termin płatności, który zostanie zapisany na fakturze wysyłkowej. Ta opcja ma zastosowanie, jeśli kupujący wybierze metodę płatności Za pobraniem. Domyślnie ma wartość 7 dni.

Miejsce wystawienia – wpisz miejscowość, która ma być widoczna na dokumencie jako miejsce jego wystawienia.

Język faktur – jeśli obsługujesz zamówienia z zagranicy, wybierz język:

• język kraju klienta, jeżeli dostępny lub angielski – język faktury będzie odpowiadał krajowi kupującego, jeśli jest obsługiwany (pl, en, en-GB, ar, cn, cz, de, es, et, fa, fr, hu, hr, it, nl, ru, sk, sl, tr). Jeśli nie będzie obsługiwany, zostanie zastosowany język angielski
• Zawsze angielski
• Zawsze polski

Uwagi do dokumentu – treść, która znajdzie się na fakturze w polu Uwagi. Możesz w tym miejscu użyć shortcode [order_number]. Na dokumencie zostanie zastąpiony numerem zamówienia.

Parametry faktury proforma

Termin płatności dla faktur proforma – określ termin płatności, który zostanie zapisany na fakturze proforma.

Status zamówienia – w przypadku automatycznego wystawiania faktur proforma, wybierz status zamówienia, przy którym proforma zostanie automatycznie wystawiona.

Automatycznie wysyłaj faktury proformy po wystawieniu – zaznacz, jeśli chcesz aby faktury proforma były wysyłane automatycznie po wystawieniu.

Obsługa OSS (dawniej VAT MOSS)

Ustawienia znajdziesz w zakładce Wystawianie faktur, w grupie Wsparcie dla OSS. Najpierw skonfiguruj klasy i stawki podatkowe WooCommerce dla krajów sprzedaży.

Walidacja VIES – włącza sprawdzanie numerów VAT z krajów UE w rejestrze VIES. Opcja jest dostępna przy włączonych podatkach. Weryfikacja VIES uruchamia także sprawdzanie formatu numeru i polskiej sumy kontrolnej.

Wybierz co robić, jeśli walidacja się nie powiedzie – wybierz reakcję na niepoprawny wynik lub niedostępność VIES:

• Nie pozwalaj na złożenie zamówienia i wyświetl komunikat błędu – klient musi poprawić numer albo potwierdzić jego poprawność w dodatkowym polu, jeśli wtyczka wyświetli takie potwierdzenie.
• Pozwól na złożenie zamówienia ale nie usuwaj VAT – zamówienie może zostać złożone, lecz błąd VIES nie daje zwolnienia z VAT.
• Pozwól na złożenie zamówienia i usuń VAT – błąd VIES nie blokuje zamówienia i może pozwolić na zwolnienie, jeżeli spełnione są pozostałe warunki opisane poniżej.

Błędny format lub niepoprawna suma kontrolna nie są pomijane przez powyższe ustawienia. Potwierdzenie klienta jest deklaracją, a nie pozytywnym wynikiem sprawdzenia w rejestrze.

Stawki VAT dla OSS – wskaż klasy podatkowe WooCommerce używane do obsługi OSS. Wybór klasy nie tworzy stawek dla poszczególnych krajów.

Pozwól na deklarowanie poprawności adresu – w transakcjach B2C z produktami z klas OSS wtyczka porównuje kraj adresu rozliczeniowego z krajem ustalonym na podstawie IP. Przy rozbieżności klient potwierdza lokalizację w formularzu. Nie jest to sprawdzanie ulicy ani kodu pocztowego.

Zwolnienie z VAT w formularzu zamówienia

Mechanizm wymaga włączonej walidacji VIES i produktu należącego do klasy wybranej dla OSS. Kraj i numer do sprawdzenia zależą od ustawienia WooCommerce określającego, na podstawie jakiego adresu obliczany jest podatek:

• dla adresu rozliczeniowego używany jest NIP nabywcy;
• dla oddzielnego adresu wysyłki używany jest NIP wysyłki; pusty NIP odbiorcy nie jest zastępowany NIP-em nabywcy;
• mechanizm nie usuwa VAT dla kraju bazowego sklepu ani automatycznie dla klientów spoza UE.

W trybach pytających o fakturę klient musi zaznaczyć prośbę o dokument, aby jego numery były uwzględniane w tym mechanizmie.

Jak wtyczka rozpoznaje rodzaj transakcji?

• OSS – dla klienta z innego kraju UE niż Polska i kraj bazowy sklepu, gdy zamówienie ma zastosowaną stawkę tego kraju z klasy wybranej dla OSS i nie zostało rozpoznane jako unijne B2B. Samo włączenie VIES nie oznacza OSS.
• WDT – dla zamówienia bez dodatniego VAT, z nabywcą będącym firmą i unijnym numerem VAT z prefiksem innym niż PL, gdy kraje rozliczenia i wysyłki należą do UE i są inne niż Polska, a zamówienie zawiera wyłącznie towary fizyczne. Wtyczka przekazuje dokument typu WDT ze stawką 0%.
• Eksport towarów – dla zamówienia bez dodatniego VAT, z krajami rozliczenia i wysyłki spoza UE oraz wyłącznie towarami fizycznymi. Wtyczka przekazuje dokument eksportu towarów ze stawką 0%.
• Odwrotne obciążenie – dla rozpoznanego unijnego B2B bez dodatniego VAT i bez towarów fizycznych. Wtyczka dodaje oznaczenie odwrotnego obciążenia.

Jeśli w zamówieniu nie ma kraju wysyłki, przy rozpoznawaniu WDT i eksportu wtyczka korzysta z kraju rozliczeniowego. Produkty wirtualne i koszyki mieszane nie spełniają warunku „wyłącznie towary fizyczne”. Rozpoznanie procedury na dokumencie nie zastępuje konfiguracji podatków zamówienia.

Wynik VIES w zamówieniu

Przy włączonej walidacji VIES w edycji zamówienia z krajem rozliczeniowym w UE pojawia się panel EU VAT. Zawiera numer VAT, wynik weryfikacji, informację o deklaracji klienta oraz dane kraju rozliczeniowego i kraju ustalonego na podstawie IP.

Ryczałt

Włącz – włącz ustawienie, jeśli jesteś ryczałtowcem.

Wybierz stawkę – wybierz domyślną stawkę ryczałtu odpowiadającą wymaganiom skarbowym. Jeśli sprzedajesz produkty w różnych stawkach ryczałtu, możesz zmodyfikować stawki w edycji produktu, za pomocą zmiany w polu Ryczałt.

Dla pozycji wysyłki wtyczka domyślnie wybiera najwyższą ze stawek ryczałtu przypisanych do produktów zamówienia. Zachowanie można zmienić filtrami.

Faktury walutowe

Faktura walutowa jest dostępna dla zamówień z włączoną obsługą podatków WooCommerce, gdy waluta zamówienia jest inna niż PLN. Wtyczka umożliwia wystawienie takiego dokumentu z poziomu edycji zamówienia WooCommerce, w metaboxie Fakturownia. Przy przygotowaniu danych dokumentu wtyczka przekazuje do Fakturowni walutę zamówienia oraz informacje potrzebne do przeliczenia na PLN. Źródło kursu zależy od kraju rozliczeniowego klienta: dla krajów UE wtyczka przekazuje ECB, a dla pozostałych NBP. Faktury walutowe mogą być także wystawiane automatycznie według ustawień wystawiania faktur.

Pola fakturowe w formularzu zamówienia

Wtyczka obsługuje klasyczny formularz zamówienia oraz formularz oparty na blokach WooCommerce. Sposób wyświetlania pól zależy od wybranego trybu wystawiania dokumentów.

Klasyczny formularz zamówienia

• W trybach Pytaj kupującego… pojawia się prośba o dokument. Zaznaczenie pola pokazuje NIP nabywcy. NIP wysyłki jest pokazywany przy wybranym oddzielnym adresie wysyłki.
• W pozostałych trybach NIP nabywcy jest widoczny bez zaznaczania prośby o fakturę. Nie oznacza to automatycznego wystawiania dokumentów w trybie ręcznym.
• Etykieta prośby zależy od konfiguracji: Chcę otrzymać fakturę VAT, Chcę otrzymać fakturę bez VAT albo Chcę otrzymać rachunek.

Blokowy formularz zamówienia

1. Otwórz stronę zamówienia w edytorze blokowym WordPressa.
2. Sprawdź obecność bloku pól faktury wtyczki Fakturownia w obrębie formularza zamówienia. Jeśli go nie ma, dodaj blok Faktura w obszarze pól formularza.
3. Dostosuj tytuł, opis oraz etykiety nabywcy, odbiorcy, numerów NIP i nazw firm.
4. Opcja Zastąp pole Firma pozwala wyświetlać pola firmy w bloku faktury i ukrywać standardowe pola firmy w adresach WooCommerce.
5. Zapisz stronę i sprawdź formularz na przykładowym zamówieniu.

W bloku etykietę prośby o fakturę możesz ustawić w edytorze. Nie musi być identyczna z etykietą klasycznego formularza.

Nabywca i odbiorca dokumentu

Dane nabywcy pochodzą z adresu rozliczeniowego i NIP-u nabywcy. Od wersji 2.0 wtyczka może dodatkowo przekazać dane odbiorcy z adresu wysyłki. Robi to, gdy:

1. w zamówieniu istnieje adres wysyłki;
2. dane adresu wysyłki różnią się od danych rozliczeniowych;
3. uzupełniony jest NIP wysyłki.

Wtyczka przekazuje nazwę firmy odbiorcy, a przy jej braku imię i nazwisko, następnie ulicę, kod pocztowy, miasto, kraj, NIP i dostępny telefon wysyłki. Ta funkcja nie zmienia nabywcy i nie dodaje oddzielnego odbiorcy do paragonu.

Przykład: firma A jest nabywcą, a firma B odbiera towar pod innym adresem. Wpisz dane firmy A w adresie rozliczeniowym, a dane firmy B i jej NIP w adresie wysyłki. Samo wpisanie innego adresu bez NIP-u wysyłki nie doda odbiorcy do dokumentu.

Wystawianie dokumentów

Dane fakturowe w edycji zamówienia

W WooCommerce → Zamówienia → edycja zamówienia otwórz edycję danych rozliczeniowych, aby sprawdzić lub poprawić NIP nabywcy. NIP odbiorcy znajdziesz w danych wysyłki. W trybach pytających o dokument w danych rozliczeniowych możesz także zmienić prośbę o fakturę lub rachunek.

Przed wystawieniem dokumentu zapisz zmiany w zamówieniu. W trybach pytających o fakturę odznaczenie prośby o dokument powoduje wyczyszczenie numerów NIP podczas zapisu. Prośba o fakturę może być prezentowana jako Tak lub Nie w sformatowanym adresie na podsumowaniu zamówienia i w wiadomościach WooCommerce. Pusty NIP nie powinien dodawać pustej etykiety do adresu.

Widok na liście zamówień

Jeśli kupujący zaznaczył opcję “Chcę otrzymać fakturę VAT”, zobaczysz to na liście zamówień WooCommerce:

Jeśli dla zamówienia został wystawiony dokument, zostanie on zaprezentowany na liście zamówień w twoim sklepie:

Metabox Fakturownia w edycji zamówienia

Aby wystawić fakturę, otwórz ekran edycji zamówienia i przejdź do metaboksa Fakturowni:

Kliknij parametry, aby przed wystawieniem dokumentu zmienić jego dane. Dla faktur i paragonów możesz ustawić kwotę zapłaconą, datę wystawienia, datę sprzedaży, termin i metodę płatności oraz uwagi. Proforma ma datę wystawienia, termin i metodę płatności oraz uwagi.

Data sprzedaży – poprawna data podana w parametrach ma pierwszeństwo. Bez niej wtyczka korzysta kolejno z daty ukończenia zamówienia, zapłaty i utworzenia zamówienia.

Kwota zapłacona – domyślnie dla statusów W trakcie realizacji i Zrealizowane wtyczka przyjmuje wartość zamówienia, a dla innych statusów zero. Przy pobraniu kwota pozostaje zerowa do osiągnięcia statusu Zrealizowane. W parametrach możesz ją zmienić; wartość wpływa na status płatności dokumentu.

Kliknij Wystaw fakturę lub przycisk właściwego typu dokumentu. Po wystawieniu możesz użyć przycisku @, aby ręcznie wysłać wiadomość do klienta.

Przed ponownym wystawieniem dokumentu dla tego samego zamówienia sprawdź istniejący dokument w Fakturowni. Ponowne wystawienie nie oznacza automatycznego anulowania poprzedniego dokumentu.

Faktura proforma

Proformę wystawisz ręcznie w edycji zamówienia albo automatycznie po osiągnięciu statusu wybranego w Parametrach faktury proforma. Przy włączonych podatkach dostępna jest zwykła proforma, a przy wyłączonych podatkach także proforma bez VAT. W zakładce faktur bez VAT jej ustawienia są pokazywane po wybraniu typu dokumentu Faktury bez VAT.

Wystawienie proformy nie oznacza oznaczenia dokumentu jako opłaconego. Wtyczka nie przekazuje do proformy daty sprzedaży.

Faktura korygująca

Przejdź do WooCommerce → Ustawienia → Integracja → Fakturownia i w zakładce wystawiania faktur zaznacz Automatycznie wystawiaj korekty po zwrocie. Opcja jest dostępna także w konfiguracji faktur bez VAT i domyślnie jest wyłączona.

1. Upewnij się, że zamówienie ma wystawioną przez integrację fakturę źródłową. Wtyczka musi znać ID dokumentu w Fakturowni.
2. Otwórz zamówienie i wykonaj zwrot częściowy lub pełny w WooCommerce. Zaznacz zwracane pozycje i uzupełnij ilości, kwoty oraz przyczynę zwrotu.
3. Wtyczka przygotuje korektę na podstawie ostatniego utworzonego zwrotu. Przyczyna zwrotu zostanie przekazana jako przyczyna korekty.
4. Sprawdź dokument i notatki zamówienia. Przy włączonej opcji korekt wiadomość z dokumentem podlega zasadom automatycznej wysyłki.

Wtyczka obsługuje wiele korekt do jednego zamówienia. Samo ręczne ustawienie statusu Zwrócone nie tworzy zwrotu z pozycjami i nie zastępuje powyższej procedury.

Ręczny przycisk wystawiania korekty jest domyślnie ukryty. Deweloper może go udostępnić filtrem fakturownia/ui/correction_button. Korekta nadal wymaga dokumentu źródłowego i danych zwrotu.

Wycofywanie dokumentów obsługuj w Fakturowni, zgodnie z ich statusem i dostępnymi tam operacjami. Nie każdy dokument można usunąć, w szczególności po jego przyjęciu przez KSeF.

Jak przeprowadzić zwrot w WooCommerce →

Widok kupującego

Dostęp do faktur z poziomu strony Moje konto

Kupujący, po zalogowaniu do sklepu z poziomu strony Moje konto będzie miał możliwość pobrania faktury po przejściu do podglądu złożonego zamówienia:

Edycja NIP-u

Klient może zmienić NIP nabywcy w Moje konto → Adresy → Adres rozliczeniowy oraz NIP odbiorcy w edycji Adresu wysyłki. Numery są zapisywane na koncie i mogą być uzupełniane w kolejnych zamówieniach. Przy zapisie adresu podlegają włączonym walidatorom.

Zmiana danych konta nie aktualizuje automatycznie wcześniej wystawionych dokumentów. Poniżej przykład edycji NIP-u rozliczeniowego:

E-mail z PDF-em wysyłany ze sklepu

Wiadomość z dokumentem jest wysyłana przez sklep na adres rozliczeniowy zamówienia i zawiera plik PDF w załączniku oraz link do jego pobrania. Wygląd wiadomości zależy od szablonu WooCommerce i ewentualnych modyfikacji sklepu. Sprawdź ustawienia i terminy wysyłki →

Synchronizacja stanów magazynowych

Synchronizacja jest opcjonalna. Łączy produkty WooCommerce z produktami Fakturowni przez ID produktu lub SKU, zależnie od kierunku i operacji. Zmiana stanu w Fakturowni jest przekazywana do sklepu webhookiem; wystawienie dokumentu ze sklepu może zmniejszać stan w Fakturowni zgodnie z jej konfiguracją magazynową.

Wtyczka przyjmuje stan otrzymany w webhooku. Jeśli produkt należy do kilku magazynów, sprawdź zakres tej wartości po stronie Fakturowni przed uruchomieniem synchronizacji. Wybór ID magazynu nie oznacza, że wtyczka samodzielnie wyliczy stan tylko tego magazynu z danych webhooka.

Synchronizacja WooCommerce > Fakturownia

Przy włączonej synchronizacji wystawiany dokument wskazuje powiązany produkt i wybrany magazyn. Aby dokument sprzedaży wpływał na stan, skonfiguruj automatyczne dokumenty wydania w Fakturowni.

1. Jeśli produkt ma zapisane ID Fakturowni, wtyczka przekazuje to ID. Wariant bez własnego ID może skorzystać z powiązania produktu nadrzędnego.
2. Jeśli nie ma ID, ale jest SKU, wtyczka wyszukuje produkt w Fakturowni po kodzie produktu.
3. Jedno dopasowanie pozwala użyć produktu na dokumencie. Wiele dopasowań powoduje błąd. Przy braku dopasowania produkt może zostać utworzony, jeśli włączysz opcję Nowe produkty.
4. Brak ID i SKU powoduje błąd powiązania produktu.

Sama ręczna zmiana ilości produktu w WooCommerce nie wysyła tej ilości do Fakturowni. Kierunek opisany powyżej opiera się na dokumentach wystawianych przez integrację.

Synchronizacja Fakturownia > WooCommerce

Po zmianie produktu Fakturownia wysyła webhook product:update. Wtyczka sprawdza token i aktualizuje produkty WooCommerce powiązane przez ID Fakturowni oraz produkt znaleziony po SKU, jeżeli kod produktu występuje w webhooku.

Zmianę stanu w Fakturowni może wywołać dokument magazynowy PZ albo faktura lub paragon wystawione poza sklepem. Wtyczka zapisuje stan otrzymany z Fakturowni, zamiast ponownie odejmować od niego ilość zamówienia.

Dodawanie produktów

Synchronizację możesz skonfigurować dla:

• Sklepów już istniejących i zaczynających z Fakturownią (magazyn jest w WooCommerce)
• Użytkowników Fakturowni i zaczynających z WooCommerce (magazyn jest w Fakturowni)

Sposoby synchronizowania produktów:

Import do WooCommerce – wyeksportuj produkty z Fakturowni z ich ID i kodem produktu, przygotuj plik CSV i użyj importera produktów WooCommerce. Jeżeli pobrany plik jest w innym formacie, np. XLS, zapisz go jako CSV przed importem.

Import do Fakturowni – produkty z SKU (jeśli nie ma, można łatwo wygenerować wtyczką) można eksportować w WooCommerce do CSV, a następnie zaimportować do Fakturowni.

Automatycznie – opcjonalnie wtyczka może dodawać produkty przy wystawianiu faktury.

Dane tworzonego produktu:

• nazwa
• kod produktu (SKU)
• opis
• cena regularna netto i brutto oraz stawka podatku wyliczone według ustawień WooCommerce
• adres zdjęcia produktu, jeśli produkt ma zdjęcie

Konfiguracja

Przejdź do sekcji Magazyn:

Synchronizacja – włącz, aby aktywować dwustronną synchronizację magazynową. Synchronizacja jest opcjonalna – domyślnie faktury są wystawiane bez obsługi magazynu.

ID magazynu – wybierz magazyn utworzony w Fakturowni, z którym chcesz synchronizować stany magazynowe.

Nowe produkty – pozwala tworzyć produkt w Fakturowni podczas wystawiania dokumentu, gdy nie ma powiązanego ID i wyszukiwanie po SKU nie zwróci produktu. Wymaga włączonej synchronizacji magazynowej. Nie ustawia stanu magazynowego i nie zastępuje dokumentu PZ.

Fakturownia udostępnia także własną opcję Produkty na fakturze → Automatycznie dodawaj do bazy produkty z faktury. Jest to ustawienie serwisu, odrębne od tworzenia produktu przez API wtyczki. Przykład lokalizacji ustawienia w Fakturowni →

Synchronizacja cen – zaznacz Włącz synchronizację cen. Funkcja może działać niezależnie od synchronizacji stanów. Zakres i wymagania synchronizacji cen →

Adres webhooka – będzie uzupełniony automatycznie (czytaj więcej).

Token webhooka – będzie uzupełniony automatycznie (czytaj więcej).

Reszta konfiguracji jest po stronie Fakturowni.

Ustawienia Fakturowni

Jak ustanowić połączenie?

• Przejdź do zakładki Ustawienia konta > Integracja,
• W sekcji Webhooki w polu Rodzaj wybierz product:update,
• Z ustawień wtyczki skopiuj Adres webhooka i wklej w kolumnie Adres,
• Z ustawień wtyczki skopiuj Token webhooka i wklej w kolumnie Api token.

Stany magazynowe

• Przejdź do zakładki Ustawienia konta > Twoje konto,
• Zaznacz opcję Obsługa magazynów,
• Przejdź do zakładki Ustawienia konta > Konfiguracja > Magazyny,
  w sekcji Magazyny dla opcji Automatyczne tworzenie dokumentów wydania wybierz Tworzenie WZ przy wystawieniu faktury przychodowej.

Import do WooCommerce i synchronizacja

Aby do importowanego produktu przypisać ID produktu z Fakturowni, należy:

• W pliku CSV zmienić nazwę importowanej kolumny z ID produktu na _fakturownia_product_id.
• W importerze produktów WooCommerce zmapuj kolumnę ID na dane meta o kluczu _fakturownia_product_id. Nie importuj ID Fakturowni jako ID produktu WooCommerce.
• Produkt z Fakturowni można również przypisać ręcznie do produktu w WooCommerce. W edycji produktu w zakładce Magazyn jest select z wyszukiwarką produktów Fakturowni.

Dla produktów, których ilości chcesz synchronizować w sklepie, włącz zarządzanie stanem magazynowym:

Import produktów do Fakturowni z WooCommerce

Jeśli prowadzisz magazyn w WooCommerce i chciałbyś przenieść jego zawartość do systemu Fakturownia, wykonaj poniższe kroki:

Zakładając, że masz już utworzone produkty WooCommerce, a ich parametry takie jak cena, stan magazynowy i SKU (jeśli nie ma, można łatwo wygenerować wtyczką), uzupełnione, możesz wyeksportować produkty z WooCommerce do pliku CSV.

W tym celu przejdź do menu Produkty → Eksport:

W formularzu generowania pliku CSV wybierz następujące kolumny do eksportu:

• ID,
• SKU,
• Nazwa,
• Krótki opis,
• Magazyn,
• Cena.

Następnie zaloguj się do systemu Fakturownia, przejdź do sekcji Produkty i wybierz z menu po prawej Import produktów:

W kolejnym kroku załącz plik wygenerowany w WooCommerce i przejdź dalej:

Jeśli pobieranie danych z pliku zakończy się powodzeniem i otrzymasz komunikat Gotowe, kliknij przycisk Przejrzyj dane i importuj:

W drugim kroku zmapuj poszczególne pola zgodnie z kolejnością w jakiej zostały one umieszczone w pliku CSV przez eksporter WooCommerce:

• id – pomiń ID produktu WooCommerce przy tworzeniu nowego produktu w Fakturowni; oba systemy nadają własne identyfikatory.
• code : Kod Produktu
• name : Nazwa
• description : Opis
• warehouse_quantity : Stany magazynowe
• price_gross – cena brutto. Jeśli eksportujesz ceny zapisane jako netto w WooCommerce, przelicz je na brutto przed przypisaniem do tego pola albo wybierz właściwe pole ceny netto w importerze Fakturowni.

Po imporcie sprawdź kody produktów, ceny i ilości w Fakturowni. Następnie skonfiguruj webhook oraz dokumenty wydania i przetestuj wystawienie dokumentu dla jednego powiązanego produktu.

Synchronizacja cen

Przejdź do WooCommerce → Ustawienia → Integracja → Fakturownia → Magazyn, zaznacz Włącz synchronizację cen i zapisz zmiany. Nie musisz włączać synchronizacji ilości, aby korzystać z synchronizacji cen.

• WooCommerce → Fakturownia – po zapisie produktu lub wariantu w edycji administracyjnej wtyczka wysyła cenę regularną i stawkę podatku. Produkt musi mieć zapisane ID Fakturowni. Samo SKU nie wystarcza w tym kierunku.
• Fakturownia → WooCommerce – po odebraniu webhooka product:update wtyczka zapisuje cenę regularną produktu dopasowanego przez ID lub SKU. Jeżeli w WooCommerce podatki są włączone i ceny są wprowadzane z podatkiem, używa ceny brutto. W pozostałych przypadkach używa ceny netto.
• Stawki podatkowe – są przekazywane z WooCommerce do Fakturowni. Webhook z Fakturowni nie zmienia klasy ani stawki podatkowej produktu WooCommerce.

Synchronizacja dotyczy ceny regularnej. Nie synchronizuje dat promocji ani osobnego pola ceny promocyjnej. Cena otrzymana z Fakturowni musi być większa od zera, aby została zapisana w sklepie.

Dla kierunku Fakturownia → WooCommerce skonfiguruj webhook i token. Dla wariantów przypisz ID właściwego produktu Fakturowni bezpośrednio w edycji wariantu.

Walidacja NIP w checkout

Włącz opcję Poprawność numeru NIP w ustawieniach wystawiania dokumentów, aby sprawdzać format numeru przy składaniu zamówienia. Funkcja działa także przy wyłączonych podatkach.

• Dla polskiego NIP-u wtyczka sprawdza 10 cyfr oraz sumę kontrolną. Akceptuje numer z prefiksem PL i bez niego.
• Dla obsługiwanych krajów sprawdza format właściwy dla danego kraju. Numery zagraniczne zwykle wymagają prefiksu, np. DE; dla greckiego VAT używany jest prefiks EL.
• Przed sprawdzeniem wtyczka zamienia litery na wielkie i usuwa spacje, myślniki, przecinki oraz kropki. Samo użycie tych separatorów nie oznacza błędu.
• Weryfikuje NIP nabywcy oraz, gdy używany jest oddzielny adres wysyłki wymagający dostawy, NIP odbiorcy.

W trybach pytających o dokument numery są sprawdzane po zaznaczeniu prośby o fakturę lub rachunek. Pusty NIP nie jest sam w sobie odrzucany przez walidatory formatu i VIES. Ewentualny wymóg numeru wynikający z danych firmy lub konfiguracji Fakturowni może zostać zgłoszony przy wystawianiu dokumentu.

Walidacja VIES jest osobnym ustawieniem. Po jej włączeniu wtyczka sprawdza numery z UE w rejestrze oraz ich format; ustawienie reakcji na nieudaną walidację dotyczy wyniku VIES, a nie błędnej sumy kontrolnej.

Stawka podatkowa ZW

Aby oznaczać wybrane produkty jako zwolnione z VAT przy włączonych podatkach WooCommerce:

1. Utwórz klasę podatkową ze stawką 0% i przypisz ją odpowiednim produktom.
2. W ustawieniach Fakturowni we wtyczce wybierz tę klasę w polu Klasa podatkowa dla stawki ZW.
3. Uzupełnij pole Podstawa prawna zwolnienia. Wtyczka przekazuje je do dedykowanego pola podstawy zwolnienia dokumentu.

Przy wyłączonych podatkach i wybranym typie Faktury bez VAT pozycje faktury otrzymują zw. Nie musisz wymuszać tej wartości własnym filtrem.

PKWiU jest odrębnym oznaczeniem produktu pobieranym z atrybutu. Nie zastępuje podstawy zwolnienia i nie jest ograniczone do produktów ze stawką ZW.

Troubleshooting

Nie działa synchronizacja magazynowa

1. Sprawdź włączenie synchronizacji, wybrany magazyn, powiązanie produktu i zarządzanie stanem w WooCommerce.
2. Zweryfikuj webhook product:update, jego adres i token w Fakturowni. Nie pomyl tokenu webhooka z tokenem autoryzacji API.
3. Zmień stan testowego produktu w Fakturowni i sprawdź dostarczenie webhooka do sklepu.
4. Jeśli webhook nie dociera, poproś administratora o sprawdzenie logów serwera, reguł CDN, zapory i .htaccess. Reguły blokujące wywołania bez nagłówka User-Agent mogą blokować webhook. Dostosuj konkretną regułę lub wyjątek dla tego połączenia.
5. Włącz debugowanie i sprawdź komunikaty dotyczące API.

Po każdej zmianie ponów test dla jednego produktu. Jeśli nadal potrzebujesz pomocy, napisz do nas.

Najczęstsze błędy zwracane z API Fakturowni

• 401 – błędy związane z autoryzacją: domena, token
  Komunikat wskazuje na brak autoryzacji.
  Sprawdź czy w ustawieniach wtyczki wprowadzono prawidłowy token oraz domenę: https://www.wpdesk.pl/docs/fakturownia-woocommerce-docs/#autoryzacja
• 422 – błędy po stronie Fakturowni np. brak danych dla firmy. Sprawdź w takim przypadku, czy w panelu Fakturowni zostały poprawnie dodane dane firmy lub czy ich nie brakuje. Sprawdź też ustawienia pod adresem https://NAZWAKONTA.fakturownia.pl/departments Kod 422 może też oznaczać brak produktu (np. po usunięciu w Fakturowni) powiązanego z pozycją w zamówieniu. W takiej sytuacji sprawdź aktualność pola “Produkt w Fakturowni” oraz stanu magazynowego dla produktów z takiego zamówienia:
  
  Powinny odpowiadać istniejącym produktom w Fakturowni. Łatwo możesz sprawdzić, który produkt nie jest aktualny lub został usunięty w Fakturowni sprawdzając jego ID (widoczne w polu “Produkt w Fakturowni”):
  pod adresem https://NAZWAKONTA.fakturownia.pl/products/ID. Wpisz nr ID bez znaku #. Dla nieistniejących produktów w Fakturowni otrzymasz kod błędu 404. Adres możesz odwiedzić po zalogowaniu w Fakturowni.

Obsługa parametru GTU

Wtyczka daje możliwość ustawienia parametru GTU dla każdego produktu indywidualnie. Przejdź do edycji produktu WooCommerce i wybierz kod GTU z listy, jeśli chcesz, żeby do pozycji z tym produktem był przypisywany kod GTU podczas wystawiania faktur:

Masowe dodawanie kodu GTU do wszystkich produktów WooCommerce

Poniższy przykład ustawia jeden kod GTU dla opublikowanych produktów głównych. Nie obejmuje osobnych wpisów wariantów ani produktów w innych statusach i nadpisuje wcześniejsze GTU objętych nim produktów.

Kod jest przeznaczony dla deweloperów. Dodaj go tymczasowo do własnej wtyczki lub pliku functions.php motywu potomnego, ustaw właściwy kod GTU i otwórz panel administracyjny jako użytkownik mogący zarządzać WooCommerce. W dużym katalogu wykonaj aktualizację partiami zamiast jednym wywołaniem.

add_action( 'admin_init', function () {
    if ( ! current_user_can( 'manage_woocommerce' ) || 'yes' === get_option( 'wpdesk_fakturownia_gtu_done' ) ) {
        return;
    }

    $gtu = 'GTU_06';
    $product_ids = get_posts( [
        'post_type'      => 'product',
        'post_status'    => 'publish',
        'posts_per_page' => -1,
        'fields'        => 'ids',
    ] );

    foreach ( $product_ids as $product_id ) {
        update_post_meta( $product_id, '_fakturownia_gtu_code', $gtu );
    }

    update_option( 'wpdesk_fakturownia_gtu_done', 'yes' );
} );

Wybierz kod od GTU_01 do GTU_13. Po wykonaniu sprawdź produkty i usuń kod. Ustawienie wpdesk_fakturownia_gtu_done zapobiega ponownemu wykonaniu przykładu; jego usunięcie pozwala uruchomić go ponownie.

Oznaczenia dotyczące procedur dla faktur przychodowych

Wtyczka pozwala oznaczać wystawiane faktury zgodnie z oznaczeniami transakcji przychodowych. Oznaczenia ustawisz indywidualnie dla każdego produktu, jeśli chcesz, aby wystawiane faktury VAT były oznaczane szczególnymi rodzajami transakcji. Wybierz z listy rodzaj transakcji:

Jeśli w zamówieniu będą produkty z różnymi oznaczeniami, to faktura zostanie oznaczona wszystkimi parametrami, które występują przy pozycjach zamówienia.

Integracja z wtyczką Kalkulator Jednostek dla WooCommerce

Wtyczka Fakturownia WooCommerce jest kompatybilna z wtyczką Kalkulator Jednostek dla WooCommerce. Wtyczka Kalkulator Jednostek dla WooCommerce umożliwia włączenie kalkulacji ceny produktu na podstawie wymiarów na stronie produktowej.

Aby wyświetlić jednostkę miary na fakturze, która została ustawiona w Kalkulatorze Jednostek dla WooCommerce, przejdź do edycji produktu i wybierz zakładkę Kalkulator Jednostek. Następnie zaznacz checkbox z opcją Zaznacz to pole, aby stany magazynowe były zmniejszane według ustalonej jednostki.

Wiadomości e-mail z fakturami

Wtyczka wykorzystuje mechanizm wiadomości WooCommerce. Dokumenty są wysyłane przez sklep po włączeniu automatycznej wysyłki właściwego typu: faktury, proformy, paragonu albo rachunku. Wiadomość z korektą jest powiązana z opcją automatycznego wystawiania korekt.

Opóźnienie wysyłki – domyślnie po utworzeniu dokumentu wtyczka planuje wysyłkę wiadomości po 5 minutach. Wysyłka następuje, gdy Action Scheduler wykona zadanie; może więc nastąpić później niż po dokładnie pięciu minutach. Bez dostępnego Action Schedulera wtyczka próbuje wysłać wiadomość od razu.

Ustawienia i szablony wiadomości znajdziesz w WooCommerce → Ustawienia → E-maile. Konfiguracja i modyfikowanie wiadomości WooCommerce →

Przy własnych szablonach sprawdź ich zgodność z bieżącą wersją wtyczki. Aktualne szablony korzystają ze standardowych hooków wiadomości WooCommerce. Deweloper może zmienić opóźnienie lub wyłączyć odkładanie wysyłki filtrami.

Tryb debugowania

Przejdź do WooCommerce → Ustawienia → Integracja → Fakturownia → Tryb debugowania.

Tryb debugowania – zaznacz Włącz tryb debugowania i zapisz zmiany. Logi połączenia znajdziesz w WooCommerce → Status → Logi; szukaj źródła fakturownia lub użyj odnośnika w ustawieniach wtyczki.

Zablokuj żądanie API – po włączeniu debugowania możesz dodatkowo zablokować wysyłanie żądań API wykonywanych w kontekście administratora. Wtyczka zapisze żądanie i zakończy operację komunikatem o symulacji. W tym trybie może być zablokowane także pobieranie danych, np. produktu lub PDF-u.

Blokada dotyczy wywołań użytkownika z uprawnieniem manage_options. Nie jest globalnym trybem testowym dla klientów sklepu ani dla zadań wykonywanych w tle.

Po zakończeniu diagnostyki ręcznie wyłącz debugowanie i blokadę API, a następnie zapisz zmiany.

Jeśli potrzebujesz pomocy, napisz do nas i dołącz opis operacji oraz odpowiednie logi.

Opcje dla zaawansowanych użytkowników

Poniższe informacje są przeznaczone dla deweloperów. Przykłady dodaj do własnej wtyczki albo pliku functions.php motywu potomnego. Sprawdź wynik na zamówieniu testowym przed użyciem modyfikacji w sklepie.

Identyfikatory pól fakturowych

Techniczna nazwa bloku pól faktury to wpdesk/fakturownia-checkout.

Od wersji 2.0.1 klasyczny formularz używa dotychczasowych nazw pól. Nie dodawaj drugiego pola NIP pod inną nazwą, jeżeli dane mają być odczytywane przez integrację.

Pole	Nazwa w klasycznym checkout i na koncie	Klucz danych zamówienia
NIP nabywcy	billing_nip	_billing_nip
NIP wysyłki / odbiorcy	shipping_nip	_shipping_nip
Prośba o fakturę VAT lub bez VAT	billing_faktura	_billing_faktura
Prośba o rachunek	billing_rachunek	_billing_rachunek

Własny kod powinien odczytywać zamówienia przez wc_get_order(), metody obiektu WC_Order i get_meta(), aby obsługiwać również HPOS. Dane prośby o dokument traktuj jako wartość logiczną; w zależności od miejsca zapisu mogą mieć postać yes/no lub 1/0.

Przechwytywanie danych faktury

Filtr fakturownia/core/api/request otrzymuje tablicę całego żądania oraz zamówienie tuż przed wysłaniem dokumentu do API. Dane dokumentu są w $data['invoice']. Przykład oznacza dokument jako objęty MPP i dopisuje numer zamówienia do uwag:

add_filter( 'fakturownia/core/api/request', function ( $data, $order ) {
    $data['invoice']['split_payment'] = 1;
    $note = 'Zamówienie: ' . $order->get_order_number() . ' PL';
    $existing = (string) ( $data['invoice']['description'] ?? '' );
    $data['invoice']['description'] = trim( $existing . PHP_EOL . $note );
    return $data;
}, 10, 2 );

Powyższy przykład ustawia MPP dla każdego dokumentu przechodzącego przez filtr. Dodaj własny warunek, jeśli oznaczenie ma dotyczyć tylko określonych zamówień.

Przeliczenie faktury bez VAT na PLN

Przykład dodaje docelową walutę przeliczenia PLN do faktury bez VAT, gdy podatki WooCommerce są wyłączone, a zamówienie jest w innej walucie. Nie zmienia waluty samego zamówienia.

add_filter( 'fakturownia/core/api/request', function ( $data, $order ) {
    if ( ! wc_tax_enabled() && 'PLN' !== $order->get_currency() && 'vat' === ( $data['invoice']['kind'] ?? '' ) ) {
        $data['invoice']['exchange_currency'] = 'PLN';
    }
    return $data;
}, 10, 2 );

Dodatkowe filtry do wykorzystania

Filtry danych dokumentu otrzymują tablicę danych dokumentu i obiekt DocumentData. W przeciwieństwie do filtra całego żądania pola dokumentu są tu bezpośrednio w $data.

• fakturownia/invoice/data – dane faktury.
• fakturownia/invoice_without_vat/data – dane faktury bez VAT.
• fakturownia/invoice_proforma/data – dane proformy.
• fakturownia/invoice_proforma_without_vat/data – dane proformy bez VAT.
• fakturownia/invoice_foreign/data – dane faktury walutowej.
• fakturownia/invoice_correction/data – dane korekty.
• fakturownia/receipt/data – dane paragonu.
• fakturownia/bill/data – dane rachunku.

Niektóre typy dokumentów dziedziczą przygotowanie danych po innych typach, dlatego przy łączeniu filtrów uwzględnij kolejność ich wykonania.

Przy tworzeniu produktu w Fakturowni dostępne są filtry wartości oraz obiekt produktu WooCommerce jako drugi argument:

• fakturownia/core/create_product/name – nazwa;
• fakturownia/core/create_product/sku – kod produktu;
• fakturownia/core/create_product/prices – tablica cen netto i brutto;
• fakturownia/core/create_product/tax – stawka podatku;
• fakturownia/core/create_product/description – opis;
• fakturownia/core/create_product/img_url – adres zdjęcia.

fakturownia/sync/product_update_data otrzymuje całe żądanie aktualizacji produktu i jego ID w Fakturowni. Akcje fakturownia/sync/before_webhook_update i fakturownia/sync/after_webhook_update otrzymują dane zweryfikowanego webhooka.

Stawkę ryczałtu dla wysyłki zmienisz filtrami fakturownia/lump_sums/shipping_lump_sums (wybrana stawka i pozycje produktów) oraz fakturownia/lump_sums/single_shipping_lump_sum (stawka pozycji wysyłki i pozycja zamówienia).

Przykłady wykorzystania filtrów

ID transakcji w polu Uwagi

Jeśli bramka płatności, np. Przelewy24, PayU lub Tpay, zapisuje identyfikator transakcji w zamówieniu WooCommerce, poniższy kod dopisze go do uwag faktury, zachowując dotychczasowy tekst:

add_filter( 'fakturownia/invoice/data', function ( $data, $document_data ) {
    $order = $document_data->getOrder();
    if ( $order instanceof WC_Order && '' !== (string) $order->get_transaction_id() ) {
        $existing = (string) ( $data['description'] ?? '' );
        $data['description'] = trim( $existing . PHP_EOL . 'ID płatności: ' . $order->get_transaction_id() );
    }
    return $data;
}, 10, 2 );

Imię i nazwisko kupującego na fakturze

Jeśli jako nabywca jest przekazywana firma, poniższy kod dopisze imię i nazwisko do jej nazwy. Dane osoby prywatnej pozostaną obsługiwane standardowo.

add_filter( 'fakturownia/invoice/data', function ( $data, $document_data ) {
    $client = $document_data->getClientData();
    $name = trim( $client->getFirstName() . ' ' . $client->getLastName() );
    if ( '' !== trim( (string) $client->getCompanyName() ) && ! empty( $data['buyer_name'] ) && '' !== $name ) {
        $data['buyer_name'] .= ', ' . $name;
    }
    return $data;
}, 10, 2 );

Dane odbiorcy na fakturze

Do standardowej obsługi odbiorcy nie potrzebujesz dodatkowego filtra. Wtyczka pobiera dane z adresu wysyłki, gdy różni się on od danych rozliczeniowych i ma uzupełniony NIP. Warunki i przykład →

Własne reguły możesz przygotować przez filtr danych dokumentu, zmieniając pola recipient_name, recipient_street, recipient_post_code, recipient_city, recipient_country, recipient_tax_no i opcjonalnie recipient_phone.

Kolumna Rabat kwotowy na fakturze

Domyślnie wtyczka przekazuje wartości pozycji po rabatach z zamówienia WooCommerce. Osobną kolumnę rabatu można przygotować jako modyfikację danych dokumentu. API Fakturowni obsługuje show_discount, discount_kind o wartości amount oraz pole discount w pozycjach.

Zmiana musi uwzględniać ceny przed rabatem, liczbę sztuk, VAT, zaokrąglenia oraz jednoznaczne powiązanie pozycji dokumentu z pozycją zamówienia. Samo włączenie kolumny nie odtwarza rabatów WooCommerce. Parametry i przykłady API Fakturowni →

Kolumna Rabat procentowy na fakturze

Analogiczna modyfikacja może używać discount_kind o wartości percent_unit dla jednostkowej ceny netto, percent_unit_gross dla jednostkowej ceny brutto lub percent_total dla ceny całkowitej. Dobierz wariant do przekazywanych cen i sprawdź, czy końcowe wartości dokumentu zgadzają się z zamówieniem. Rabat wynikający z kuponów WooCommerce nie musi mieć jednej wspólnej wartości procentowej dla wszystkich pozycji.

Dodanie podstawy zwolnienia na faktury bez VAT

Użyj ustawienia Podstawa prawna zwolnienia. Wtyczka sama ustawia stawkę zw na fakturze bez VAT i przekazuje podstawę do exempt_tax_kind. Nie potrzebujesz filtra wymuszającego samo zw.

Sterowanie wysyłką e-maili

• fakturownia/email/auto_send – zezwolenie na automatyczną wysyłkę; otrzymuje wartość logiczną, zamówienie i typ dokumentu. Zwrócenie false blokuje wysyłkę. Zwrócenie true nie zastępuje ustawienia wysyłki danego typu dokumentu.
• fakturownia/email/delay_enabled – steruje odłożeniem automatycznej wysyłki; otrzymuje wartość logiczną, zamówienie i typ dokumentu.
• fakturownia/email/delay_seconds – czas oczekiwania w sekundach, domyślnie 300. Filtr otrzymuje samą wartość opóźnienia.

Przykład zmienia opóźnienie na 10 minut:

add_filter( 'fakturownia/email/delay_seconds', function ( $seconds ) {
    return 10 * MINUTE_IN_SECONDS;
} );

Aby zrezygnować z opóźnienia i próbować wysyłki bezpośrednio po wystawieniu dokumentu:

add_filter( 'fakturownia/email/delay_enabled', '__return_false' );

Zmiana filtrów opóźnienia dotyczy nowych wywołań; nie przesuwa zadań już zaplanowanych.

FAQ

Dlaczego na fakturze brakuje NIP-u klienta?

1. Sprawdź wersję wtyczki. Wersja 2.0.1 przywróciła dotychczasowe nazwy pól klasycznego checkoutu i poprawiła współpracę z Flexible Checkout Fields.
2. Otwórz zamówienie i sprawdź, czy NIP nabywcy został zapisany w danych rozliczeniowych. NIP wysyłki jest numerem odbiorcy, nie nabywcy.
3. W trybie pytającym o dokument sprawdź prośbę o fakturę. Bez niej pola NIP nie są używane do obsługi prośby o dokument.
4. W klasycznym checkout sprawdź nazwy pól billing_nip i shipping_nip; w checkout blokowym sprawdź obecność bloku faktury.
5. Jeżeli formularz jest modyfikowany przez inne wtyczki, porównaj zachowanie na zamówieniu testowym po wyłączeniu tych modyfikacji.

Jak modyfikować formularz zamówienia?

Do dodatkowych zmian klasycznego checkoutu możesz użyć Flexible Checkout Fields. Zachowaj identyfikatory pól integracji i unikaj dublowania NIP-u. Samo zainstalowanie edytora pól nie naprawi danych, które nie zostały zapisane w zamówieniu. Dla checkoutu blokowego konfiguruj blok faktury i sprawdź zgodność używanego rozszerzenia z blokami.

Dlaczego odbiorca nie pojawia się na fakturze?

Sprawdź, czy adres wysyłki różni się od adresu rozliczeniowego i czy ma zapisany NIP. Przy identycznych danych albo pustym NIP-ie wysyłki wtyczka nie dodaje oddzielnego odbiorcy. Paragon nie korzysta z tej funkcji.

Błąd 422 buyer_tax_no

Sprawdź NIP zapisany w danych nabywcy zamówienia, jego kraj i wymagany prefiks. Włącz Poprawność numeru NIP, aby wychwytywać błędny format lub sumę kontrolną przy składaniu nowych zamówień. Po poprawieniu danych zapisz zamówienie i ponów wystawienie dokumentu.

Błąd 401 – brak autoryzacji

Sprawdź API Token i Domenę w WooCommerce → Ustawienia → Integracja → Fakturownia → Autoryzacja. Token skopiuj z Ustawienia → Ustawienia konta → Integracja w Fakturowni. Upewnij się, że dotyczy właściwego konta.

Po zapisaniu ustawień ponów operację, przy której wystąpił błąd.

Produkt nie jest powiązany z Fakturownią i nie ma SKU

W edycji produktu WooCommerce wybierz istniejący Produkt w Fakturowni albo uzupełnij SKU zgodne z kodem produktu w Fakturowni. Do wystawiania dokumentów z magazynem wystarczy prawidłowe powiązanie przez ID lub wyszukanie po SKU. Do wysyłania zmian ceny z WooCommerce wymagane jest zapisane ID Fakturowni.

Błąd 422 – brak konta

Zweryfikuj Domenę. Dla adresu https://twojadomena.fakturownia.pl/ wpisz twojadomena, bez protokołu, ukośników i końcówki domeny. Sprawdź również token i dostęp do właściwej firmy. Zapisz zmiany i ponów wystawienie dokumentu.

Błąd 422 seller_name

Sprawdź dane sprzedawcy w Fakturowni, w tym nazwę firmy. Jeśli w integracji podajesz ID Firmy, sprawdź dane i dostęp do wskazanego działu, a nie tylko do firmy głównej.

Błąd 422 positions.name

Sprawdź pełną odpowiedź API i pozycję wskazaną w komunikacie. Zweryfikuj nazwę produktu oraz aktualność powiązanego ID lub kodu w Fakturowni. Sam kod błędu nie oznacza, że każde SKU musi mieć co najmniej cztery znaki.

Stan zmienia się po dokumencie ze sklepu, ale nie po dokumencie wystawionym w Fakturowni

Sprawdź kierunek Fakturownia → WooCommerce: webhook product:update, token, dopasowanie ID lub SKU i dostęp do adresu webhooka. Poproś administratora o sprawdzenie blokad CDN, zapory i reguł .htaccess, w tym blokowania żądań bez User-Agent. Pełna procedura diagnostyczna →

Could not resolve host

Sprawdź pole Domena zgodnie z instrukcją autoryzacji. Jeżeli nazwa jest poprawna, administrator serwera powinien sprawdzić rozwiązywanie DNS i dostęp serwera do Fakturowni.

Nie znaleziono żadnego produktu o kodzie: XXX

Sprawdź zgodność SKU w WooCommerce z kodem produktu w Fakturowni oraz dostępność produktu w wybranym magazynie. Możesz przypisać produkt bezpośrednio przez ID. Jeśli produkt jeszcze nie istnieje, dodaj go w Fakturowni albo włącz Nowe produkty przy aktywnej synchronizacji magazynowej.

Automatyczne utworzenie produktu nie tworzy dokumentu PZ ani nie ustawia ilości. Przy przenoszeniu katalogu użyj eksportu CSV WooCommerce i importu do Fakturowni.

Błąd 403 – brak uprawnień do konta

Sprawdź dostęp tokenu do konta i firmy lub działu. Zweryfikuj ID Firmy; pozostaw je puste, jeżeli chcesz używać domyślnej firmy konta. Błąd nie musi oznaczać wyłącznie niepoprawnego ID, dlatego sprawdź również uprawnienia tokenu.

Faktura WDT wymaga NIP-u sprzedawcy z przedrostkiem kraju

Dodaj prefiks PL do NIP-u firmy lub działu w Fakturowni używanego przez integrację. Jeśli wybrane jest konkretne ID firmy, zmień dane właśnie tego działu. Następnie ponów wystawienie faktury.

Numer jest poprawny, ale VIES go nie potwierdza

Odróżnij wynik „numer niepoprawny” od niedostępności rejestru. Wersja 2.0.3 poprawia połączenie VIES przy niektórych wersjach OpenSSL. Sprawdź aktualizację wtyczki, kraj i prefiks numeru oraz ustawienie reakcji na błąd VIES.

Wynik pozytywny jest pamiętany przez 24 godziny, negatywny przez godzinę, a błąd usługi przez 15 sekund. Ponowne wywołanie w tym czasie może użyć zapamiętanego wyniku.

Faktura powstała, ale klient nie otrzymał wiadomości

1. Sprawdź włączenie automatycznej wysyłki właściwego typu dokumentu i adres e-mail w zamówieniu.
2. Uwzględnij domyślne opóźnienie 5 minut. Sprawdź zadania Action Schedulera w WooCommerce → Status → Zaplanowane działania, wyszukując fakturownia/email/send_delayed.
3. Sprawdź notatki zamówienia, dostępność PDF-u i logi. Jeśli pobranie PDF-u się nie powiedzie, wtyczka zapisuje błąd i nie wysyła wiadomości bez dokumentu. Ten mechanizm nie planuje automatycznie ponownej próby.
4. Po usunięciu przyczyny wyślij wiadomość ręcznie przyciskiem @ przy dokumencie w zamówieniu. Jeśli sklep nadal nie wysyła wiadomości, sprawdź konfigurację poczty WooCommerce.

Dlaczego korekta nie wystawiła się po zwrocie?

Sprawdź Automatycznie wystawiaj korekty po zwrocie, obecność faktury źródłowej i wykonanie rzeczywistego zwrotu WooCommerce. Samo ustawienie statusu Zwrócone nie wystarczy. W razie błędu sprawdź notatki zamówienia i logi integracji.