eInvoice Viewer for KSeF – Handbuch
1 · Überblick
Der eInvoice Viewer for KSeF zeigt polnische E-Rechnungen aus dem staatlichen Rechnungssystem KSeF lesbar an. Er versteht die aktuelle Struktur FA(3) und die vorige Struktur FA(2). Die Rechnung erscheint in ihrer eigenen Gliederung mit den Gruppen und Feldern des polnischen Schemas und wird nicht in die europäische Norm EN 16931 umgerechnet. Jedes Feld trägt eine deutsche oder englische Bezeichnung und eine kurze Erklärung; Codes wie die Rechnungsart oder der Steuersatz stehen als Klartext da.
Es gibt ihn in zwei Formen, die ein Produkt sind: als WordPress-Plugin, das den Viewer auf einer Seite Ihrer Website zeigt, und als App, also als Ordner mit einer HTML-Datei, der ohne Server im Browser läuft. Beide zeigen eine Rechnung mit demselben Element auf dieselbe Weise und tragen dieselbe Fassungsnummer. Die Kapitel 1 bis 11 beschreiben beide gemeinsam; wo Plugin und App sich unterscheiden, verweist ein Satz auf Kapitel 12 „Als App“ oder Kapitel 13 „Als WordPress-Plugin“.
Der Viewer ist eigenständig. Er ist kein Zusatz zum eInvoice Viewer for PEPPOL & EN16931 und braucht kein anderes Paket. Er richtet sich an alle, die KSeF-Rechnungen erhalten oder verarbeiten und sie ohne polnische Fachkenntnis verstehen müssen: den Rechnungseingang mit polnischen Lieferanten, Steuerberatung, Softwarehäuser und Integratoren.
Was der Viewer kann
- Er erkennt die Struktur FA(3) oder FA(2) am Dokument selbst.
- Er zeigt den Kopf der Rechnung mit Nummer, Datum, Währung und Gesamtbetrag.
- Er zeigt die KSeF-Nummer, wenn der Dateiname sie so trägt, wie KSeF heruntergeladene Rechnungen benennt. In der Datei selbst steht die Nummer nie.
- Er zeigt die Steuersummen je Satz als Tabelle, nur mit den Sätzen, die einen Wert tragen.
- Er zeigt die Kennzeichen der Rechnung, etwa das Split-Payment oder die Margenbesteuerung. Gesetzte Kennzeichen stehen oben mit einem erklärenden Satz; alle Kennzeichen lassen sich aufklappen.
- Er zeigt die Rechnungspositionen als Tabelle; jedes weitere Feld einer Position klappt darunter auf.
- Er zeigt den Anhang der Rechnung mit seinen Schlüssel-Wert-Listen, Texten und Tabellen und bietet eingebettete Dateien zum Speichern an.
- Er zeigt jeden Wert der Datei. Ein Wert, den der Feldkatalog nicht kennt, steht mit seinem Pfad unter „Nicht im Katalog“, damit nichts verloren geht.
- Er blendet auf Wunsch je Feld die polnische Originalbezeichnung und den Pfad ein.
- Er liest die Rechnung vollständig im Browser; die Datei wird nirgendwohin gesendet.
- Die Oberfläche gibt es auf Deutsch, Englisch und Französisch, die Feldnamen auf Deutsch und Englisch.
Was der Viewer nicht kann
- Er prüft die Rechnung nicht gegen die Regeln von KSeF. Ob eine Rechnung von KSeF angenommen würde, sagt er nicht.
- Er erzeugt keine Rechnungen und schickt nichts an KSeF.
- Er liest keine ZUGFeRD-, XRechnung- oder Peppol-Rechnungen. Diese folgen der EN 16931 und sind Sache des eInvoice Viewers for PEPPOL & EN16931.
- Er liest nicht die Struktur FA(1). Sie wurde 2023 abgelöst, und der Viewer meldet eine solche Datei als nicht unterstützt.
- Er prüft bei einer signierten Datei die Signatur nicht. Er zeigt die enthaltene Rechnung und vermerkt, dass die Signatur nicht geprüft wurde.
- Er speichert nichts und führt keine Liste geöffneter Rechnungen.
In welcher Form er kommt
| Form | Bezug | Voraussetzung | So wird er benutzt |
|---|---|---|---|
| WordPress-Plugin | Kaufprodukt, ZIP-Datei aus dem Shop auf einvoicetools.de | WordPress 6.5 oder neuer (getestet bis 7.1), PHP 8.2 oder neuer | den Kurzbefehl [spks_ksef_viewer] auf eine Seite setzen |
| App | Kaufprodukt, ZIP-Datei aus dem Shop auf einvoicetools.de | ein aktueller Browser mit eingeschaltetem JavaScript | den Ordner ablegen und einvoice-viewer-for-ksef.html öffnen |
screenshots/ks-beleg.de.pngEine geladene FA(3)-Rechnung: oben die Ablagefläche mit den beiden Schaltern und dem Knopf „Zurücksetzen“, darunter der Rechnungskopf mit Nummer, Datum, Währung, KSeF-Nummer und Gesamtbetrag, das gesetzte Kennzeichen zur Margenbesteuerung und die ersten Blöcke der Rechnung2 · Installieren
Als WordPress-Plugin
Statt des Hochladens können Sie den entpackten Ordner einvoice-viewer-for-ksef auch nach wp-content/plugins/ legen und das Plugin danach unter Plugins aktivieren. Das Plugin hat keine eigene Einstellungsseite. Aktualisieren und Entfernen beschreibt Kapitel 13.
Als App
Die App wird nicht installiert, sondern nur abgelegt. Sie braucht keinen Server und kein PHP und lädt in der Voreinstellung nichts aus dem Internet. Den Inhalt des Ordners, die Einstellungen und das Aktualisieren beschreibt Kapitel 12.
3 · Erste Schritte
screenshots/ks-ablage.de.pngDie leere Ablagefläche des Viewers: der Text „E-Rechnung hierher ziehen oder klicken, um eine Datei zu wählen“ und darunter die Angabe „Polnische KSeF-E-Rechnung, Struktur FA(3) oder FA(2), als XML“4 · Arbeiten mit dem KSeF-Viewer
Eine Rechnung öffnen
Sie ziehen eine XML-Datei auf die Ablagefläche, klicken auf die Fläche und wählen die Datei, oder Sie springen mit der Tabulatortaste auf die Fläche und drücken die Eingabetaste oder die Leertaste. Der Viewer erkennt die Struktur nicht an der Dateiendung, sondern am Dokument: am Wurzelelement Faktura, am Namensraum des Schemas und an Formularcode und Variante im Kopf der Datei. Wenn Sie mehrere Dateien auf einmal übergeben, zählt nur die erste; der Viewer zeigt immer eine Rechnung.
Ist die Datei keine FA(3)- oder FA(2)-Rechnung, meldet der Viewer: „Nicht unterstützte Datei. Bitte laden Sie eine polnische KSeF-E-Rechnung in der Struktur FA(3) oder FA(2) als XML hoch.“ Das gilt auch für FA(1)-Dateien und für E-Rechnungen nach EN 16931.
Der Rechnungskopf
Oben steht der Kopf mit der Rechnungsnummer, dem Rechnungsdatum, der Währung und dem Rechnungsbetrag. Dazu kommt die KSeF-Nummer, wenn der Dateiname ohne Endung genau der KSeF-Nummer entspricht, so wie KSeF heruntergeladene Rechnungen benennt. Der Viewer vermerkt dann „aus dem Dateinamen“, denn in der Rechnungsdatei selbst steht diese Nummer nie. Haben Sie die Datei umbenannt, fehlt die KSeF-Nummer in der Anzeige.
screenshots/ks-kopf.de.pngRechnungskopf mit Rechnungsnummer, Rechnungsdatum, Währung und Rechnungsbetrag; daneben die KSeF-Nummer mit dem Vermerk „aus dem Dateinamen“Die Gruppen des Schemas
Die Rechnung erscheint in der Gliederung des polnischen Schemas, darunter Kopfdaten, Steuersummen, Korrekturangaben, Anzahlungen, Zusatzangaben, Zahlung, Transaktionsbedingungen, Bestellung, Positionen und Anhang. Jedes Feld trägt eine deutsche oder englische Bezeichnung. Hinter dem Namen steht ein kleines „i“; wenn Sie mit der Maus darüberfahren oder es mit der Tastatur anwählen, erscheint die kurze Erklärung des Feldes.
Ein Feld mit einer Codeliste zeigt den Klartext und dahinter in Klammern den Code aus der Datei, zum Beispiel die Rechnungsart, den Steuersatz oder die Zahlungsart. Länder- und Währungsnamen nennt der Browser selbst in der eingestellten Sprache; was er nicht kennt, ergänzt die beiliegende Codeliste. Beträge erscheinen in der Schreibweise der eingestellten Sprache. Felder, die für die vorliegende Rechnungsart besonders wichtig sind, kennzeichnet der Viewer mit „Wichtig für diese Rechnungsart“ und einer farbigen Kante.
Nur gefüllte Felder
Der Schalter „Nur gefüllte Felder“ in der Werkzeugleiste blendet die Felder aus, die in dieser Rechnung keinen Wert tragen. Ohne den Schalter sehen Sie auch die leeren Felder des Katalogs und damit, was das Schema vorsieht und was diese Rechnung ausgelassen hat.
Die Steuersummen
Die Steuersummen stehen als Tabelle je Steuersatz, mit den Spalten für den Satz, die Nettosumme, die Steuer und, wenn vorhanden, die Steuer in Landeswährung. Es erscheinen nur die Sätze, die in der Rechnung einen Wert tragen; die leeren Sätze des Schemas füllen die Tabelle nicht auf. Die übrigen Felder des Blocks stehen darunter.
screenshots/ks-steuersummen.de.pngTabelle der Steuersummen mit je einer Zeile pro Steuersatz, der in der Rechnung einen Wert trägtDie Kennzeichen
Das Schema sieht eine Reihe von Kennzeichen vor, etwa für das Split-Payment, die Margenbesteuerung oder die Steuerbefreiung. Gesetzte Kennzeichen stehen oben, jedes mit einem erklärenden Satz. Mit „Alle Kennzeichen anzeigen“ klappen Sie die vollständige Liste auf; ist keines gesetzt, sagt der Viewer „Keines dieser Kennzeichen ist gesetzt.“
screenshots/ks-kennzeichen.de.pngDer Block der Kennzeichen mit dem Satz, dass gesetzte Kennzeichen oben auf der Rechnung stehen, und darunter der aufgeklappte Bereich „Alle Kennzeichen anzeigen“Die Positionen
Die Rechnungspositionen erscheinen als Tabelle; Zahlenspalten sind rechtsbündig. Jede Zeile zeigt die wichtigsten Angaben der Position; mit „Weitere Angaben“ klappen alle übrigen Felder der Position darunter auf. Auf dieselbe Weise erscheinen die Bestellzeilen. So bleibt die Tabelle lesbar, und trotzdem geht kein Wert verloren.
screenshots/ks-positionen.de.pngTabelle der Rechnungspositionen; bei einer Zeile ist „Weitere Angaben“ aufgeklappt und zeigt die übrigen Felder der PositionDer Anhang
Eine FA(3)-Rechnung kann einen Anhang mit zusätzlichen Angaben tragen. Der Viewer zeigt ihn mit seinen Schlüssel-Wert-Listen, Texten und Tabellen. Spaltenköpfe, Zeilen und Summenzeile einer Tabelle sind dabei Daten der Rechnung und werden so angezeigt, wie sie in der Datei stehen. Ein eingebetteter Dateiinhalt wird mit seiner Größe genannt und trägt den Knopf Speichern; ein Klick legt die Datei über den Download Ihres Browsers ab. Ist der Inhalt nicht lesbar, meldet der Viewer „Der Anhang konnte nicht entschlüsselt werden.“
screenshots/ks-anhang.de.pngDer Anhang einer FA(3)-Rechnung mit einer Schlüssel-Wert-Liste, einem Textabsatz und einer Tabelle mit Spaltenköpfen und SummenzeileOriginalbezeichnung und Pfad
Der Schalter „Originalbezeichnung und Pfad“ blendet an jedem Feld die polnische Bezeichnung aus dem Schema und den Pfad in der Datei ein, zum Beispiel Fa/P_2. Bei Tabellen des Anhangs steht dann auch der Datentyp der Spalte unter dem Spaltenkopf. So finden Sie einen angezeigten Wert in der XML-Datei oder in der offiziellen Beschreibung des Schemas wieder.
screenshots/ks-original-pfad.de.pngAusschnitt der Rechnungsansicht mit eingeschaltetem Schalter „Originalbezeichnung und Pfad“: unter jeder deutschen Feldbezeichnung stehen der polnische Name und der PfadNicht im Katalog
Enthält die Datei einen Wert, den der mitgelieferte Feldkatalog nicht kennt, zeigt der Viewer ihn mit seinem Pfad im Abschnitt „Nicht im Katalog“. Die Erklärung dazu lautet: „Diese Werte stehen in der Datei, aber nicht im Feldkatalog dieses Formats. Sie werden mit ihrem Pfad gezeigt, damit nichts verloren geht.“
screenshots/ks-nicht-im-katalog.de.pngAbschnitt „Nicht im Katalog“ mit einem Wert und seinem Pfad in der Datei sowie dem erklärenden Satz darüberSignierte Dateien
Eine KSeF-Rechnung kann in einer Signaturhülle verpackt sein. Der Viewer liest die Rechnung aus der signierten Datei heraus und vermerkt „signiert; Signatur nicht geprüft“. Enthält die signierte Datei keine lesbare Rechnung, sagt er das. Die Gültigkeit der Signatur prüft der Viewer nicht.
Die Sprache
Die Bedienelemente gibt es auf Deutsch, Englisch und Französisch, die Feldnamen und Erklärungen auf Deutsch und Englisch. Bei französischer Oberfläche stehen die Feldnamen deshalb auf Englisch, und der Viewer sagt dazu: „Die Feldnamen dieses Formats gibt es in dieser Sprache nicht. Sie stehen deshalb auf Englisch da.“ Im Plugin folgt die Sprache der Seite, und einen Sprachumschalter gibt es nicht. Die App hat oben rechts eine Sprachwahl mit DE, EN und FR; ein Wechsel stellt die Seitentexte und die geöffnete Rechnung um (Kapitel 12).
Zurücksetzen
Sobald eine Rechnung geladen ist, steht in der Werkzeugleiste der Knopf Zurücksetzen. Er leert die Anzeige und blendet die Werkzeugleiste und die Zeile mit dem Dateinamen wieder aus. Die Rechnung ist danach nirgends mehr vorhanden, weil der Viewer sie nicht speichert.
5 · Einstellungen
Der Viewer hat in der Ansicht selbst nur die beiden Schalter aus Kapitel 4. Im Übrigen unterscheiden sich die beiden Formen:
- In der App stehen die Einstellungen in der Datei
config.jsim Ordner der App. Sie legen dort die Startsprache fest und ob die Schriften aus dem Ordner oder von Google Fonts kommen (Kapitel 12). - Im Plugin gibt es keine eigene Einstellungsseite und keine eigenen Einstellungen. Der Kurzbefehl hat keine Attribute. Die Gestaltung folgt dem Design-Kit, das für alle eInvoice-Werkzeuge der Website gemeinsam gewählt wird (Kapitel 13).
6 · Besondere Fälle
Sie wollen die KSeF-Nummer einer Rechnung sehen. Öffnen Sie die Datei unter dem Dateinamen, den KSeF beim Herunterladen vergibt. Der Viewer liest die Nummer aus dem Namen; eine umbenannte Datei trägt sie nicht mehr.
Sie wollen mit einem polnischen Lieferanten über ein Feld sprechen. Schalten Sie „Originalbezeichnung und Pfad“ ein. Unter dem deutschen Feldnamen stehen dann die polnische Bezeichnung aus dem Schema und der Pfad, etwa Fa/P_13_1. Beides kennen der Lieferant und seine Software.
Sie wollen schnell sehen, was eine Rechnung besonders macht. Sehen Sie oben auf die gesetzten Kennzeichen; jedes steht dort mit einem erklärenden Satz. Mit „Alle Kennzeichen anzeigen“ sehen Sie auch, was nicht gesetzt ist.
Sie wollen nur lesen, was die Rechnung enthält, ohne leere Felder. Schalten Sie „Nur gefüllte Felder“ ein. Leere Felder des Schemas verschwinden aus der Ansicht; die Tabelle der Steuersummen zeigt ohnehin nur Sätze mit Wert.
Sie erhalten noch Rechnungen in der älteren Struktur FA(2). Öffnen Sie sie wie eine FA(3)-Rechnung. Der Viewer erkennt die Struktur an der Datei und nutzt für FA(2) einen eigenen Feldkatalog.
Sie wollen jeden Abruf nach außen ausschließen. Nehmen Sie die App mit ihrer Voreinstellung; sie löst dann keinen einzigen Abruf aus (Kapitel 12). Das Plugin lädt ohnehin nur Dateien von Ihrer eigenen Website (Kapitel 9).
Sie wollen das Werkzeug weitergeben. Geben Sie den ganzen Ordner der App weiter, etwa als ZIP. Der Empfänger entpackt ihn und öffnet die Startdatei; er braucht nichts zu installieren.
7 · Zusammenspiel mit anderen Paketen
Der KSeF-Viewer arbeitet allein. Er braucht kein anderes Paket, und kein anderes Paket erweitert seine Anzeige.
| Paket | Was im Zusammenspiel dazukommt |
|---|---|
| eInvoice Viewer for PEPPOL & EN16931 | Nichts in der Anzeige. Die beiden Viewer ergänzen sich im Formatumfang: der eine zeigt Rechnungen nach EN 16931 (XRechnung, ZUGFeRD / Factur-X, Peppol), der andere KSeF-Rechnungen. Beide können auf derselben Website stehen. Ist das Plugin des EN-16931-Viewers installiert, gilt dessen Wahl des Design-Kits auch für das KSeF-Plugin. |
| Andere eInvoice-Werkzeuge mit Einstellungsseite (Plugin) | Die dort gewählte gemeinsame Einstellung „Design-Kit“ gilt auch für das KSeF-Plugin. |
Zusätze wie „Extended Profiles“, „Technical Details“ oder „Visualizer“ gehören zum eInvoice Viewer for PEPPOL & EN16931 und wirken nicht im KSeF-Viewer.
8 · Wenn etwas nicht geht
Meldungen, die nur in einer der beiden Formen vorkommen, sind mit „(Plugin)“ oder „(App)“ gekennzeichnet.
| Anzeichen | Ursache | Abhilfe |
|---|---|---|
| „Nicht unterstützte Datei. Bitte laden Sie eine polnische KSeF-E-Rechnung in der Struktur FA(3) oder FA(2) als XML hoch.“ | Die Datei ist keine FA(3)- oder FA(2)-Rechnung, etwa eine FA(1)-Datei, eine XRechnung, ein ZUGFeRD-PDF, oder das XML ist beschädigt. | Öffnen Sie die XML-Datei der KSeF-Rechnung. Rechnungen nach EN 16931 zeigt der eInvoice Viewer for PEPPOL & EN16931. |
| „Die Datei ist zu groß.“ (Plugin) | Die Datei überschreitet die Größe, die der Viewer im Plugin liest. | Prüfen Sie, ob es wirklich die Rechnungsdatei ist und nicht ein Paket mit weiteren Dateien. |
| „Die Datei konnte nicht gelesen werden.“ | Der Browser konnte die Datei nicht öffnen, oder sie ist beschädigt. | Laden Sie die Datei erneut aus KSeF herunter und versuchen Sie es noch einmal. |
| „Die signierte Datei enthält keine lesbare Rechnung.“ | Die Datei trägt eine Signatur, aber darin steckt keine FA(3)- oder FA(2)-Rechnung. | Lassen Sie sich die Rechnung als unverpackte XML-Datei geben. |
| „Der Feldkatalog für … konnte nicht geladen werden.“ | Die Kataloge fehlen: im Plugin der Ordner assets/data/ksef/, in der App der Ordner data/. Im Plugin kann auch ein Sicherheitsplugin den Abruf blockieren. | Installieren Sie das Plugin vollständig neu, oder stellen Sie den Ordner der App vollständig aus dem ZIP wieder her. |
| „Der Anhang konnte nicht entschlüsselt werden.“ | Der eingebettete Inhalt des Anhangs ist nicht in lesbarer Form enthalten. | Die übrige Rechnung wird trotzdem gezeigt. Fragen Sie beim Aussteller nach. |
| Die Feldnamen sind englisch, obwohl die Oberfläche französisch ist. | Feldnamen gibt es nur auf Deutsch und Englisch. | Keine; der Viewer sagt es über der Rechnung. |
| Werte stehen unter „Nicht im Katalog“. | Die Datei trägt Elemente, die der beiliegende Katalog nicht kennt. | Die Werte sind vollständig da. Prüfen Sie, ob eine neuere Fassung vorliegt. |
| Die KSeF-Nummer fehlt im Kopf. | Der Dateiname trägt die Nummer nicht, etwa weil die Datei umbenannt wurde. | Öffnen Sie die Datei unter dem Namen, den KSeF beim Herunterladen vergibt. |
Die Seite zeigt den Kurzbefehl [spks_ksef_viewer] als Text. (Plugin) | Das Plugin ist nicht aktiv. | Aktivieren Sie es unter Plugins. |
| Die Ablagefläche erscheint nicht, obwohl das Plugin aktiv ist. (Plugin) | Der Kurzbefehl steht nicht im Inhalt einer einzelnen Seite oder eines Beitrags, sondern etwa in einem Widget oder einer Vorlage, und die Skriptdateien wurden nicht geladen. | Setzen Sie den Kurzbefehl in den Seiteninhalt, oder lassen Sie die Dateien mit dem Filter spks_force_enqueue laden (Kapitel 10). |
| Die Bedienelemente sind englisch, obwohl die Seite deutsch ist. (Plugin) | Die Sprachtabelle i18n/de.json.js fehlt oder konnte nicht geladen werden. Ohne Tabelle zeigt der Viewer seine englischen Quelltexte. | Installieren Sie das Plugin vollständig neu. |
| Die Seite steht in einer anderen Schrift als erwartet. (App) | Der Ordner assets/fonts/ fehlt, oder fontsLocal steht auf false und Google Fonts ist nicht erreichbar. | Stellen Sie den Ordner wieder her oder setzen Sie fontsLocal auf true. Die Funktion ist davon nicht berührt. |
| Nach dem Aktualisieren sind die Einstellungen weg. (App) | Die Datei config.js wurde durch die frische Fassung überschrieben. | Tragen Sie Ihre Werte erneut ein und sichern Sie die Datei vor der nächsten Aktualisierung. |
9 · Datenschutz und Sicherheit
Eine Rechnung enthält Namen, Anschriften, Steuernummern, Bankverbindungen und Beträge.
- Die Rechnung bleibt in beiden Formen im Browser. Der Browser liest die Datei an Ort und Stelle. Sie wird nicht auf Ihre Website hochgeladen und an keinen anderen Server geschickt. Ein gespeicherter Anhang geht nur von Ihrem Browser auf Ihre Festplatte.
- Im Plugin kommen nur die Dateien des Plugins von Ihrer Website. Der Browser lädt Skript, Stildateien, Sprachtabelle und Feldkataloge aus dem Ordner des Plugins auf Ihrem Server. Das Plugin lädt nichts von fremden Servern.
- In der App geht in der Voreinstellung nichts nach außen. Schriften, Kataloge, Sprachtabellen und Stylesheets liegen im Ordner. Nur wenn Sie in
config.jsden SchlüsselfontsLocalauffalsestellen, holt die Seite beim Öffnen Schriften von Google Fonts; die Rechnung wird auch dann nicht gesendet. - Gespeichert wird keine Rechnung. Das Plugin legt keine Einstellungen und keine Rechnungsdaten in der Datenbank ab. Die App merkt sich im Browser nur die zuletzt angeklickte Sprache unter dem Schlüssel
einvoice-viewer-lang; diesen Schlüssel teilen sich alle Viewer von invoiceTools in demselben Browser. - Signaturen werden nicht geprüft. Eine signierte Datei wird gelesen, aber die Anzeige „signiert; Signatur nicht geprüft“ ist keine Aussage über die Echtheit.
- Abgeschirmte Gestaltung. Der Viewer zeichnet in einem eigenen, abgeschirmten Bereich der Seite (Shadow DOM). Die Gestaltung Ihres Themes wirkt nicht auf ihn, und seine Stildateien wirken nicht auf Ihre Seite.
Tipp: Prüfen Sie es selbst: Öffnen Sie die Netzwerkanzeige Ihres Browsers (Taste F12) und ziehen Sie eine Rechnung in den Viewer. Im Plugin werden nur Dateien von Ihrer eigenen Website abgerufen, in der App mit der Voreinstellung gar keine, und keine Anfrage mit Rechnungsdaten geht hinaus.
10 · Für Entwickler
Das Werkzeug ist in beiden Formen dasselbe HTML-Element <einvoice-group-viewer> mit abgeschirmter Gestaltung (Shadow DOM). Das KSeF-Format meldet sich beim Laden selbst an.
Gemeinsam
| Stelle | Art | Bedeutung |
|---|---|---|
| Attribute | data-lang, data-lang-switch, data-css, data-max-size, data-catalog-index | Feste Sprache (de, en oder fr); 0 blendet die eigene Sprachwahl aus; Stylesheets für den Shadow Root; Größengrenze in Byte; Adresse eines Katalogverzeichnisses, nur ohne catalogs. |
| Eigenschaften und Methoden | catalogs, model, setLanguage(code), showXml(text, { name }) | Kataloge setzen; das gelesene Modell lesen; Sprache umstellen; eine Rechnung als Text übergeben. |
| Ereignisse | einvoice-document-ready, einvoice-language-changed, einvoice-reset | Steigen am Element auf. Das erste trägt in detail Format, Modell und Dateinamen, das zweite die Sprache. |
globalThis.EInvoiceGroupViewer | Klasse des Elements | addFormat() meldet ein Format an. |
globalThis.einvoiceI18n | Sprachtabellen | Die Dateien in i18n/ tragen die Oberflächentexte für Deutsch und Französisch ein; Englisch ist die Quellsprache. einvoiceI18n.available nennt die verfügbaren Sprachen. Mehrere Pakete auf einer Seite führen ihre Tabellen zusammen. |
Die Erkennung prüft den Namensraum http://crd.gov.pl/wzor/2025/06/25/13775/ für FA(3) und http://crd.gov.pl/wzor/2023/06/29/12648/ für FA(2), jeweils mit Formularcode und Variante im Kopf.
Im Plugin
| Art | Name | Bedeutung |
|---|---|---|
| Kurzbefehl | spks_ksef_viewer | Der Viewer. Attribute werden nicht ausgewertet. Der Kurzbefehl gibt das Element mit data-lang nach der Sprache der Seite, data-lang-switch="0", data-css (Viewer, Kit-Tokens, Kit, Gruppenansicht) und data-catalog-index (die Adresse von assets/data/ksef/index.json) aus. |
| Filter | spks_force_enqueue | Erhält true oder false und entscheidet, ob Stil- und Skriptdateien des Viewers schon früh auf wp_enqueue_scripts geladen werden. Standard: true auf einer einzelnen Seite oder einem Beitrag, deren Inhalt den Kurzbefehl enthält, sonst false. |
| Filter | einvoice_design_kit | Gemeinsamer Filter aller eInvoice-Werkzeuge. Erhält den Kurznamen des gewählten Kits aus der Option einvoice_design_kit (Standard h) und erlaubt, das Kit im Code zu setzen. Ein Wert, zu dem im Ordner assets/css/ dieses Plugins kein Kit liegt, führt zu Kit H. |
| Option | einvoice_design_kit | Die gemeinsame Einstellung des Design-Kits. Das Plugin liest sie nur und registriert sie nicht selbst. |
| Konstanten | SPKS_VERSION, SPKS_FILE, SPKS_DIR, SPKS_URL, SPKS_SHORTCODE | Fassung, Hauptdatei, Verzeichnis, Adresse des Plugins und der Name des Kurzbefehls. |
| Stil- und Skriptkennungen | spks-kit, spks-viewer-element, spks-i18n-index, spks-i18n | Die Marken des Design-Kits im Dokument, das Skriptbündel assets/js/einvoice-ksef-viewer.bundle.js, die Liste der verfügbaren Sprachen und die Sprachtabelle. Die Kennung spks-i18n existiert auch ohne Tabelle, damit das Bündel geladen wird. |
| Skriptmodul | assets/js/einvoice-ksef-viewer.bundle.js | Wird mit type="module" ausgeliefert; das Plugin ändert dafür das von WordPress erzeugte <script>-Tag und erhält dessen übrige Attribute, etwa einen CSP-Nonce. |
| Feldkataloge | assets/data/ksef/index.json und die dort genannten Dateien | Je ein Katalog für FA(3) und FA(2), je Sprache Deutsch und Englisch. |
| Textdomäne | einvoice-viewer-for-ksef | Übersetzungen liegen im Ordner /languages des Plugins; die Sprachtabellen in i18n/ werden daraus beim Bau erzeugt. |
add_filter( 'spks_force_enqueue', '__return_true' );In der App
| Stelle | Art | Bedeutung |
|---|---|---|
window.einvoiceConfig | Objekt in config.js | Die Einstellungen aus Kapitel 12. Das Seitenskript liest lang, die Startseite fontsLocal. |
globalThis.einvoiceData | Verzeichnis der Datenpakete | Die Skriptdateien in data/ tragen sich hier ein. Das Seitenskript baut daraus die Kataloge je Profil (ksef-fa3, ksef-fa2) und Sprache (de, en) und setzt sie als Eigenschaft catalogs. |
Startdatei, app.js, einvoice-viewer-for-ksef.js | erzeugte Dateien | Entstehen beim Bau des Pakets; ein Handeingriff geht mit der nächsten Fassung verloren. Das Element steht in einvoice-viewer-for-ksef.js als klassisches Skript, weil Browser ES-Module von file:// nicht laden. |
Beide Formen stehen unter der Lizenz GPL-2.0-or-later. Die Kataloge tragen Texte aus dem MIT-lizenzierten Schema des polnischen Finanzministeriums.
11 · Fassungen
Die vollständige Liste der Änderungen steht in der Datei CHANGELOG.md im Ordner der App und in der readme.txt des Plugins.
| Fassung | Änderung |
|---|---|
| 1.0.0 | Erste Fassung. Zeigt KSeF-Rechnungen der Strukturen FA(3) und FA(2) in ihrer eigenen Gliederung, mit deutschen und englischen Feldnamen und Klartext für Codes, vollständig im Browser. |
12 · Als App
12.1 Ordner und Startdatei
Die App ist der Ordner einvoice-viewer-for-ksef. Er muss vollständig bleiben. Zu ihm gehören:
| Inhalt | Wozu |
|---|---|
einvoice-viewer-for-ksef.html | die Startseite |
einvoice-viewer-for-ksef.js, app.js | das Werkzeug und das Skript der Seite |
config.js | die Einstellungen (Abschnitt 12.2) |
data/ | die Feldkataloge und Codelisten für FA(3) und FA(2) auf Deutsch und Englisch; ohne sie kann die Seite die Rechnung nicht erklären |
i18n/ | die Sprachtabellen der Oberfläche |
assets/ | Gestaltung, Druck-Stylesheet und Schriften |
manual/ | dieses Handbuch als Seite, deutsch und englisch |
CHANGELOG.md, Lizenzdateien | die Änderungen und die Lizenztexte |
Die Startseite läuft mit einem Doppelklick von der Festplatte, von einem USB-Stick, von einem Netzlaufwerk oder von einem Webserver. Auf einem Netzlaufwerk teilen Sie den Pfad zur Startdatei mit; auf den Arbeitsplätzen ist nichts einzurichten.
12.2 Die Datei config.js
Die App hat keine Einstellungsseite. Ihre Einstellungen stehen in config.js. Sie öffnen die Datei mit einem Texteditor, ändern einen Wert, speichern und laden die Seite neu. Die Datei ist in allen Apps von invoiceTools gleich aufgebaut und trägt sechs Schlüssel; dieser Viewer wertet zwei davon aus.
| Einstellung | Standard | Wirkung |
|---|---|---|
lang | '' | Die Sprache, in der die Seite startet: 'de', 'en' oder 'fr'. Leer bedeutet die Sprache des Browsers. Hat jemand an diesem Browser schon einmal eine Sprache angeklickt, geht diese gemerkte Wahl vor. Fällt alles aus, startet die Seite auf Deutsch. |
fontsLocal | true | true heißt: die Schriften aus assets/fonts/, ohne Abruf nach außen. false heißt: Verweis auf Google Fonts, mit Rückfall auf Systemschriften. |
dataSource | 'local' | In dieser Fassung ohne Wirkung. Die Kataloge werden immer aus dem Ordner data/ gelesen; die Seite fragt nie online nach. |
onlineUpdates | false | In dieser Fassung ohne Wirkung. |
serviceUrl | '' | In dieser Fassung ohne Wirkung. Die Seite ruft keinen Dienst auf. |
allowedProfiles | [] | In dieser Fassung ohne Wirkung. Die Seite zeigt jede FA(3)- und FA(2)-Rechnung. |
In config.js steht außerdem ein Kommentar zum Zusatz „Extended Profiles“ und zum Ordner data/protected/. Er stammt aus der gemeinsamen Vorlage der Apps und betrifft den eInvoice Viewer for PEPPOL & EN16931; für KSeF-Rechnungen hat er keine Bedeutung.
Für eine Seite, die immer auf Englisch startet und ihre Schriften von Google Fonts holt, ändern Sie zwei Zeilen:
lang: 'en',
fontsLocal: false,Für den Betrieb hinter einer Firewall lassen Sie die Datei, wie sie ist. Die Seite löst dann keinen Abruf aus, auch keinen, der fehlschlagen würde. Das ist wichtig, weil ein blockierter Abruf trotzdem im Protokoll des Proxys steht und dort wie ein Datenabfluss aussieht.
12.3 Die Sprachwahl
Oben rechts steht die Sprachwahl mit DE, EN und FR. Ein Wechsel stellt die Seitentexte und die geöffnete Rechnung um. Die Seite startet in der Sprache, die zuletzt angeklickt wurde, sonst nach lang aus config.js, sonst in der Sprache des Browsers.
12.4 Drucken und Schriften
Im Ordner liegt assets/css/kit-print.css. Die Datei ist bewusst nicht angemeldet. Sie richtet die Seite fürs Papier ein: weißer Grund, keine Werkzeugleiste, Signalkanten als Linie statt als Schatten. Ergänzen Sie dazu im <head> der Startdatei hinter dem Kit diese Zeile:
<link rel="stylesheet" href="assets/css/kit-print.css" media="print">Die Reihenfolge zählt: Die Zeile muss nach dem Kit stehen, sonst setzen sich die Bildschirmregeln durch.
Sie dürfen den Ordner assets/fonts/ löschen, wenn der Ordner kleiner werden soll. Die Ansicht bleibt vollständig gestaltet und steht dann in Systemschriften.
12.5 Aktualisieren und Entfernen
Achtung: Ein neues Paket bringt eine frische config.js mit. Wer sie blind überschreibt, verliert seine Einstellungen.
Zum Entfernen löschen Sie den Ordner. Die App legt keine Datenbank an und schreibt nichts außerhalb ihres Ordners auf den Datenträger.
13 · Als WordPress-Plugin
13.1 Der Kurzbefehl
Der Viewer erscheint auf jeder Seite, die den Kurzbefehl [spks_ksef_viewer] trägt. Der Kurzbefehl hat keine Attribute.
[spks_ksef_viewer]Die Sprache des Viewers folgt der Sprache der Seite: Deutsch, Englisch oder Französisch; jede andere Seitensprache führt zu Englisch. Einen Sprachumschalter für Besucher zeigt das Plugin nicht.
13.2 Das Design-Kit
Das Plugin hat keine eigene Einstellungsseite und speichert keine eigenen Einstellungen. Es folgt dem Design-Kit, das für alle eInvoice-Werkzeuge der Website gemeinsam gewählt wird.
| Einstellung | Standard | Wirkung |
|---|---|---|
| Design-Kit der eInvoice-Werkzeuge | Kit H | Bestimmt Farben, Schriften und Maße des Viewers. Das Plugin liest die gemeinsame Wahl, bietet aber selbst keine Auswahl an. Die Auswahl steht auf der Einstellungsseite eines anderen eInvoice-Werkzeugs, etwa des eInvoice Viewers for PEPPOL & EN16931. Ist kein solches Werkzeug installiert, oder ist das gewählte Kit in diesem Plugin nicht enthalten, zeichnet der Viewer mit Kit H, ohne die Wahl zu ändern. |
Hinweis: Das Plugin bringt die Stildateien seiner Kits selbst mit. Es lädt nur die Farb- und Maßangaben des Kits in die Seite; das vollständige Kit wirkt allein innerhalb des Viewers, sodass Ihr Theme unverändert bleibt.
13.3 Aktualisieren und Entfernen
Eine neue Fassung laden Sie unter Plugins → Neues Plugin hinzufügen → Plugin hochladen hoch; WordPress ersetzt die vorhandene Fassung. Da das Plugin keine eigenen Einstellungen speichert, geht dabei nichts verloren. Die Stil- und Skriptdateien tragen die Fassungsnummer in ihrer Adresse, sodass Browser nach einer Aktualisierung die neuen Dateien laden.
Sie deaktivieren und löschen das Plugin unter Plugins. Das Plugin legt keine eigenen Einträge in der Datenbank an, weder Einstellungen noch Rechnungsdaten; es bleibt nichts zurück. Die gemeinsame Einstellung „Design-Kit“ liest das Plugin nur; angelegt wird sie von einem anderen Werkzeug.
14 · Bilderliste
Diese Liste zeigt, welche Bildschirmfotos dieses Handbuch erwartet und welche im Ordner screenshots/ des Pakets gefunden wurden. Ein Bild heißt immer Kennung.Sprache.png, zum Beispiel ks-beleg.de.png. Fehlt die deutsche Fassung, zeigt das Handbuch die englische. Auf den Bildern sind nur Beispieldaten zu sehen.
| Stand | Datei | Was zu sehen ist |
|---|---|---|
| – | ks-beleg.de.png | Eine geladene FA(3)-Rechnung: oben die Ablagefläche mit den beiden Schaltern und dem Knopf „Zurücksetzen“, darunter der Rechnungskopf mit Nummer, Datum, Währung, KSeF-Nummer und Gesamtbetrag, das gesetzte Kennzeichen zur Margenbesteuerung und die ersten Blöcke der Rechnung |
| – | ks-ablage.de.png | Die leere Ablagefläche des Viewers: der Text „E-Rechnung hierher ziehen oder klicken, um eine Datei zu wählen“ und darunter die Angabe „Polnische KSeF-E-Rechnung, Struktur FA(3) oder FA(2), als XML“ |
| – | ks-kopf.de.png | Rechnungskopf mit Rechnungsnummer, Rechnungsdatum, Währung und Rechnungsbetrag; daneben die KSeF-Nummer mit dem Vermerk „aus dem Dateinamen“ |
| – | ks-steuersummen.de.png | Tabelle der Steuersummen mit je einer Zeile pro Steuersatz, der in der Rechnung einen Wert trägt |
| – | ks-kennzeichen.de.png | Der Block der Kennzeichen mit dem Satz, dass gesetzte Kennzeichen oben auf der Rechnung stehen, und darunter der aufgeklappte Bereich „Alle Kennzeichen anzeigen“ |
| – | ks-positionen.de.png | Tabelle der Rechnungspositionen; bei einer Zeile ist „Weitere Angaben“ aufgeklappt und zeigt die übrigen Felder der Position |
| – | ks-anhang.de.png | Der Anhang einer FA(3)-Rechnung mit einer Schlüssel-Wert-Liste, einem Textabsatz und einer Tabelle mit Spaltenköpfen und Summenzeile |
| – | ks-original-pfad.de.png | Ausschnitt der Rechnungsansicht mit eingeschaltetem Schalter „Originalbezeichnung und Pfad“: unter jeder deutschen Feldbezeichnung stehen der polnische Name und der Pfad |
| – | ks-nicht-im-katalog.de.png | Abschnitt „Nicht im Katalog“ mit einem Wert und seinem Pfad in der Datei sowie dem erklärenden Satz darüber |