KSeF-Integration: So funktioniert das KSeF-2.0-Modul von KRONENWERK

KRONENWERK enthält ein KSeF-2.0-Modul, das sich mit dem KSeF-Token eines Steuerpflichtigen authentifiziert, eine Online-Sitzung öffnet, FA(3)-Rechnungen verschlüsselt mit dem Schlüssel des Ministeriums einreicht, die KSeF-Nummer abfragt, das UPO abruft und eingehende Rechnungen liest. Das Modul ist gegen die Umgebungen des Ministeriums gebaut und getestet, wurde aber noch nicht gegen das produktive KSeF eingesetzt, und KRONENWERK verkauft derzeit keine Abonnements an polnische Unternehmen, bis dies nachgewiesen ist. Für die Übermittlung lautet der Status: Noch nicht bereit. Ihre Integration würde die gewöhnliche API darum herum nutzen — Kunden, Entwürfe, Webhooks —, und nichts KSeF-Spezifisches ist über die API exponiert.

Was KSeF ist, in einem Absatz

KSeF (Krajowy System e-Faktur) ist das zentrale polnische Clearance-System: Eine strukturierte Rechnung im FA(3)-Schema wird beim System des Finanzministeriums eingereicht, das sie validiert, eine KSeF-Nummer vergibt und eine amtliche Empfangsbestätigung (UPO, urzędowe poświadczenie odbioru) zurückgibt. Bis diese Nummer existiert, ist die Datei rechtlich keine Rechnung. Damit unterscheidet sich Polen von Deutschland, wo eine konforme, auf beliebigem Weg gesendete Datei die Pflicht erfüllt, und von Belgien, wo der Weg das Peppol-Netzwerk ist. Hintergrund auf KSeF erklärt; das Schema auf FA(3); die Übersicht unter E-Rechnung in Polen.

Was das KSeF-2.0-Modul von KRONENWERK tut

Das Modul implementiert die KSeF API 2.0, wie sie in der OpenAPI-Spezifikation des Ministeriums veröffentlicht ist (Pfade und Feldnamen von dort übernommen, nicht aus dem Gedächtnis). Es arbeitet je Steuerpflichtigem: Jeder Aufruf erfolgt im Kontext einer NIP mit dem KSeF-Token dieses Steuerpflichtigen, und Zugriffstoken werden je NIP zwischengespeichert und vor Ablauf erneuert.

Es gibt zwei Authentifizierungsmethoden des Ministeriums; das Modul verwendet die KSeF-Token-Methode, bei der ein JSON-Dokument mit einem zuvor erhaltenen Systemtoken gesendet wird statt einer mit XAdES signierten XML-Anfrage. Das Token gehört dem Unternehmen und wird ihm innerhalb von KSeF ausgestellt; KRONENWERK speichert es versiegelt und verwendet es ausschließlich zur Authentifizierung. Das Ministerium dokumentiert beide Methoden und weist darauf hin, dass selbstsignierte Zertifikate nur in der Testumgebung akzeptiert werden.

Warum es umgebungsabhängig und noch nicht bereit ist

Das Ministerium veröffentlicht drei Umgebungen, und das Modul ist jeweils gegen genau eine davon konfiguriert:

Das Modul von KRONENWERK wurde gegen die Nicht-Produktionsumgebungen des Ministeriums erprobt. Es wurde nicht gegen das produktive KSeF eingesetzt, wo eine Einreichung ein Rechtsakt ist, von dem die steuerliche Position einer anderen Partei abhängt. Bis eine echte Einreichung mit echtem UPO durchgeführt und verifiziert wurde, kennzeichnet KRONENWERK die Übermittlung als Noch nicht bereit und verkauft keine Abonnements an polnische Unternehmen. Das ist eine Aussage über den Nachweis, nicht über die Testabdeckung: Der Unterschied zwischen „der Client besteht seine Tests" und „das Ministerium hat unsere Rechnung angenommen" ist der, der zählt, und er steht noch aus.

Die FA(3)-Erzeugung selbst — das XML aus den Fakten eines Entwurfs zu erzeugen und gegen das Schema zu validieren — ist Mit Einschränkungen unterstützt: Das Dokument wird erzeugt, aber eine FA(3)-Datei ohne KSeF-Nummer ist keine Rechnung, sodass ihr Nutzen durch den obigen Übermittlungsstatus begrenzt ist.

Wie ein Entwickler die API darum herum nutzen würde

Nichts an der KRONENWERK-API ist KSeF-spezifisch. Wird der polnische Weg verfügbar, sieht eine Integration genauso aus wie für jedes andere Land: Die KSeF-Arbeit steckt in Ausstellung und Übermittlung, die beide im Produkt bleiben.

1. Legen Sie den polnischen Kunden mit POST /customers an, einschließlich country: "PL" und der NIP des Käufers in vatId. FA(3) identifiziert den Käufer über die NIP, und ein Kunde ohne NIP kann nicht über KSeF fakturiert werden.
2. Starten Sie den Entwurf mit POST /invoices/drafts und einem Idempotency-Key.
3. Eine Person vervollständigt den Entwurf im Produkt und stellt ihn aus. Das Polen-Modul rendert FA(3)-XML und validiert es; die Nummer wird verbraucht und invoice.issued in die Warteschlange gestellt.
4. Die Person übermittelt die ausgestellte Rechnung aus dem Produkt. Das Modul authentifiziert sich mit dem unter Einstellungen → Zustellung gespeicherten KSeF-Token des Unternehmens, öffnet eine Sitzung, reicht ein, fragt ab, schließt und speichert KSeF-Nummer und UPO. Ein unbekanntes Ergebnis blockiert das erneute Senden, bis eine Abgleichsabfrage KSeF gefragt hat, ob es das Dokument bereits hält.
5. Ihr Endpunkt empfängt invoice.issued, später invoice.paid oder invoice.cancelled. KSeF-Nummer, UPO und Übermittlungsstatus werden im Produkt angezeigt und sind heute nicht über die API verfügbar.

Was das Unternehmen konfigurieren muss, wenn der Weg verfügbar ist: Stammdaten der juristischen Person mit ihrer NIP (aus der Steuernummer abgeleitet), das unter Einstellungen → Zustellung eingegebene KSeF-Token — KRONENWERK validiert es sofort durch einen authentifizierten Aufruf mit genau dem gerade gespeicherten Token und weigert sich, ein Token zu behalten, das nicht funktioniert — sowie für Ihre Integration einen API-Schlüssel mit customers:write, customers:read, invoices:write, invoices:read und companies:read plus einen Webhook-Endpunkt. Die allgemeine API-Mechanik steht auf der Seite zur Buchhaltungs-API und der Seite zur Rechnungs-API.

Grundlagen der KSeF API 2.0, mit Quellen

Falls Sie stattdessen eine Direktintegration prüfen, ist das Material des Ministeriums die Primärquelle, und hier fangen Sie an.

• Integratorenleitfaden: Der Leitfaden des Ministeriums (in der aktuellen Fassung datiert auf den 5. Mai 2026) behandelt Authentifizierung, Berechtigungen, KSeF-Zertifikate, Offline-Modi, QR-Codes, interaktive und Batch-Sitzungen, Rechnungsabruf, inkrementellen Abruf, Verwaltung von KSeF-Token, Verschlüsselungsschlüssel, Limits und Testdaten, mit Beispielen in C# und Java aus seinen quelloffenen Referenzclients. github.com/CIRFMF/ksef-docs.
• OpenAPI: Jede Umgebung liefert ihre eigene Spezifikation unter /docs/v2; die der Testumgebung liegt unter api-test.ksef.mf.gov.pl/docs/v2. Fehler sind Problem-Dokumente nach RFC 7807 mit detail und einer errors[]-Liste.
• Authentifizierung: Challenge abrufen (zehn Minuten gültig), dann entweder einen mit XAdES signierten XML-AuthTokenRequest mit qualifiziertem Zertifikat oder KSeF-Zertifikat senden oder ein JSON-Dokument mit einem KSeF-Token; Status abfragen; JWT-Zugriffstoken und Refresh-Token einlösen. Die authentifizierende Partei muss mindestens eine aktive Berechtigung für den gewählten Kontext halten (eine NIP, eine interne Kennung oder eine zusammengesetzte EU-USt-Kennung). uwierzytelnianie.md.
• Sitzungen: Eine interaktive Sitzung nimmt Rechnungen einzeln entgegen und gibt je Rechnung einen Status zurück; das Schließen der Sitzung löst die Erzeugung eines Sammel-UPO aus. Eine Batch-Sitzung ist für Masseneinreichungen gesondert dokumentiert. Öffentliche Schlüssel zur Verschlüsselung des Sitzungsschlüssels und des KSeF-Tokens werden vom Ministerium veröffentlicht und rotieren.
• Umgebungen und Wartung: TEST und DEMO dürfen niemals Produktionsrechnungen oder echte Parteidaten erhalten; das Ministerium plant Wartungsarbeiten an den Testumgebungen von 16:00 bis 18:00 Uhr und veröffentlicht API-relevante Änderungen in seinem Changelog. srodowiska.md.

Der KSeF-Leitfaden für Entwickler geht tiefer auf das Schema und das Sitzungsmodell ein.

Wie KRONENWERK damit umgeht

Noch nicht bereit für die Übermittlung. Das KSeF-2.0-Modul — Token-Authentifizierung, Sitzung, FA(3)-Einreichung, UPO-Abruf und Empfang — ist gebaut und umgebungsabhängig und wurde nicht gegen das produktive KSeF eingesetzt. KRONENWERK verkauft derzeit keine Abonnements an polnische Unternehmen, bis dies nachgewiesen ist, und nichts auf dieser Seite darf so gelesen werden, als impliziere es eine behördliche oder produktive Abnahme. Die FA(3)-Erzeugung ist Mit Einschränkungen unterstützt. Die API exponiert keinen KSeF-spezifischen Endpunkt, kein Ereignis und kein Feld; sobald der Weg nachgewiesen ist, nutzen Integrationen dieselben Kunden-, Entwurfs- und Webhook-Aufrufe wie überall sonst. Die Länderseite zu Polen finden Sie unter Polen; den E-Rechnungsumfang des Produkts auf E-Rechnung.