Invoice Pilot

Invoice Pilot erweitert WooCommerce um länderspezifische Rechnungsstellung für alle 27 EU-Mitgliedstaaten. Schon am Checkout werden die richtigen Rechnungsfelder erfasst (italienische SDI-/PEC-Codes, französische SIRET, deutsche Leitweg-ID, polnische NIP, rumänische CUI usw.); anschließend werden aus der Bestellung unveränderliche PDF- und XML-Rechnungen, Gutschriften, Proforma- und Angebotsdokumente erzeugt. Das PDF wird mit mPDF gerendert; der XML-Container wird anhand des Käuferlandes automatisch gewählt und deckt elf nationale Profile ab, darunter FatturaPA (IT), XRechnung (DE), KSeF FA(2) (PL), Factur-X (FR), CIUS_RO (RO), Facturae (ES) sowie UBL 2.1 / PEPPOL BIS 3.0 als generischer Fallback.

Über die Dokument-Engine hinaus bringt Invoice Pilot erstklassige Integrationen mit sechs Buchhaltungs-Anbietern mit — SmartBill (Rumänien), Fatture in Cloud (Italien), Xero, QuickBooks Online, Fortnox (Schweden) und Sage —, einen VAT-Validator, der den europäischen VIES-Dienst mit einem länderspezifischen Format-Fallback kombiniert, ein Dashboard mit KPI-Karten und Trend-Charts sowie eine optionale Multi-Provider-KI-Schicht (Anthropic Claude, OpenAI, Google Gemini, DeepSeek, Grok xAI) für Checkout-Smart-Fill, Compliance-Pre-Flight, Zeilenübersetzung und natürlichsprachige Dokumentensuche. Das Plugin unterstützt zudem WordPress-Multisite mit eigenen Tabellen pro Site und einer netzwerkweiten Übersicht.

Highlights

• WooCommerce-getriebener Dokument-Lebenszyklus für Rechnungen, Gutschriften, Proforma-Dokumente und Angebote, mit reservierten Nummernkreisen, einem sauberen Issue-/Regenerate-/Reissue-/Void-/ Credit-Note-Flow und dokumenttyp-spezifischem Styling (Disclaimer-Banner bei nicht-fiskalischen Dokumenten, „Gültig bis”-Labels bei Angeboten, „Erstattungsbetrag” bei Gutschriften, Zahlungsblock bei Angebot und Gutschrift ausgeblendet).
• Länderspezifische EU-27-Rechnungsfelder, sowohl gegen den klassischen Shortcode-Checkout als auch gegen den Block-Checkout ab WooCommerce 8.6 registriert (über die Additional Checkout Fields API).
• PDF-Rendering über mPDF mit einer von drei mitgelieferten Vorlagen (Minimal, Classic, Modern), inklusive Picker für Akzentfarbe, Textfarbe, Schriftart und Verkäufer-Logo.
• Elf XML-Writer, die automatisch nach Käuferland gewählt werden: 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) — mit UBL 2.1 / PEPPOL BIS 3.0 als universellem Fallback.
• VAT-Validierungskette, die den europäischen VIES-SOAP-Dienst mit länderspezifischer Offline-Regex-Validierung kombiniert, ergänzt um einen DB-gestützten Cache und einen stündlichen Cron, der veraltete Einträge erneut validiert.
• Sechs Buchhaltungs-Integrationen — SmartBill, Fatture in Cloud, Xero, QuickBooks Online, Fortnox und Sage — jeweils mit verschlüsselten Zugangsdaten, Push-/Status-/Void-Operationen und einer Retry-Queue. Der Integrations-Tab nutzt einen klebrigen Provider-Selektor, sodass das Panel, das Sie gerade konfigurieren, über Speichervorgänge hinweg geöffnet bleibt.
• Optionale KI-Schicht mit fünf Anbietern (Anthropic, OpenAI, Google Gemini, DeepSeek, Grok xAI), die Smart-Fill, Compliance-Check, Zeilenübersetzung und natürlichsprachige Suche abdeckt; das Plugin funktioniert vollständig auch ohne API-Key.
• Dashboard mit Zeitraumwahl, fünf KPI-Karten und zwei Trend-Charts; ein separates Integrations-Log erfasst jeden Push und jeden Fehler.
• WordPress-Multisite-Unterstützung — jede Sub-Site hat eigene Tabellen, Einstellungen und Nummernzähler, plus eine Netzwerk-Admin-Seite, die Statistiken aggregiert.

Voraussetzungen

Die Block-Checkout-Integration ist gegen die Additional Checkout Fields API von WooCommerce registriert (eingeführt mit WooCommerce 8.6). Auf älteren WooCommerce-Versionen fügt der klassische Filter woocommerce_billing_fields weiterhin VAT-, Steuernummer- und länderspezifische Felder in den Shortcode-Checkout ein — das Plugin degradiert also sauber.

Installation

1. Laden Sie das aktuelle Invoice-Pilot-ZIP aus der GitHub-Seite Releases  herunter.
2. Öffnen Sie in WordPress Plugins → Installieren → Plugin hochladen.
3. Wählen Sie das ZIP aus und klicken Sie auf Jetzt installieren.
4. Klicken Sie auf Plugin aktivieren.
5. Öffnen Sie Invoice Pilot → Einstellungen, um Verkäuferdaten, Nummernkreise und optionale Integrationen zu konfigurieren.

Bei der Aktivierung legt das Plugin seine Datenbanktabellen an, installiert die Standardeinstellungen und legt fünf Nummernkreise an (einen pro Dokumenttyp): INV (Rechnung, Standard), REC (Beleg), CN (Gutschrift), PRO (Proforma) und Q (Angebot), alle mit dem Muster YYYY-NNNN und jährlichem Reset. Zudem werden vier Cron-Jobs geplant: tägliches Log-Cleanup, alle fünfzehn Minuten Retry für fehlgeschlagene Integrations-Pushes, stündliche VIES-Revalidierung und tägliche Aktualisierung des Fatture-in-Cloud-Tokens.

Unter WordPress-Multisite läuft dasselbe Bootstrap pro Site automatisch, sobald eine neue Sub-Site angelegt wird (wp_initialize_site).

Konfiguration

Alle Bildschirme von Invoice Pilot liegen unter dem Hauptmenüpunkt Invoice Pilot in der WordPress-Admin-Seitenleiste:

• Dashboard — KPI-Karten und Trend-Charts.
• Dokumente — moderne Datentabelle mit jedem ausgestellten Dokument (Rechnung, Gutschrift, Proforma, Angebot, Beleg) mit vereinheitlichter Toolbar (KI-Suche + Typfilter), farblich kodierten Status-Pills (paid / void / converted / draft / issued), 20-zeiliger Paginierung und Inline-Aktionen für PDF / XML / Löschen.
• Einstellungen — Konfigurationsseite mit acht Tabs (unten dokumentiert).
• Log — Einträge des Integrations-Logs mit Aufbewahrung und manueller Cleanup-Aktion.

Die Einstellungsseite ist in folgende Tabs aufgeteilt — in der Reihenfolge, in der sie in der UI erscheinen:

1. Allgemein
2. Nummernkreise
3. Dokumenttypen
4. Vorlagen
5. VAT-Validierung
6. Integrationen
7. AI
8. Erweitert

Allgemein

Der Tab Allgemein ist in drei Karten unterteilt: Lizenz, Verkäuferdaten und Dokument-Defaults.

Lizenz

Die Karte Verkäuferdaten enthält die Identität, die auf jedem ausgestellten Dokument gedruckt wird; Dokument-Defaults enthält eine kleine Anzahl WooCommerce-spezifischer Vorgaben.

Nummernkreise

Der Tab Nummernkreise ist eine CRUD-Tabelle über die Nummernkreise, die in der eigenen series-Tabelle des Plugins liegen. Jede Zeile bestimmt, wie Dokumente eines bestimmten Typs nummeriert werden.

Spalten: Slug, Muster, Zähler, Reset, Standard, Aktiv, Aktionen (Bearbeiten / Löschen).

Das Formular „Hinzufügen / Bearbeiten” zeigt:

Beim Umbenennen eines Slugs wird die Series-Zeile in place aktualisiert (Ganzzahl-ID und Verweise bleiben erhalten), und die Einstellung default_series wird automatisch mitgezogen, falls sie auf den alten Slug zeigte. Das Löschen eines Nummernkreises entfernt keine bestehenden Dokumente — diese behalten ihre Nummern.

Dokumenttypen

Der Tab Dokumenttypen schaltet optionale Dokumenttypen ein oder aus und enthält die FatturaPA-spezifischen Einstellungen für bollo und ritenuta.

Karte Dokumenttypen

Karte FatturaPA — italienisches B2B

Vorlagen

Wählen Sie eine der drei mitgelieferten PDF-Vorlagen und passen Sie Farben und Typografie an.

Zusätzliche Felder:

Der Tab bettet zudem eine Live-PDF-Vorschau ein (gerendert über den REST-Endpunkt /wp-json/invoice-pilot/v1/preview-template), sodass Sie Vorlagen vor dem Speichern vergleichen können. Ein Wechsel des Radio-Buttons tauscht das iframe sofort; die Auswahl wird erst dauerhaft, wenn Sie Vorlage speichern drücken.

Über dem iframe sitzt ein Dokumenttyp-Wähler, mit dem Sie die Darstellung jedes der vier Dokumenttypen vorab prüfen — invoice, credit_note, proforma, quote — mit derselben Vorlage, demselben Beispiel-Verkäufer und demselben Beispiel-Käufer. Pro Typ gelten folgende Unterschiede:

Angebote benennen die prominenten Felder „Ausgestellt” / „Fällig am” zusätzlich in Gültig bis um und den Hero-Gesamtwert in Geschätzter Gesamtbetrag; Gutschriften benennen ihn in Erstattungsbetrag um. Diese Unterschiede stammen aus einer typenspezifischen Label-Override-Map und einem doc_type_context()-Helper, der in die Template-Engine fließt — die drei mitgelieferten Designs (Minimal / Classic / Modern) behalten so dokumenttyp-übergreifend ein konsistentes visuelles Erscheinungsbild, ohne dass Template-Dateien dupliziert werden.

Der Footer enthält das Käuferland immer in seiner ausgeschriebenen englischen Form (z.B. Germany, nicht DE) — der ISO-Code aus der Bestellung wird vor dem Rendern über PHPs Locale::getDisplayRegion() aufgelöst, damit die gerenderte Rechnung sowohl für menschliche Käufer als auch für Steuerprüfer lesbar bleibt. Die Verkäufer-USt-IdNr. selbst wird gemäß VAT-Format auf PDF in Allgemein → Standardwerte gedruckt — standardmäßig im VIES-Präfix-Stil (VAT IT04032690614), mit der Option Ohne für Rechtsräume, die die nackte Nummer bevorzugen.

Der Dispatcher, der den richtigen XML-Container pro Käuferland auswählt, ist der Filter invoice_pilot_xml_writer_for_country — Host-Code kann ihn pro ISO überschreiben (siehe Hooks und Filter).

VAT-Validierung

Am Checkout (und auf jedem Adress-Bildschirm, der das Feld enthält) eingegebene VAT-IDs durchlaufen eine Kette von Validatoren. Jeder Validator wird über einen eigenen Schalter aktiviert und läuft in der Reihenfolge, bis einer ein positives Ergebnis liefert; sowohl positive als auch negative Antworten werden für die konfigurierte TTL gecached.

Eine schreibgeschützte Zeile Cache-Status zeigt die Anzahl der gecachten Einträge sowie wie viele davon abgelaufen und zur Eviction vorgemerkt sind.

Test VAT-Validierung — eine kleine Tester-Karte unterhalb der Einstellungen führt jeden Provider direkt gegen eine einzelne VAT-ID aus, umgeht die Kettenreihenfolge und den Cache, sodass Sie sehen, ob VIES die Nummer tatsächlich bestätigt hat oder nur die Offline-Formatprüfung.

EU-27-Standard-MwSt-Sätze einspielen — die unterste Karte füllt WooCommerce → Einstellungen → Steuer → Standard-Sätze mit dem aktuellen Standard-MwSt-Satz für jeden EU-27-Mitgliedstaat (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%). Standardmäßig werden nur fehlende Länder eingefügt; aktivieren Sie Bestehende Sätze überschreiben, um jedes Land auf den kanonischen Wert zu setzen (nützlich, nachdem die EU einen nationalen Satz angepasst hat). Die Karte listet auch jede (ISO, Satz)-Kombination, damit Sie genau sehen, was geschrieben wird, bevor Sie den Button drücken.

Integrationen

Der Integrations-Tab rendert ein Panel pro registriertem Integrations-Anbieter hinter einem einzigen Anbieter-Selektor oben — wählen Sie den Anbieter, den Sie konfigurieren möchten, und nur dessen Karte ist sichtbar; die übrigen bleiben verborgen im DOM. Der Selektor bleibt über Speichervorgänge hinweg klebrig: Wenn Sie das Formular eines Anbieters speichern (oder den Tab mit ?integration=<id> in der URL aufrufen), bleibt beim nächsten Rendern dieser Anbieter ausgewählt — Sie werden also nicht zurück auf den als Erstes registrierten Anbieter geworfen.

Standardmäßig bringt Invoice Pilot sechs Anbieter mit; Drittanbieter-Code kann weitere über den Filter invoice_pilot_integration_providers registrieren.

Jedes Anbieter-Panel schließt mit einer Karte Verbindungsstatus und einem Button Verbindung testen ab. Der Button setzt einen leichten Request gegen die gespeicherten Zugangsdaten ab und druckt die Antwort der Gegenstelle aus — speichern Sie das Formular zuerst, falls Sie gerade neue Token eingefügt haben.

SmartBill

Rumänischer Rechnungsdienst. Zugangsdaten werden mit der symmetrischen Crypto-Schicht des Plugins verschlüsselt gespeichert.

Wenn aktiv, ruft Invoice Pilot beim Ausstellen POST /SBORO/api/v2/invoice auf, anschließend pull_status zur Reconciliation und void, sobald eine Rechnung storniert wird.

Fatture in Cloud

Italienischer Rechnungsdienst. OAuth-Tokens werden verschlüsselt gespeichert. Der tägliche Cron invoice_pilot_refresh_fic_token aktualisiert den Access-Token automatisch, sobald die Integration aktiv ist.

Gemäß der Produkt-Policy von Fatture in Cloud reicht Invoice Pilot FatturaPA nicht in Ihrem Namen beim SDI ein. Die SDI-Einreichung bleibt ein separater manueller Schritt innerhalb Ihres FIC-Kontos.

Xero

Globale Buchhaltungsplattform. OAuth-2.0-Tokens werden verschlüsselt gespeichert. Der Einstellungs-Tab ist oben in Connection (Status + Schaltflächen Connect / Disconnect) und darunter in Settings (App-Zugangsdaten + Push-Verhalten) gegliedert.

Verbindung herstellen

Invoice Pilot bringt einen integrierten OAuth-Flow mit — Sie müssen nicht mehr den Tanz in Postman aufführen und vier Strings in das Formular einfügen. Die End-to-End-Einrichtung sieht so aus:

1. Legen Sie auf developer.xero.com  eine Web-App mit der im Connection-Panel angezeigten Redirect-URI an — kopieren Sie diese wortwörtlich, Xero vergleicht sie zeichenweise. Apps, die nach dem 2. März 2026 angelegt werden, können nur das granulare Scope-Set anfordern; Invoice Pilot wählt das passende automatisch.
2. Generieren Sie auf der Xero-App-Seite ein Client secret (Xero zeigt es nur einmal an), fügen Sie anschließend Client ID und Client secret in das Settings-Formular ein und speichern Sie.
3. Klicken Sie auf Connect to Xero. Sie werden durch den üblichen Zustimmungsbildschirm geführt; wenn Ihr Konto mehr als eine Organisation autorisiert, werden Sie auf einen In-Card-Picker weitergeleitet, um den Ziel-Tenant auszuwählen. Tokens werden automatisch ausgetauscht und persistiert.
4. Disconnect löscht Access- und Refresh-Token sowie die Tenant-ID, behält aber die App-Zugangsdaten, damit ein erneutes Verbinden mühelos möglich ist.

Pushes verwenden POST /Invoices mit dem Standard-Header Idempotency-Key, der aus der lokalen Rechnungs-ID + Nummer abgeleitet wird, sodass ein Netzwerk-Retry auf dieselbe Xero-InvoiceID zusammenfällt, anstatt ein Duplikat anzulegen. Das Refresh-Token wird bei einer 401 automatisch rotiert; sollte es einmal ablaufen (Xero invalidiert Refresh-Tokens nach 60 Tagen Inaktivität), klicken Sie einfach erneut auf Connect.

Felder

QuickBooks Online

Intuit QuickBooks Online — US / CA / UK / global. OAuth-2.0-Tokens werden verschlüsselt gespeichert. Der Settings-Tab ist mit Connection (Status + Connect-/Disconnect-Buttons) oben und Settings (App-Zugangsdaten + Push-Verhalten) darunter aufgebaut.

Verbindung

Invoice Pilot bringt einen integrierten OAuth-Flow mit — Sie müssen den Tanz in Postman nicht mehr aufführen und fünf Strings in das Formular einfügen. Das End-to-End-Setup ist:

1. Legen Sie auf developer.intuit.com  eine App mit QuickBooks Online and Payments als Plattform und dem Scope com.intuit.quickbooks.accounting an. Öffnen Sie den Tab Keys & OAuth und wechseln Sie zwischen Development und Production, je nachdem welche Umgebung Sie ansprechen — jede hat ihr eigenes Paar aus client_id und secret.
2. Fügen Sie die im Connection-Panel angezeigte Redirect-URI in die Liste Redirect URIs ein und klicken Sie auf Save — Intuit akzeptiert http://localhost für Development-Apps.
3. Fügen Sie Client ID und Client secret in das Settings-Formular ein, wählen Sie das passende Environment (Sandbox / Production) und speichern Sie.
4. Klicken Sie auf Connect to QuickBooks. Im Zustimmungsbildschirm von Intuit wählen Sie das Unternehmen, in das die Integration schreiben soll; die gewählte realmId wird in der Callback-URL zurückgegeben und automatisch gespeichert — es gibt keinen separaten Tenant-Picker.
5. Disconnect löscht Access- und Refresh-Token sowie die Realm-ID, behält aber die App-Zugangsdaten, damit ein erneutes Verbinden mühelos möglich ist.

Jeder Push verwendet POST /v3/company/{realmId}/invoice mit dem Query-Parameter requestid, der auf einen stabilen, pro Rechnung festen Wert gesetzt wird — QBO fasst wiederholte POSTs zur ursprünglichen Antwort zusammen, sodass ein Netzwerk-Retry niemals ein Duplikat erzeugt. Pushes führen außerdem minorversion=75 mit, damit QBO aktuelle Entity-Formen zurückgibt (ohne diesen Wert stuft das API stillschweigend auf den Vertrag aus 2017 herunter). Refresh-Tokens sind ab Ausstellung 100 Tage gültig und rotieren bei jeder Verwendung; das Plugin behandelt die Rotation bei einer 401 transparent.

Felder

Fortnox

Schwedische Buchhaltungsplattform. OAuth-2.0-Zugangsdaten verschlüsselt gespeichert.

Sage

OAuth-2.0-Buchhaltungsplattform (Sage Accounting / Business Cloud).

AI

Der AI-Tab gliedert sich in zwei Karten: Provider-Konfiguration und Features. Das Plugin funktioniert vollständig auch ohne API-Key; dieser Tab ergänzt optionale KI-gestützte Funktionen.

Provider-Konfiguration

Modelle pro Provider:

Features

Erweitert

Aufbewahrung & Deinstallation

Wartungsaktionen

• Log-Cleanup jetzt ausführen — löst die Aktion invoice_pilot_cleanup_logs sofort aus, statt auf den täglichen Cron zu warten.
• Validierungs-Cache leeren — entfernt jede Zeile aus der VAT-Validierungs-Cache-Tabelle.

Eine kleine Versionen-Zeile am unteren Rand zeigt die aktuelle Plugin-Version und die DB-Schema-Version.

Nutzung

Eine Rechnung aus einer WooCommerce-Bestellung automatisch ausstellen

Der Standard-Workflow erfordert keinen manuellen Eingriff.

1. Ein Kunde gibt in WooCommerce eine Bestellung auf. Der Checkout zeigt die Felder VAT-Nummer und Steuernummer sowie alle länderspezifischen Felder, die für das Rechnungsland registriert sind (z. B. SDI recipient code und Certified email (PEC) bei IT-Bestellungen). Das VAT-Feld validiert live, während der Kunde tippt — ein grünes ✓-Badge erscheint im Input, wenn die Kette die Nummer bestätigt, ein rotes ✕, wenn sie fehlschlägt. Ist der Käufer in einem anderen EU-Mitgliedstaat und die VAT ist gültig, setzt WooCommerce die MwSt im Warenkorb automatisch auf null (innergemeinschaftlicher B2B-Reverse-Charge — siehe Einstellungen → VAT-Validierung).
2. Erreicht die Bestellung den Trigger-Status aus Einstellungen → Allgemein → Trigger-Status (standardmäßig processing), stellt Invoice Pilot eine Rechnung im Standardnummernkreis (INV) aus, legt einen unveränderlichen JSON-Snapshot der Bestellung an, rendert das PDF, erzeugt das XML-Envelope für das Käuferland und pusht in jede aktive Integration.
3. Der Bestell-Bildschirm erhält eine Invoice-Pilot-Metabox, die die ausgestellten Dokumente mit Links auf PDF und XML auflistet — plus Schaltflächen für Neu generieren, Neu ausstellen, Stornieren, Gutschrift erstellen, Proforma erstellen, Angebot erstellen und An Anbieter pushen.

Die Invoice-Pilot-Metabox zeigt für das jüngste nicht stornierte Dokument der Bestellung Folgendes an: die Dokument-Nummer (z. B. INV-2026-0063), die Status-Pill (Issued / Paid / Void), die Download-Buttons PDF und XML (token-signierte REST-Links), eine Aktion Dokument neu generieren, die die Artefakte gegen die aktuelle Vorlage und die aktuellen Verkäuferdaten neu rendert, ohne die Dokumentnummer zu ändern, sowie einen Bereich Andere Dokumente, der Ein-Klick-Buttons Proforma erstellen und Angebot erstellen bereitstellt. Ist eine Integration aktiv, erscheint zusätzlich neben den PDF- / XML-Links ein Button An Anbieter pushen, der den Integrationsaufruf gegen das konfigurierte Ziel wiederholt.

Manuelles Ausstellen

Falls die automatische Ausgabe deaktiviert ist oder die Bestellung den Trigger-Status noch nicht erreicht hat, zeigt die Bestell-Metabox einen Button Jetzt ausstellen. Es greift derselbe Ablauf — Snapshot, PDF, XML, Integrations-Push —, läuft aber auf Anfrage.

Gutschriften aus Erstattungen

Ist Gutschrift bei WC-Erstattung automatisch ausstellen aktiv (Standard), löst jede in WooCommerce auf eine Bestellung mit existierender Rechnung erstellte Erstattung eine Gutschrift im Nummernkreis CN aus. Die Gutschrift verweist auf die übergeordnete Rechnung und referenziert sie im XML. Das gerenderte PDF trägt oben den Disclaimer-Banner „Refund of INV-…”, eine Status-Pill CREDIT NOTE, Erstattungsbetrag in der Hero-Zelle und blendet den IBAN-/Zahlungsmethoden-Footer aus (der ursprüngliche Zahlungsfluss greift nicht mehr). Sie können eine Gutschrift — voll oder teilweise — auch manuell über die Karte Aktionen auf dem Bearbeiten-Bildschirm der Rechnung erzeugen, solange die übergeordnete Rechnung im Status issued ist.

Proforma-Dokumente und Angebote

Sind die entsprechenden Schalter aktiv, zeigt der Bestell-Bildschirm zudem die Schaltflächen Proforma erstellen und Angebot erstellen an. Beide produzieren nicht-fiskalische Dokumente — bei Angeboten wird ein PDF gerendert, aber kein XML erzeugt. Das PDF trägt ein typenspezifisches Visual: oben ein Disclaimer-Banner („Proforma — kein steuerrechtliches Dokument.” / „Angebot — kein steuerrechtliches Dokument, freibleibend.”), eine Status-Pill „QUOTE” / „PROFORMA” anstelle von „ISSUED”; bei Angeboten wechselt zudem das prominente Datumslabel auf Gültig bis und der Hero-Gesamtwert auf Geschätzter Gesamtbetrag. Angebote blenden den IBAN-/Zahlungsmethoden-Block aus, da noch keine Zahlung fällig ist.

Ein Proforma lässt sich über die Aktion Konvertieren in eine Rechnung umwandeln — das Dokument wird unter dem konfigurierten Rechnungs-Nummernkreis neu nummeriert.

Eine Rechnung an den Kunden senden

Das Plugin registriert eine Bestell-Aktion Invoice-Pilot-Rechnung an Kunden senden im Standard-Dropdown der Bestellaktionen von WooCommerce, die das PDF per wp_mail() an den Käufer mailt.

Dokumente herunterladen

PDFs und XML-Container werden über einen öffentlich adressierbaren, aber token-signierten REST-Endpunkt ausgeliefert:

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

{format} ist pdf oder xml. Der Token wird beim Ausstellen des Dokuments erzeugt und in der Bestell-Metabox sowie der Rechnungsliste angezeigt.

Dashboard

Invoice Pilot → Dashboard öffnet oben eine Karte Aktivitätsübersicht über einer Karte Trends. Die Aktivitätsübersicht zeigt eine Zeitraum-Leiste mit vier Fenstern — 7 Tage, 14 Tage, 30 Tage (Standard) und 90 Tage — sowie fünf KPI-Karten:

• Rechnungen — Gesamtzahl der im Zeitraum ausgestellten Dokumente.
• Net revenue — Summe der Netto-Beträge in der Shop-Währung, gerendert mit dem Währungssymbol der Locale und zwei Nachkommastellen (z. B. €3,876.09 oder 3.876,09 € je nach Locale des Admins).
• VAT collected — Summe der VAT-Beträge aus dem unveränderlichen Snapshot. Gleiche locale-bewusste Währungsformatierung wie bei Net revenue. Eine separate Schema-Migration füllt diesen Wert für Rechnungen nach, die vor Schema-Version 1.3.1 ausgestellt wurden, als die Spalte beim Schreiben noch nicht befüllt wurde.
• Avg value — Nettoumsatz geteilt durch die Rechnungsanzahl, ebenfalls währungsformatiert.
• B2B / B2C — Verhältnis von B2B-Rechnungen (Käufer mit VAT-Nummer) zu B2C-Rechnungen im selben Zeitraum.

Unter den KPIs rendert die Karte Trends zwei Charts nebeneinander — Invoices over time (ein zweiachsiges Linien-/Flächen-Chart mit der Rechnungsanzahl auf der linken Achse und dem Nettoumsatz-Verlauf als gefüllte Fläche auf der rechten Achse) und By buyer country (ein Donut-Chart der Top-Käufer-ISO-Codes mit Farb-Legende darunter). Sämtliche Werte werden aus /wp-json/invoice-pilot/v1/dashboard?days=N befüllt.

Dokumentenliste

Invoice Pilot → Dokumente listet jedes ausgestellte Dokument mit Status-Pills (paid / void / converted / draft / issued — farbcodiert nach Lebenszyklus), einer Spalte Compliance mit dem farbcodierten Badge aus dem KI-Pre-Flight-Check sowie Inline-Aktionen pro Zeile für PDF / XML / Löschen. Die Seite paginiert 20 Zeilen am Stück und stellt eine vereinheitlichte Toolbar bereit, die die KI-Freitextsuche mit einem Dokumenttyp-Filter (invoice / credit_note / proforma / quote / receipt) sowie einem laufenden Zähler rechts kombiniert. Bei aktivierter KI-Suche akzeptiert das Suchfeld Freitext-Anfragen (etwa „Deutsche Rechnungen letzten Monat über 1.000 EUR”), die der konfigurierte Provider in eine Listenabfrage übersetzt; die aufgelösten Filter-Chips erscheinen über der Tabelle, damit Sie genau sehen, wie das Modell Ihren Satz interpretiert hat.

WooCommerce-Bestellliste

Invoice Pilot fügt der Standard-WooCommerce-Bestellliste (/wp-admin/admin.php?page=wc-orders) eine einzelne Spalte Invoice hinzu, damit der Shop-Betreiber auf einen Blick sieht, welche Bestellungen bereits dokumentiert sind und welche nicht — ohne den Bestellbildschirm zu verlassen. Die Spalte steht zwischen Bestellung und Datum und zeigt die vom konfigurierten Nummernkreis vergebene Dokumentnummer (beispielsweise INV-2026-0063), wortgetreu aus der unveränderlichen Spalte number gelesen, mit einem kleinen Augen-Vorschausymbol neben der Nummer, das das gerenderte PDF inline in einem neuen Tab öffnet.

Bestellungen ohne ausgestelltes Dokument rendern einen Gedankenstrich — nützlich, um Trigger-Status-Diskrepanzen zu diagnostizieren oder Bestellungen herauszufiltern, die einen manuellen wp invoice-pilot issue-Lauf benötigen. Derselbe Renderer verdrahtet sowohl die klassische Posts-Tabellen-Spalte (manage_edit-shop_order_columns) als auch die HPOS-Spalte (manage_woocommerce_page_wc-orders_columns), sodass die Darstellung unabhängig davon identisch ist, welcher Bestell-Speicher in Ihrem Shop aktiv ist.

Integrations-Log

Invoice Pilot → Log erfasst jeden Integrations-Push, jede Antwort und jeden Fehler. Die Toolbar oben kombiniert einen Selektor Bulk actions + Button Apply (derzeit ein Ein-Aktion- Mehrfachlöschen), ein provider-Dropdown und ein action-Dropdown — beide aus den tatsächlich im Log vorkommenden Werten gefüllt, sodass nur Filter angezeigt werden, die zu einer realen Zeile passen — sowie einen laufenden Eintragszähler rechts.

Das Datengrid trägt acht Spalten:

Sensible Payload-Felder werden vom Core\Logger des Plugins beim Schreiben redigiert, sodass Request- und Response-Bodies bedenkenlos im Log verbleiben können. Alte Einträge entfernt der tägliche Cron invoice_pilot_cleanup_logs gemäß der Einstellung Log-Aufbewahrung (Tage) im Tab Erweitert.

Netzwerk-Admin (Multisite)

In einem Multisite-Netzwerk erscheint in der Netzwerk-Admin-Seitenleiste zusätzlich die Seite Invoice Pilot Network. Sie aggregiert Rechnungs-Zähler und Summen über alle Sub-Sites hinweg, auf denen Invoice Pilot aktiv ist.

EU-27-Rechnungsstellung

Invoice Pilot bringt eine Registry länderspezifischer Rechnungsfelder für alle 27 EU-Mitgliedstaaten mit. Jedes Feld ist am Checkout optional (das Plugin erzwingt keine B2B-Daten auf einer B2C-Bestellung); die Validierung greift erst, wenn das Käuferland der ISO des Feldes entspricht.

Die Registry deckt derzeit ab:

Die Block-Checkout-Integration registriert die Felder unter dem Namespace invoice-pilot/... über die Additional Checkout Fields API. Standardmäßig sind im Block-Checkout nur die italienischen Felder sichtbar, um nicht-italienische Käufer nicht zu überfordern; der Schalter Alle EU-27-Felder am Checkout unter Allgemein schaltet den vollen Satz frei. Der klassische Shortcode-Checkout zeigt stets die vollständige Registry, gefiltert nach dem gewählten Rechnungsland.

Länderspezifische Felder werden an der Bestellung persistiert, in den unveränderlichen Rechnungs-Snapshot kopiert und von den XML-Writern konsumiert — der italienische ei_recipient_code wird im FatturaPA-Envelope zu CodiceDestinatario / PECDestinatario, die deutsche leitweg_id in XRechnung zu BuyerReference / EndpointID 0204.

Integrationen

SmartBill

SmartBill (Rumänien) ist über den Filter invoice_pilot_integration_providers an den IntegrationManager des Plugins angeschlossen und implementiert die Standard-Provider-Schnittstelle: push, pull_status, void und test_connection.

• Push mappt den Rechnungs-Snapshot auf das JSON-Schema von SmartBill und ruft mit der konfigurierten CIF und Series POST /SBORO/api/v2/invoice auf.
• Status-Sync gleicht beim Lauf des 15-Minuten-Retry-Crons den Status draft / issued / paid ab.
• Void storniert in SmartBill eine zuvor gepushte Rechnung, sobald die Quell-Rechnung in WordPress storniert wird.

Alle Aktionen werden im Integrations-Log festgehalten. Fehler werden in die Queue gestellt und vom Cron invoice_pilot_retry_integrations erneut versucht.

Fatture in Cloud

Fatture in Cloud (Italien) folgt derselben Provider-Schnittstelle und mappt den Rechnungs-Snapshot auf das entity / items_list-Schema, das der Issued-Document-Endpunkt von FIC erwartet. Italienische länderspezifische Felder werden explizit gemappt:

• ei_recipient_code → ei_code
• ei_certified_email → certified_email
• Käufer-VAT / Steuernummer / Provinz / Land → entsprechende entity-Keys

OAuth-Zugangsdaten werden verschlüsselt gespeichert. Der tägliche Cron invoice_pilot_refresh_fic_token aktualisiert den Access-Token, sobald die Integration aktiv ist. Mit Kunden anlegen auf an legt die Integration bei der ersten Rechnung an einen Käufer einen neuen Kunden-Datensatz in FIC an.

Invoice Pilot reicht FatturaPA nicht in Ihrem Namen beim SDI ein. Die SDI-Einreichung bleibt ein separater manueller Schritt innerhalb Ihres Fatture-in-Cloud-Kontos.

KI-Smart-Fill

Die KI-Schicht ist vollständig optional. Ohne konfigurierten API-Key stellt das Plugin weiterhin Rechnungen aus, rendert PDF und XML, validiert VAT-IDs und pusht in Integrationen — lediglich die vier KI-Funktionen unten sind dann nicht verfügbar.

Fünf Provider werden unterstützt:

Der API-Key wird mit der symmetrischen Crypto-Schicht des Plugins verschlüsselt gespeichert. Ein Druck auf Verbindung testen setzt einen minimalen Request gegen den gewählten Endpunkt ab und zeigt einen etwaigen Fehler der Gegenstelle direkt an, falls die Zugangsdaten nicht stimmen.

Sobald ein Key hinterlegt ist, lassen sich vier Funktionen unabhängig schalten:

• Smart-Fill am Checkout — Am Checkout erscheint ein Textfeld „Rechnungsdaten einfügen”. Das Modell parst den Freitext und füllt das strukturierte WooCommerce-Formular, einschließlich der länderspezifischen Felder. Pro Session rate-limitiert.
• Compliance-Pre-Flight-Check — Jede Rechnung läuft kurz vor der Ausgabe durch das Modell; mit der Option Ausgabe bei Findings auf Error-Niveau blockieren lässt sich die Ausgabe bei kritischen Befunden verhindern (z. B. eine italienische B2B-Rechnung ohne SDI-Empfänger-Code).
• Zeilen automatisch übersetzen — Rechnungspositionsbeschreibungen werden in die Sprache des Käufers übersetzt. Ist das Schwester-Plugin Polyglot  installiert, übernimmt dessen Übersetzungs-Pipeline diese Aufgabe.
• Natürlichsprachige Dokumentensuche — Das Suchfeld auf der Dokumente-Admin-Seite akzeptiert Freitext-Anfragen, die das Modell in eine Listenabfrage übersetzt.

Jede Funktion hat ein eigenes Rate-Limit pro Stunde.

Hooks und Filter

Zentralisierte Hook-Namen liegen in der Klasse \InvoicePilot\Core\Hooks. Die vollständige Liste:

Einen eigenen XML-Writer registrieren:

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

Einen eigenen Integrations-Provider registrieren:

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

Länderspezifische Checkout-Felder ausblenden oder erweitern (zum Beispiel um Italiens ei_certified_email (PEC)- und fiscal_regime (RF-Code)-Eingaben zu entfernen, wenn Ihr Shop diese nie benötigt — kein Plugin-Fork erforderlich):

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
);

Der Filter läuft sowohl im PHP-Submit-Validierungspfad als auch im JS-Snapshot, das an das WC-Blocks-Checkout geliefert wird, sodass die beiden Ebenen synchron bleiben. Maschinennamen der derzeit ausgelieferten Felder (verwenden Sie diese im Filter):

Die vollständige Registry pro Land ist in CountryFieldRegistry::install_defaults() definiert und deckt alle EU-27-ISOs ab.

FAQ

Reicht Invoice Pilot FatturaPA beim SDI ein?

Nein. Invoice Pilot erzeugt das FatturaPA-XML und speichert es an der Bestellung; die SDI-Einreichung ist bewusst als separater manueller Schritt vorgesehen (bzw. erfolgt über die Fatture-in-Cloud-Integration aus Ihrem Konto heraus).

Kann ich einen Writer für ein nicht eingebautes Land ergänzen?

Ja. Hängen Sie sich in invoice_pilot_xml_writer_for_country ein und geben Sie Ihre eigene Implementierung von \InvoicePilot\Modules\Xml\XmlWriterInterface zurück.

Funktioniert es mit dem WooCommerce-Block-Checkout?

Ja. Länderspezifische Felder sind über die Additional Checkout Fields API von WooCommerce 8.6+ registriert — sie erscheinen sowohl im Block-Checkout als auch im klassischen Shortcode-Checkout. Auf WooCommerce-Versionen vor 8.6 wird nur der klassische Filter-Pfad genutzt.

Funktioniert es mit WordPress-Multisite?

Ja. Jede Sub-Site hat eigene Tabellen, Einstellungen und Nummernzähler. Eine Netzwerk-Admin-Seite unter Netzwerk-Admin → Invoice Pilot Network aggregiert Rechnungs-Zähler über das Netzwerk hinweg. Auf neuen Sub-Sites werden Tabellen und Standard-Nummernkreise automatisch über den Hook wp_initialize_site angelegt.

Werden Zugangsdaten verschlüsselt?

Ja. SmartBill-Tokens, Fatture-in-Cloud-OAuth-Tokens und der KI-API-Key werden mit \InvoicePilot\Core\Crypto verschlüsselt gespeichert. Lassen Sie ein Token-Feld beim nächsten Speichern leer, um den bereits gespeicherten Wert zu behalten.

Was passiert mit meinen Daten, wenn ich das Plugin lösche?

Nichts — sofern Sie es nicht ausdrücklich wünschen. Der Standard für Erweitert → Daten bei Deinstallation löschen ist aus, daher bleiben Tabellen, Optionen, Integrations-Logs und der Validierungs-Cache über Deaktivierung / Reaktivierung hinweg erhalten. Schalten Sie die Option ein, damit die uninstall.php-Routine beim Löschen des Plugins durch WordPress alles entfernt.

Wo bekomme ich einen API-Key für die KI-Funktionen?

Jeder Provider hat seine eigene Konsole: Anthropic unter console.anthropic.com , OpenAI unter platform.openai.com , Google AI Studio unter aistudio.google.com , DeepSeek unter platform.deepseek.com  und Grok unter console.x.ai . Der AI-Tab verlinkt direkt auf die Konsole des gewählten Providers.

Brauche ich einen KI-Key, damit das Plugin funktioniert?

Nein. Die KI-Funktionen (Smart-Fill, Compliance-Check, Zeilenübersetzung, natürlichsprachige Suche) sind optional. Die Kern-Rechnungs-Engine — Dokument-Lebenszyklus, PDF- und XML-Erzeugung, VAT-Validierung, Integrationen, Dashboard — läuft auch ohne API-Key.

Fehlerbehebung

Die Rechnung wird nicht ausgestellt, wenn die Bestellung auf Processing wechselt

Prüfen Sie Einstellungen → Allgemein → Trigger-Status. Standard ist processing; haben Sie ihn z. B. auf completed geändert, feuert die Auto-Issue-Routine nur beim konfigurierten Status. Sie können auch aus der Bestell-Metabox Jetzt ausstellen drücken, um unabhängig vom Trigger manuell auszustellen.

Der Checkout zeigt zu viele (oder zu wenige) Länder-Felder

Standardmäßig sind nur die italienischen SDI-Felder sichtbar. Öffnen Sie Einstellungen → Allgemein → Document defaults → Länderspezifische Rechnungsfelder und wählen Sie den Umfang:

• Aus — nur universelle MwSt- und Steuer-ID-Felder sichtbar.
• Nur Italien (SDI / PEC / Steuerregime) — Standard.
• Alle EU-27 länderspezifischen Felder — jede ISO der Registry.

Die Einstellung gilt sowohl für den Block-Checkout als auch für den klassischen Shortcode-Checkout. Länderspezifische Felder werden weiterhin client-seitig ausgeblendet, wenn das Rechnungsland nicht übereinstimmt.

Die VAT-Validierung hängt oder läuft in ein Timeout

Der VIES-Dienst ist gelegentlich langsam oder nicht verfügbar. Das Plugin hält einen Cache pro VAT für die konfigurierte TTL (24 Stunden Standard) und validiert veraltete Einträge stündlich über den Cron invoice_pilot_revalidate_vies neu. Ist VIES offline, akzeptiert der Validator Länderspezifisches Format weiterhin korrekt formatierte Nummern. Sie können die Cache-TTL unter Einstellungen → VAT-Validierung auch erhöhen.

Das Dashboard zeigt keine Daten

Das Dashboard-SQL nutzt JSON_EXTRACT / JSON_UNQUOTE auf der unveränderlichen Snapshot-Spalte. Stellen Sie sicher, dass Ihr Datenbank-Server MySQL 5.7+ oder MariaDB 10.2+ ist. Zeigt die Zeitraum-Leiste das richtige Fenster, die Karten bleiben aber auf --, rufen Sie /wp-json/invoice-pilot/v1/dashboard?days=30 direkt auf und prüfen Sie die Antwort — REST-Authentifizierungsfehler erscheinen als rest_forbidden.

Integrations-Push schlägt fehl

Öffnen Sie Invoice Pilot → Log und suchen Sie den fehlgeschlagenen Eintrag — die Spalte HTTP markiert Nicht-2xx-Antworten mit einem farbigen Badge, und die Spalte Fehler zeigt die Fehlermeldung der Gegenstelle in Rot. Der fehlgeschlagene Eintrag wird automatisch alle fünfzehn Minuten vom Cron invoice_pilot_retry_integrations erneut versucht; Sie können in der Bestell-Metabox An Anbieter pushen drücken, um sofort zu wiederholen. Mit der Aktion Löschen in einer Zeile entfernen Sie einen Einzeleintrag, ohne auf den Aufbewahrungs-Cron zu warten.

„Verbindung testen” im AI-Tab meldet einen Fehler

Die in Rot zurückgegebene Meldung stammt direkt vom Endpunkt des Providers. Häufige Ursachen:

• Ein ungültiger oder widerrufener API-Key — erzeugen Sie einen neuen und fügen ihn ins Feld API-Key ein, dann speichern.
• Ein Modellname, auf den das Konto keinen Zugriff hat — wählen Sie ein anderes Modell aus dem Dropdown.
• Vom Host blockiertes ausgehendes Netzwerk — prüfen Sie, dass ausgehendes HTTPS zu api.anthropic.com, api.openai.com, generativelanguage.googleapis.com, api.deepseek.com oder api.x.ai erlaubt ist.

E-Mails an Kunden kommen nicht an

Kundenrechnungs-E-Mails werden über die Funktion wp_mail() von WordPress verschickt. Trifft keine Mail ein, liegt das fast immer an der Mail-Konfiguration der Site, nicht an Invoice Pilot. Installieren Sie ein Transaktions-Mail-Plugin (etwa eines, das WordPress-Mails über SMTP versendet) und lösen Sie die Bestell-Aktion Invoice-Pilot-Rechnung an Kunden senden aus einer Test-Bestellung erneut aus.