KSeF-Umgebungen TEST, DEMO und PRD: sicher integrieren

KSeF bietet drei öffentliche API-Umgebungen für unterschiedliche Aufgaben. TEST ist eine gemeinsam genutzte Integrationsumgebung für synthetische Daten und simulierte Fehler. DEMO verwendet echte Identitäten und Berechtigungen für eine produktionsnahe Prüfung, doch Rechnungsinhalte müssen fiktiv bleiben. PRD stellt rechtswirksame Rechnungen aus. Eine sichere Integration trennt sämtliche Zugangsdaten und Datensätze voneinander und setzt denselben festgeschriebenen Build nacheinander in diesen Umgebungen ein.

Dieser Leitfaden wurde am 28. August 2026 anhand der Dokumentation des polnischen Finanzministeriums und von CIRF geprüft. KSeF führt API-Änderungen schrittweise nach Umgebung ein. Beziehen Sie deshalb das offizielle Änderungsprotokoll und den aktuellen OpenAPI-Vertrag jeder Umgebung in die Freigabeplanung ein. Dieser Beitrag bietet technische Hinweise, keine Steuer- oder Rechtsberatung.

Worin unterscheiden sich KSeF TEST, DEMO und PRD?

Der Unterschied besteht nicht nur im Hostnamen. Jede Umgebung hat ein eigenes Vertrauensmodell, eigene Datenregeln und Zugangsdaten, einen eigenen API-Stand und eigene Folgen einer erfolgreichen Übermittlung.

Diese Grenzen ergeben sich aus der Unterstützung für Integratoren des Ministeriums und der KSeF-Umgebungsmatrix von CIRF. Die Aliasnamen sind wichtig, weil die offizielle Dokumentation beide Varianten verwendet: TEST heißt auch TE oder Integrationsumgebung, DEMO auch TR oder Vorproduktionsumgebung.

Eine Regel überdauert jeden Versionswechsel: Übernehmen Sie weder Daten noch Zugangsdaten aus einer Umgebung in eine andere. Geben Sie getesteten Code und die Konfigurationsstruktur für die nächste Umgebung frei, richten Sie die Zielumgebung aber unabhängig davon ein.

Wie sollten Sie die Endpunkte der KSeF-Umgebungen konfigurieren?

Wählen Sie ein fest zugelassenes Umgebungsprofil und keine beliebige URL. Ein Produktionsprozess darf seine Basisadresse niemals aus einem Anfrageparameter, einem Rechnungsfeld oder einer veränderbaren Datenbankeinstellung übernehmen.

Eine kleine unveränderliche Zuordnung macht die Auswahl sichtbar:

KSEF_ENVIRONMENTS = {
  test: {
    api_base: "https://api-test.ksef.mf.gov.pl/v2",
    docs: "https://api-test.ksef.mf.gov.pl/docs/v2"
  },
  demo: {
    api_base: "https://api-demo.ksef.mf.gov.pl/v2",
    docs: "https://api-demo.ksef.mf.gov.pl/docs/v2"
  },
  production: {
    api_base: "https://api.ksef.mf.gov.pl/v2",
    docs: "https://api.ksef.mf.gov.pl/docs/v2"
  }
}.freeze

profile = KSEF_ENVIRONMENTS.fetch(ENV.fetch("KSEF_ENV").to_sym)

Das ist nur die öffentliche Hälfte des Profils. Halten Sie auch die folgenden Werte als eine an die jeweilige Umgebung gebundene Einheit getrennt:

• Verweis auf Zertifikat und privaten Schlüssel;
• Speicher für KSeF-Token, Access-Token und Refresh-Token;
• Cache für öffentliche KSeF-Schlüssel samt ausgewählter publicKeyId;
• Namensraum in Datenbank oder Objektspeicher für XML und UPO;
• Warteschlange, Wiederholungsbudget und Koordinator für Anfragelimits;
• Dashboards, Warnmeldungen und Protokollkennzeichnungen;
• Schalter zum Aktivieren und sofortigen Abschalten der Produktion.

Der Hinweis zu produktiven Zugangsdaten des Ministeriums ist eindeutig: Produktionsschlüssel und KSeF-Zugangsdaten gehören zu PRD. Ein Token, Zertifikat oder Verschlüsselungsschlüssel aus TEST oder DEMO ist keine produktive Zugangsberechtigung. Der Leitfaden zu öffentlichen Schlüsseln beschreibt zudem deren Rotation. Speichern Sie deshalb nicht einen globalen Schlüssel für alle drei Umgebungen im Cache.

Von KSeF zurückgegebene URLs nicht umschreiben

KSeF kann signierte URLs zum Hoch- oder Herunterladen zurückgeben. CIRF zufolge entspricht deren Host der aufgerufenen Umgebung. Prüfen Sie einen zurückgegebenen Host anhand der Positivliste des ausgewählten Profils und verwenden Sie anschließend die vollständige URL unverändert. Ersetzen Sie weder den Host noch stellen Sie /v2 voran. Hängen Sie auch kein produktives Bearer-Token an eine Speicher-URL.

Das wirkt nebensächlich, bis eine Hilfsfunktion für normale API-Routen eine signierte URL des Objektspeichers erhält. Behandeln Sie API-Basisadressen und zurückgegebene Ressourcen-URLs als zwei verschiedene Datentypen.

Was sollten Sie in der KSeF-TEST-Umgebung prüfen?

In TEST weisen Sie mit synthetischen Daten nach, dass Ihr Client den API-Vertrag und Fehlerzustände beherrscht. Der Zugang ist bewusst einfacher als in der Produktion. Deshalb kann TEST nicht belegen, dass produktive Identitäten oder Berechtigungen funktionieren.

TEST akzeptiert selbst signierte Zertifikate und simulierte Zugangsdaten. Über die Endpunkte unter /testdata/* können Sie Testpersonen, Unternehmensstrukturen und Berechtigungen anlegen, Szenarien mit Anhängen aktivieren, einen Kontext sperren, die Gültigkeit eines Zertifikats verkürzen und Limitprofile ändern. Ausführbare Beispiele veröffentlicht CIRF im Leitfaden zu Testdatenszenarien.

Nutzen Sie diese Möglichkeiten, um Zustände zu prüfen, die sich unter normalen Bedingungen nur aufwendig auslösen lassen:

1. gültige und ungültige Authentifizierung;
2. Berechtigungsfehler trotz erfolgreicher Authentifizierung;
3. Ablauf und Rotation von Zertifikaten;
4. Fehler bei Online- und Stapelübermittlungen;
5. Behandlung von HTTP 429 und gemeinsames Pausieren aller Aufträge bei ausgeschöpftem Kontingent;
6. Neustart des Prozesses, während eine Rechnung noch asynchron verarbeitet wird;
7. unbekannte Antwortfelder und neue Warn-Header;
8. Abruf der UPO, nachdem der ursprüngliche Hintergrundprozess nicht mehr läuft.

Das Ziel ist nicht nur ein erfolgreicher Standardfall. Sie brauchen den Nachweis, dass die Integration einen bekannten Zustand erreicht, wenn KSeF eine Anfrage annimmt, verzögert, ablehnt, drosselt oder die Antwort um neue Felder ergänzt.

Warum echte Daten in TEST unsicher sind

TEST ist kein privater Mandant. Da sich mehrere Integratoren im selben synthetischen Unternehmenskontext authentifizieren können, sind Daten unter Umständen außerhalb Ihres Testlaufs sichtbar. CIRF fordert Integratoren daher auf, zufällige Kennungen und keine echten Unternehmensdaten zu verwenden.

Diese Warnung betrifft mehr als Namen. Übermitteln Sie keine echten Rechnungsnummern, Adressen, Positionsbeschreibungen, Bankdaten, E-Mail-Adressen, Kundenreferenzen oder Produktions-XML, bei denen lediglich die NIP ersetzt wurde. Erzeugen Sie einen vollständig synthetischen Testdatensatz. Legen Sie ihn bei Bedarf neu an, denn TEST-Daten werden regelmäßig gelöscht und keine aktuelle offizielle Quelle nennt ein festes Aufbewahrungsintervall.

Eine Umgebungssperre sollte produktive Kunden-IDs und bekannte Präfixe produktiver Rechnungen bereits vor der Serialisierung ablehnen. Diese Prüfung gehört in den Anwendungscode und nicht in eine Freigabe-Checkliste, die jemand überspringen kann.

Was sollten Sie in KSeF DEMO validieren?

DEMO prüft die Teile, die TEST bewusst simuliert: echte Identitäten bei der Authentifizierung, tatsächliche Eigentumsverhältnisse und reale Berechtigungsketten. Es ist die Generalprobe für einen Release-Kandidaten und keine zweite Testumgebung für beliebige Identitäten.

Laut der Ankündigung zum Start von DEMO des Ministeriums verwendet die Umgebung tatsächliche Authentifizierungsdaten und mit der Produktion vergleichbare Berechtigungen. Hier zeigt sich der Unterschied zwischen „unser XAdES-Code funktioniert“ und „dieses Zertifikat darf mit der erforderlichen Berechtigung für diesen Steuerpflichtigen handeln“. Der Leitfaden zur KSeF-Authentifizierung behandelt diesen Ablauf im Detail.

DEMO sollte fünf Freigabefragen beantworten:

• Kann sich die echte Organisation über den vorgesehenen Zertifikatspfad authentifizieren?
• Verfügen die vorgesehenen Personen und Systeme tatsächlich über die erforderlichen KSeF-Berechtigungen?
• Funktioniert der Release-Kandidat mit den in der Produktion unterstützten Rechnungsformaten?
• Bleibt er unter produktionsnahen Anfragelimits stabil?
• Kann er nach einem Neustart die Statusabfrage und Beweissicherung fortsetzen?

Verwenden Sie genau den Build, den Sie veröffentlichen möchten. Vermeiden Sie DEMO-spezifische Branches und manuelle Änderungen. Falls eine abweichende Konfiguration nötig ist, gehört sie in das Umgebungsprofil und nicht in Code, der sein Verhalten unbemerkt ändert.

Echte Anmeldung bedeutet keine echten Rechnungsinhalte

DEMO verbindet echte Identitäten mit fiktiven Rechnungsdaten. Das Ministerium weist darauf hin, dass Rechnungen dort keine Rechtswirkung entfalten und später gelöscht werden. Zugleich kann die Umgebung migrierte oder aus der Produktion stammende Daten enthalten, die nicht anonymisiert sind und daher wie Produktionsdaten geschützt werden.

Beides trifft gleichzeitig zu. Ihre Testdaten müssen fiktiv sein, während bereits in DEMO vorhandene Datensätze dennoch vertraulich sein können. Wenden Sie dieselben Zugriffsbeschränkungen und dieselbe Protokollbereinigung wie in der Produktion an. Bezeichnen Sie DEMO nicht als Datenbank mit harmlosen Beispieldatensätzen.

Warum ist ein Smoke-Test in PRD trotzdem eine echte Rechnung?

PRD kennt keinen folgenlosen Modus für „Testrechnungen“. Wenn KSeF das Dokument annimmt und eine KSeF-Nummer vergibt, gelangt die Rechnung in den Rechtsverkehr.

Das KSeF-2.0-Handbuch, Teil II des Ministeriums warnt davor, dass eine versehentliche Testrechnung in der Produktion umsatzsteuerliche Folgen haben kann. Artikel 108 Absatz 1 des polnischen Umsatzsteuergesetzes ist eindeutig: Wer in einer Rechnung Umsatzsteuer ausweist, muss sie entrichten.

Der erste Test der Rechnungsstellung muss daher auf einem echten Geschäftsvorgang beruhen. Erfüllen Sie zuvor folgende Voraussetzungen:

• Richten Sie produktive Zugangsdaten direkt in PRD ein, statt sie aus DEMO zu kopieren.
• Prüfen Sie den Steuerpflichtigenkontext und die Berechtigungen mit Aufrufen, die keine Rechnung ausstellen.
• Vergewissern Sie sich, dass die Rechnung echt, freigegeben und bereit für die Buchhaltung ist.
• Beginnen Sie mit einer leeren oder gezielt bestückten Warteschlange.
• Lassen Sie Status, KSeF-Nummer und UPO von einer zuständigen Person überwachen.
• Sorgen Sie dafür, dass Sie neue Übermittlungen stoppen können, ohne Referenzen bereits angenommener Rechnungen zu verlieren.

Bauen Sie niemals einen automatischen Wechsel von TEST oder DEMO zu PRD ein. Bei einem erneuten Versuch darf sich die ausgewählte Umgebung nicht ändern. Speichern Sie die Umgebung zusammen mit jeder Sitzungsreferenz, Rechnungsreferenz, KSeF-Nummer und jedem UPO-Objektschlüssel, damit der Abgleich nie Grenzen zwischen Umgebungen überschreitet.

Der Leitfaden zu UPO und Statusabfragen erläutert, welche Nachweise zu jeder angenommenen Rechnung gehören. Eine HTTP-Antwort mit 202 oder eine Sitzungsreferenz ist noch keine endgültige Annahme.

Wie wirkt sich Versionsdrift bei der KSeF-API auf die Freigabe aus?

TEST kann eine neuere Version als DEMO und PRD ausführen. So erfahren Sie frühzeitig von Änderungen. Zugleich kann eine erfolgreiche Prüfung in einer Umgebung einen anderen API-Vertrag als die Zielumgebung verwenden.

Das offizielle Änderungsprotokoll verzeichnet API 2.7.1 für TEST am 26. August 2026; die Bereitstellung in DEMO und PRD ist für den 15. beziehungsweise 23. September geplant. Zum Prüfdatum war 2.6.1 die neueste als in PRD bereitgestellt verzeichnete Version. Dieser konkrete Stand wird veralten, das gestaffelte Vorgehen bleibt jedoch relevant.

Halten Sie vor jeder Freigabe Folgendes fest:

Erzeugen Sie keinen Client aus dem main-Branch des Repositorys in der Annahme, er entspreche der Produktion. Arbeiten Sie mit dem getesteten Vertrag in einer festen Version, tolerieren Sie dokumentierte zusätzliche Antwortfelder und führen Sie vor der Bereitstellung Kompatibilitätstests mit der Zielumgebung aus.

Die Anfragelimits zeigen, warum das nötig ist. Ältere offizielle Texte nannten für TEST zehnmal höhere Standardlimits als für die Produktion. Laut dem späteren Änderungsprotokoll für API 2.5.0 wurden die TEST-Standardlimits an PRD angeglichen, während TEST seine Simulationsendpunkte behielt. Verlassen Sie sich deshalb auf die zur Laufzeit wirksamen Grenzwerte und den ausführlichen Leitfaden zu Wiederholungsversuchen mit KSeF, statt einen festen Multiplikator in den Code zu schreiben.

Wie sieht eine sichere Checkliste für die KSeF-Freigabe aus?

Stützen Sie die Freigabe auf Nachweise, nicht auf Annahmen. Die folgende Checkliste ist eine technische Zusammenfassung und keine vom Ministerium vorgeschriebene Vorgehensweise.

In lokalen Tests und CI

• Legen Sie FA(3)-Schemas und reproduzierbare Testdaten fest.
• Prüfen Sie exakt die Bytefolge, die Sie hashen, verschlüsseln und übermitteln.
• Halten Sie die Umgebungsauswahl außerhalb der Rechnungsdaten.
• Lehnen Sie jeden Host ab, der nicht auf einer der drei offiziellen Positivlisten steht.
• Prüfen Sie unbekannte Felder und unterbrochene asynchrone Verarbeitung.

In TEST

• Erzeugen Sie neue synthetische Identitäten und Nutzdaten.
• Prüfen Sie Erfolg, Ablehnung, Drosselung, Ablauf und Neustart.
• Stellen Sie sicher, dass keine produktiven Kennungen oder Geheimnisse in Protokolle oder Speicher gelangen.
• Erfassen Sie die OpenAPI-Version von TEST, die beim Testlauf verwendet wurde.

In DEMO

• Authentifizieren Sie sich mit der vorgesehenen echten Unternehmensidentität.
• Prüfen Sie die tatsächlichen Berechtigungsbeziehungen.
• Übermitteln Sie ausschließlich fiktive oder anonymisierte Rechnungsinhalte.
• Verwenden Sie produktionsnahe Limits und den Release-Kandidaten.
• Gleichen Sie Status, Referenzen und UPO nach einem erzwungenen Neustart ab.

Vor und während der Umstellung auf PRD

• Vergleichen Sie das aktuelle OpenAPI-Dokument von PRD mit dem festgelegten Clientvertrag.
• Richten Sie neue PRD-Zertifikate, -Token und -Berechtigungen sowie einen neuen Cache für öffentliche Schlüssel ein.
• Aktivieren Sie Sperren für synthetische Mandanten und Testdaten.
• Prüfen Sie zunächst Vorgänge, die keine Rechnung ausstellen.
• Übermitteln Sie eine echte Rechnung und gleichen Sie anschließend deren endgültigen Status und UPO ab.
• Erhöhen Sie das Volumen schrittweise und beobachten Sie 429, Fehler und die Verweildauer in der Warteschlange.

Nutzen Sie den Leitfaden zur FA(3)-Struktur zusammen mit dieser Checkliste. Eine erfolgreiche XSD-Prüfung und Tests in TEST bestätigen die XML-Struktur und das Verhalten des Clients, nicht die steuerliche Behandlung oder rechtliche Vollständigkeit einer echten Rechnung. Bei Fehlern hilft der Leitfaden zur Fehlerbehebung bei der KSeF-Validierung, ohne eine unklare Übermittlung unbedacht zu wiederholen.

Wie behandelt KSeF Kit die Grenzen zwischen den Umgebungen?

Am sichersten ist ein Umgebungswechsel, den Ihr Team nicht selbst pflegen muss. KSeF Kit ist ein eigenständiges Produkt für Teams, deren Rechnungen aus Stripe stammen. Es wandelt finalisierte Stripe-Rechnungen in FA(3) um, übermittelt sie, wartet auf das KSeF-Ergebnis, speichert die UPO und schreibt die KSeF-Nummer zurück in den Quelldatensatz.

Der öffentliche Leitfaden zur Verbindung beschreibt die Einrichtung für TEST und Produktion. Damit ist KSeF Kit eine gezielte Alternative zur Eigenentwicklung für die Stripe-Abrechnung, aber keine Lösung für jedes Buchhaltungssystem, jede Rechnungsart oder jede steuerliche Entscheidung.

Ob Sie eine verwaltete Lösung oder einen eigenen Client nutzen, die Grenze bleibt gleich: synthetische Arbeit in TEST, echte Identität mit fiktiven Rechnungen in DEMO und ausschließlich echte, freigegebene Rechnungen in PRD. Setzen Sie denselben Code nacheinander in den Umgebungen ein. Übernehmen Sie niemals deren Geheimnisse oder Daten.