KSeF-2.0-API-Leitfaden für Entwickler: Auth, Sessions, FA(3), UPO, Offline

KSeF 2.0 ist die REST-API des polnischen Finanzministeriums für das nationale E-Rechnungssystem (Krajowy System e-Faktur). Eine Integration authentifiziert sich mit einer Challenge, die mit einem qualifizierten Zertifikat signiert oder mit einem KSeF-Token verschlüsselt wird, tauscht das Ergebnis gegen ein kurzlebiges JWT, öffnet eine Session mit einem selbst erzeugten AES-Schlüssel, reicht mit diesem Schlüssel verschlüsselte FA(3)-XML-Rechnungen ein, fragt deren Status ab und lädt das UPO herunter — die amtliche Empfangsbestätigung, die einer Rechnung ihre KSeF-Nummer und ihre rechtliche Existenz gibt. Dieser Leitfaden folgt dieser Abfolge und behandelt anschließend die Batch-Einreichung, die Offline-Modi, Limits und wie sich das KSeF-Modul von KRONENWERK darauf abbildet.

Umgebungen

Es gibt drei öffentliche Umgebungen, und sie sind nicht austauschbar. Alles Folgende gilt für alle drei; die Basis-URL wählt aus, welche.

Die API-Dokumentation wird unter /docs/v2 unter jeder Basis-URL ausgeliefert, und dieselbe OpenAPI-Beschreibung, Leitfäden und offiziellen Client-Bibliotheken (C# und Java) werden von der CIRFMF-Organisation des Ministeriums auf GitHub veröffentlicht. Seit dem 1. Oktober 2025 haben die Testumgebungen geplante Wartungsfenster (16:00–18:00 Uhr), in denen Aufrufe fehlschlagen können. Reichen Sie niemals Produktionsrechnungen oder echte Unternehmensdaten bei TEST oder DEMO ein.

Authentifizierung

Jeder geschützte Aufruf trägt ein JWT-Zugriffstoken. Es zu erhalten ist ein fünfstufiger Ablauf, dessen erster und letzter Schritt unabhängig vom Berechtigungsnachweis gleich sind.

1. Challenge. POST /auth/challenge liefert einen Challenge-Wert und einen Zeitstempel. Er ist 10 Minuten gültig.
2. Identität nachweisen, auf eine von zwei Arten:
   • XAdES-Signatur. Erstellen Sie ein AuthTokenRequest-XML mit der Challenge, der Kontextkennung (NIP, interne Kennung oder EU-USt-Kennung des Unternehmens, für das Sie handeln) und dem Typ der Subjektkennung, signieren Sie es per XAdES mit einem qualifizierten Zertifikat (persönliches oder Organisations-Qualifikationszertifikat, Profil Zaufany, ein KSeF-Zertifikat oder ein Peppol-Provider-Zertifikat) und senden Sie es an POST /auth/xades-signature.
   • KSeF-Token. Verketten Sie {ksefToken}|{timestampMs}, verschlüsseln Sie mit RSA-OAEP (SHA-256, MGF1) unter Verwendung des veröffentlichten öffentlichen Schlüssels des Ministeriums, kodieren Sie Base64 und senden Sie es zusammen mit Challenge und Kontext an POST /auth/ksef-token. KSeF-Tokens werden innerhalb von KSeF von jemandem ausgestellt, der bereits eine Berechtigung für das Unternehmen hat; sie eignen sich für unbeaufsichtigte Integrationen.
   Beide Aufrufe liefern ein temporäres Authentifizierungstoken und eine Referenznummer.
3. Abfragen. GET /auth/{referenceNumber} mit dem temporären Token, bis der Status endgültig ist. Die Verifizierung ist asynchron — das System prüft die Signatur und das Zertifikat gegen OCSP/CRL.
4. Einlösen. POST /auth/token/redeem tauscht das temporäre Token einmalig gegen ein accessToken (JWT, etwa 15 Minuten, die genaue Lebensdauer steht im exp-Claim) und ein refreshToken (etwa 7 Tage).
5. Erneuern. POST /auth/token/refresh mit dem Refresh-Token liefert ein neues Zugriffstoken mit den aktuellen Berechtigungen des Unternehmens.

Berechtigungen werden in KSeF je Unternehmen und je Rolle erteilt (Ausstellen, Lesen, Berechtigungsnachweise verwalten und so weiter); ein Zugriffstoken spiegelt die Berechtigungen zum Zeitpunkt der Ausstellung wider und wird ungültig, wenn sie entzogen werden. Eine Autorisierungsrichtlinie kann ein Token auf IP-Adressen oder -Bereiche beschränken. Bewahren Sie beide Tokens als Geheimnisse auf.

Interaktive Session: Einreichen, Status, UPO

Eine interaktive Session reicht Rechnungen einzeln ein, synchron auf der Leitung und asynchron in der Verarbeitung. Es ist der Modus, den die meiste Rechnungssoftware verwendet.

1. Schlüssel vorbereiten. Erzeugen Sie einen 256-Bit-AES-Schlüssel und einen 128-Bit-IV. Verschlüsseln Sie den Schlüssel mit dem öffentlichen RSA-Schlüssel des Ministeriums (RSAES-OAEP, MGF1 mit SHA-256). Die Client-Bibliotheken des Ministeriums enthalten einen CryptographyService, der das übernimmt.
2. Öffnen. POST /sessions/online mit der Schemaversion (FA(3) — das aktuelle Rechnungsschema; FA(2) wird in der Dokumentation noch genannt) und dem verschlüsselten Schlüssel. Die Antwort enthält eine Session-referenceNumber und validUntil. Eine Session lebt 12 Stunden, und mehrere können unter einem Zugriffstoken parallel offen sein.
3. Senden. POST /sessions/online/{referenceNumber}/invoices mit der Rechnung, verschlüsselt mit AES-256-CBC und PKCS#7-Padding und Base64-kodiert, plus SHA-256-Hash und Größe sowohl der Klartext- als auch der verschlüsselten Datei. Die Antwort bestätigt den Empfang; die Validierung gegen Schema und Geschäftsregeln beginnt sofort und asynchron.
4. Abfragen. GET /sessions/{referenceNumber}/invoices listet den Status jeder Rechnung: angenommen mit KSeF-Nummer oder abgelehnt mit Begründung. Fragen Sie mit Back-off ab, nicht in einer engen Schleife.
5. Schließen. POST /sessions/online/{referenceNumber}/close beendet die Session und löst die Erzeugung des Sammel-UPO aus.
6. UPO abrufen. Das UPO (Urzędowe Poświadczenie Odbioru) ist ein signiertes XML-Dokument, das die angenommenen Rechnungen mit ihren KSeF-Nummern und Annahmezeitstempeln auflistet. Speichern Sie es zusammen mit den Rechnungen: Es ist der Nachweis, dass die Rechnung im rechtlichen Sinne ausgestellt wurde.

Die KSeF-Nummer, nicht Ihre interne Nummer, ist das, was der Käufer in seinem eigenen KSeF-Eingang sieht und was ein Verwendungszweck bei der Zahlung möglicherweise angeben muss. Das Ausstellungsdatum für Mehrwertsteuerzwecke ist das Datum, an dem die Rechnung von KSeF angenommen wurde, was vom Datum im FA(3) abweichen kann — ein Punkt, der für jeden konkreten Fall eine fachliche Bestätigung erfordert.

Batch-Session

Eine Batch-Session reicht viele Rechnungen als eine verschlüsselte ZIP-Datei ein. Sie eignet sich für Monatsabschlussläufe und Migrationen.

1. Legen Sie die FA(3)-XML-Dateien in eine ZIP-Datei.
2. Teilen Sie die ZIP-Binärdatei in Teile von höchstens 100 MB, fortlaufend nummeriert.
3. Verschlüsseln Sie jeden Teil mit AES-256-CBC nach demselben Schlüsselschema wie oben; berechnen Sie SHA-256 und Größe jedes verschlüsselten Teils.
4. POST /sessions/batch mit dem verschlüsselten Schlüssel, den ZIP-Metadaten, der Schemaversion und der Teileliste. Die Antwort liefert eine referenceNumber und je Teil eine Upload-URL, Methode und Header.
5. Laden Sie jeden Teil als rohe Binärdaten an seine URL hoch. Das Upload-Fenster beträgt 20 Minuten je deklariertem Teil, zusammengefasst.
6. POST /sessions/batch/{referenceNumber}/close, dann fragen Sie den Session-Status ab und laden das Sammel-UPO wie bei einer interaktiven Session herunter.

Beide Session-Typen akzeptieren bis zu 10.000 Rechnungen. Eine Rechnung darf höchstens 1 MB groß sein, oder 3 MB mit Anhang.

Rechnungen lesen

Die Empfangsseite ist symmetrisch. POST /invoices/query/metadata liefert Rechnungsmetadaten für einen Subjekttyp (Aussteller, Empfänger und so weiter) und einen Datumsbereich, seitenweise mit pageOffset und pageSize. GET /invoices/ksef/{ksefNumber} lädt eine Rechnung anhand der KSeF-Nummer herunter. Für den Massenabruf startet POST /invoices/exports einen asynchronen Export unter einem von Ihnen bereitgestellten Verschlüsselungsschlüssel, und GET /invoices/exports/{referenceNumber} meldet den Fortschritt und liefert das verschlüsselte Paket. Eine Integration, die jede Eingangsrechnung sehen muss, fragt die Metadatenabfrage inkrementell ab, statt wiederholt zu exportieren.

Offline-Modi

Drei Modi erlauben es einem Steuerpflichtigen, außerhalb von KSeF auszustellen und nachträglich einzureichen. Jeder hat seinen eigenen Auslöser und seine eigene Frist, und jeder ist rechtlich eigenständig.

Eine Offline-Rechnung ist ein normales FA(3) mit zwei aufgedruckten oder eingebetteten QR-Codes: KOD I, mit dem der Käufer die Rechnung in KSeF verifizieren kann, und KOD II, der die Identität des Ausstellers anhand seines KSeF-Zertifikats bestätigt. Setzen Sie bei der späteren Einreichung offlineMode: true in der Sendeanfrage in beiden Session-Typen. Wird KSeF während des Einreichungsfensters nicht verfügbar, beginnt die Frist neu und kann bis zu 7 Werktage ab Ende des Ausfalls laufen.

Limits und Fehler

Das Ministerium dokumentiert Limits je Kontext (das Unternehmen, für das Sie handeln) und je Berechtigungsnachweis statt je API-Schlüssel: 10.000 Rechnungen je Session, 1 MB oder 3 MB je Rechnung, 100 MB je Batch-Teil sowie Obergrenzen für Zertifikatsanträge und aktive Zertifikate je Kennung (für eine NIP zum Zeitpunkt des Lesens 300 Anträge und 100 aktive Zertifikate). Anfrageraten-Limits existieren — die Dokumentation sagt, das System beschränke die Anzahl der Anfragen, um die Stabilität zu schützen — und werden in einem separaten Dokument zu Ratenlimits beschrieben; planen Sie für HTTP 429 mit Wiederholung und Back-off statt für eine feste Zahl.

Fehler kommen als HTTP-Status mit einem JSON-Body zurück, der das Problem beschreibt: 400 für fehlerhafte Anfragen, 401 für ein fehlendes oder abgelaufenes Token, 403 für eine Berechtigung, die das Token nicht trägt, und Validierungsfehler je Rechnung, die im Session-Status und nicht beim Sendeaufruf gemeldet werden. Schemafehler (das XML entspricht nicht FA(3)) und semantische Fehler (eine NIP, die nicht existiert, ein Datum außerhalb des zulässigen Fensters, ein Duplikat) treten in verschiedenen Phasen auf; lesen Sie den Statuseintrag jeder Rechnung, statt einem 2xx beim Upload zu vertrauen.

Wie KRONENWERK das handhabt

NOCH NICHT BEREIT Das KSeF-2.0-Modul von KRONENWERK implementiert den oben beschriebenen Ablauf: Token-Authentifizierung (Challenge, verschlüsseltes KSeF-Token, Einlösen, Erneuern), eine interaktive Session mit einem je Session erzeugten AES-Schlüssel, FA(3)-Erzeugung und -Einreichung, Statusabfrage, UPO-Abruf und Lesen empfangener Rechnungen. Es ist per Konfiguration umgebungsabhängig — derselbe Code zielt je nach Einstellungen auf TEST, DEMO oder Produktion — und es wurde nicht gegen das produktive KSeF eingesetzt. Aus diesem Grund verkauft KRONENWERK derzeit keine Abonnements an polnische Unternehmen, und nichts auf dieser Seite sollte als Produktionsfreigabe gelesen werden. Die FA(3)-Erzeugung selbst ist MIT EINSCHRÄNKUNGEN UNTERSTÜTZT: Das XML wird bei der Ausstellung erzeugt und gegen das Schema geprüft, aber die Übermittlung und die daraus resultierende KSeF-Nummer und das UPO hängen davon ab, dass sich das Modul in der Produktion bewährt. Die öffentliche API stellt keine KSeF-Operationen bereit: POST /invoices/drafts legt einen Entwurf an, die Ausstellung erfolgt im Produkt, und kein Endpunkt reicht FA(3) ein, liefert eine KSeF-Nummer oder ruft ein UPO ab. Siehe KSeF-Integration für das, was die API bietet, KSeF erklärt und FA(3) für das Format sowie die Polen-Übersicht und die Länderseite für den aktuellen Status.