KSeF-Zertifikat oder Token: So binden Sie CRM und Onlineshop an die API von KSeF 2.0 an
Wie sich ein CRM, ein Onlineshop oder ein B2B-Portal bei der API von KSeF 2.0, dem polnischen E-Rechnungssystem, anmeldet: KSeF-Token oder KSeF-Zertifikat, Gültigkeit der Tokens nach 2026 laut Entwurf vom 27.10.2026, wie Sie ein Zertifikat erhalten, das Offline-Zertifikat sowie die Umgebungen TEST und DEMO.
Das Wichtigste in Kürze
- Ein CRM, ein Onlineshop oder ein B2B-Portal, das selbst Rechnungen an das KSeF (Krajowy System e-Faktur, das polnische E-Rechnungssystem) sendet, meldet sich bei der API von KSeF 2.0 mit einem KSeF-Token oder mit einem KSeF-Zertifikat zur Authentifizierung an. Beide Methoden funktionieren parallel.
- Nach der geltenden Verordnung funktionieren Tokens bis zum 31. Dezember 2026. Das polnische Finanzministerium hat angekündigt, dass die Methode bleibt, und der Entwurf zur Änderung der Verordnung vom 27. Oktober 2026 sieht vor, dass bestehende Tokens bis zum 30. November 2027 und neue höchstens 365 Tage gültig sind. Stand 14. November 2026 ist das ein Entwurf.
- Ein KSeF-Zertifikat ist höchstens 2 Jahre gültig. Sie beantragen es in der Aplikacja Podatnika KSeF 2.0 (der Steuerzahler-App des Finanzministeriums) oder über die API, nach der Anmeldung mit Profil Zaufany (staatliches polnisches E-Government-Login), einer qualifizierten Signatur oder einem qualifizierten Siegel. Mit einem Token können Sie kein Zertifikat bestellen.
- Für Rechnungen im Offline-Modus brauchen Sie ein separates Offline-Zertifikat: Ohne dieses kann das System den zweiten QR-Code nicht erzeugen.
- Die Integration testen Sie zuerst in der Umgebung TEST, danach in DEMO und erst ganz zum Schluss in der Produktion.
Wie meldet sich ein CRM oder Onlineshop bei der API von KSeF 2.0 an?
Ein Programm, das Rechnungen ohne menschliches Zutun an das KSeF sendet, meldet sich nicht mit einem Passwort an. Bei jeder Verbindung durchläuft es ein kurzes Verfahren: Es holt sich vom KSeF eine einmalige Challenge, bestätigt sie mit dem Token oder mit einer Signatur per Zertifikat und erhält dafür einen Zugriffstoken, mit dem es Rechnungen sendet und abruft. Der Zugriffstoken ist nur etwa eine Viertelstunde gültig, der Refresh-Token höchstens 7 Tage. Danach muss sich das System erneut authentifizieren.
| Schritt | API-Aufruf | Was Sie wissen sollten |
|---|---|---|
| 1. Challenge | POST /auth/challenge | Die Challenge ist 10 Minuten gültig. |
| 2a. Zertifikat | POST /auth/xades-signature | Das System signiert ein XML-Dokument mit der Challenge und der NIP (polnische Steuernummer) per XAdES-Signatur: mit KSeF-Zertifikat, qualifizierter Signatur oder qualifiziertem Siegel. |
| 2b. KSeF-Token | POST /auth/ksef-token | Das System sendet den Token zusammen mit dem Zeitstempel der Challenge, verschlüsselt mit dem öffentlichen Schlüssel des polnischen Finanzministeriums. |
| 3. Status | GET /auth/{referenceNumber} | Abfrage, bis ein Ergebnis vorliegt. Eine qualifizierte Signatur wird beim Aussteller unter Umständen länger geprüft, ein KSeF-Zertifikat sofort. |
| 4. Zugriffstokens | POST /auth/token/redeem | Liefert den Zugriffstoken und den Refresh-Token. Ein zweiter Aufruf mit demselben Authentifizierungstoken endet mit einem Fehler. |
| 5. Erneuerung | POST /auth/token/refresh | Neuer Zugriffstoken ohne erneute Anmeldung, solange der Refresh-Token gültig ist. |
Token oder KSeF-Zertifikat: Was eignet sich für die Integration?
Laut den FAQ des Finanzministeriums funktionieren Token und Zertifikat parallel, und ein externes System kann das eine oder das andere verwenden. Sie unterscheiden sich darin, wie man sie erhält, wie lange sie gültig sind und was man mit ihnen sonst noch tun kann.
| Merkmal | KSeF-Token | KSeF-Zertifikat (Authentifizierung) |
|---|---|---|
| Was ist das | Eine im KSeF erzeugte Zeichenfolge mit festgelegtem Berechtigungsumfang, z. B. Senden und Lesen von Rechnungen. | Elektronischer Identitätsnachweis einer Person oder eines Unternehmens mit einem Schlüsselpaar. Der private Schlüssel bleibt bei Ihnen. |
| Bezug | Sie erzeugen ihn nach der Anmeldung in der Aplikacja Podatnika KSeF 2.0 oder über die API (POST /tokens). | Antrag in der Aplikacja Podatnika KSeF 2.0 oder über die API, nach der Anmeldung mit Profil Zaufany, qualifizierter Signatur oder qualifiziertem Siegel. |
| Gültigkeit | Geltendes Recht: bis 31.12.2026. Entwurf vom 27.10.2026: bestehende bis 30.11.2027, neue höchstens 365 Tage. | Höchstens 2 Jahre, Verlängerung während der Gültigkeit möglich. |
| Berechtigungen | Im Token hinterlegt. Ein anderer Umfang bedeutet einen neuen Token. | Das Zertifikat enthält keine: Das KSeF prüft die Berechtigungen der Person oder des Unternehmens, auf die bzw. das es ausgestellt ist. |
| Anforderungen an das System | Verschlüsselung des Tokens mit dem öffentlichen Schlüssel des Finanzministeriums. | XAdES-Signatur des Authentifizierungsdokuments. |
| Einschränkungen | Nach der Anmeldung mit Token können Sie kein KSeF-Zertifikat erzeugen. | Damit melden Sie sich nicht in der Aplikacja Podatnika KSeF an: Es dient Systemen, die sich über die API verbinden. |
Der Token ist für den Start einfacher, weil das System keine XAdES-Dokumente signieren muss. Das Zertifikat bietet eine längere und planbare Gültigkeit und hat bei einer Integration, die Sie heute aufbauen, noch einen Vorteil: Es hängt nicht davon ab, wie die Änderung der Vorschriften zu den Tokens ausgeht. Am sichersten bauen Sie die Integration so, dass sich die Anmeldemethode in den Einstellungen umstellen lässt, ohne das Programm umzubauen.
Wie erhalten Sie Schritt für Schritt ein KSeF-Zertifikat?
Seit Februar 2026 beantragen Sie das Zertifikat in der Aplikacja Podatnika KSeF 2.0 oder über die API von KSeF 2.0. Das Moduł Certyfikatów i Uprawnień (MCU, Modul für Zertifikate und Berechtigungen), in dem Zertifikate ab November 2025 ausgestellt wurden, lief bis Ende Januar 2026. In der App sieht das so aus:
- Melden Sie sich in der Aplikacja Podatnika KSeF 2.0 mit Profil Zaufany (über login.gov.pl), einer qualifizierten Signatur oder dem qualifizierten Siegel des Unternehmens an. Prüfen Sie, dass Sie im Kontext der richtigen NIP arbeiten.
- Öffnen Sie den Reiter „Certyfikaty“ (Zertifikate) und wählen Sie „Wnioskuj o certyfikat“ (Zertifikat beantragen). Die Daten für den Antrag übernimmt die App aus der Anmeldung.
- Wählen Sie den Verwendungszweck: Authentifizierung oder Offline-Modus. Ein Zertifikat hat genau einen Verwendungszweck, für beides brauchen Sie also zwei Anträge.
- Sichern Sie den privaten Schlüssel. Das Schlüsselpaar entsteht beim Antrag, an das Ministerium geht nur der öffentliche Schlüssel. Ohne den privaten Schlüssel ist das Zertifikat nutzlos, und wer ihn besitzt, kann im Rahmen Ihrer Berechtigungen in Ihrem Namen handeln.
- Laden Sie das Zertifikat herunter und spielen Sie es zusammen mit dem privaten Schlüssel über einen sicheren Kanal in das System ein. Schicken Sie den Schlüssel nicht per E-Mail.
- Notieren Sie das Ablaufdatum. Ein neues Zertifikat können Sie bestellen, bevor das alte abläuft. Richten Sie eine Erinnerung mindestens einen Monat vorher ein.
Das System kann den Antrag auch selbst über die API stellen: Es prüft die Limits (GET /certificates/limits), ruft die Antragsdaten ab (GET /certificates/enrollments/data), sendet eine CSR-Anfrage im Format PKCS#10 (POST /certificates/enrollments), prüft den Status und ruft das Zertifikat ab (POST /certificates/retrieve). Die Dokumentation lässt Schlüssel vom Typ RSA 2048 und EC P-256 zu und empfiehlt EC. Widerrufen kann ein Zertifikat nur sein Inhaber, z. B. wenn der Schlüssel in falsche Hände geraten ist (POST /certificates/{numer}/revoke), und ein widerrufenes Zertifikat lässt sich nicht wiederherstellen.
Wessen Zertifikat sollte das System des Unternehmens nutzen?
Ein Zertifikat bestätigt die Identität, verleiht aber keine Berechtigungen. Das KSeF prüft bei jeder Verbindung, was die Person oder das Unternehmen darf, auf die bzw. das das Zertifikat ausgestellt ist. Laut den FAQ des Finanzministeriums kann ein Zertifikat eine natürliche Person erhalten, die über NIP oder PESEL (polnische Personenidentifikationsnummer) identifiziert wird, sowie ein Unternehmen, das sich mit einem qualifizierten Siegel anmeldet. Ein Unternehmenszertifikat kann man mit Mitarbeitern teilen, das Zertifikat eines Einzelunternehmers ist persönlich.
- Unternehmenszertifikat (qualifiziertes Siegel): Die Integration hängt nicht von einer einzelnen Person ab. Eine sinnvolle Wahl für ein CRM oder einen Onlineshop, aus dem die Rechnungen des ganzen Unternehmens kommen.
- Zertifikat eines Mitarbeiters: Funktioniert, solange dieser Mitarbeiter im KSeF Berechtigungen für das Unternehmen hat. Verlässt er das Unternehmen und verliert die Berechtigungen, sendet das System keine Rechnungen mehr.
- Buchhaltungsbüro oder externer Dienstleister: Meldet sich mit dem eigenen Zertifikat an und handelt im Rahmen der Berechtigungen, die das Unternehmen erteilt hat. Der Entwurf zur Änderung der Verordnung vom 27. Oktober 2026 sieht außerdem ein Zertifikat vor, das im Kontext einer einzigen, angegebenen NIP ausgestellt wird und damit nur für einen bestimmten Kunden funktioniert. Das ist ein Entwurf.
Wann brauchen Sie ein KSeF-Zertifikat für den Offline-Modus?
Wenn Sie eine Rechnung ohne Verbindung zum KSeF ausstellen, müssen Sie sie mit zwei QR-Codes kennzeichnen. Der erste ermöglicht die Prüfung der Rechnung im KSeF, der zweite bestätigt die Identität des Ausstellers und erfordert ein KSeF-Zertifikat für den Offline-Modus. Ein solches Zertifikat dient nicht der Anmeldung, und ein Zertifikat für die Anmeldung kann den QR-Code nicht signieren. Die Fristen für das Nachsenden der Rechnung laut API-Dokumentation:
| Modus | Wann | Frist für den Versand an das KSeF |
|---|---|---|
| offline24 | Aus beliebigem Grund, Entscheidung des Steuerpflichtigen | Bis zum nächsten Werktag nach dem Ausstellungsdatum |
| offline (Nichtverfügbarkeit) | Bekannt gegebene Nichtverfügbarkeit des KSeF | Bis zum nächsten Werktag nach dem Ende der Nichtverfügbarkeit |
| Notfallmodus | Bekannt gegebener Ausfall des KSeF | Bis zu 7 Werktage nach dem Ende des Ausfalls |
| Totalausfall | In den Massenmedien bekannt gegebener Ausfall | Rechnung ohne QR-Codes und ohne Pflicht zum Nachsenden an das KSeF |
Für das System bedeutet das vier Dinge: Versand der Rechnung mit Kennzeichnung des Offline-Modus, Ausstellungsdatum ausschließlich aus dem Feld P_1, beide QR-Codes auf dem Ausdruck und im PDF sowie Überwachung der Nachsendefrist. Ein Onlineshop oder CRM ohne Offline-Zertifikat kann während einer Nichtverfügbarkeit des KSeF keine korrekte Rechnung an ein Unternehmen ausstellen.
Wo testen Sie die KSeF-Integration: TEST, DEMO oder Produktion?
| Umgebung | API-Adresse | Wofür sie dient |
|---|---|---|
| TEST | api-test.ksef.mf.gov.pl | Erste Integrationstests. Fiktive NIP-Nummern, selbst erzeugte Zertifikate, Daten können für andere Integratoren sichtbar sein. Wartungspausen zwischen 16 und 18 Uhr. |
| DEMO (Vorproduktion) | api-demo.ksef.mf.gov.pl | Letzte Prüfung in einer produktionsnahen Konfiguration. Ohne echte Rechnungen und Unternehmensdaten. |
| Produktion | api.ksef.mf.gov.pl | Rechnungen mit voller Rechtswirkung. |
In TEST prüfen Sie Anmeldung, Rechnungsversand, Ablehnung, Korrekturrechnung und Offline-Modus. In DEMO wiederholen Sie dasselbe mit dem Zertifikat, das Sie in der Produktion verwenden werden. Echte Rechnungen senden Sie an keine dieser Umgebungen.
Was muss die Integration außer der Anmeldung noch abdecken?
- Erneuerung des Zugriffs: Erneuern des Zugriffstokens und erneute Anmeldung, wenn der Refresh-Token abläuft.
- Erinnerungen an die Gültigkeit: Warnung vor dem Ablauf von Zertifikat oder Token, gesendet an die Person, die für Ersatz sorgen kann.
- Sichere Aufbewahrung: Token und privater Schlüssel in einem Secrets-Tresor oder in einer verschlüsselten Konfiguration, niemals im Programmcode oder in einer Tabellenkalkulation.
- Austauschbare Anmeldemethode: Wechsel vom Token zum Zertifikat ohne Umbau der Integration.
- Rechnungen: Versand im Schema FA(3), KSeF-Nummer und UPO (Urzędowe Poświadczenie Odbioru, die amtliche Empfangsbestätigung) zur Rechnung, Umgang mit Ablehnungen, Korrekturrechnungen mit der KSeF-Nummer der ursprünglichen Rechnung, Abruf von Eingangsrechnungen und Limits für API-Anfragen.
Die Wege, Onlineshop und CRM an das KSeF anzubinden (App des Finanzministeriums, Rechnungsprogramm, Plugin, API-Gateway, direkte Integration), haben wir mit Preisen im Artikel KSeF in CRM und Onlineshop: 5 Integrationswege zusammengestellt, die Fristen für 2027 in der KSeF-Checkliste 2027. Die Begriffe finden Sie im IT-Glossar.
Wann reicht ein fertiges Programm, und wann brauchen Sie eine Integration?
Wenn Sie Rechnungen in einem Rechnungsprogramm oder auf einer Shopplattform mit KSeF-Anbindung ausstellen, spielen Sie das Zertifikat oder den Token dort nach der Anleitung des Anbieters ein und brauchen keinen Entwickler. Eine Integration mit der API lohnt sich, wenn die Rechnung in Ihrem CRM, B2B-Portal oder Bestellsystem entsteht, wenn Sie mehrere Rechnungsquellen haben oder wenn die KSeF-Nummer zur Bestellung und zur Zahlung zurückfließen soll.
UNSEEN setzt solche Integrationen ab 1.400 EUR netto um (UN·Connect), ein Finanzmodul mit KSeF-Anbindung ab 6.850 EUR netto (UN·Finance). Den Versand von Rechnungen ins KSeF haben wir u. a. im CRM für ein Unternehmen aus dem Bereich erneuerbare Energien umgesetzt: Eine im System ausgestellte Rechnung geht zusammen mit dem UPO ins KSeF, und Eingangsrechnungen kommen zurück ins System. Den vollen Umfang beschreiben wir auf der Seite Rechnungen aus CRM und Onlineshop ins KSeF.
Häufige Fragen zu KSeF-Zertifikat und Token
Änderungsverlauf
- Erste Version. Authentifizierungsmethoden, Gültigkeit von Tokens und Zertifikaten, Umgebungen und Offline-Modi am 14.11.2026 im Dziennik Ustaw, beim RCL, auf den Seiten des Finanzministeriums und in der API-Dokumentation von KSeF 2.0 geprüft.
Quellen
- Verordnung des Ministers für Finanzen und Wirtschaft vom 12. Dezember 2025 über die Nutzung des KSeF, Dz.U. 2025 Pos. 1815 (§ 6, § 13) (geprüft am 14.11.2026)
- RCL: Entwurf einer Verordnung zur Änderung der Verordnung über die Nutzung des KSeF (27.10.2026) (geprüft am 14.11.2026)
- Polnisches Finanzministerium: KSeF-Zertifikate (geprüft am 14.11.2026)
- Polnisches Finanzministerium: Fragen und Antworten zu KSeF 2.0 (geprüft am 14.11.2026)
- API-Dokumentation KSeF 2.0: Authentifizierung (geprüft am 14.11.2026)
- API-Dokumentation KSeF 2.0: KSeF-Zertifikate (geprüft am 14.11.2026)
- API-Dokumentation KSeF 2.0: KSeF-Tokens (geprüft am 14.11.2026)
- API-Dokumentation KSeF 2.0: Offline-Modi (geprüft am 14.11.2026)
- API-Dokumentation KSeF 2.0: Umgebungen (geprüft am 14.11.2026)
- Infor.pl: Änderungen im KSeF ab 2027, Entwurf zur Änderung der Verordnung (9.11.2026) (Sekundärquelle)
Der Artikel dient der Information und ersetzt keine Steuerberatung: In Steuerfragen ist der Rat Ihres Buchhalters oder Steuerberaters maßgeblich.
Sie brauchen eine individuelle Beratung?
Vereinbaren Sie ein kostenloses Beratungsgespräch auf Polnisch oder Englisch. Wir analysieren Ihr Geschäft und schlagen konkrete Lösungen vor.
Kostenloses Gespräch buchen (30 Min.)