Invoice Pilot

Invoice Pilot rozszerza WooCommerce o świadome kraju fakturowanie dla wszystkich 27 państw członkowskich UE. Zbiera odpowiednie pola rozliczeniowe na checkoucie (włoskie kody SDI / PEC, francuski SIRET, niemiecki Leitweg-ID, polski NIP, rumuński CUI itd.), a następnie wystawia z zamówienia niezmienne faktury, noty kredytowe, proformy i oferty w PDF i XML. PDF jest renderowany przez mPDF; envelope XML jest dobierany automatycznie do kraju kupującego i pokrywa jedenaście profili narodowych, w tym FatturaPA (IT), XRechnung (DE), KSeF FA(2) (PL), Factur-X (FR), CIUS_RO (RO), Facturae (ES) oraz UBL 2.1 / PEPPOL BIS 3.0 jako uniwersalny fallback.

Poza silnikiem dokumentów Invoice Pilot dostarcza pierwszorzędne integracje z sześcioma dostawcami księgowymi — SmartBill (Rumunia), Fatture in Cloud (Włochy), Xero, QuickBooks Online, Fortnox (Szwecja) i Sage — walidator VAT konsultujący europejską usługę VIES z fallbackiem do formatu per kraj, dashboard z kartami KPI i wykresami trendów oraz opcjonalną warstwę AI od wielu dostawców (Anthropic Claude, OpenAI, Google Gemini, DeepSeek, Grok xAI) na potrzeby smart-fillu checkoutu, pre-flight compliance, tłumaczeń linii i wyszukiwania dokumentów językiem naturalnym. Wtyczka wspiera też WordPress Multisite z tabelami per witryna i sieciową stroną podsumowania.

Wyróżniki

• Sterowany WooCommerce cykl życia dokumentów dla faktur, not kredytowych, proform i ofert, z zarezerwowanymi seriami numeracji, czystym przepływem wystawianie / regeneracja / ponowne wystawienie / unieważnienie / nota kredytowa oraz stylowaniem per typ dokumentu (baner ostrzegawczy na dokumentach niefiskalnych, etykiety „Ważne do” na ofertach, „Łączna kwota zwrotu” na notach kredytowych, blok płatności ukryty na ofertach i notach kredytowych).
• Pola rozliczeniowe specyficzne dla UE-27 zarejestrowane zarówno wobec klasycznego checkoutu shortcode’owego, jak i checkoutu blokowego WooCommerce 8.6+ (przez API Additional Checkout Fields).
• Renderowanie PDF przez mPDF z użyciem jednego z trzech wbudowanych szablonów (Minimal, Classic, Modern), z selektorem koloru akcentu, koloru tekstu, rodziny fontu i logo sprzedawcy.
• Jedenastu writerów XML, dobieranych automatycznie do kraju kupującego: FatturaPA (IT), Factur-X / CII (FR), XRechnung 3.0 (DE), KSeF FA(2) (PL), CIUS_RO 1.0.0 (RO), Facturae 3.2.2 (ES), SAF-T PT (PT), OIOUBL (DK), Finvoice 3.0 (FI), ebInterface 6.1 (AT), myDATA InvoicesDoc (GR / EL), z UBL 2.1 / PEPPOL BIS 3.0 jako uniwersalnym fallbackiem.
• Łańcuch walidacji VAT łączący europejską usługę SOAP VIES z offline’ową walidacją regexową per kraj, cache opartym o bazę i godzinowym cronem, który rewaliduje przeterminowane wpisy.
• Sześć integracji księgowych — SmartBill, Fatture in Cloud, Xero, QuickBooks Online, Fortnox i Sage — każda z zaszyfrowanymi danymi uwierzytelniającymi, operacjami push / status / void i kolejką ponawiania. Zakładka ustawień Integracje używa „lepkiego” selektora dostawcy, dzięki czemu panel, który właśnie konfigurujesz, pozostaje otwarty między zapisami.
• Opcjonalna warstwa AI z pięcioma dostawcami (Anthropic, OpenAI, Google Gemini, DeepSeek, Grok xAI) obsługującymi smart-fill, sprawdzanie compliance, tłumaczenie linii i wyszukiwanie językiem naturalnym; wtyczka w pełni działa bez klucza API.
• Dashboard z selektorem okresu, pięcioma kartami KPI i dwoma wykresami trendów; osobny Log integracji rejestruje każdy push i porażkę.
• Wsparcie WordPress Multisite — każda podwitryna ma własne tabele, ustawienia i liczniki numeracji, a strona w administracji sieci agreguje statystyki.

Wymagania

Integracja z checkoutem blokowym jest rejestrowana przez WooCommerce Additional Checkout Fields API (wprowadzone w WooCommerce 8.6). Na starszych wersjach WooCommerce klasyczny filtr woocommerce_billing_fields dalej dodaje VAT, kod podatkowy i pola specyficzne dla kraju do checkoutu shortcode’owego, więc wtyczka degraduje się gracjalnie.

Instalacja

1. Pobierz najnowszy ZIP Invoice Pilota ze strony GitHubowych Releases .
2. W WordPressie otwórz Wtyczki → Dodaj nową → Wyślij wtyczkę.
3. Wybierz ZIP i kliknij Zainstaluj teraz.
4. Kliknij Włącz wtyczkę.
5. Otwórz Invoice Pilot → Ustawienia, by skonfigurować dane sprzedawcy, serie numeracji i opcjonalne integracje.

Aktywacja tworzy tabele bazy wtyczki, instaluje domyślne ustawienia i zasiewa pięć serii numeracji (jedna per typ dokumentu): INV (faktura, domyślna), REC (paragon), CN (nota kredytowa), PRO (proforma) i Q (oferta), wszystkie używające wzorca YYYY-NNNN z roczną resetacją. Zaplanowane są też cztery zadania cron: codzienne czyszczenie logu, ponawianie nieudanych pushy integracji co piętnaście minut, godzinowa rewalidacja VIES i codzienne odświeżanie tokenu Fatture in Cloud.

W WordPress Multisite ten sam bootstrap per witryna odpala się automatycznie, gdy tworzona jest nowa podwitryna (wp_initialize_site).

Konfiguracja

Wszystkie ekrany Invoice Pilota leżą pod głównym menu Invoice Pilot w bocznym pasku admina WordPressa:

• Dashboard — karty KPI i wykresy trendów.
• Dokumenty — nowoczesna data-grid listująca każdy wystawiony dokument (faktura, nota kredytowa, proforma, oferta, paragon), z jednolitym paskiem narzędzi (wyszukiwanie AI + filtr typu), kolorowymi pigułkami statusu (paid / void / converted / draft / issued), paginacją po 20 wierszy i akcjami inline PDF / XML / Usuń.
• Ustawienia — ośmiozakładkowa strona konfiguracji (udokumentowana poniżej).
• Log — wpisy logu integracji z retencją i ręczną akcją czyszczenia.

Strona Ustawień dzieli się na następujące zakładki, w kolejności pojawiania się w UI:

1. Ogólne
2. Serie
3. Typy dokumentów
4. Szablony
5. Walidacja VAT
6. Integracje
7. AI
8. Zaawansowane

Ogólne

Zakładka Ogólne jest podzielona na trzy karty: Licencja, Dane sprzedawcy i Domyślne dokumentu.

Licencja

Dane sprzedawcy zawierają tożsamość drukowaną na każdym wystawionym dokumencie; Domyślne dokumentu zawierają parę domyślnych ustawień na poziomie WooCommerce.

Serie

Zakładka Serie to tabela CRUD nad seriami numeracji trzymanymi we własnej tabeli series wtyczki. Każdy wiersz kontroluje, jak numerowane są dokumenty danego typu.

Kolumny: Slug, Wzorzec, Licznik, Reset, Domyślna, Włączona, Akcje (Edytuj / Usuń).

Formularz Dodaj / Edytuj wystawia:

Zmiana sluga aktualizuje wiersz serii w miejscu (zachowując ID i wszystkie referencje) i automatycznie migruje ustawienie default_series, jeśli wskazywało na stary slug. Usunięcie serii nie kasuje istniejących dokumentów; zachowują swoje numery.

Typy dokumentów

Zakładka Typy dokumentów przełącza opcjonalne typy dokumentów i wystawia ustawienia bollo i ritenuta specyficzne dla FatturaPA.

Karta Typy dokumentów

Karta FatturaPA — włoskie B2B

Szablony

Wybierz jeden z trzech wbudowanych szablonów PDF i dostosuj jego kolory oraz typografię.

Dodatkowe pola:

Zakładka osadza też podgląd PDF na żywo (renderowany przez endpoint REST /wp-json/invoice-pilot/v1/preview-template), dzięki czemu możesz porównywać szablony obok siebie przed zapisem. Zmiana radio przełącza iframe od razu; wybór utrwala się dopiero po wciśnięciu Zapisz szablon.

Nad iframem siedzi selektor Typ dokumentu, dzięki czemu możesz podejrzeć, jak każdy z czterech typów dokumentów jest renderowany — invoice, credit_note, proforma, quote — z tym samym szablonem, przykładowym sprzedawcą i przykładowym kupującym. Różnice stosowane per typ to:

Oferty dodatkowo zmieniają wyróżnione komórki „Wystawiono” / „Termin płatności” na Ważne do i przemianowują główny totalk na Szacunkowa kwota; noty kredytowe zmieniają go na Łączna kwota zwrotu. Te różnice biorą się z mapy nadpisań etykiet per typ i z helpera doc_type_context() podawanego do silnika szablonów, dzięki czemu trzy wbudowane projekty (Minimal / Classic / Modern) utrzymują spójną tożsamość wizualną w obrębie typów dokumentów bez dublowania plików szablonów.

Stopka zawsze pokazuje kraj kupującego w pełnej angielskiej formie (np. Germany, nie DE) — kod ISO z zamówienia jest przed renderem rozwiązywany przez PHP-owe Locale::getDisplayRegion(), dzięki czemu wyrenderowana faktura pozostaje czytelna dla ludzkich kupujących i audytorów podatkowych. Sam numer VAT sprzedawcy jest drukowany zgodnie z VAT number format on PDF w Ogólne → Domyślne dokumentu — domyślnie w stylu VIES z prefiksem (VAT IT04032690614), z opcją Bare dla jurysdykcji, które wolą sam numer.

Dispatcher dobierający właściwy envelope XML per kraj kupującego to filtr invoice_pilot_xml_writer_for_country, więc kod hosta może nadpisać per ISO (zobacz Hooks and filters).

Walidacja VAT

Identyfikatory VAT wpisane na checkoucie (i na każdym ekranie adresu, który wystawia to pole) są przepuszczane przez łańcuch walidatorów. Każdy walidator włącza się niezależnym przełącznikiem i odpala po kolei, aż któryś zwróci pozytywny wynik; zarówno udane, jak i negatywne odpowiedzi są cache’owane na skonfigurowany TTL.

Tylko do odczytu wiersz Stan cache raportuje liczbę zacache’owanych wpisów i ile z nich wygasło i czeka na eviction.

Test walidacji VAT — mała karta testera pod ustawieniami odpala każdego providera bezpośrednio na jednym numerze VAT, omijając kolejność łańcucha i cache, dzięki czemu zobaczysz, czy VIES faktycznie potwierdził numer, czy zrobił to tylko offline’owy check formatu.

Zasiej standardowe stawki VAT UE-27 — karta na dole wypełnia WooCommerce → Ustawienia → Podatek → Stawki standardowe aktualną standardową stawką VAT dla każdego państwa członkowskiego UE-27 (AT 20% BE 21% BG 20% HR 25% CY 19% CZ 21% DK 25% EE 22% FI 25.5% FR 20% DE 19% GR 24% HU 27% IE 23% IT 22% LV 21% LT 21% LU 17% MT 18% NL 21% PL 23% PT 23% RO 21% SK 23% SI 22% ES 21% SE 25%). Domyślnie wstawiane są tylko brakujące kraje; zaznacz Nadpisz istniejące stawki, aby wymusić odświeżenie każdego wiersza do wartości kanonicznej (przydatne po krajowej podwyżce VAT). Karta listuje też każdą parę (ISO, stawka), więc widzisz dokładnie, co zostanie zapisane, zanim klikniesz przycisk.

Integracje

Zakładka Integracje renderuje jeden panel per zarejestrowany dostawca integracji za pojedynczym selektorem Dostawca u góry — wybierz dostawcę, którego chcesz skonfigurować, i widoczna jest tylko jego karta, pozostałe pozostają w DOM ukryte. Selektor jest lepki między zapisami: gdy zapisujesz formularz dostawcy (albo trafiasz na zakładkę z ?integration=<id> w URL-u), kolejny render utrzymuje tego dostawcę wybranym, dzięki czemu nie zostajesz odbity do tego, który jest pierwszy w kolejności rejestracji.

Domyślnie Invoice Pilot dostarcza sześciu dostawców; kod zewnętrzny może zarejestrować dodatkowych przez filtr invoice_pilot_integration_providers.

Każdy panel dostawcy zamyka karta Status połączenia z przyciskiem Testuj połączenie. Przycisk wystawia lekkie żądanie wobec zapisanych danych i drukuje odpowiedź upstreamu — najpierw zapisz formularz, jeśli właśnie wkleiłeś nowe tokeny.

SmartBill

Rumuński dostawca fakturowania. Dane uwierzytelniające są szyfrowane at rest w symetrycznej warstwie kryptograficznej wtyczki.

Po włączeniu Invoice Pilot przy wystawieniu woła POST /SBORO/api/v2/invoice, potem pull_status na reconciliation i void, gdy faktura zostaje anulowana.

Fatture in Cloud

Włoski dostawca fakturowania. Tokeny OAuth są szyfrowane w bazie. Codzienny cron invoice_pilot_refresh_fic_token odświeża access token automatycznie, gdy integracja jest włączona.

Zgodnie z polityką produktową Fatture in Cloud, Invoice Pilot nie wysyła FatturaPA do SDI w Twoim imieniu. Wysyłka do SDI pozostaje osobnym ręcznym krokiem z poziomu Twojego konta FIC.

Xero

Globalna platforma księgowa. Tokeny OAuth 2.0 są szyfrowane w bazie. Zakładka ustawień jest podzielona na Connection (status + przyciski Connect / Disconnect) u góry oraz Settings (dane uwierzytelniające aplikacji + zachowanie pushu) poniżej.

Łączenie

Invoice Pilot dostarcza wbudowany przepływ OAuth — nie musisz już robić tego tańca w Postmanie i wklejać czterech ciągów do formularza. Konfiguracja od początku do końca wygląda tak:

1. Utwórz aplikację Web na developer.xero.com  z URI przekierowania wydrukowanym w panelu Connection — skopiuj go dosłownie, Xero porównuje go znak po znaku. Aplikacje utworzone po 2 marca 2026 mogą żądać wyłącznie granularnego zestawu uprawnień; Invoice Pilot dobiera odpowiedni automatycznie.
2. Wygeneruj Client secret na stronie aplikacji Xero (Xero pokazuje go tylko raz), następnie wklej Client ID i Client secret do formularza Settings i zapisz.
3. Kliknij Connect to Xero. Zostaniesz przeprowadzony przez standardowy ekran zgody i, jeśli Twoje konto autoryzuje więcej niż jedną organizację, zostaniesz przekierowany do selektora wewnątrz karty, by wybrać docelowego tenanta. Tokeny są wymieniane i zapisywane automatycznie.
4. Disconnect czyści access + refresh tokeny i tenant id, pozostawiając jednocześnie dane uwierzytelniające aplikacji, by ułatwić ponowne połączenie.

Pushe używają POST /Invoices ze standardowym nagłówkiem Idempotency-Key wyprowadzonym z lokalnego id faktury + numeru, więc ponowienie sieciowe zwija się do tego samego Xero InvoiceID zamiast tworzyć duplikat. Refresh token rotuje automatycznie przy 401; jeśli kiedykolwiek wygaśnie (Xero unieważnia refresh tokeny po 60 dniach braku aktywności), wystarczy kliknąć Connect ponownie.

Pola

QuickBooks Online

Intuit QuickBooks Online — US / CA / UK / globalnie. Tokeny OAuth 2.0 są szyfrowane w bazie. Zakładka ustawień jest podzielona na Connection (status + przyciski Connect / Disconnect) u góry oraz Settings (dane uwierzytelniające aplikacji + zachowanie pushu) poniżej.

Łączenie

Invoice Pilot dostarcza wbudowany przepływ OAuth — nie musisz już robić tego tańca w Postmanie i wklejać pięciu ciągów do formularza. Konfiguracja od początku do końca wygląda tak:

1. Utwórz aplikację na developer.intuit.com  z QuickBooks Online and Payments jako platformą oraz scope’em com.intuit.quickbooks.accounting. Otwórz zakładkę Keys & OAuth i przełączaj się między Development a Production w zależności od środowiska, na które celujesz — każde ma własną parę client_id + secret.
2. Dodaj URI przekierowania wydrukowany w panelu Connection do listy Redirect URIs i kliknij Save — Intuit akceptuje http://localhost dla aplikacji Development.
3. Wklej Client ID i Client secret do formularza Settings, wybierz pasujące Environment (Sandbox / Production) i zapisz.
4. Kliknij Connect to QuickBooks. Ekran zgody Intuit pozwala wybrać firmę, do której integracja ma zapisywać; wybrany realmId jest zwracany w URL-u callbacku i zapisywany automatycznie — nie ma osobnego selektora tenanta.
5. Disconnect czyści access + refresh tokeny oraz realm id, pozostawiając jednocześnie dane uwierzytelniające aplikacji, by ułatwić ponowne połączenie.

Każdy push używa POST /v3/company/{realmId}/invoice z parametrem zapytania requestid ustawionym na stabilną wartość per faktura — QBO zwija ponawiane POST-y do oryginalnej odpowiedzi, więc ponowienie sieciowe nigdy nie utworzy duplikatu. Pushe niosą też minorversion=75, dzięki czemu QBO zwraca aktualne kształty encji (bez tego API po cichu schodzi do kontraktu z 2017 roku). Refresh tokeny żyją 100 dni od wystawienia i rotują przy każdym użyciu; wtyczka obsługuje rotację transparentnie przy 401.

Pola

Fortnox

Szwedzka platforma księgowa. Dane OAuth 2.0 szyfrowane w bazie.

Sage

Platforma księgowa OAuth 2.0 (Sage Accounting / Business Cloud).

AI

Zakładka AI jest podzielona na dwie karty: Konfiguracja dostawcy i Funkcje. Wtyczka w pełni działa bez klucza API; ta zakładka dodaje opcjonalne funkcje AI.

Konfiguracja dostawcy

Modele oferowane per dostawca:

Funkcje

Zaawansowane

Retencja i odinstalowanie

Akcje konserwacyjne

• Uruchom czyszczenie logu teraz — odpala akcję invoice_pilot_cleanup_logs natychmiast, zamiast czekać na codzienny cron.
• Wyczyść cache walidacji — kasuje każdy wiersz z tabeli cache walidacji VAT.

Drobny wiersz Wersje na dole drukuje bieżącą wersję wtyczki i wersję schematu bazy.

Użytkowanie

Automatyczne wystawienie faktury z zamówienia WooCommerce

Domyślny przepływ nie wymaga żadnej ręcznej akcji.

1. Klient składa zamówienie w WooCommerce. Checkout wystawia pola Numer VAT i Kod podatkowy plus pola specyficzne dla kraju zarejestrowane dla kraju rozliczeniowego (na przykład SDI recipient code i Certified email (PEC) na zamówieniach IT). Pole VAT jest walidowane na żywo, gdy klient wpisuje — zielony badge ✓ pojawia się wewnątrz inputa, gdy łańcuch potwierdza numer, czerwony ✕ gdy zawodzi. Jeśli nabywca jest w innym państwie członkowskim UE i VAT jest poprawny, WooCommerce automatycznie zeruje VAT w koszyku (wewnątrzunijny reverse charge B2B — zob. Ustawienia → Walidacja VAT).
2. Gdy zamówienie osiąga status wyzwalający zdefiniowany w Ustawienia → Ogólne → Status wyzwalający (processing domyślnie), Invoice Pilot wystawia fakturę z użyciem Domyślnej serii (INV domyślnie), zapisuje niezmienny snapshot JSON zamówienia, renderuje PDF, generuje envelope XML dla kraju kupującego i pushuje do każdej włączonej integracji.
3. Ekran zamówienia dostaje meta box Invoice Pilot wymieniający wystawione dokumenty z linkami do PDF i XML, plus przyciski akcji Regeneruj, Wystaw ponownie, Unieważnij, Utwórz notę kredytową, Utwórz proformę, Utwórz ofertę i Push do dostawcy.

Meta box Invoice Pilot wystawia, dla najnowszego nieunieważnionego dokumentu zamówienia: numer dokumentu (np. INV-2026-0063), pigułkę statusu (Wystawiony / Opłacony / Unieważniony), przyciski pobierania PDF i XML (linki REST podpisane tokenem), akcję Regeneruj dokument, która re-renderuje artefakty wobec bieżącego szablonu i ustawień sprzedawcy bez zmiany numeru dokumentu, oraz sekcję Inne dokumenty wystawiającą przyciski jednym kliknięciem Utwórz proformę i Utwórz ofertę. Gdy włączona jest jakaś integracja, obok linków PDF / XML pojawia się przycisk Push do dostawcy, który powtarza wywołanie integracji wobec skonfigurowanego celu.

Wystawianie ręczne

Jeśli automatyczne wystawianie jest wyłączone albo zamówienie jeszcze nie osiągnęło statusu wyzwalającego, meta box zamówienia wystawia przycisk Wystaw teraz. Obowiązuje ten sam przepływ — snapshot, PDF, XML, push integracji — ale odpala się na żądanie.

Noty kredytowe ze zwrotów

Gdy Automatycznie wystawiaj notę kredytową przy zwrocie WC jest włączone (domyślnie), każdy zwrot WooCommerce utworzony wobec zamówienia z istniejącą fakturą wyzwala notę kredytową w serii CN. Nota kredytowa linkuje wstecz do faktury nadrzędnej i odnosi się do niej w XML. Wyrenderowany PDF niesie u góry baner „Zwrot dla INV-…”, pigułkę statusu CREDIT NOTE, Łączna kwota zwrotu w wyróżnionej komórce i ukrywa stopkę IBAN / metoda płatności (oryginalny przepływ płatności już nie obowiązuje). Notę kredytową możesz też wystawić ręcznie — pełną albo częściową — z karty Akcje na ekranie edycji faktury, dopóki faktura nadrzędna jest w statusie issued.

Proformy i oferty

Gdy odpowiednie przełączniki są włączone, ekran zamówienia wystawia też przyciski Utwórz proformę i Utwórz ofertę. Oba produkują dokumenty niefiskalne — PDF jest renderowany, ale dla ofert nie generuje się XML. Wyrenderowany PDF niesie wizualne potraktowanie specyficzne dla swojego typu: baner ostrzegawczy u góry („Proforma — dokument niefiskalny.” / „Oferta — dokument niefiskalny, podlega akceptacji.”), pigułkę statusu „QUOTE” / „PROFORMA” w miejsce „ISSUED”, a na ofertach wyróżniona etykieta daty zmienia się na Ważne do, a główny total na Szacunkowa kwota. Oferty ukrywają blok IBAN / metoda płatności, bo nie ma jeszcze należnej płatności.

Proformę można skonwertować na fakturę akcją Konwertuj, która przenumerowuje dokument pod skonfigurowaną serią faktur.

Wysłanie faktury klientowi

Wtyczka rejestruje akcję zamówienia Wyślij fakturę Invoice Pilot do klienta pod standardową listą akcji zamówienia WooCommerce, która e-mailuje PDF do kupującego przez wp_mail() WordPressa.

Pobieranie dokumentów

PDF-y i envelope’y XML są serwowane z publicznie adresowalnego, ale podpisanego tokenem endpointu REST:

GET /wp-json/invoice-pilot/v1/download/{id}/{format}?token=…

{format} to pdf lub xml. Token jest generowany w momencie wystawienia dokumentu i drukowany w meta boksie zamówienia i tabeli listy faktur.

Dashboard

Invoice Pilot → Dashboard otwiera kartę Przegląd aktywności nad kartą Trendy. Przegląd aktywności wystawia pasek okresów z czterema oknami — 7 dni, 14 dni, 30 dni (domyślnie) i 90 dni — oraz pięć kart KPI:

• Faktury — łączna liczba dokumentów wystawionych w danym okresie.
• Przychód netto — suma totali netto w walucie sklepu, renderowana z symbolem waluty zgodnym z locale i dwoma miejscami po przecinku (np. €3,876.09 lub 3.876,09 € w zależności od locale administratora).
• Pobrany VAT — suma totali VAT z niezmiennej migawki. Takie samo formatowanie waluty zależne od locale jak Przychód netto. Osobna migracja schematu uzupełnia tę wartość dla faktur wystawionych przed wersją schematu 1.3.1, gdzie kolumna nie była zapełniana w momencie zapisu.
• Średnia wartość — przychód netto podzielony przez liczbę faktur, również sformatowany jako waluta.
• B2B / B2C — podział faktur B2B (kupujący ma numer VAT) wobec faktur B2C w tym samym okresie.

Pod KPI karta Trendy renderuje dwa wykresy obok siebie — Invoices over time (wykres dwuosiowy line + area, z liczbą faktur na lewej osi i trendem przychodu netto wypełnionym na prawej osi) oraz By buyer country (wykres donut z najczęstszymi kodami ISO kupujących i legendą kolorów pod spodem). Wszystkie liczby są zasilane przez /wp-json/invoice-pilot/v1/dashboard?days=N.

Lista dokumentów

Invoice Pilot → Dokumenty pokazuje każdy wystawiony dokument z pigułkami statusu (paid / void / converted / draft / issued — kolorowane według stanu cyklu życia), kolumnę Compliance z kolorową odznaką produkowaną przez pre-flight check AI oraz akcje inline PDF / XML / Usuń per wiersz. Strona paginuje po 20 wierszy naraz i wystawia jednolity pasek narzędzi łączący wyszukiwanie AI wolnym tekstem z filtrem typu dokumentu (invoice / credit_note / proforma / quote / receipt) plus bieżący licznik po prawej. Gdy wyszukiwanie AI jest włączone, pole wyszukiwania przyjmuje zapytania wolnym tekstem (na przykład „niemieckie faktury w zeszłym miesiącu powyżej 1000 EUR”), które skonfigurowany dostawca tłumaczy na zapytanie listy; rozwiązane chipy filtra pojawiają się nad tabelą, dzięki czemu widzisz dokładnie, jak model rozparsował Twoje wyrażenie.

Lista zamówień WooCommerce

Invoice Pilot dodaje pojedynczą kolumnę Invoice do standardowej listy zamówień WooCommerce (/wp-admin/admin.php?page=wc-orders), dzięki czemu właściciel sklepu od razu widzi, które zamówienia mają już wystawiony dokument, a które nie, bez wychodzenia z ekranu zamówień. Kolumna siedzi między Order a Date i pokazuje numer dokumentu przypisany przez skonfigurowaną serię (na przykład INV-2026-0063) odczytany dosłownie z niezmiennej kolumny number, z małą ikonką podglądu eye obok numeru, która otwiera wyrenderowany PDF inline w nowej karcie.

Zamówienia bez wystawionego dokumentu renderują półpauzę — przydatne przy debugowaniu niezgodności statusu wyzwalającego albo filtrowaniu zamówień wymagających ręcznego uruchomienia wp invoice-pilot issue. Ten sam renderer podpina zarówno starą kolumnę tabeli postów (manage_edit-shop_order_columns), jak i kolumnę HPOS (manage_woocommerce_page_wc-orders_columns), więc doświadczenie jest identyczne niezależnie od tego, na której warstwie storage zamówień pracuje Twój sklep.

Log integracji

Invoice Pilot → Log zapisuje każdy push integracji, odpowiedź i porażkę. Pasek narzędzi u góry łączy selektor Bulk actions + przycisk Apply (obecnie jednoakcyjne bulk-delete), listę dostawca i listę akcja — obie wypełnione wartościami faktycznie obecnymi w logu, dzięki czemu pokazują wyłącznie filtry pasujące do realnego wiersza — oraz bieżący licznik wpisów po prawej.

Data-grid niesie osiem kolumn:

Wrażliwe pola payloadu są redagowane przy zapisie przez Core\Logger wtyczki, więc ciała żądań i odpowiedzi można bezpiecznie trzymać w logu. Stare wpisy są kasowane przez codzienny cron invoice_pilot_cleanup_logs zgodnie z ustawieniem Retencja logu (dni) w zakładce Zaawansowane.

Network admin (Multisite)

W sieci Multisite w bocznym pasku network admin pojawia się dodatkowa strona Invoice Pilot Network. Agreguje liczby faktur i totale we wszystkich podwitrynach, które mają aktywnego Invoice Pilota.

Fakturowanie UE-27

Invoice Pilot dostarcza rejestr pól rozliczeniowych specyficznych dla kraju dla każdego z 27 państw członkowskich UE. Każde pole jest na checkoucie opcjonalne (wtyczka nie wymusza danych B2B-only na zamówieniu B2C); walidacja odpala się tylko, gdy kraj kupującego pasuje do ISO pola.

Rejestr obecnie pokrywa:

Integracja z checkoutem blokowym rejestruje pola w przestrzeni invoice-pilot/... przez Additional Checkout Fields API. Domyślnie na checkoucie blokowym wystawione są tylko pola włoskie, by nie zalewać kupujących spoza Włoch; przełącznik Wszystkie pola UE-27 na checkoucie w Ogólne włącza pełen zestaw. Klasyczny checkout shortcode’owy zawsze renderuje cały rejestr przefiltrowany przez wybrany kraj rozliczeniowy.

Pola krajów są utrwalane na zamówieniu, kopiowane do niezmiennego snapshotu faktury i konsumowane przez writery XML — na przykład włoski ei_recipient_code staje się CodiceDestinatario / PECDestinatario w envelopie FatturaPA, a niemiecki leitweg_id staje się BuyerReference / EndpointID 0204 w XRechnung.

Integracje

SmartBill

SmartBill (Rumunia) jest podpięty do IntegrationManager wtyczki przez filtr invoice_pilot_integration_providers i wystawia standardowy interfejs dostawcy: push, pull_status, void i test_connection.

• Push mapuje snapshot faktury na schemat JSON SmartBill i woła POST /SBORO/api/v2/invoice ze skonfigurowanym CIF i serią.
• Status sync uzgadnia stan draft / issued / paid, gdy odpala się piętnastominutowy cron ponawiania.
• Void anuluje wcześniej pushowaną fakturę w SmartBill, gdy faktura źródłowa jest unieważniana w WordPressie.

Wszystkie akcje są logowane do Logu integracji. Porażki są kolejkowane i ponawiane przez cron invoice_pilot_retry_integrations.

Fatture in Cloud

Fatture in Cloud (Włochy) trzyma się tego samego interfejsu dostawcy i mapuje snapshot faktury na kształt entity / items_list oczekiwany przez endpoint dokumentu wystawionego w FIC. Włoskie pola specyficzne dla kraju są mapowane jawnie:

• ei_recipient_code → ei_code
• ei_certified_email → certified_email
• VAT kupującego / kod podatkowy / prowincja / kraj → odpowiednie klucze entity

Dane OAuth są szyfrowane w bazie. Codzienny cron invoice_pilot_refresh_fic_token odświeża access token, gdy integracja jest włączona. Ustawienie Twórz klientów na włączone powoduje, że integracja tworzy nowy rekord klienta w FIC przy pierwszej fakturze dla danego kupującego.

Invoice Pilot nie wysyła FatturaPA do SDI w Twoim imieniu. Wysyłka do SDI pozostaje osobnym ręcznym krokiem z poziomu Twojego konta Fatture in Cloud.

AI smart-fill

Warstwa AI jest w pełni opcjonalna. Bez skonfigurowanego klucza API wtyczka dalej wystawia faktury, renderuje PDF-y i XML, waliduje VAT i pushuje do integracji — niedostępne są tylko cztery funkcje AI niżej.

Wspieranych jest pięciu dostawców:

Klucz API jest trzymany zaszyfrowany w bazie w symetrycznej warstwie kryptograficznej wtyczki. Wciśnięcie Testuj połączenie wystawia minimalne żądanie do wybranego endpointu i powierzchowuje błąd upstreamu, jeśli dane są błędne.

Cztery funkcje da się przełączać niezależnie, gdy klucz jest w bazie:

• Smart-fill na checkoucie — na checkoucie pojawia się pole „Wklej dane rozliczeniowe”. Model parsuje wolny tekst i wypełnia formularz rozliczeniowy WooCommerce, łącznie z polami specyficznymi dla kraju. Limit rate per sesja.
• Pre-flight check compliance — każda faktura jest przepuszczana przez model tuż przed wystawieniem, z opcją blokowania wystawienia przy znaleziskach poziomu error, gdy wykryto krytyczny problem (na przykład włoska faktura B2B bez kodu odbiorcy SDI).
• Auto-tłumaczenie linii — opisy linii faktur są tłumaczone na język kupującego. Gdy bratnia wtyczka Polyglot  jest zainstalowana, pipeline tłumaczenia jest delegowany do niej.
• Wyszukiwanie dokumentów językiem naturalnym — pole wyszukiwania na stronie admina Dokumenty przyjmuje zapytania wolnym tekstem, które model tłumaczy na zapytanie listy.

Każda funkcja ma własny limit rate per godzina.

Hooks and filters

Scentralizowane nazwy hooków leżą w klasie \InvoicePilot\Core\Hooks. Pełna lista:

Rejestracja własnego writera XML:

add_filter(
    'invoice_pilot_xml_writer_for_country',
    function ( $writer, $iso ) {
        if ( 'NL' === $iso ) {
            return new My_Custom_Nl_Writer();
        }
        return $writer;
    },
    20,
    2
);

Rejestracja własnego dostawcy integracji:

add_filter(
    'invoice_pilot_integration_providers',
    function ( array $providers ) {
        $providers[] = new My_Custom_Provider();
        return $providers;
    }
);

Ukrywanie lub rozszerzanie pól checkoutu specyficznych dla kraju (na przykład aby usunąć monity ei_certified_email (PEC) i fiscal_regime (kod RF) Włoch, gdy Twój sklep nigdy ich nie potrzebuje — bez forkowania wtyczki):

add_filter(
    'invoice_pilot_country_fields',
    function ( array $fields, string $iso ) {
        if ( 'IT' === $iso ) {
            $fields = array_values(
                array_filter(
                    $fields,
                    fn ( $f ) => ! in_array(
                        $f->name,
                        [ 'ei_certified_email', 'fiscal_regime' ],
                        true
                    )
                )
            );
        }
        return $fields;
    },
    10,
    2
);

Filtr działa zarówno na ścieżce walidacji submitu PHP, jak i na snapshot JS dostarczanym do checkoutu WC Blocks, dzięki czemu obie warstwy pozostają zsynchronizowane. Nazwy maszynowe pól obecnie dostarczanych (użyj ich w filtrze):

Pełny rejestr per kraj jest zdefiniowany w CountryFieldRegistry::install_defaults() i obejmuje wszystkie ISO EU-27.

FAQ

Czy Invoice Pilot wysyła FatturaPA do SDI?

Nie. Invoice Pilot generuje XML FatturaPA i trzyma go na zamówieniu; wysyłka do SDI jest celowo zostawiona jako osobny ręczny krok (albo integracja Fatture in Cloud na Twoim koncie).

Czy mogę dodać writer dla kraju, którego nie ma w pakiecie?

Tak. Podepnij się pod invoice_pilot_xml_writer_for_country i zwróć własną implementację \InvoicePilot\Modules\Xml\XmlWriterInterface.

Czy działa na checkoucie blokowym WooCommerce?

Tak. Pola specyficzne dla kraju są rejestrowane przez Additional Checkout Fields API z WooCommerce 8.6+, więc pojawiają się i na checkoucie blokowym, i na klasycznym checkoucie shortcode’owym. Na wersjach WooCommerce starszych niż 8.6 używana jest tylko klasyczna ścieżka filtra.

Czy działa na WordPress Multisite?

Tak. Każda podwitryna ma własne tabele, ustawienia i liczniki numeracji. Strona network admin pod Network Admin → Invoice Pilot Network agreguje liczby faktur w sieci. Na nowych podwitrynach tabele i domyślne serie są tworzone automatycznie przez hook wp_initialize_site.

Czy dane uwierzytelniające są szyfrowane?

Tak. Tokeny SmartBill, tokeny OAuth Fatture in Cloud i klucz API AI są szyfrowane w bazie przez \InvoicePilot\Core\Crypto. Pozostawienie pola tokenu pustego przy kolejnym zapisie zachowuje istniejącą zapisaną wartość.

Co stanie się z moimi danymi, jeśli skasuję wtyczkę?

Nic, chyba że tego chcesz. Domyślne Zaawansowane → Wyczyść dane przy odinstalowaniu to wyłączone, więc tabele, opcje, logi integracji i cache walidacji są zachowywane między dezaktywacją i reaktywacją. Włącz tę opcję, jeśli chcesz, by rutyna uninstall.php skasowała wszystko, gdy WordPress kasuje wtyczkę.

Skąd wziąć klucz API do funkcji AI?

Każdy dostawca ma własną konsolę: Anthropic na console.anthropic.com , OpenAI na platform.openai.com , Google AI Studio na aistudio.google.com , DeepSeek na platform.deepseek.com  i Grok na console.x.ai . Zakładka AI linkuje wprost do konsoli wybranego dostawcy.

Czy potrzebuję klucza AI, żeby wtyczka działała?

Nie. Funkcje AI (smart-fill, sprawdzanie compliance, tłumaczenie linii, wyszukiwanie językiem naturalnym) są opcjonalne. Główny silnik fakturowy — cykl życia dokumentów, generowanie PDF i XML, walidacja VAT, integracje, dashboard — działa bez klucza API.

Rozwiązywanie problemów

Faktura nie wystawia się, gdy zamówienie przechodzi w Processing

Sprawdź Ustawienia → Ogólne → Status wyzwalający. Domyślny to processing; jeśli go zmieniłeś (np. na completed), rutyna auto-issue odpala się tylko na skonfigurowanym statusie. Możesz też wystawić ręcznie przyciskiem Wystaw teraz z meta boksu zamówienia, niezależnie od wyzwalacza.

Checkout pokazuje za dużo (lub za mało) pól krajów

Domyślnie wystawione są tylko włoskie pola SDI. Otwórz Ustawienia → Ogólne → Document defaults → Pola fakturowania specyficzne dla kraju i wybierz zakres:

• Wyłączone — pokazywane są tylko uniwersalne pola VAT i kodu fiskalnego.
• Tylko Włochy (SDI / PEC / reżim fiskalny) — domyślnie.
• Wszystkie pola UE-27 specyficzne dla kraju — każde ISO z rejestru.

Ustawienie działa zarówno na checkoucie blokowym, jak i klasycznym checkoucie shortcode’owym. Pola specyficzne dla kraju są nadal ukrywane po stronie klienta, gdy kraj rozliczeniowy nie pasuje.

Walidacja VAT wisi albo wpada w timeout

Usługa VIES bywa wolna albo niedostępna. Wtyczka trzyma cache per VAT na skonfigurowany TTL (24 godziny domyślnie) i rewaliduje stare wpisy co godzinę przez cron invoice_pilot_revalidate_vies. Gdy VIES jest offline, walidator Format per kraj dalej akceptuje poprawnie sformatowane numery. Możesz też podnieść TTL cache w Ustawienia → Walidacja VAT.

Dashboard nie pokazuje danych

SQL dashboardu polega na JSON_EXTRACT / JSON_UNQUOTE wobec niezmiennej kolumny snapshot faktury. Upewnij się, że Twój serwer bazodanowy to MySQL 5.7+ albo MariaDB 10.2+. Jeśli pasek okresu pokazuje właściwe okno, ale karty zostają na --, otwórz /wp-json/invoice-pilot/v1/dashboard?days=30 bezpośrednio i sprawdź odpowiedź — porażki uwierzytelnienia REST pojawiają się jako rest_forbidden.

Push integracji zawodzi

Otwórz Invoice Pilot → Log i znajdź nieudany wpis — kolumna HTTP flaguje odpowiedzi spoza 2xx kolorową odznaką, a kolumna Error pokazuje komunikat błędu upstreamu na czerwono. Nieudany wpis jest automatycznie ponawiany przez cron invoice_pilot_retry_integrations co piętnaście minut; możesz też wcisnąć Push do dostawcy w meta boksie zamówienia, by ponowić od razu. Akcji Usuń na wierszu używaj, by wyczyścić jednorazowy wpis bez czekania na cron retencji.

Testuj połączenie w zakładce AI raportuje błąd

Komunikat zwrócony na czerwono leci wprost z endpointu dostawcy. Typowe przyczyny:

• Nieprawidłowy albo unieważniony klucz API — wygeneruj nowy i wklej go w pole Klucz API, a potem zapisz.
• Nazwa modelu, do której konto nie ma dostępu — wybierz inny model z listy.
• Wychodzący ruch zablokowany przez hosting — sprawdź, czy wychodzące HTTPS do api.anthropic.com, api.openai.com, generativelanguage.googleapis.com, api.deepseek.com lub api.x.ai jest dozwolone.

Maile do klienta nie docierają

Maile z fakturą do klienta są wysyłane przez funkcję wp_mail() WordPressa. Jeśli żaden mail nie dochodzi, problem prawie zawsze leży w konfiguracji poczty witryny, a nie w Invoice Pilocie. Zainstaluj wtyczkę poczty transakcyjnej (na przykład taką, która kieruje pocztę WordPressa przez SMTP) i ponownie wyzwól akcję zamówienia Wyślij fakturę Invoice Pilot do klienta z testowego zamówienia.