KSeF integration

Das KSeF-Modul sendet elektronische Rechnungen an das Nationale E-Rechnungssystem (Finanzministerium). Die Rechnungen werden im Hintergrund versendet, mit automatischen Wiederholungen bei Fehlern.

Was ist KSeF

Das Nationale E-Rechnungssystem (KSeF) ist eine Plattform des Finanzministeriums zum Ausstellen, Speichern und Empfangen strukturierter Rechnungen im XML-Format. Das Plugin stellt Werkzeuge zur Integration von WooCommerce mit KSeF bereit - es erzeugt Rechnungen im erforderlichen XML-Format und übermittelt sie an das System.

Konfiguration

Gehen Sie zu WooCommerce > Einstellungen > Polski > PRO-Module > KSeF.

Verbindungseinstellungen

Einstellung	Beschreibung
KSeF-Integration aktivieren	Aktiviert das Modul
Umgebung	Test (Sandbox) oder Produktion
API-Schlüssel (Token)	Im KSeF-Portal generiertes Autorisierungstoken
USt-IdNr. des Ausstellers (NIP)	Mit dem KSeF-Konto verknüpfte USt-IdNr.

Testumgebung

KSeF stellt eine Testumgebung (Sandbox) zur Überprüfung der Integration bereit. Die Testumgebung:

erfordert keinen echten Autorisierungsschlüssel
akzeptiert Rechnungen im selben Format wie die Produktionsumgebung
übermittelt keine Daten an das Finanzamt
wird für erste Integrationstests empfohlen

Wechseln Sie nach erfolgreicher Überprüfung in der Testumgebung zur Produktionsumgebung und geben Sie den richtigen API-Schlüssel ein.

API-Token erhalten

Melden Sie sich im KSeF-Portal an: https://ksef.mf.gov.pl/
Navigieren Sie zum Bereich der Token-Verwaltung
Generieren Sie ein neues Token mit Berechtigungen zur Rechnungsausstellung
Kopieren Sie das Token und fügen Sie es in die Plugin-Einstellungen ein

Rechnungsübermittlung

Automatische Übermittlung

Nach dem Aktivieren der Option Automatische Übermittlung an KSeF sendet das Plugin die Rechnung automatisch an KSeF, sobald sich ihr Status auf “Ausgestellt” ändert. Die Übermittlung erfolgt asynchron über den Action Scheduler.

Manuelle Übermittlung

Im Bestellbereich enthält die Meta-Box “Rechnungen” eine Schaltfläche An KSeF senden. Ein Klick darauf fügt eine Übermittlungsaufgabe zur Warteschlange des Action Scheduler hinzu.

Asynchrone Verarbeitung

Das Plugin verwendet den Action Scheduler (in WooCommerce integriert) für die asynchrone Rechnungsübermittlung. Das bedeutet:

die Übermittlung blockiert die Bestellabwicklung nicht
die Rechnungen werden in einer Warteschlange nacheinander gesendet
bei einer großen Anzahl von Rechnungen verarbeitet das System sie schrittweise

XML-Erzeugung

Das Plugin erzeugt Rechnungen im XML-Format gemäß dem KSeF-Schema (FA(2)). Das XML-Dokument enthält:

Kopfzeile mit Datum und Rechnungstyp
Verkäuferdaten (USt-IdNr., Name, Adresse)
Käuferdaten (USt-IdNr., Name, Adresse)
Rechnungspositionen (Name, Menge, Nettopreis, USt-Satz, Wert)
Zusammenfassung mit Aufschlüsselung nach USt-Sätzen
Zahlungsinformationen

Das XML wird vor der Übermittlung validiert. Wenn die Validierung Fehler feststellt, wird die Rechnung nicht gesendet, und im Protokoll erscheint eine ausführliche Meldung.

Statusverfolgung

Nach der Übermittlung einer Rechnung an KSeF verfolgt das Plugin ihren Status:

Status	Beschreibung
Queued	Rechnung zur Übermittlungswarteschlange hinzugefügt
Submitted	Rechnung an KSeF übermittelt, wartet auf Verarbeitung
Accepted	Rechnung von KSeF akzeptiert, KSeF-Nummer zugewiesen
Rejected	Rechnung abgelehnt - prüfen Sie die Fehlermeldung
Error	Kommunikationsfehler mit der KSeF-API

Nachdem eine Rechnung akzeptiert wurde, speichert das Plugin die KSeF-Referenznummer in den Rechnungsmetadaten. Diese Nummer ist im Bestellbereich und auf dem PDF-Ausdruck sichtbar.

Status-Polling

Das Plugin prüft automatisch den Status übermittelter Rechnungen. Nach der Übermittlung einer Rechnung an KSeF fragt das Plugin die API alle paar Minuten nach dem Status ab (über den Action Scheduler), bis es eine Antwort “Accepted” oder “Rejected” erhält.

Fehlerbehandlung und Wiederholungen

Im Falle eines Kommunikationsfehlers mit der KSeF-API wendet das Plugin einen exponentiellen Backoff-Mechanismus an:

Versuch	Verzögerung
1. Wiederholung	5 Minuten
2. Wiederholung	25 Minuten
3. Wiederholung	125 Minuten

Nach drei fehlgeschlagenen Versuchen erhält die Rechnung den Status “Error” und erfordert einen manuellen Eingriff. Der Administrator erhält eine E-Mail-Benachrichtigung über die fehlgeschlagene Übermittlung.

Typische Fehlerursachen:

ungültiges oder abgelaufenes API-Token
XML-Validierungsfehler (z. B. fehlende Käuferdaten)
vorübergehende Nichtverfügbarkeit der KSeF-API
Nichtübereinstimmung zwischen der USt-IdNr. des Ausstellers und dem Token

Hooks

`polski_pro_ksef_submit`

Aktion, die vor der Übermittlung einer Rechnung an KSeF ausgelöst wird.

/**
 * @param int    $invoice_id ID faktury
 * @param string $xml        Wygenerowany XML faktury
 */
do_action('polski_pro_ksef_submit', int $invoice_id, string $xml);

Beispiel:

add_action('polski_pro_ksef_submit', function (int $invoice_id, string $xml): void {
    // Zapisanie kopii XML przed wysyłką
    $upload_dir = wp_upload_dir();
    $xml_path = $upload_dir['basedir'] . '/polski-pro/ksef-xml/';

    if (! is_dir($xml_path)) {
        wp_mkdir_p($xml_path);
    }

    file_put_contents(
        $xml_path . "invoice-{$invoice_id}.xml",
        $xml
    );
}, 10, 2);

`polski_pro_ksef_check_status`

Aktion, die nach der Prüfung eines Rechnungsstatus in KSeF ausgelöst wird.

/**
 * @param int    $invoice_id    ID faktury
 * @param string $status        Nowy status (accepted, rejected, error)
 * @param string $ksef_number   Numer referencyjny KSeF (tylko dla accepted)
 */
do_action('polski_pro_ksef_check_status', int $invoice_id, string $status, string $ksef_number);

Beispiel:

add_action('polski_pro_ksef_check_status', function (int $invoice_id, string $status, string $ksef_number): void {
    if ($status === 'accepted') {
        // Powiadomienie zewnętrznego systemu o zaakceptowaniu faktury
        wp_remote_post('https://erp.example.com/api/ksef-update', [
            'body' => wp_json_encode([
                'invoice_id'  => $invoice_id,
                'ksef_number' => $ksef_number,
            ]),
            'headers' => ['Content-Type' => 'application/json'],
        ]);
    }
}, 10, 3);

Diagnose

Protokolle

Das Plugin protokolliert alle KSeF-Vorgänge im WooCommerce-Protokoll. Gehen Sie zu WooCommerce > Status > Protokolle und wählen Sie die Quelle polski-pro-ksef.

Protokollierte Ereignisse:

Rechnungsübermittlung (Anfrage/Antwort)
Statusprüfung
XML-Validierungsfehler
API-Kommunikationsfehler
Übermittlungswiederholungen

Verbindung testen

In den Einstellungen des KSeF-Moduls steht eine Schaltfläche Verbindung testen zur Verfügung. Sie sendet eine Testanfrage an die KSeF-API und überprüft:

Gültigkeit des Tokens
Konnektivität mit dem KSeF-Server
Übereinstimmung der USt-IdNr. mit dem Token

Häufige Probleme

Rechnung von KSeF abgelehnt

Prüfen Sie die Fehlermeldung im WooCommerce-Protokoll
Häufigste Ursachen: fehlende USt-IdNr. des Käufers, ungültiger USt-Satz, unvollständige Adressdaten
Korrigieren Sie die Daten und übermitteln Sie erneut

API-Token funktioniert nicht

Stellen Sie sicher, dass das Token nicht abgelaufen ist
Prüfen Sie, ob das Token über Berechtigungen zur Rechnungsausstellung verfügt
Überprüfen Sie, ob die USt-IdNr. in den Plugin-Einstellungen mit derjenigen übereinstimmt, die mit dem Token verknüpft ist

Action Scheduler verarbeitet die Warteschlange nicht

Prüfen Sie, ob WP-Cron ordnungsgemäß funktioniert
Gehen Sie zu Werkzeuge > Scheduled Actions und prüfen Sie den Status der Warteschlange
Überprüfen Sie, ob keine hängengebliebenen Aufgaben vorliegen