KSeF-Integration

Das KSeF-Modul speichert die Verbindungseinstellungen für das Nationale E-Rechnungssystem. Übermitteln kann es derzeit nichts, weder produktiv noch testweise. Der API-Client dieses Plugins ist gegen KSeF 1.0 geschrieben, und diese API existiert nicht mehr. Die Hosts, die der Client kennt, sind abgeschaltet, Anfragen scheitern bereits auf der Netzwerkebene. Diese Seite beschreibt, was das Plugin heute tatsächlich tut und was Sie stattdessen nutzen können.

Was ist KSeF

Das Nationale E-Rechnungssystem (KSeF) ist eine Plattform des Finanzministeriums zum Ausstellen, Speichern und Empfangen strukturierter Rechnungen im XML-Format. Polnische Verkäufer reichen dort Rechnungen ein, statt PDF-Dokumente auszutauschen.

Warum die Übermittlung derzeit unmöglich ist

Der KSeF-Client dieses Plugins kennt genau zwei Hosts, https://ksef-test.mf.gov.pl/api und https://ksef.mf.gov.pl/api, sowie einen einzigen Endpunkt zum Sitzungsstart, /online/Session/InitSigned. Das ist die Form von KSeF 1.0. Diese Umgebungen gibt es nicht mehr:

die KSeF-1.0-Testumgebung hat das Ministerium am 1. September 2025 abgeschaltet
KSeF 1.0 im Produktivbetrieb wurde am 1. Februar 2026 endgültig abgeschaltet, zusammen mit dem alten Zertifikats- und Berechtigungsmodul
seit dem 1. Februar 2026 ist KSeF 2.0 das einzige System, und es ist verpflichtend

Daraus folgt unmissverständlich: Mit diesem Plugin lässt sich heute keine Rechnung übermitteln, bei keiner Einstellung. Nicht produktiv, und auch nicht testweise, denn der Host, den der Client anspricht, ist verschwunden. Es gibt keinen Schalter und keine Konfiguration, die das ändern würde.

Was KSeF 2.0 verlangt

KSeF 2.0 ist keine Fortschreibung der alten Schnittstelle, sondern ein anderes Protokoll:

andere Basisadresse: https://api-test.ksef.mf.gov.pl/v2 für Tests, https://api.ksef.mf.gov.pl/v2 für den Produktivbetrieb
andere Authentifizierung: zuerst POST /auth/challenge, dann POST /auth/ksef-token mit dem KSeF-Token, das gemeinsam mit dem Zeitstempel der Challenge verschlüsselt wird, danach POST /auth/token/redeem für das Zugriffstoken. Nichts davon entspricht InitSigned.
andere Übermittlung: eine Sitzung wird mit POST /sessions/online eröffnet und übergibt dabei einen AES-256-Schlüssel, der mit dem öffentlichen Schlüssel des Ministeriums verschlüsselt ist. Die Rechnung geht anschließend bereits verschlüsselt an /sessions/online/{referenceNumber}/invoices, zusammen mit den SHA-256-Prüfsummen des Klartext- und des verschlüsselten Dokuments.

Eine Neufassung des Clients gegen KSeF 2.0 ist geplant. Ein Termin dafür wird hier nicht genannt, solange keiner zugesagt werden kann.

Was diese Version leistet

Funktion	Stand
KSeF-Verbindungseinstellungen und Speicherung der Zugangsdaten	Verfügbar
KSeF-Kennzeichnung von Bestellungen (FREE-Plugin)	Verfügbar
Übermittlung an KSeF, produktiv oder testweise	Nicht möglich, die API des Clients existiert nicht mehr
Schaltfläche, Massenaktion oder geplante Aufgabe, die übermittelt	Nicht in dieser Version
Vom Ministerium zurückgemeldete Status und KSeF-Referenznummern	Nicht in dieser Version
Herunterladen des Rechnungs-XML aus dem Adminbereich	Verfügbar als UBL / PEPPOL, siehe unten
JPK_FA-Bericht	Verfügbar

Die Route POST /wp-json/polski-pro/v1/invoices/{id}/ksef ist im Code weiterhin vorhanden und reiht eine Hintergrundaufgabe ein. Bauen Sie nicht darauf: Die Aufgabe ruft den alten KSeF-1.0-Host auf und schlägt fehl, weil dieser Host nicht mehr antwortet. Es gibt keine Adminseite, keine Schaltfläche und keine Massenaktion, die etwas übermittelt.

Betrachten Sie dieses Modul bis zur Neufassung als Ort, an dem Sie Zugangsdaten hinterlegen und Bestellungen kennzeichnen, nicht als Kanal zur Einreichung von Rechnungen.

Konfiguration

Für die KSeF-Felder gibt es keine gerenderte Einstellungsseite. Die Werte liegen in der Option polski_pro_ksef und werden über die REST-Route der PRO-Einstellungen geschrieben, genau wie die Zugangsdaten der Versanddienstleister:

PUT /wp-json/polski-pro/v1/settings
Content-Type: application/json
X-WP-Nonce: {wp_rest Nonce}

{
  "ksef": {
    "enabled": true,
    "environment": "test",
    "api_token": "..."
  }
}

Die Route erfordert die Berechtigung manage_woocommerce. Der gespeicherte Payload ersetzt die gesamte Option polski_pro_ksef, senden Sie daher alle Schlüssel, die erhalten bleiben sollen, in derselben Anfrage mit. Alternativ setzen Sie einzelne Werte mit wp option patch update polski_pro_ksef api_token "...".

Gespeicherte Werte sind Vorbereitung. Kein Wert in dieser Option führt dazu, dass eine Rechnung KSeF erreicht.

Verbindungseinstellungen

Schlüssel	Beschreibung
`enabled`	Kennzeichnet das Modul als aktiv
`environment`	Wird als `test` oder `production` gespeichert. Beide Werte zeigen auf Adressen, die abgeschaltet sind.
`api_token`	Im KSeF-Portal generiertes Autorisierungstoken
`auto_send`	Wird gespeichert, aber von nichts gelesen. Ein Aktivieren übermittelt nichts.

Die USt-IdNr. des Ausstellers (NIP) gehört nicht zu dieser Option. Sie stammt aus den Verkäuferdaten in den Einstellungen unter Rechnungen und erscheint auf den Rechnungen, die das Plugin bereits erzeugt.

Zum Thema Token

Ein hier hinterlegtes Token wird derzeit von nichts verwendet, weil kein Aufruf mehr sein Ziel erreicht. Wenn Sie trotzdem vorbereiten möchten, beachten Sie zwei Punkte:

Tokens, die im alten Berechtigungsmodul von KSeF 1.0 erzeugt wurden, sind mit dessen Abschaltung hinfällig. Zugangsdaten für KSeF 2.0 verwalten Sie im aktuellen KSeF-Portal des Finanzministeriums.
Das Token als Authentifizierungsmethode endet am 31. Dezember 2026. Ab dem 1. Januar 2027 ist ein KSeF-Zertifikat der einzige Weg in das System. Wer die Anbindung plant, sollte den Zertifikatsweg von vornherein mitdenken.

KSeF-Bereitschaft im FREE-Plugin

Das FREE-Plugin Polski enthält ein eigenes Modul KSeF-Bereitschaft unter Polski > Module. Es nimmt niemals Kontakt zu KSeF auf, es ist von der Abschaltung also nicht betroffen und funktioniert wie beschrieben. Es zeigt Ihnen, welche Bestellungen eine strukturierte Rechnung benötigen.

Bei aktiviertem Modul gilt:

jede über den Checkout aufgegebene Bestellung wird auf eine Käufer-NIP geprüft, und die Bestellungs-Metaangabe _polski_ksef_required wird auf yes oder no gesetzt
in der Bestellliste erscheint eine Spalte KSeF mit einer Markierung bei gekennzeichneten Bestellungen
im Bestellbildschirm erscheint unter der Rechnungsadresse eine KSeF-Zeile, die die Metaangabe _polski_ksef_status ausliest; diese bleibt auf pending, solange sie nicht von Ihrem eigenen Code beschrieben wird

Die einzige Einstellung des Moduls, Automatisch anhand der NIP erkennen, steuert die oben beschriebene Erkennung.

Erweiterungspunkte

polski/ksef/is_required filtert das Erkennungsergebnis, bevor es gespeichert wird.

add_filter('polski/ksef/is_required', function (bool $required, WC_Order $order): bool {
    // Bestellungen unter 100 PLN nie kennzeichnen.
    if ($order->get_total() < 100) {
        return false;
    }

    return $required;
}, 10, 2);

polski/ksef/invoice_ready wird mit der WC_Order ausgelöst, sobald eine Bestellung als KSeF-pflichtig gekennzeichnet wurde. Das ist der passende Hook, wenn Sie in der Zwischenzeit über Ihr eigenes Buchhaltungssystem oder über die Weboberfläche von KSeF einreichen.

Wie Sie Rechnungsdaten heute exportieren

Die folgenden Funktionen sprechen KSeF nicht an und sind von der Abschaltung in keiner Weise betroffen. Sie liefern Ihnen weiterhin maschinenlesbare Rechnungsdokumente:

die Meta-Box PEPPOL / UBL (XML) im Bestellbildschirm lädt eine einzelne Rechnung als UBL-Datei nach EN 16931 / PEPPOL herunter
die Adminseite JPK_FA-Bericht erzeugt ein JPK_FA(3)-XML für alle im gewählten Zeitraum ausgestellten Rechnungen

Beides ist keine KSeF-Einreichung, deckt aber den üblichen Fall ab, Rechnungsdaten in eine Buchhaltungssoftware oder ein Steuermeldewerkzeug zu übernehmen. Siehe Buchhaltungsexporte.