KSeF (Krajowy System e-Faktur, „Nationales System für elektronische Rechnungen“) ist die verpflichtende Plattform des polnischen Finanzministeriums für die elektronische B2B-Rechnungsstellung. Polnische mehrwertsteuerpflichtige Unternehmen müssen jede Rechnung im Format FA(3) an KSeF senden und eine offizielle Kennung (Numer KSeF) erhalten, bevor sie die Rechnung an den Kunden verteilen.
B2Brouter übernimmt den vollständigen Zyklus: Signatur mit dem Steuerzertifikat, Umwandlung in FA(3), Versand, Empfang der KSeF-Nummer sowie Erstellung des QR-Codes und des offiziellen Belegs (UPO).
Für wen — Unternehmen mit polnischer NIP (Numer Identyfikacji Podatkowej). Nicht polnische Unternehmen können KSeF nicht aktivieren und nicht als Transport bei einem polnischen Kontakt auswählen. Die Rechnung würde nicht gesendet.
KSeF-Umgebungen — Das Ministerium stellt drei Umgebungen bereit: Produktion, Demo (echte Daten, aber ohne steuerliche Wirkung) und Test (offene Sandbox für Integrationen). Die Produktionsinstanz von B2Brouter spricht mit KSeF Produktion; die Staging-Instanz spricht je nach Zertifikatskonfiguration mit KSeF Test oder Demo.
Produktion — Öffnen Sie das offizielle KSeF-Webportal des polnischen Finanzministeriums unter ap.ksef.mf.gov.pl/web und identifizieren Sie sich mit Ihrem steuerlichen Identitätssystem (Profil Zaufany, qualifizierte Signatur o. ä.). Erzeugen Sie im Portal im Bereich Zertifikate/Zugangsdaten ein Authentifizierungszertifikat, das mit Ihrer NIP verknüpft ist, und exportieren Sie es im Format PKCS#12 (.p12 oder .pfx) mit Passwort. Die Datei hat einen ähnlichen Namen wie <NIP>_Uwierzytelnianie.pfx (Uwierzytelnianie = Authentifizierung).
Test (Tests und Integrationen) — Das entsprechende Testportal ist ap-test.ksef.mf.gov.pl/web. Sie können ein selbstsigniertes Zertifikat mit OpenSSL erzeugen. Der Subject muss im Feld serialNumber=TINPL-<NIP> die NIP enthalten. Vor der Verwendung müssen Sie es in demselben Portal manuell registrieren. Ohne diesen Schritt lehnt KSeF Test alle Signaturen dieses Zertifikats als unbekannt ab.
Nur PKCS#12 (.p12 / .pfx) ist gültig — Eine .crt-Datei reicht nicht: Sie enthält nur den öffentlichen Teil, nicht den privaten Schlüssel, und KSeF benötigt beide für die Authentifizierung der Signatur. Wenn das Portal etwas anderes liefert, exportieren Sie erneut und wählen ausdrücklich PKCS#12 mit „privaten Schlüssel einschließen“. Nur als letzter Ausweg, wenn Sie .crt und .key getrennt haben, können Sie sie mit OpenSSL kombinieren:
openssl pkcs12 -export \
-in ksef_certificate.crt \
-inkey ksef_private_key.key \
-out ksef_certificate.p12 \
-name "<UNTERNEHMENSNAME> <NIP>" \
-passout pass:<PASSWORT>
Verschlüsselungsalgorithmus — 3DES oder AES — Wenn Sie den Fehler „Certificate password is invalid“ erhalten, obwohl das Passwort korrekt ist, ist die Datei mit einem alten Algorithmus verschlüsselt (RC2-40bit, typisch für Exporte aus altem Windows). KSeF und B2Brouter akzeptieren nur 3DES oder AES. Exportieren Sie mit OpenSSL erneut:
Zertifikat — laden Sie die Datei .p12 oder .pfx hoch.
PIN — Passwort des Zertifikats.
Umgebung — standardmäßig Produktion. Demo oder Test nur bei Tests.
Speichern.
Beim Speichern verbindet sich B2Brouter mit KSeF, validiert das Zertifikat und prüft, ob die NIP des Subject mit der NIP des Kontos übereinstimmt oder ob das Unternehmen über ZAW-FA autorisiert ist. Wenn die Validierung korrekt ist, wird das Zertifikat gespeichert und KSeF für Ihr Konto aktiviert.
Sobald KSeF aktiv ist, wird der Steuerbericht automatisch erzeugt — Sie müssen nichts weiter tun. Jede an einen polnischen Kontakt über KSeF ausgestellte Rechnung erzeugt automatisch ihren Tax Report und wird im selben Ausstellungsfluss an KSeF gesendet. Wenn Sie per API integrieren, konfigurieren Sie tax_report_setting mit auto_generate: true und auto_send: true, damit der Ablauf dem der UI entspricht.
Wenn der Subject des Zertifikats nicht mit der NIP des Kontos übereinstimmt — Sie müssen im offiziellen Portal das Formular ZAW-FA einreichen, um Ihr Unternehmen zur Ausstellung von Rechnungen mit diesem Zertifikat zu autorisieren. Bis ZAW-FA genehmigt ist, lehnt KSeF Rechnungen mit Fehler 450 oder ähnlich ab.
Vor dem Ausstellen einer Rechnung an einen Kunden muss dieser in den Kontakten vorhanden sein.
Kontakte → Neuer Kontakt.
Wählen Sie das Land des Kunden.
Geben Sie die Steuerkennung ein. Sie hängt vom Land des Kunden ab (siehe Tabelle unten).
Kennung validieren und fortfahren — bei polnischen Kunden verbindet sich B2Brouter mit dem Register des Ministeriums, prüft die NIP und vervollständigt den Firmennamen automatisch.
Füllen Sie die Adresse aus (Straße, Postleitzahl, Stadt).
Konfigurieren Sie die Zustellmethode und wählen Sie KSeF als Transport. Wenn die Option KSeF nicht erscheint, ändern Sie den Netzwerktyp zu dem, der KSeF in der Liste anzeigt. In manchen Konten ist dies ein offenes Netzwerk, das mehrere Transporte gruppiert.
KSeF verlangt, dass der Kunde in einer von drei sich gegenseitig ausschließenden Strukturen angegeben wird. Wenn Sie Formate mischen (NIP mit Präfix, Präfix ohne Land usw.) im selben Konto, erhalten Sie intermittierende Fehler: Manche Rechnungen laufen durch, andere werden abgelehnt.
Kundentyp
Einzugebende Kennung
Wie KSeF sie im XML erzeugt
Polnisch
NIP (genau 10 Ziffern, ohne Präfix PL)
Podmiot2/DaneIdentyfikacyjne/NIP
Anderes EU-Land
MwSt.-Nummer ohne Länderpräfix (z. B. 123456789 für DE123456789)
KodUE (Code) + NrVatUE (Nummer, max. 12 Zeichen)
Außerhalb der EU
Steuerkennung des Landes
KodKraju + NrID
Formate nicht mischen — Senden Sie für denselben Kunden immer denselben Kennungstyp. Wenn Sie eine Rechnung als polnisch (PL + NIP) und die nächste als EU (DE + VAT) senden, wendet KSeF unterschiedliche Validierungsregeln an und das Ergebnis wird inkonsistent.
Griechenland: Steuercode EL, nicht GR — Im EU-Steuerfeld (in KSeF KodUE) wird Griechenland mit EL identifiziert. In der Adresse wird GR verwendet. Wenn das Formular im Steuerfeld GR erlaubt, korrigieren Sie es zu EL; sonst lehnt KSeF die Rechnung mit KodUE: 'GR' is not an element of the set {...} ab.
Währung — PLN für inländische Rechnungen. Für Fremdwährungen füllen Sie den Wechselkurs zu PLN am Rechnungsdatum aus. Er wird im KSeF-Feld KursWalutyZ gesendet.
Notizen — Freitext, der als Rechnungsfuß (Stopka) im offiziellen PDF erscheint. Nützlich für rechtliche Klauseln, Vertragsbedingungen oder Informationen, die in kein anderes Feld passen.
Befreite Transaktion (Befreiung nach MwSt.-Gesetz)
Inländisches Reverse Charge
oo
Odwrotne obciążenie — PL Reverse Charge
Nicht steuerbar EU
np I
Nicht steuerbare grenzüberschreitende Dienstleistungen (Art. 28b)
Befreite Zeilen (zw) — rechtliche Grundlage im Kommentar — Für befreite Zeilen geben Sie die rechtliche Grundlage (z. B. „art. 43 ust. 1 pkt 37 ustawy VAT“) im Feld Kommentar der Zeile an. Im PDF erscheinen zwei Absätze: eine automatische allgemeine rechtliche Anmerkung und der von Ihnen geschriebene Kommentar.
Für einen Export außerhalb der EU mit Fremdwährung:
MwSt.-Satz: 0 EX.
Land des Käufers: Nicht-EU-Land.
Wechselkurs: Kurs des Tages vor dem MwSt.-Datum nach EZB- oder NBP-Tabelle.
Verwenden Sie nicht zw (befreit) für Exporte — Ein Export ist 0 EX (Nullsatz für Export, P_13_6_3). Wenn Sie zw verwenden, wird der Betrag zwischen inländischem Nullsatz und Befreiung doppelt geführt, und KSeF lehnt die Meldung ab oder verfälscht sie.
Im Profil einer ausgestellten Rechnung sehen Sie den aktuellen Status, nach Registrierung den Numer KSeF und den UPO-Beleg.
Sending → Registered → (QR + Numer KSeF + UPO)
↘ Error
Sending — B2Brouter hat das Dokument signiert und gesendet. Die tatsächliche Registrierung bei KSeF kann einige Minuten dauern, besonders zu Spitzenzeiten oder am Monatsende.
Registered ✅ — KSeF hat validiert und den Numer KSeF (NrKSeF) zugewiesen. Der QR der gedruckten Rechnung zeigt diese Nummer und der offizielle Registrierungsbeleg wird verfügbar.
Error ❌ — KSeF hat das Dokument abgelehnt. Der Grund erscheint im Profil (Code + Beschreibung auf Polnisch).
Der QR erscheint sofort, aber das bedeutet nicht, dass KSeF die Rechnung akzeptiert hat — B2Brouter erzeugt den QR-Code lokal aus kryptografischem Hash, NIP und Datum. Er ist sofort sichtbar, auch wenn die Rechnung später in Fehler endet. Der einzige verlässliche Akzeptanzindikator ist der Status Registered. Wenn der Status Error ist, ist die Rechnung unabhängig vom erzeugten QR oder Link nicht in KSeF registriert. Solange die Rechnung Sending ist, trägt der QR die Kennzeichnung OFFLINE.
Was er ist. Der UPO (Urzędowe Poświadczenie Odbioru, offizieller Empfangsnachweis) ist der Beleg, den KSeF ausstellt, wenn es die Rechnung akzeptiert und registriert. Er dient als administrativer Empfangsnachweis: der rechtliche und steuerlich relevante Beweis, dass Sie die Pflicht zur Registrierung der Rechnung in KSeF zu einem konkreten Zeitpunkt erfüllt haben.
Technisch ist er ein vom polnischen Finanzministerium digital signiertes XML-Dokument. Er enthält den der Rechnung zugewiesenen Numer KSeF (NrKSeF), den exakten Zeitstempel der Registrierung und die Signatur des Ministeriums. Es ist kein visuelles PDF, sondern ein maschinenlesbarer rechtlicher Nachweis.
Woher er kommt. KSeF erzeugt ihn im Moment der Validierung und Annahme der Rechnung. Er wird nicht von B2Brouter und nicht von Ihnen erzeugt.
Registrierung in B2Brouter bestätigen. Wenn die Rechnung in Registered wechselt, öffnen Sie den zugehörigen KSeF Tax Report, der vom Rechnungsprofil aus verlinkt ist. Im Tab Aktivität sehen Sie das erfolgreiche Versandereignis mit dem zugewiesenen Numer KSeF — die Bestätigung, dass KSeF das Dokument empfangen, validiert und registriert hat.
UPO-XML-Datei für Ihr Buchhaltungsarchiv erhalten. Die Originaldatei ist auf zwei Wegen verfügbar:
Über das offizielle KSeF-Portal — ap.ksef.mf.gov.pl/web oder ap-test.ksef.mf.gov.pl/web für die Testumgebung. Mit Ihrem steuerlichen Identitätssystem können Sie die UPOs Ihres Kontos direkt beim Ministerium anzeigen und herunterladen. Das sind die offiziellen Originale.
Über die B2Brouter-API — wenn Sie über die API integrieren, ist der UPO als Anhang des Tax Reports verfügbar. Siehe KSeF-Entwickleranleitung.
Bewahren Sie UPOs mit der Rechnung auf — Sie haben rechtlichen Wert bei einer Steuerprüfung. Laden Sie sie aus KSeF oder per API herunter und archivieren Sie sie zusammen mit der Originalrechnung.
Öffnen Sie die Rechnung und lesen Sie Code + Fehlerbeschreibung.
Korrigieren Sie die problematischen Daten (Kontakt, NIP, Beträge usw.).
Senden Sie die Rechnung erneut. B2Brouter versucht die Registrierung bei KSeF mit den korrigierten Daten erneut.
Ausnahme — Rechnungsnummer wurde von KSeF bereits gesehen — Wenn die Ablehnung darauf beruht, dass die Rechnungsnummer bereits in einem früheren Versand verwendet wurde, können Sie dasselbe Dokument nicht erneut senden: Löschen Sie es, korrigieren Sie die Daten und erstellen Sie eine neue Rechnung mit anderer Nummer.
Eine Berichtigungsrechnung (faktura korygująca) ändert eine frühere KSeF-Rechnung. Das Dokument verknüpft das Original (DaneFaKorygowanej) und stellt die betroffenen Zeilen mit Angabe des vorherigen und neuen Zustands neu dar.
Öffnen Sie die bei KSeF bereits registrierte Originalrechnung.
Berichtigungsrechnung erstellen — B2Brouter füllt automatisch KSeF-Nummer, Rechnungsnummer und Datum des Originals aus.
Geben Sie den Effekttyp (TypKorekty) an:
1 — Wirkung zum Datum der Originalrechnung. Verwendung: Korrekturen von Fehlern, die bei Ausstellung bestanden (falsch berechneter Betrag, falscher MwSt.-Satz).
2 — Wirkung zum Datum der Berichtigungsrechnung. Verwendung: spätere Ereignisse (Rückgaben, nachträgliche Rabatte).
3 — Wirkung zu einem anderen Datum — geben Sie es ausdrücklich an.
Aktualisieren Sie die Zeilen auf den neuen Zustand (Mengen, Preise, MwSt.-Sätze).
Wenn Sie einen Textgrund der Korrektur hinzufügen möchten, z. B. „Korekta ilości — dostawa niepełna“, oder rechtlichen Text, schreiben Sie ihn in das Feld Notizen der Rechnung. Er wird im offiziellen Fuß des Dokuments (Stopka/Informacje/StopkaFaktury) gesendet und ist im KSeF-PDF sichtbar.
Ausstellen und senden.
Zustand „vorher / nachher“ — Die aus dem Formular ausgestellte Berichtigung enthält direkt die Zeilen mit den neuen Werten. Dies ist der übliche Fall und für die meisten Korrekturen ausreichend. Wenn Sie die formale Darstellung vorher/nachher benötigen (ursprüngliche stornierte Zeilen plus neue im selben Dokument mit Marker Stan przed je Zeile), ist diese Option nur per API verfügbar: siehe Entwickleranleitung.
Für die Berichtigung einer ZAL (Anzahlung) verwenden Sie KOR_ZAL; für die Berichtigung einer ROZ (Schlussabrechnung) verwenden Sie KOR_ROZ. Das Verfahren ist identisch mit einer normalen KOR.
Sobald KSeF im Konto aktiviert ist, wird Ihre NIP als Empfänger registriert und polnische Lieferanten können Ihnen Rechnungen direkt dorthin senden.
Ausgaben → dort finden Sie alle empfangenen KSeF-Rechnungen.
Öffnen Sie eine Rechnung, um die Details zu sehen.
Wo die Numer KSeF einer empfangenen Rechnung steht — Die offizielle KSeF-Nummer (NrKSeF) erscheint nicht auf dem Bild der PDF-Vorschau, sondern im Bereich Aktivität der empfangenen Rechnung (Format XXXXXXXXXX-AAAAMMDD-XXXXXXXXXXXX-XX). Der QR ist im PDF nur sichtbar, wenn der Lieferant ihn in sein Bild aufgenommen hat.
Eine Rechnung, die der Lieferant ausgestellt haben will, erscheint nicht unter Ausgaben — Prüfen Sie zuerst, ob das PDF des Lieferanten einen KSeF-QR-Code enthält. Ohne QR wurde die Rechnung nicht über KSeF gesendet; der Lieferant hat die Registrierung möglicherweise nicht abgeschlossen. Wenn ein QR vorhanden ist, scannen Sie ihn und kopieren Sie die URL. Mit dieser URL können wir prüfen, ob das Dokument wirklich in KSeF existiert.
Neu — in B2Brouter empfangen, wartet auf Ihre Prüfung.
Gelesen — Sie haben sie mindestens einmal geöffnet.
Genehmigt / Abgelehnt — der von Ihnen zugewiesene Status. Es wird keine Nachricht an den Lieferanten gesendet; KSeF hat keinen Akzeptanz-/Ablehnungskanal wie Peppol.
Zertifikat trotz korrektem Passwort abgelehnt — PKCS#12 ist mit einem alten Algorithmus (RC2-40bit) verschlüsselt, typisch für Exporte aus altem Windows. Exportieren Sie mit 3DES oder AES erneut (siehe § 1).
450 - Nip nabywcy: '…' jest nieprawidłowy — NIP des Käufers ungültig. Prüfen Sie 10 Ziffern + Prüfziffer. Für EU-Kontakte verwenden Sie die EU-MwSt.-Nummer ohne Präfix (siehe § 2).
KodUE: 'GR' is not an element of the set — Griechenland muss im EU-Steuerfeld als EL stehen, nicht GR. Bearbeiten Sie den Kontakt und korrigieren Sie dies.
„Contact Email can’t be blank“ — der Transport des Kontakts ist E-Mail, aber es gibt keine Adresse. Fügen Sie eine E-Mail hinzu oder ändern Sie den Transport.
Status Error, aber QR und URL wurden erzeugt — normal. Der QR wird lokal berechnet und hängt nicht von der KSeF-Akzeptanz ab. Der Status Error ist maßgeblich: Die Rechnung ist nicht registriert.
Rechnung, die der Lieferant ausgestellt haben will, erscheint nicht unter Ausgaben — prüfen Sie, ob das PDF des Lieferanten einen KSeF-QR-Code enthält. Ohne QR wurde sie nicht wirklich registriert.
Nicht polnisches Konto versucht KSeF als Transport zu verwenden — KSeF ist nur für Konten mit polnischer NIP verfügbar. Verwenden Sie bei diesem Kontakt Peppol oder E-Mail.
MwSt.-Zusammenfassung zeigt „23% lub 22%“ — offizielles Label der Ministeriumsvorlage, das den historischen Satz (22 %) und den aktuellen Satz (23 %) in einem Feld kombiniert. Das ist kein Fehler.
Feld „Nazwa banku“ (Bankname) leer — KSeF verlangt den Banknamen nicht und B2Brouter füllt ihn nicht automatisch aus. Wenn Sie ihn benötigen, fügen Sie ihn in Notizen hinzu.
Dieses Handbuch beschreibt die UI. Wenn Sie B2Brouter per API integrieren, ist die offizielle Referenz die KSeF-Entwickleranleitung. Sie behandelt die Endpunkte Tax Report Settings, Tax Reports, Invoices und Contacts, das vollständige Mapping zwischen JSON und FA(3), Status-Webhooks und den Download des UPO.
Authentifizierung über statischen API key (Header X-B2B-API-Key) + API-Version (X-B2B-API-Version). KSeF-spezifische Funktionen erfordern Version 2025-10-13 oder neuer.
