eInvoice Viewer for FatturaPA – Manual

1 · Overview

eInvoice Viewer for FatturaPA displays Italian e-invoices in the FatturaPA format in readable form. FatturaPA is the invoice format of the Italian Sistema di Interscambio (SdI). Such an invoice arrives as an XML file or as a signed file with the extension .p7m; anyone who opens it in an editor sees Italian element names and codes. The viewer reads the file in the browser and shows it in its own outline, with German or English field names and with plain text for the codes. It does not convert it into the European standard EN 16931.

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 and needs no other package of the eInvoice family, not even eInvoice Viewer for PEPPOL & EN16931. It is meant for everyone who receives or checks FatturaPA invoices and wants to read them without Italian specialist software: accounting departments with Italian suppliers, tax advisers, integrators and software houses.

What the viewer can do

• It reads FatturaPA invoices of format version 1.2, both to public administrations (FPA12) and to private parties (FPR12).
• It reads signed files with the extension .p7m, also Base64-encoded, unpacks them in the browser and shows them like an XML file.
• It gives every field a German or English name and, where it helps, a short explanation. Codes such as document type, tax regime, reason without tax or payment method appear as plain text.
• It shows the head with document type, number, date, currency and, if the invoice states it, total amount; seller, buyer and, where present, tax representative and third parties; the lines, the tax summary and the payment details as tables.
• It shows every invoice of a file. A FatturaPA file can carry several invoices from the same seller to the same buyer; each gets a section of its own.
• It lists embedded attachments with their size and offers a button 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".
• A switch shows the original Italian name and the path for every field.
• 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 the SdI. It does not say whether an invoice will be accepted.
• It does not check signatures. For a .p7m file it says that the file was signed and the signature was not checked.
• It creates no invoices, sends nothing to the SdI and stores nothing.
• 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 simplified invoice (FatturaPA semplificata). It has a schema of its own; the viewer reports such a file as not supported.
• It does not ship the Italian code texts of the schema. The German and English names and plain texts are its own translations.

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, put the shortcode [spfp_fatturapa_viewer] on it and publish the page. In the block editor use the "Shortcode" block or a paragraph.

Instead of uploading, you can also place the unpacked folder einvoice-viewer-for-fatturapa 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-fatturapa, open the file einvoice-viewer-for-fatturapa.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 with the text "Drag an e-invoice here or click to choose a file" and the line "Italian e-invoice FatturaPA 1.2, as XML or signed as .p7m".

1. Drag a FatturaPA invoice (XML or .p7m) onto the zone, or click and choose the file. The file dialogue offers both extensions.
2. The invoice appears. Above it are the toolbar with two switches and the button Reset, and a line with file name, format variant and invoice number. At the top of the invoice is the head, followed by the groups of the schema.
3. Drag in the next invoice if you want to read another one. It replaces the previous one.

4 · Working with the FatturaPA viewer

Opening an invoice

You drag the 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. If you drag in several files at once, the viewer reads only the first. It first checks whether it is a FatturaPA invoice of version 1.2, as XML or as a signed .p7m file. Any other file is rejected with the sentence "Unsupported file. Please upload an Italian FatturaPA invoice of version 1.2, as XML or as a signed .p7m file." The file does not leave the browser in the process.

The head of the invoice

At the top is the head with the document type as plain text, the invoice number, the invoice date and the currency. It shows the invoice amount only if the invoice states it; the schema makes this detail optional, and many invoices leave it out. If the file contains several invoices, the head names their number under "Invoices in this file" and adds that it shows the first.

The invoice in its outline

Below the head follow the groups of the Italian schema as sections with headings, such as transmission data, seller, buyer, document data, lines, tax summary and payment details. Every field stands with name and value; an empty field shows a dash. If a field carries an explanation, a small "i" follows the name; with the mouse over it or with the Tab key it appears as a tooltip. Codes are resolved: instead of TD01 you read the meaning, and the code follows in brackets. The browser itself names countries and currencies. Amounts, quantities, percentages and dates appear in the notation of the chosen language.

Several invoices in one file

A FatturaPA file can carry several invoices from the same seller to the same buyer. The viewer shows every invoice under a heading of its own ("Invoice 1", "Invoice 2" and so on), each with its own document data, lines, tax summary and payment details. The details of seller and buyer that apply to all invoices of the file appear once.

Seller, buyer, tax representative and third parties

The parties of the invoice stand in groups of their own: the seller (Cedente/Prestatore), the buyer (Cessionario/Committente) and, where the file contains them, the tax representative and third parties such as the transmitter. Every group shows its fields with German or English names, such as tax number, VAT identification, address and the seller's tax regime as plain text.

Lines, tax summary and payment details

The lines of the invoice, the summary per tax rate and the payment details appear as tables, with amounts and quantities right-aligned. In the tax summary a reason without tax (Natura) appears as plain text, in the payment details the payment method and payment terms likewise. If a row carries more details than the table has columns, you find them under the expander More details in the same row.

Relevant for this type of invoice

For a credit note (document type TD04) the group of linked invoices carries the mark "Relevant for this type of invoice" and a coloured edge, because it says which invoice the credit note refers to. Other document types highlight no group. Flags such as the KSeF viewer shows at the top of the invoice do not exist for FatturaPA.

Only filled fields

The switch Only filled fields in the toolbar hides empty fields and empty groups, so that only what the file actually contains remains. Switched off, you see all fields of the catalogue, the empty ones with a dash; this way you recognise which details the invoice does not give.

Original name and path

The switch Original name and path shows below every name the original Italian name of the field from the schema and the path of the value in the XML file. This helps when you work with an Italian business partner or with the schema and want to find the field in the file.

Attachments

Attachments embedded in the invoice (Allegati), such as a PDF, stand in a group of their own with name, size and the button Save. A click hands the file to your browser for download, byte for byte under its name from the invoice. The viewer does not open attachments in the page. If an attachment cannot be decoded, its place says "The attachment could not be decoded."

Signed files

The viewer unpacks a signed invoice with the extension .p7m in the browser and shows it exactly like an XML file. The line above the invoice says "signed; signature not checked". If the signed file contains no readable invoice, the viewer reports "The signed file contains no readable invoice." If the XML file itself carries an embedded signature, the viewer shows it as present with the number of its values and the note "not checked".

Not in the catalog

Every value of the file appears on the page. A value the field catalogue does not know appears with its path under "Not in the catalog", with the note: "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." For invoices under schema 1.2 this section should stay empty; the catalogue covers all 297 paths of the schema.

The language

The controls and messages come in German, English and French, the field names and plain texts 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 page texts, toolbar and the open invoice (chapter 12).

Resetting

The button Reset clears the display, hides toolbar and file line and clears the file selection. 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

An Italian supplier sends you a file with the extension .p7m. Drag it unchanged onto the drop zone. The viewer unpacks it and shows the invoice. Note the line "signed; signature not checked": you must establish the validity of the signature by other means.

You have to tell a supplier which field you mean. Switch on Original name and path. Below every name then stand the Italian element name and the path, exactly the words the supplier finds in their software.

A file contains several invoices. The head names the number under "Invoices in this file" and shows the first. Below it every invoice stands under its own heading. Scroll to the invoice you are looking for; the details of seller and buyer appear once for all.

You want the attachment of an invoice, such as a PDF file, on your computer. Click Save next to the attachment you want. The file is saved unchanged under its name.

You want to offer visitors of your website a display for Italian invoices. In the plugin, put [spfp_fatturapa_viewer] on a public page. Visitors need no login, and their invoices never reach your server, because the browser reads them.

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 viewer works on its own and needs no other package. Add-ons to eInvoice Viewer for PEPPOL & EN16931 such as "Extended Profiles" have no effect on this 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 file is read completely in the browser, including unpacking a .p7m file and decoding an attachment. It is not uploaded to your website and is sent nowhere.
• In the plugin only the plugin's files come from your website. Fonts, style files and the field catalogues belong to the plugin. It loads nothing from other servers.
• In the app nothing goes outside as delivered. Fonts, catalogues, language tables and style sheets are loaded from the folder. Only if you set the key fontsLocal in config.js to false does the page fetch fonts from Google Fonts (fonts.googleapis.com); the invoice is not sent even then. Catalogues are never fetched online in this version.
• No invoice is stored. The plugin stores no setting and no invoice data in the database; it only reads the shared setting "Design kit". The app only remembers the language last chosen by click in the browser, under the key einvoice-viewer-lang. A saved attachment ends up where your browser puts downloads.
• Attachments stay files. An attachment is saved only on request and is never executed or displayed in the page.
• Signatures are not checked. That an invoice arrived signed therefore does not mean it is unchanged or comes from the issuer named.

10 · For developers

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

Shared

In the plugin

In the app

Both forms are licensed under GPL-2.0-or-later.

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-fatturapa. 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.

The comment in config.js on the "Extended Profiles" add-on and the folder data/protected/ comes from the shared template of the apps and concerns the EN 16931 viewers, not FatturaPA.

For a page that starts in English as long as nobody has chosen another language in the browser, and loads fonts from Google Fonts, change two lines:

	lang: 'en',
	fontsLocal: false,

For use behind a firewall, leave fontsLocal at true. The page then makes no request, not even a failing one that would look like a data leak in the proxy's log.

12.3 The language choice

At the top right is the language choice with DE, EN and FR. A change switches page texts, toolbar and the open invoice. Numbers and dates follow the language: German with decimal comma and DD.MM.YYYY, English with decimal point and YYYY-MM-DD, French with decimal comma and DD/MM/YYYY. The page starts in the language last chosen by click, 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, deliberately not registered. It sets the page up for paper: white background, no toolbar, signal edges as lines instead of shadows. 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. Because the start page is generated anew with every version, enter the line again after an update.

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, and enter the print style sheet again if you used it.

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 and in every post that carries the shortcode [spfp_fatturapa_viewer]. The shortcode evaluates no attributes. The plugin loads its style and script files only on pages whose content contains the shortcode.

[spfp_fatturapa_viewer]

The language of the viewer follows the language of the page: German, English or French; with any other page language it is English. The plugin has no language switch for visitors.

13.2 The design kit

The plugin has no settings page and creates no setting of its own. It follows the design kit chosen for all eInvoice tools of the website together and does not offer the choice itself.

13.3 Updating and removing

Upload a new version under Plugins → Add New Plugin → Upload Plugin and let WordPress replace the existing version, or replace the folder on the server. The shortcode on your pages stays valid. The plugin appends the version number to its style and script files, so browsers load the new files after an update.

You deactivate and delete the plugin under Plugins. The plugin creates no setting of its own in the database and stores no invoice data; nothing of it remains after deletion. Pages carrying the shortcode then show it as text. The shared setting "Design kit" belongs to the other eInvoice tools and is kept.

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 fp-ansicht.en.png. The images show sample data only.