eInvoice Viewer — Visualizer – Manual

1 · Overview

The Visualizer is an add-on for the WordPress plugin "eInvoice Viewer for PEPPOL & EN16931". The viewer shows an e-invoice in a view made for the screen. The Visualizer additionally shows the same invoice as a printable document in one of five layouts and offers it as a PDF file for download. The PDF carries the original invoice XML embedded in it.

The add-on is meant for everyone who wants to print, file, pass on or show an e-invoice to someone who expects a familiar invoice image: accounting, clerks, auditors, tax firms and the operators of portals that offer their visitors a viewer.

What the Visualizer can do:

• It shows the invoice that is open in the viewer in one of five print-oriented layouts: Kontor, Ledger, Leiste, Business Central and Norm.
• It opens the chosen layout as a print view of its own with a button "Print" that calls the browser's print dialog.
• From the chosen layout it produces a PDF file in the format PDF/A-3, in which the original invoice XML is embedded.
• It fits into the viewer's toolbar. The viewer's own view stays as it is.
• It runs entirely on your own server, without requests to the outside and without a third-party service.

What the Visualizer cannot do:

• It does not work without the viewer. It has no shortcode of its own and no upload field of its own.
• It has no settings page. You can bring neither a logo nor your own colours, fonts or texts into the layouts, and you cannot create a layout of your own.
• The language of a layout cannot be chosen separately from the site. All five layouts follow the language of the page, German, English or French; for any other language they appear in German.
• It does not check the invoice for validity. It shows what the viewer has read.
• It invents no invoice data. The XML in the PDF is always the original file and is never derived anew from the drawn sheet.
• It stores nothing. There is no list of produced documents and no archive.

Requirements:

2 · Installation

The Visualizer is a paid product. You receive it as a ZIP file through the shop on invoicePress.de. It is not available in the WordPress.org plugin directory.

Way A: upload the ZIP file

1. Make sure that the plugin "eInvoice Viewer for PEPPOL & EN16931" is installed and active. Without the viewer WordPress does not activate the add-on.
2. Sign in to WordPress as an administrator.
3. Open Plugins → Add New Plugin → Upload Plugin.
4. Choose the ZIP file from the shop and start the installation.
5. Activate the plugin eInvoice Viewer — Visualizer.
6. Open a page with the viewer and load an invoice. The choice of layouts appears in the toolbar.

Way B: put the folder in place

1. Make sure that the viewer is installed and active.
2. Unpack the ZIP file on your computer.
3. Upload the unpacked plugin folder into the directory /wp-content/plugins/ of your server.
4. Open the page Plugins in WordPress and activate eInvoice Viewer — Visualizer.
5. Open a page with the viewer and load an invoice.

Way C: in the viewer app

For the viewer app the add-on is a ZIP file of its own in the shop. There it draws the layouts entirely in the browser, without WordPress and without a server.

1. Unpack the ZIP file into the folder of the app, where its start file lies. Afterwards the file einvoice-viewer-visualizer.js lies next to the start file, with the manual and the German and French texts in the folder addons/visualizer/. The same file also works next to the one-file app of the viewer; there it is enough to lay just this file next to it. Without the folder it fetches the texts of the chosen language from invoicePress.de when needed.
2. Reload the app in the browser and open an invoice. The toolbar now shows the selection of layouts and the button Visualizer.
3. Choose a layout and press Visualizer. The invoice opens in the chosen layout in the tab "Layout" next to the invoice; Print above it opens the browser's print dialog. With a viewer older than 2.38.0 the layout opens in a window of its own.

The app creates no PDF file. In the browser's print dialog you can still save the invoice as PDF.

Updating

You receive a new version again as a ZIP file. You install it the same way as the first one; when putting the folder in place, you replace the existing folder completely. Since the add-on has no settings of its own, nothing is lost.

Removing

Deactivate the plugin on the page Plugins and delete it there. The choice of layouts disappears from the toolbar, and the viewer keeps working unchanged. The add-on creates no settings of its own and stores no invoices, so no invoice data remain. The design kit choice ( option einvoice_design_kit ) is a shared setting of all eInvoice tools on your site; it stays, because it does not belong to the Visualizer alone.

3 · First steps

1. Open the page of your site on which the viewer stands. That is a page with the shortcode [spev_einvoice_viewer].
2. Load an e-invoice into the viewer, for example an XRechnung or a ZUGFeRD PDF. The viewer shows the invoice in its own view.
3. Choose a layout in the viewer's toolbar, for example "Kontor (DIN 5008)", and press the button "Visualizer".

1. The invoice appears as a print view in the chosen layout. Above the sheet stands a bar with the button "Print".

1. Press "Print" to open your browser's print dialog, or download the invoice in the viewer as a PDF file with "Download as PDF".

4 · Working with the Visualizer

Choosing a layout

As soon as the add-on is active, the viewer's toolbar offers five layouts to choose from. Each layout shows exactly the invoice data the viewer has read. The invoice is not uploaded a second time for this: the viewer hands over the data it has already read.

All five layouts are labelled in the language of the page: German, English or French. On a page in another language they appear in German. Units, countries and tax categories stand there with their name only, for example "3 m²" instead of "3 MTK - m²".

Kontor

Kontor sets the invoice as a German business letter with fold marks according to DIN 5008. You take it when the invoice is to be printed, folded and filed or sent by post.

Ledger and Leiste

Ledger is an international layout in the style of audit documents. The tax category stands there as text. Leiste is a compact layout with an information rail that shows many details densely on one sheet.

Business Central

This layout is modelled on the invoice image of Microsoft Dynamics 365 Business Central. It fits if your documents otherwise come from this environment and should look uniform.

Norm

Norm reproduces the sample presentation of an invoice that stands in the ZUGFeRD specification on pages 91 and 92. It shows the 25 details that § 14 of the German VAT Act ( UStG ) requires on an invoice, each bound to its business term of the standard. Norm looks the same on screen, in print and as a PDF, because all three are produced from the same layout description. It uses a sans-serif font throughout, puts postcode and city on one line, gives quantities with their unit and prices with at least two decimals, right-aligns the totals and carries page numbers. Norm writes numbers and dates as the language of your site prescribes.

The print view and the button "Print"

The print view is a self-contained document in the tab "Layout". Above it stands the button "Print". It calls your browser's print dialog; there you choose a printer or "Save as PDF". The bar itself is not printed. Its look follows the design kit chosen for the eInvoice tools of your site. The sheet below is not affected by it.

Download as PDF

"Download as PDF" produces a PDF file in the chosen layout on your server and delivers it as a download with the file name invoice.pdf. The file is built as PDF/A-3 (conformance level B) and carries the invoice XML as an attachment. The attachment panel is set so that a PDF program shows it on opening.

Where the XML comes from depends on the loaded file:

• If you loaded a ZUGFeRD or Factur-X PDF, the XML embedded in it is extracted and embedded again unchanged.
• If you loaded a CII or UBL file, this file itself is embedded.

The XML is never derived anew from the drawn sheet. For this step the browser sends the original file to your server once more, next to the data it has read.

Empty fields and missing totals

A field without a value is printed with a dash in the layouts instead of disappearing. This also applies to the fields "Global identifier" and "Identifier scheme" of seller, buyer, payee and delivery. A total that the invoice does not state stays empty and is not shown as 0.00. If a party carries a simple and a global identifier, the layouts show both separately. Allowances and charges of a line form one full-width table per line.

Switching it off on one page

In the shortcode of the viewer you switch off on a single page what this add-on shows, for example [spev_einvoice_viewer button_spev_visualizer="no"]. Without the attribute everything stays on.

A switch only takes something off this page. Who may use the add-on at all is set with "Available from role" in the settings of the viewer. The viewer app uses the same names in config.js, for example features: { tab_visualizer: false }. Only the value false without quotes switches off.

5 · Settings

The Visualizer has no settings page of its own and no options of its own. There is only one setting that touches its look, and it is shared by all eInvoice tools:

Shortcodes

The Visualizer brings no shortcode of its own. It appears wherever the viewer's shortcode stands:

[spev_einvoice_viewer]

The viewer's manual describes the attributes of this shortcode.

Available from role

On the page eInvoice Viewer → Viewer you choose under "Add-ons available from role" from which role the Visualizer appears in the viewer. Visitors below this role see neither the choice of layouts nor "Download as PDF", and the server answers a request built by hand with "This add-on is not available for your account." The choice exists from the viewer 2.35.0.

Switching off the PDF button

You can switch off the PDF download only with a filter in the source code, not with a setting. The example stands in chapter 10.

6 · Special cases

You want to file an XRechnung and need a sheet of paper. Load the invoice into the viewer, choose "Kontor (DIN 5008)", open the print view and press "Print". The fold marks help with folding and punching.

You want to pass on a pure XML invoice as one file that anyone can open. Load the CII or UBL file, choose a layout and download the PDF. The recipient sees the invoice as a sheet, and the original XML sits as an attachment in the same PDF.

You have a ZUGFeRD PDF whose visual image is hard to read. Load the PDF, choose a layout and download the new PDF. The sheet is set anew; the embedded XML is the same as in the original PDF.

You want to show the invoice to a foreign business partner or auditor. Open the viewer on the English or French version of your site, if there is one. All five layouts and the PDF then appear in that language.

You want to show that an invoice carries the mandatory details according to § 14 UStG. Choose Norm. The layout shows the 25 required details in the arrangement of the sample invoice from the ZUGFeRD specification.

You run a public portal and want to offer the layouts but have no PDF produced on your server. Switch off the PDF download with the filter from chapter 10. The print view with the button "Print" stays.

7 · Working with other packages

The layouts show the fields of EN 16931. The additional fields of the "Extended Profiles" add-on do not appear in them; none of the five layouts binds a field of an extension.

8 · Troubleshooting

The table gives the messages as they appear on an English site.

9 · Privacy and security

What goes to the server. Unlike the display in the viewer, the layouts are produced on your server. To draw a layout, the visitor's browser sends the invoice data read by the viewer to your WordPress installation. For the PDF it additionally sends the original invoice file, so that its XML can be embedded.

What is stored. Nothing. The data are processed only for the duration of the one request. The result goes back to the browser as a page or as a PDF file; no copy stays on the server.

What goes to the outside. Nothing. The add-on makes no request to a third-party service. The PDF is produced with the bundled library mPDF on your server.

Who can use the function. The layouts and the PDF download are also available to visitors who are not logged in, just like the viewer itself, unless a role is chosen under "Add-ons available from role". Every request is checked with a security token (nonce). It is fetched fresh, so that the function also works on pages that come from a cache.

10 · For developers

The server answers errors with the status values 400 (missing or unreadable input), 403 (security check, switched-off PDF download or a role below "Add-ons available from role"), 422 (invoice cannot be displayed or embedded) and 500 (missing library).

Switching off the PDF download, for example in a small plugin of your own:

add_filter( 'sp_einvoice_viewer_pdf_export_enabled', '__return_false' );

The produced PDF carries the entry "eInvoice Viewer — Visualizer" with the version number as an additional producer tool.

11 · Versions

12 · 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 vz-werkzeugleiste.en.png. The images show sample data only.