eInvoice Viewer for KSeF – Manual

1 · Overview

eInvoice Viewer for KSeF displays Polish e-invoices from the state invoicing system KSeF in readable form. It understands the current structure FA(3) and the previous structure FA(2). The invoice appears in its own outline with the groups and fields of the Polish schema and is not converted into the European standard EN 16931. Every field carries a German or English name and a short explanation; codes such as the invoice type or the tax rate appear as plain text.

It comes in two forms that are one product: as a WordPress plugin, which shows the viewer on a page of your website, and as an app, that is, a folder with an HTML file that runs in the browser without a server. Both show an invoice with the same element in the same way and carry the same version number. Chapters 1 to 11 describe both together; where plugin and app differ, a sentence points to chapter 12 "As an app" or chapter 13 "As a WordPress plugin".

The viewer stands on its own. It is not an add-on to eInvoice Viewer for PEPPOL & EN16931 and needs no other package. It is meant for everyone who receives or processes KSeF invoices and must understand them without knowing Polish or the schema: incoming invoices from Polish suppliers, tax advisers, software houses and integrators.

What the viewer can do

• It recognises the structure FA(3) or FA(2) from the document itself.
• It shows the head of the invoice with number, date, currency and total amount.
• It shows the KSeF number when the file name carries it the way KSeF names downloaded invoices. The number never stands in the file itself.
• It shows the tax totals per rate as a table, only with the rates that carry a value.
• It shows the flags of the invoice, such as split payment or margin taxation. Set flags appear at the top with an explaining sentence; all flags can be expanded.
• It shows the invoice lines as a table; every further field of a line expands below it.
• It shows the attachment of the invoice with its key-value lists, texts and tables and offers embedded files for saving.
• It shows every value of the file. A value the field catalogue does not know appears with its path under "Not in the catalog", so that nothing is lost.
• On request it shows the original Polish name and the path for every field.
• It reads the invoice completely in the browser; the file is sent nowhere.
• The interface comes in German, English and French, the field names in German and English.

What the viewer cannot do

• It does not check the invoice against the rules of KSeF. Whether KSeF would accept an invoice, it does not say.
• It creates no invoices and sends nothing to KSeF.
• It does not read ZUGFeRD, XRechnung or Peppol invoices. These follow EN 16931 and are the business of eInvoice Viewer for PEPPOL & EN16931.
• It does not read the structure FA(1). It was replaced in 2023, and the viewer reports such a file as not supported.
• It does not check the signature of a signed file. It shows the invoice inside and notes that the signature was not checked.
• It stores nothing and keeps no list of opened invoices.

In which form it comes

2 · Installation

As a WordPress plugin

1. Download the ZIP file from the shop on einvoicetools.de to your computer.
2. In WordPress, open Plugins → Add New Plugin and choose Upload Plugin.
3. Choose the ZIP file, click Install Now and then Activate Plugin.
4. Create a page, write the shortcode [spks_ksef_viewer] into the content and publish the page.

Instead of uploading, you can also place the unpacked folder einvoice-viewer-for-ksef in wp-content/plugins/ and then activate the plugin under Plugins. The plugin has no settings page of its own. Updating and removing are described in chapter 13.

As an app

1. Download the ZIP file from the shop on einvoicetools.de and unpack it wherever you like: in your documents, on a USB stick, on a network drive or in a directory of your web server.
2. In the folder einvoice-viewer-for-ksef, open the file einvoice-viewer-for-ksef.html with a double click.

The app is not installed, only placed. It needs no server and no PHP and, as delivered, loads nothing from the internet. The content of the folder, the settings and updating are described in chapter 12.

3 · First steps

1. Open the page with the shortcode or the start file of the app. You see the drop zone "Drag an e-invoice here or click to choose a file" with the note that a Polish KSeF e-invoice in the structure FA(3) or FA(2) as XML is expected.

1. Drag a KSeF invoice as an XML file onto the zone, or click and choose the file.
2. The invoice appears. Above it are the toolbar with the two switches and the button Reset, and a line with the file name, the structure recognised, such as "KSeF FA(3) 1-0E", and the invoice number. At the top of the invoice is the head, followed by the groups of the schema.
3. Switch on "Original name and path". Every field now also shows its Polish name from the schema and its path in the file.
4. Drag in the next invoice if you want to read another one. It replaces the previous one.

4 · Working with the KSeF viewer

Opening an invoice

You drag an XML file onto the drop zone, click the zone and choose the file, or move to the zone with the Tab key and press Enter or the space bar. The viewer does not recognise the structure by the file extension but by the document: by the root element Faktura, by the namespace of the schema and by form code and variant in the head of the file. If you hand over several files at once, only the first counts; the viewer always shows one invoice.

If the file is not an FA(3) or FA(2) invoice, the viewer reports: "Unsupported file. Please upload a Polish KSeF e-invoice in the structure FA(3) or FA(2) as XML." This also applies to FA(1) files and to e-invoices under EN 16931.

The invoice head

At the top is the head with the invoice number, the invoice date, the currency and the invoice amount. The KSeF number is added when the file name without extension is exactly the KSeF number, the way KSeF names downloaded invoices. The viewer then notes "taken from the file name", because this number never stands in the invoice file itself. If you renamed the file, the KSeF number is missing from the display.

The groups of the schema

The invoice appears in the outline of the Polish schema, among them head data, tax totals, correction details, advance payments, additional details, payment, transaction terms, order, lines and attachment. Every field carries a German or English name. After the name stands a small "i"; when you move the mouse over it or select it with the keyboard, the short explanation of the field appears.

A field with a code list shows the plain text and after it, in brackets, the code from the file, for example the invoice type, the tax rate or the payment method. The browser itself names countries and currencies in the chosen language; what it does not know, the bundled code list adds. Amounts appear in the notation of the chosen language. Fields that matter most for the invoice type at hand are marked "Relevant for this type of invoice" and a coloured edge.

Only filled fields

The switch "Only filled fields" in the toolbar hides the fields that carry no value in this invoice. Without the switch you also see the empty fields of the catalogue and thereby what the schema provides and what this invoice left out.

The tax totals

The tax totals appear as a table per tax rate, with columns for the rate, the net total, the tax and, if present, the tax in local currency. Only the rates that carry a value in the invoice appear; the empty rates of the schema do not fill the table. The other fields of the block stand below it.

The flags

The schema provides a number of flags, for example for split payment, margin taxation or tax exemption. Set flags appear at the top, each with an explaining sentence. With "Show all flags" you expand the complete list; if none is set, the viewer says "None of these flags is set."

The lines

The invoice lines appear as a table; number columns are right-aligned. Every row shows the most important details of the line; with "More details" all other fields of the line expand below it. The order lines appear the same way. The table stays readable, and still no value is lost.

The attachment

An FA(3) invoice can carry an attachment with additional details. The viewer shows it with its key-value lists, texts and tables. Column headings, rows and total row of a table are data of the invoice and are shown as they stand in the file. An embedded file content is named with its size and carries the button Save; a click puts the file down through your browser's download. If the content cannot be read, the viewer reports "The attachment could not be decoded."

Original name and path

The switch "Original name and path" shows the Polish name from the schema and the path in the file for every field, for example Fa/P_2. For tables of the attachment, the data type of the column then also appears below the column heading. This way you find a displayed value again in the XML file or in the official description of the schema.

Not in the catalog

If the file contains a value the bundled field catalogue does not know, the viewer shows it with its path in the section "Not in the catalog". The explanation reads: "These values are in the file but not in the field catalog of this format. They are shown with their path, so that nothing is lost."

Signed files

A KSeF invoice can be wrapped in a signature envelope. The viewer reads the invoice out of the signed file and notes "signed; signature not checked". If the signed file contains no readable invoice, it says so. The viewer does not check the validity of the signature.

The language

The controls come in German, English and French, the field names and explanations in German and English. With a French interface the field names therefore appear in English, and the viewer says: "The field names of this format are not available in this language. They are shown in English." In the plugin the language follows the page, and there is no language switch. The app has a language choice at the top right with DE, EN and FR; a change switches the page texts and the open invoice (chapter 12).

Resetting

As soon as an invoice is loaded, the toolbar has the button Reset. It clears the display and hides the toolbar and the file-name line again. The invoice then exists nowhere any more, because the viewer does not store it.

5 · Settings

In the view itself the viewer has only the two switches from chapter 4. Beyond that, the two forms differ:

• In the app the settings are in the file config.js in the folder of the app. There you set the start language and whether the fonts come from the folder or from Google Fonts (chapter 12).
• In the plugin there is no settings page and there are no settings of its own. The shortcode has no attributes. The design follows the design kit chosen for all eInvoice tools of the website together (chapter 13).

6 · Special cases

You want to see the KSeF number of an invoice. Open the file under the file name KSeF gives it when downloading. The viewer reads the number from the name; a renamed file no longer carries it.

You want to talk to a Polish supplier about a field. Switch on "Original name and path". Below the field name then stand the Polish name from the schema and the path, for example Fa/P_13_1. Both are known to the supplier and their software.

You want to see quickly what makes an invoice special. Look at the set flags at the top; each stands there with an explaining sentence. With "Show all flags" you also see what is not set.

You want to read only what the invoice contains, without empty fields. Switch on "Only filled fields". Empty fields of the schema disappear from the view; the table of tax totals shows only rates with a value anyway.

You still receive invoices in the older structure FA(2). Open them like an FA(3) invoice. The viewer recognises the structure from the file and uses a field catalogue of its own for FA(2).

You want to rule out every request to the outside. Use the app with its default settings; it then makes no request at all (chapter 12). The plugin loads only files from your own website anyway (chapter 9).

You want to pass the tool on. Pass on the whole folder of the app, for example as a ZIP. The recipient unpacks it and opens the start file; nothing needs to be installed.

7 · Working with other packages

The KSeF viewer works on its own. It needs no other package, and no other package extends its display.

Add-ons such as "Extended Profiles", "Technical Details" or "Visualizer" belong to eInvoice Viewer for PEPPOL & EN16931 and have no effect in the KSeF viewer.

8 · Troubleshooting

Messages that occur in only one of the two forms are marked "(plugin)" or "(app)".

9 · Privacy and security

An invoice contains names, addresses, tax numbers, bank details and amounts.

• In both forms the invoice stays in the browser. The browser reads the file on the spot. It is not uploaded to your website and is sent to no other server. A saved attachment only goes from your browser to your disk.
• In the plugin only the plugin's files come from your website. The browser loads script, style files, language table and field catalogues from the plugin's folder on your server. The plugin loads nothing from outside servers.
• In the app nothing goes outside as delivered. Fonts, catalogues, language tables and style sheets are in the folder. Only if you set the key fontsLocal in config.js to false does the page fetch fonts from Google Fonts when it opens; the invoice is not sent even then.
• No invoice is stored. The plugin stores no settings and no invoice data in the database. The app only remembers the language last clicked in the browser, under the key einvoice-viewer-lang; all viewers by invoiceTools in the same browser share this key.
• Signatures are not checked. A signed file is read, but the note "signed; signature not checked" says nothing about authenticity.
• Shielded design. The viewer draws in its own shielded area of the page (shadow DOM). Your theme's design does not affect it, and its style files do not affect your page.

10 · For developers

In both forms the tool is the same HTML element <einvoice-group-viewer> with shielded design (shadow DOM). The KSeF format registers itself when loaded.

Shared

Recognition checks the namespace http://crd.gov.pl/wzor/2025/06/25/13775/ for FA(3) and http://crd.gov.pl/wzor/2023/06/29/12648/ for FA(2), each with form code and variant in the head.

In the plugin

add_filter( 'spks_force_enqueue', '__return_true' );

In the app

Both forms are licensed under GPL-2.0-or-later. The catalogues carry texts from the MIT-licensed schema of the Polish Ministry of Finance.

11 · Versions

The complete list of changes is in the file CHANGELOG.md in the folder of the app and in the plugin's readme.txt.

12 · As an app

12.1 Folder and start file

The app is the folder einvoice-viewer-for-ksef. It must stay complete. It contains:

The start page runs with a double click from the hard disk, from a USB stick, from a network drive or from a web server. On a network drive you share the path to the start file; nothing needs to be set up on the workstations.

12.2 The file config.js

The app has no settings page. Its settings are in config.js. You open the file with a text editor, change a value, save and reload the page. The file has the same structure in all apps by invoiceTools and carries six keys; this viewer evaluates two of them.

config.js also contains a comment on the "Extended Profiles" add-on and the folder data/protected/. It comes from the shared template of the apps and concerns eInvoice Viewer for PEPPOL & EN16931; it has no meaning for KSeF invoices.

For a page that always starts in English and fetches its fonts from Google Fonts, change two lines:

	lang: 'en',
	fontsLocal: false,

For use behind a firewall, leave the file as it is. The page then makes no request, not even one that would fail. This matters because a blocked request still appears in the proxy's log, where it looks like a data leak.

12.3 The language choice

At the top right is the language choice with DE, EN and FR. A change switches the page texts and the open invoice. The page starts in the language clicked last, otherwise after lang from config.js, otherwise in the language of the browser.

12.4 Printing and fonts

The folder contains assets/css/kit-print.css. The file is deliberately not registered. It sets the page up for paper: white background, no toolbar, signal edges as lines instead of shadows. To use it, add this line in the <head> of the start file after the kit:

<link rel="stylesheet" href="assets/css/kit-print.css" media="print">

The order matters: the line must come after the kit, otherwise the screen rules win.

You may delete the folder assets/fonts/ if the folder is to become smaller. The view stays fully styled and then uses system fonts.

12.5 Updating and removing

1. Back up your file config.js to another place.
2. Replace the folder of the app with the folder from the new ZIP.
3. Transfer your settings into the new config.js.

To remove the app, delete the folder. The app creates no database and writes nothing outside its folder to the disk.

13 · As a WordPress plugin

13.1 The shortcode

The viewer appears on every page that carries the shortcode [spks_ksef_viewer]. The shortcode has no attributes.

[spks_ksef_viewer]

The language of the viewer follows the language of the page: German, English or French; any other page language leads to English. The plugin shows no language switch for visitors.

13.2 The design kit

The plugin has no settings page of its own and stores no settings of its own. It follows the design kit chosen for all eInvoice tools of the website together.

13.3 Updating and removing

Upload a new version under Plugins → Add New Plugin → Upload Plugin; WordPress replaces the existing version. Since the plugin stores no settings of its own, nothing is lost. The style and script files carry the version number in their address, so browsers load the new files after an update.

You deactivate and delete the plugin under Plugins. The plugin creates no entries of its own in the database, neither settings nor invoice data; nothing stays behind. The shared setting "Design kit" is only read by the plugin; another tool creates it.

14 · List of images

This list shows which screenshots this manual expects and which were found in the folder screenshots/ of the package. An image is always named key.language.png, for example ks-beleg.en.png. The images show sample data only.