E-Invoice Finder
Menu
Länder Software Fristen Leitfäden Check Pflicht prüfen
ENFRDEPLNL
Polen · KSeF-Betrieb

KSeF-API überwachen und Störungen im ERP bearbeiten

Überwachen Sie KSeF-Sitzungen, Rechnungsstatus, UPO, Limits und Störungen mit einem ERP-Leitfaden für Abgleich, Alarmierung und sichere Wiederaufnahme.

Kurzfazit:
  • Umfang: Sitzungen und jede Rechnung bis zum belegbaren Ergebnis verfolgen.
  • Risiko: Unklarer Zustand kann zu fehlenden Belegen oder Dubletten führen.
  • Aktion: Referenzen sichern, API-Antworten abgleichen und Wiederaufnahme üben.
Polen-Readiness-BerichtOffizielle Quellen
Zuletzt geprüft: 27. Juli 2026Offizielle QuellenKlare ZusammenfassungPraktische Information, keine Rechtsberatung
Offizielle Quellen priorisiert
Prüfdatum sichtbar
Kostenloser Check ohne Registrierung

Was Sie wissen müssen

Leitfaden

Monitoring-Modell: drei Ebenen und durchgängige Kennungen

KSeF 2.0 verarbeitet Einreichungen asynchron. Deshalb sollte das Betriebsmodell drei Ebenen verbinden: den lokalen ERP- oder Joblauf, die KSeF-Sitzung und jede darin enthaltene Rechnung. Bewahren Sie die Sitzungsreferenz, jede Rechnungsreferenz, die lokale ERP-/Job-ID, relevante Zeitstempel sowie die zurückgegebene KSeF-Nummer und den aktuellen Status gemeinsam auf. So lässt sich eine fachliche Rechnung auch nach einem Prozessneustart oder Schichtwechsel eindeutig zuordnen. Ein Korrelationsobjekt kann etwa ERP-Beleg PL-2026-4711, Exportlauf J-884, KSeF-Referenzen und später die KSeF-Nummer verbinden, ohne Rechnungsinhalte zu protokollieren. Die offizielle Anleitung vom 20. April 2026 beschreibt die Überwachung interaktiver und Batch-Sitzungen sowie UPO für Rechnungen und eine gesamte Sitzung. Das System sollte Sitzungen auflisten, eine einzelne Sitzung prüfen, aggregierte Rechnungszahlen lesen, Rechnungen einer Sitzung auflisten und eine Rechnung über ihre Referenz kontrollieren können. Ein häufiger Fehler ist, nur den Sendejob als erfolgreich zu markieren: Transporterfolg beweist weder Verarbeitung noch Nachweisverfügbarkeit.

Leitfaden

Lebenszyklus von Sitzung, Rechnung und UPO

Modellieren Sie den Lebenszyklus ausdrücklich als offen, in Verarbeitung, erfolgreich verarbeitet oder abgelehnt – jeweils nach der aktuell zurückgegebenen API-Antwort und nicht nach selbst erfundenen Statusbedeutungen. Die konkreten Statuswerte und Endpunkte müssen aus der jeweils aktuellen OpenAPI- und offiziellen Dokumentation übernommen werden, weil sie sich weiterentwickeln können. Nach dem Versand fragt die Integration zunächst den Sitzungsstatus ab, liest dann die Rechnungen der Sitzung und gleicht jede Rechnungsreferenz einzeln ab. Die API ermöglicht außerdem, eine Rechnung anhand ihrer Referenz zu prüfen. Eine aggregierte Sitzungszahl ist nützlich, ersetzt jedoch niemals den Einzelabgleich: Zehn verarbeitete Dokumente in der Übersicht sagen nicht automatisch, welche zehn lokalen Belege betroffen sind. Ein Rechnungs- oder Sitzungs-UPO darf erst heruntergeladen werden, wenn die Antwort eine verfügbare UPO-Referenz ausweist. Versprechen Sie Anwendern daher nicht, dass unmittelbar nach der Übertragung ein UPO bereitsteht. Speichern Sie den Nachweis mit nachvollziehbarer Zuordnung und Integritätskontrolle im vorgesehenen Archiv. Wenn ein Dashboard „gesendet“ anzeigt, während KSeF noch verarbeitet, muss die Benutzeroberfläche diesen Zwischenzustand klar von „erfolgreich verarbeitet“ trennen.

Leitfaden

Beobachtbarkeit: Felder, Kennzahlen und Dashboard

Ein brauchbares Dashboard zeigt nicht nur technische Erreichbarkeit, sondern den fachlichen Rückstand. Pro Vorgang gehören lokale ID, Sitzungs- und Rechnungsreferenz, Erstellungs-, Sende- und letzte Prüfzeit, letzter von KSeF gemeldeter Status, KSeF-Nummer (sobald vorhanden), UPO-Verfügbarkeit, Versuchskontext und zuständiges Team in einen geschützten Statusspeicher. Pro Sitzung sind aggregierte Zahlen aus der API neben den lokal erwarteten, zugeordneten, erfolgreich verarbeiteten, abgelehnten und noch ungeklärten Rechnungen hilfreich. Differenzen müssen sichtbar bleiben, bis sie erklärt sind. Kennzahlen können offene Vorgänge nach Alter, nicht zugeordnete Referenzen, Ablehnungsvolumen, 429-Antworten, ausstehende Nachweise und Dead-Letter-Fälle umfassen; Grenzwerte legt das Unternehmen anhand seines Volumens und seiner Risikotoleranz fest, nicht dieser Leitfaden. Protokolle dürfen weder Rechnungspayloads noch Zugangsdaten, private Schlüssel oder Tokens enthalten. Nutzen Sie maskierte technische Metadaten, restriktive Zugriffe und eine nachvollziehbare Änderungs- und Bedienhistorie. Das wichtigste Dashboard-Signal ist nicht „API grün“, sondern „alle erwarteten Rechnungen eindeutig mit dem aktuellen KSeF-Ergebnis abgeglichen“.

Leitfaden

Alarmstufen und klare Verantwortung

Definieren Sie Alarmstufen nach Auswirkung statt nach pauschalen, hier nicht belegbaren Zeitgrenzen. Eine Informationsmeldung kann wachsenden Rückstand anzeigen. Eine Warnung passt zu wiederholten Rate-Limits, mehr ungeklärten Rechnungen oder einer auffälligen Abweichung der Zahlen. Ein kritischer Vorfall liegt nach internen Kriterien vor, wenn fristkritische Verarbeitung, Nachweisführung oder ein wesentlicher Rechnungsstrom gefährdet ist. Jede Stufe braucht einen Eigentümer: Integration/Plattform prüft Transport, Authentisierung und API-Antworten; ERP-Betrieb verantwortet Jobs und Zuordnung; Finance oder Tax Operations beurteilt fachliche Ablehnungen und Fristen; Security übernimmt mögliche Schlüssel- oder Tokenereignisse; Incident Lead koordiniert Kommunikation und Entscheidungen. Erfinden Sie keine SLA, Polling-Takte oder Ausfallschwellen. Dokumentieren Sie stattdessen, wer welche Evidenz prüft, wer einen Lieferantenfall eröffnet und wer eine Wiederaufnahme freigibt. Eine typische Fehlkonstruktion ist ein Alarm, der an ein unbeaufsichtigtes Postfach geht oder nur „KSeF Fehler“ meldet, ohne Sitzungsreferenz, Umfang und nächste Prüfhandlung.

Leitfaden

HTTP 429, Limits und dublettensichere Wiederaufnahme

KSeF besitzt API- und Kontextlimits. Die offiziellen Standard-Kontextgrenzen nennen höchstens 10.000 Rechnungen in einer interaktiven oder Batch-Sitzung; aktuelle oder individuelle Limits können abweichen und sind abfragbar. Planen Sie Kapazität deshalb mit den zur Laufzeit ermittelten Werten. Für inkrementelle Downloads verlangt die offizielle Anleitung ausdrücklich, HTTP 429 und den Header Retry-After zu behandeln. Die Integration sollte die angegebene Warteinformation respektieren, Last entzerren und kontrolliert fortsetzen, ohne hier feste Intervalle oder eine erfundene Anzahl von Versuchen zu hinterlegen. Idempotenz beginnt vor dem Versand: Ein stabiler lokaler Vorgangsschlüssel und persistierte KSeF-Referenzen verhindern, dass ein Worker nach einem Timeout blind neu einreicht. Bei unklarem Ausgang zuerst Sitzung und Rechnungsreferenz abfragen, danach lokale und entfernte Evidenz abgleichen; nur ein genehmigter, eindeutig begründeter Pfad darf eine erneute Einreichung auslösen. Beispiel: Bricht die Verbindung nach dem Absenden ab, bleibt der Beleg „ungeklärt“, nicht „fehlgeschlagen“. Die Recovery-Routine sucht die bekannte Referenz und prüft den aktuellen Zustand. Erst wenn der Abgleich das weitere Vorgehen eindeutig trägt, wird fortgesetzt.

Leitfaden

Ablehnungen, manuelle Prüfung und vollständiger Abgleich

Eine Ablehnung ist ein fachlich zu bearbeitendes Ergebnis, kein Anlass für eine endlose technische Wiederholung. Erfassen Sie die von der aktuellen API bereitgestellte Fehler- oder Statusinformation zusammen mit den Referenzen, klassifizieren Sie den Fall und leiten Sie ihn an eine Dead-Letter- oder manuelle Prüfwarteschlange weiter. Dort sollte ein berechtigter Bearbeiter den Quellbeleg, die Validierung und gegebenenfalls Stammdaten korrigieren, ohne sensible Inhalte in Tickets oder Logs zu duplizieren. Nach einer zulässigen Korrektur muss die neue Verarbeitung weiterhin auf den ursprünglichen lokalen Vorgang verweisen, damit Historie und Entscheidung nachvollziehbar bleiben. Der periodische ERP-Abgleich vergleicht mindestens erwartete Exporte, angelegte Sitzungen, Rechnungslisten der Sitzungen, Einzelstatus, zurückgegebene KSeF-Nummern und verfügbare UPO. Prüfen Sie auch Sonderfälle: Sitzung abgeschlossen, aber lokale Zuordnung unvollständig; Aggregat stimmt, einzelne Referenz fehlt; Nachweis verfügbar, Archivierung aber fehlgeschlagen; oder Rechnung abgelehnt, während das ERP sie bereits als abgeschlossen führt. Automatisierung darf eindeutige Fälle schließen, doch Widersprüche gehören in eine kontrollierte Warteschlange mit Vier-Augen-Freigabe, wenn die interne Risikoregel dies verlangt.

Leitfaden

Offizielle Störungsmeldungen und Grenze der Betriebsentscheidung

Die offizielle Dokumentation unterscheidet offline24, das vom Steuerpflichtigen gewählt wird, den Offline-Betrieb bei angekündigter Nichtverfügbarkeit, den Notfallmodus während eines offiziell bekannt gegebenen Ausfalls und den Totalausfall. Diese Kategorien sind keine technischen Vermutungen. Ein Timeout, eine 429-Antwort oder ein lokaler Netzwerkfehler allein autorisiert keinen Wechsel in einen offiziellen Ausfall- oder Notfallmodus. Das Incident-Team muss technische KSeF-Mitteilungen und die für den konkreten Fall freigegebenen Verfahren prüfen, Zeit und Inhalt der Mitteilung sichern und die Entscheidung durch die zuständige fachliche Rolle dokumentieren. Monitoring sollte offizielle technische Kommunikationskanäle beobachten, aber eine Meldung nicht ohne fachliche Prüfung automatisch in einen rechtlichen Betriebsmodus übersetzen. Halten Sie Runbooks für jede zulässige Lage getrennt: Auslöser und Quelle, Verantwortliche, zulässige Verarbeitung, benötigte Evidenz, Kommunikation, Wiederaufnahme und nachgelagerter Abgleich. Diese Seite bietet Betriebsorientierung, keine Rechts- oder Steuerberatung. Maßgeblich bleiben aktuelle offizielle Hinweise und geeignete polnische Fachberatung. Ein verbreiteter Fehler ist, „API nicht erreichbar“ unmittelbar mit „offizieller KSeF-Ausfall“ gleichzusetzen.

Leitfaden

Tabletop-Beispiel: Timeout nach einer Batch-Übertragung

Übungsszenario: Ein Batch-Worker überträgt einen Lauf mit 1.200 erwarteten Rechnungen. Nach einer erfolgreichen Transportphase tritt beim anschließenden Statusabruf ein Timeout auf. Der Einsatzleiter lässt keine automatische Neueinreichung zu. Das Team sichert Job-ID, Sitzungsreferenz, Rechnungsreferenzen, Zeitstempel, maskierte Antwortmetadaten und den letzten bekannten Status. Es prüft zunächst lokale Netzwerk- und Authentisierungsereignisse, anschließend die offiziellen technischen Mitteilungen. Liegt keine offizielle Bekanntgabe vor, wird auch kein offizieller Ausfallmodus unterstellt. Sobald der Zugriff möglich ist, ruft die Integration den Sitzungszustand und die aggregierten Rechnungszahlen ab, listet die Rechnungen der Sitzung und gleicht alle 1.200 lokalen Datensätze einzeln ab. Erfolgreich verarbeitete Rechnungen werden mit KSeF-Nummer verbunden; abgelehnte Fälle gehen mit sicherer Referenz in die manuelle Prüfung; offene Ergebnisse bleiben sichtbar. UPO werden nur dort geladen, wo eine verfügbare Referenz zurückgegeben wird. Als Evidenzpaket dienen Ereigniszeitleiste, offizielle Meldungen, verantwortliche Entscheidungen, Zählabgleich, Einzelzuordnung und Nachweisstatus – nicht Rechnungsinhalte oder Geheimnisse. Die Übung endet erst, wenn Archivfehler und Differenzen einem Eigentümer zugewiesen sind.

Leitfaden

Anbieterauswahl und nächste Schritte

Prüfen Sie Anbieter nicht nur anhand einer „KSeF-Anbindung“. Fordern Sie eine Demonstration der asynchronen Statusführung, der Einzel- und Sitzungsabfragen, der aggregierten Zahlen, des UPO-Downloads, der Laufzeit-Limitabfrage und der Behandlung von 429 samt Retry-After. Lassen Sie zeigen, wie die Lösung nach einem Prozessabbruch persistierte Referenzen nutzt, Dubletten verhindert, widersprüchliche Zustände in manuelle Prüfung überführt und jeden lokalen Beleg mit KSeF-Nummer und Nachweis korreliert. Sicherheitskriterien sind geheimnisfreie Logs, Schutz von Tokens und privaten Schlüsseln, rollenbasierter Zugriff, Audit-Trail sowie sichere Exporte für Archiv und Incident-Evidenz. Vertraglich sollten Supportwege, Änderungsmanagement für OpenAPI und offizielle Statusentwicklungen, Datenportabilität und Verantwortungsgrenzen klar sein, ohne unbelegte Verfügbarkeitsversprechen als technischen Ersatz für Recovery zu akzeptieren. Nächster Schritt ist ein Test mit erfolgreichen, abgelehnten, verzögerten und zunächst unklaren Rechnungen sowie simulierten 429-, Timeout- und Worker-Neustart-Fällen. Führen Sie danach einen vollständigen ERP-Abgleich und eine Tabletop-Übung durch. Aktualisieren Sie Runbook und Integration fortlaufend anhand der aktuellen OpenAPI, offiziellen Dokumentation und technischen Mitteilungen.

Checkliste

Sitzungsreferenz, Rechnungsreferenz, lokale ERP-/Job-ID und Zeitstempel dauerhaft miteinander verknüpfen.

Transporterfolg im ERP klar von Verarbeitung, Ablehnung und noch offenem Status trennen.

Sitzungsaggregate regelmäßig mit der Einzelzuordnung aller erwarteten Rechnungen abgleichen.

UPO nur herunterladen und zusagen, wenn die API eine verfügbare UPO-Referenz ausweist.

Aktuelle API- und Kontextlimits zur Laufzeit abfragen und Kapazitätsplanung daran ausrichten.

HTTP 429 behandeln, Retry-After respektieren und Last kontrolliert wieder aufnehmen.

Bei unklarem Ausgang zuerst Status und Referenzen abgleichen, statt automatisch erneut zu senden.

Ablehnungen und Widersprüche in eine verantwortete Dead-Letter- oder manuelle Prüfwarteschlange leiten.

Rechnungspayloads, Zugangsdaten, private Schlüssel und Tokens konsequent aus Logs fernhalten.

Störungs- und Wiederanlaufübungen mit offiziellen Mitteilungen, Evidenzpaket und End-to-End-Abgleich durchführen.

Häufige Fragen

Wie prüft ein ERP den KSeF-Sitzungsstatus?

Es speichert die beim Start erhaltene Sitzungsreferenz und fragt den Zustand über die in der aktuellen offiziellen OpenAPI dokumentierte Funktion ab. Zusätzlich sollte es aggregierte Rechnungszahlen und die Rechnungsliste der Sitzung lesen und diese mit den lokal erwarteten Belegen vergleichen. Der Sitzungsstatus allein schließt den Einzelabgleich nicht ab.

Wann ist ein UPO in KSeF verfügbar?

Nicht zwingend direkt nach der Übertragung. Die Verarbeitung erfolgt asynchron. Ein Rechnungs- oder Sitzungs-UPO sollte erst als verfügbar gelten und heruntergeladen werden, wenn die API-Antwort eine entsprechende verfügbare UPO-Referenz ausweist. Vorher sollte das ERP den Zustand als offen oder in Verarbeitung darstellen, soweit dies der aktuellen Antwort entspricht.

Was ist der Unterschied zwischen Rechnungs-UPO und Sitzungs-UPO?

Die offizielle Anleitung sieht den Abruf eines Nachweises für eine einzelne Rechnung und für eine ganze Sitzung vor. Beide müssen über die von der API bereitgestellten Referenzen eindeutig abgelegt werden. Ein Sitzungsnachweis ersetzt nicht die Zuordnung des Ergebnisses und der KSeF-Nummer zu jedem lokalen Rechnungsdatensatz.

Welche Daten sollten für den KSeF-Abgleich gespeichert werden?

Mindestens lokale ERP- oder Job-ID, Sitzungsreferenz, jede Rechnungsreferenz, relevante Zeitstempel, letzter zurückgegebener Status, KSeF-Nummer und UPO-Verfügbarkeit. Die Speicherung muss geschützt und nachvollziehbar sein. Rechnungsinhalte, Tokens, private Schlüssel und andere Zugangsdaten gehören nicht in technische Logs.

Wie behandelt die Integration pending, abgelehnt und HTTP 429?

Ein noch nicht abgeschlossenes Ergebnis bleibt offen und wird anhand aktueller API-Antworten weiter verfolgt. Eine Ablehnung geht zur fachlichen Korrektur oder manuellen Prüfung, statt blind wiederholt zu werden. Bei HTTP 429 ist Retry-After zu beachten; feste Intervalle oder pauschale Wiederholungszahlen sollten nicht ohne Grundlage erfunden werden.

Wie lässt sich nach einem Timeout sicher wiederholen?

Zunächst gar nicht neu einreichen: Der Timeout lässt offen, ob KSeF den Vorgang bereits angenommen und verarbeitet hat. Die Integration fragt mit den persistierten Sitzungs- und Rechnungsreferenzen den aktuellen Zustand ab und gleicht ihn mit dem ERP ab. Erst ein eindeutig begründeter und freigegebener Recovery-Pfad darf eine erneute Einreichung auslösen.

Wie verhindert man Dubletten bei KSeF-Störungen?

Durch stabile lokale Vorgangsschlüssel, persistierte KSeF-Referenzen, idempotente Worker und einen verpflichtenden Abgleich vor jedem erneuten Versand. Unklare Fälle gehören in einen sichtbaren Zwischenzustand oder eine manuelle Warteschlange. Ein Neustart des Jobs darf nicht automatisch bedeuten, dass sämtliche Rechnungen nochmals übertragen werden.

Darf das ERP nach mehreren Timeouts in den Offline- oder Notfallmodus wechseln?

Nein, nicht allein aufgrund von Timeouts. Die offiziellen Unterlagen unterscheiden offline24, angekündigte Nichtverfügbarkeit, offiziell bekannt gegebenen Notfall und Totalausfall. Der Wechsel muss aktuellen offiziellen Mitteilungen und genehmigten Verfahren folgen; technische Beobachtungen eines Engineers sind dafür keine eigenständige Autorisierung.

Wichtige Regeln, Formate und Begriffe

Europäische KommissionEN 16931Richtlinie 2014/55/EUstrukturierte elektronische RechnungKSeF-API-Monitoring und StörungsleitfadenPolen

Weiterlesen

Offizielle Quellen

Wir priorisieren offizielle Regierungs- und EU-Quellen, soweit verfügbar, und zeigen Prüfdatumsangaben sichtbar an.