KSeF 2.0 erklärt: Authentifizierung, Sessions, UPO, Offline-Modi, QR-Codes

KSeF 2.0 ist die Version des polnischen nationalen E-Rechnungssystems, die seit dem 1. Februar 2026, als KSeF 1.0 abgeschaltet wurde, als einzige in Kraft ist. Software authentifiziert sich mit einer qualifizierten Signatur oder einem KSeF-Token und erhält JWT-Zugriffstoken, öffnet eine interaktive oder eine Batch-Session, sendet AES-verschlüsseltes FA(3)-XML und bekommt je Rechnung eine 35-stellige KSeF-Nummer sowie je Session eine amtliche Empfangsbestätigung (UPO) zurück. Offline-Modi, QR-Codes und KSeF-Zertifikate decken die Fälle ab, in denen die Rechnung den Käufer außerhalb des Systems erreicht.

Was sich von KSeF 1.0 zu 2.0 geändert hat

KSeF 2.0 ist ein neuer API-Vertrag, kein Patch: Die Authentifizierung wurde von den Sessions getrennt, JWT-Token ersetzten die alte sessiongebundene Anmeldung, die Verschlüsselung wurde in jedem Modus verpflichtend, die Bezeichnungen wurden RESTful gestaltet, und ein Zertifikatsmodul kam hinzu.

Die Übersicht des Ministeriums für Integratoren nennt die wesentlichen Änderungen: die Authentifizierung als eigenständiger Schritt, der wiederverwendbare, erneuerbare und widerrufbare Token liefert; ein einheitliches Initialisierungsmodell für POST /sessions/online und POST /sessions/batch, die jeweils einen Formularcode und einen verschlüsselten AES-Schlüssel entgegennehmen; die verpflichtende clientseitige Verschlüsselung jeder Rechnung, wobei RSA-OAEP (SHA-256, MGF1-SHA-256) den Sitzungsschlüssel schützt; einheitliche Kennungen (NIP, PESEL, Fingerprint) als explizite Enums; und interne KSeF-Zertifikate für Authentifizierung und Offline-Ausstellung. Die API ist in OpenAPI 3.0.4 beschrieben, mit interaktiver Dokumentation unter api.ksef.mf.gov.pl/docs/v2, und das Ministerium veröffentlicht quelloffene Client-Bibliotheken für C# und Java.

Umgebungen: Test, Demo, Produktion

Es gibt drei öffentliche Umgebungen, und nur die Produktion hat rechtliche Wirkung.

Der Zeitplan des Ministeriums: Offene API-Tests begannen am 30. September 2025, die Demo-API wurde am 15. Oktober 2025 geöffnet, die Testumgebung von KSeF 1.0 wurde am 1. September 2025 geschlossen, und die Produktion von KSeF 2.0 ging am 1. Februar 2026 nach einer technischen Pause vom 26. bis 31. Januar in Betrieb. Von der API zurückgegebene URLs zeigen immer auf die aufgerufene Umgebung. Geplante Wartungen der Testumgebungen können zwischen 16:00 und 18:00 Uhr stattfinden, und nur integrationsrelevante Änderungen werden im Changelog angekündigt.

Authentifizierung: Signatur, KSeF-Token, Zertifikate

Jeder geschützte Aufruf braucht ein JWT-accessToken. Um eines zu erhalten, weist der Client nach, wer er ist (das authentifizierende Subjekt) und für wen er handelt (der Kontext, in der Regel eine NIP), und KSeF prüft, ob das Subjekt in diesem Kontext mindestens eine aktive Berechtigung hält.

1. Challenge. POST /auth/challenge liefert eine Challenge, die 10 Minuten gültig ist.
2. Identitätsnachweis, auf eine von zwei Arten:
   • XAdES-Signatur. Der Client baut ein AuthTokenRequest-XML (Challenge, Kontextkennung — NIP, interne ID oder NIP-VAT-EU-Kombination — und Subjektkennungstyp certificateSubject oder certificateFingerprint, optional eine Richtlinie für zulässige IPs) und signiert es. Zulässige Signierer: ein qualifiziertes Zertifikat einer natürlichen Person mit PESEL oder NIP, ein qualifiziertes Organisationssiegel mit der NIP, eine Signatur des Trusted Profile (Profil Zaufany), ein KSeF-Zertifikat oder ein Zertifikat eines Peppol-Service-Providers. Selbstsignierte Zertifikate werden nur auf TEST akzeptiert.
   • KSeF-Token. Eine JSON-Anfrage mit einem zuvor erzeugten Systemtoken. Token werden mit POST /tokens nach mindestens einer XAdES-Authentifizierung erzeugt, tragen eine Berechtigungsliste wie InvoiceRead, InvoiceWrite, CredentialsRead, CredentialsManage und sind vertrauliche Geheimnisse.
3. Token. Die Antwort liefert ein accessToken und ein refreshToken; Zugriffstoken laufen ab, können ohne erneute Authentifizierung erneuert werden und werden automatisch widerrufen, wenn die Berechtigungen verloren gehen. Sessions werden unter GET /auth/sessions aufgelistet und mit DELETE /auth/sessions/current oder über die Referenznummer widerrufen.

KSeF-Zertifikate werden vom System selbst ausgestellt und sind keine qualifizierten Zertifikate. Ein Zertifikat trägt genau einen Typ: Authentication (Schlüsselverwendung digitale Signatur) für die Anmeldung oder Offline (Schlüsselverwendung Nichtabstreitbarkeit) zum Signieren des zweiten QR-Codes auf Offline-Rechnungen; es kann nicht beides. Die Beantragung (/certificates/enrollments) ist nur nach einer XAdES-Authentifizierung, im eigenen Namen des Subjekts, mit einem PKCS#10-CSR möglich, und ein Zertifikat ist höchstens zwei Jahre gültig. Standardlimits: 300 Anträge und 100 aktive Zertifikate je NIP, 12 und 6 je PESEL oder Fingerprint.

Die Berechtigungen selbst werden im System erteilt: Ein Unternehmen ohne qualifiziertes Siegel benennt auf dem Formular ZAW-FA eine natürliche Person, und diese Person erteilt dann weitere Rechte, zum Beispiel an einen Buchhalter oder an das Zertifikat eines Software-Integrators.

Sessions: interaktiv und Batch

Eine interaktive Session sendet Rechnungen einzeln und eignet sich für Rechnungssoftware; eine Batch-Session sendet ein ZIP mit bis zu 10.000 Rechnungen in verschlüsselten Teilen von höchstens 100 MB und eignet sich für Massen-Uploads. Beide beginnen mit demselben JSON: dem Formularcode (Schemaversion) und dem mit dem öffentlichen Schlüssel des Ministeriums verschlüsselten AES-Schlüssel der Session.

Interaktiv

1. Erzeugen Sie einen 256-Bit-AES-Schlüssel und einen 128-Bit-IV; verschlüsseln Sie den Schlüssel mit RSA-OAEP unter Verwendung des aktuellen öffentlichen Schlüssels aus GET /security/public-key-certificates.
2. POST /sessions/online mit dem Formularcode (FA(3)) und dem verschlüsselten Schlüssel. Die Antwort liefert eine referenceNumber und validUntil; eine Session lebt 12 Stunden, und mehrere können parallel offen sein.
3. POST /sessions/online/{referenceNumber}/invoices mit jeder Rechnung, verschlüsselt mit AES-256-CBC (PKCS#7-Padding), ihrem Hash und ihrer Größe. Die Antwort gibt eine Dokumentreferenznummer zurück.
4. Fragen Sie GET /sessions/{referenceNumber} und GET /sessions/{referenceNumber}/invoices nach dem Status je Rechnung, der KSeF-Nummer und der Rechnungs-UPO ab.
5. POST /sessions/online/{referenceNumber}/close. Das Schließen startet die asynchrone Erzeugung der Sammel-UPO für die Session.

Batch

Der Client zippt die XML-Dateien, teilt das ZIP vor der Verschlüsselung binär in Teile von höchstens 100 MB, verschlüsselt jeden Teil, beschreibt die Teile beim Öffnen von POST /sessions/batch in fileParts, lädt sie auf die zurückgegebenen URLs hoch und schließt die Session. Das Ministerium empfiehlt, je Original-XML einen SHA-256-Hash festzuhalten, damit KSeF-Status den lokalen Dokumenten zugeordnet werden können. Standardlimits je Kontext: 1 MB je Rechnung (3 MB mit Anhang), 10.000 Rechnungen je Session, 500 je Sammelkennung.

KSeF-Nummer und UPO

Die KSeF-Nummer ist der Nachweis, dass eine Rechnung existiert; die UPO (Urzędowe Poświadczenie Odbioru) ist die amtliche Empfangsbestätigung einer Session und ihrer Rechnungen.

Die Nummer hat immer 35 Zeichen: NIP-YYYYMMDD-XXXXXXXXXXXX-CC — die zehnstellige NIP des Verkäufers, das Datum, an dem die Rechnung zur Verarbeitung angenommen wurde, ein zwölfstelliger hexadezimaler technischer Teil und eine zweistellige CRC-8-Prüfsumme (Polynom 0x07, Startwert 0x00). Software kann eine Nummer offline validieren, indem sie die Prüfsumme neu berechnet. Sie darf nicht mit der eigenen Rechnungsnummer des Verkäufers im Feld P_2 verwechselt werden.

Vor der Vergabe einer Nummer prüft KSeF zwei Dinge: dass das XML dem aktuellen Schema entspricht und dass der Sender in diesem Kontext ausstellungsberechtigt ist. Eine abgelehnte Datei ist keine Rechnung; sie wird korrigiert und erneut eingereicht, nicht mit einer Korrekturrechnung „berichtigt“. Bei einer Online-Rechnung ist das Ausstellungsdatum das Übermittlungsdatum, sofern das Feld P_1 damit übereinstimmt, auch wenn die Nummer erst am nächsten Tag eintrifft.

Offline-Modi

Vier Modi ermöglichen die weitere Ausstellung, wenn die Verbindung oder das System nicht verfügbar ist; drei davon verlangen, dass die Rechnung anschließend mit offlineMode: true innerhalb einer gesetzlichen Frist an KSeF gesendet wird.

In den Offline-Modi ist das Ausstellungsdatum das Datum in P_1, nicht das Übermittlungsdatum. Außer im Notfallmodus empfängt der Käufer die Rechnung in KSeF und erhält vor der Übermittlung keine Kopie; im Notfallmodus wird die FA(3)-Datei dem Käufer auf vereinbartem Weg zugestellt und nachträglich nummeriert. Fällt ein angekündigter Ausfall in das Zeitfenster von offline24 oder der Nichtverfügbarkeit, verschiebt sich die Frist auf 7 Werktage nach Ende dieses Ausfalls. Eine außerhalb von KSeF ausgestellte Rechnung darf niemals innerhalb des Systems neu ausgestellt werden — das erzeugt zwei Rechnungen für einen Umsatz.

QR-Codes auf Visualisierungen

Eine außerhalb von KSeF übergebene Visualisierung — PDF, Ausdruck, E-Mail-Anhang — trägt einen QR-Code, damit jeder die Rechnung im System prüfen kann; Offline-Rechnungen tragen zwei.

• KOD I verweist auf die Prüfseite und erlaubt dem Inhaber, die Rechnung zu prüfen und mit zusätzlichen Daten herunterzuladen. Darunter steht die KSeF-Nummer, wenn sie bekannt ist, oder das Wort OFFLINE, bevor die Nummer vergeben wurde.
• KOD II bestätigt die Identität des Ausstellers bei Offline-Rechnungen. Er wird mit einem Offline-KSeF-Zertifikat signiert; ein Authentication-Zertifikat kann nicht verwendet werden. KSeF prüft, dass das Zertifikat existiert, gültig, nicht widerrufen und nicht gesperrt ist und dass sein Subjekt im Kontext aktive Ausstellungsrechte hält.

Die Codes werden lokal vom Client aus den Rechnungsdaten erzeugt (ISO/IEC 18004:2024), und der Link-Host folgt der Umgebung. Eine Visualisierung darf dem Käufer erst übergeben werden, wenn die Rechnung in KSeF registriert ist, außer im Notfallmodus.

Rechnungen empfangen

Käufer holen Rechnungen aus KSeF ab, statt sie per E-Mail zu erhalten. Die API bietet Rechnungsabfragen und den inkrementellen Download neu ausgestellter Rechnungen im Kontext des Käufers, und das Ministerium bestätigt, dass Software sie automatisch abrufen darf. Ausländische Käufer ohne NIP können sich nicht anmelden und erhalten stattdessen eine Kopie mit KOD I. Die zurückkommende FA(3)-Datei ist auf der Seite zum FA(3)-Schema dokumentiert.

So geht KRONENWERK damit um

Noch nicht bereit für die Übermittlung. Das KSeF-2.0-Modul von KRONENWERK — Token-Authentifizierung, interaktive Session, FA(3)-Einreichung, UPO-Abruf und Empfang — ist gebaut und umgebungsabhängig und wurde noch nicht gegen das produktive KSeF eingesetzt. FA(3)-Erzeugung und Schemavalidierung sind Mit Einschränkungen unterstützt. KRONENWERK verkauft keine Abonnements an polnische Unternehmen, bis die produktive Einreichung nachgewiesen ist; siehe die Übersichtsseite Polen und die Länderseite Polen.

Das Design folgt der Regel, die das System vorgibt: Eine Rechnung ist in KRONENWERK erst „ausgestellt“, wenn KSeF eine Nummer zurückgegeben hat, und eine Einreichung, deren Antwort verloren ging, wird abgeglichen, indem KSeF gefragt wird, was es hält, statt erneut gesendet zu werden, denn ein blinder Wiederholungsversuch würde eine zweite rechtsgültige Rechnung erzeugen. Entwickler, die eigene Systeme integrieren, können das mit KSeF-Integration und dem Schritt-für-Schritt-KSeF-Leitfaden vergleichen. Diese Seite beschreibt das System des Ministeriums; sie ist keine Steuer- oder Rechtsberatung.

Häufig gestellte Fragen

Brauche ich eine qualifizierte Signatur, um die KSeF-API zu nutzen?

Für die erste Authentifizierung ja — ein qualifiziertes Zertifikat, ein qualifiziertes Siegel, eine Signatur des Trusted Profile oder ein KSeF-Zertifikat. Danach kann Software ein KSeF-Token oder ein KSeF-Authentication-Zertifikat verwenden.

Was ist der Unterschied zwischen der KSeF-Nummer und der UPO?

Die KSeF-Nummer ist die 35-stellige Kennung, die jeder angenommenen Rechnung zugewiesen wird; die UPO ist die amtliche Empfangsbestätigung, die für eine Session erzeugt wird, nach dem Schließen der Session verfügbar ist und auch je Rechnung vorliegt.

Was bedeutet offline24?

Der Steuerpflichtige stellt eine FA(3)-Rechnung ohne Verbindung aus und muss sie bis zum nächsten Werktag an KSeF übermitteln; der Käufer empfängt sie in KSeF, und die Visualisierung trägt zwei QR-Codes.

Kann ich auf der Testumgebung mit echten Daten testen?

Nein. Das Ministerium erklärt, dass TEST-Daten zwischen Integratoren geteilt werden und zufällige NIPs sowie anonymisierte Daten verwendet werden müssen; DEMO nutzt echte Zugangsdaten, hat aber keine rechtliche Wirkung.

Wird jede Rechnung verschlüsselt?

Ja. In KSeF 2.0 wird jede Rechnung, ob interaktiv oder im Batch, clientseitig mit einem AES-Schlüssel verschlüsselt, der selbst beim Öffnen der Session mit dem öffentlichen Schlüssel des Ministeriums verschlüsselt wird.