eInvoice Validator for Mustang – Manual

1 · Overview

The eInvoice Validator for Mustang is a WordPress plugin. It provides a drop zone on a page of your site on which a visitor drops an e-invoice. The invoice is checked by the Mustangproject validator that you have put on your server yourself. The validation report then appears on the page and can be downloaded as a file.

The plugin is meant for operators of a WordPress site who want to offer invoice checking on their own server: for customers, for suppliers or for their own colleagues.

What the plugin does

• With a shortcode it puts a drop zone for e-invoices on a page or in a post.
• It accepts ZUGFeRD and Factur-X PDF as well as CII and UBL XML, by drag and drop or through file selection.
• For a PDF it reads the embedded invoice already in the browser and sends only this XML to your server.
• For every check it starts the Mustang validator on your server and shows its report in a plain-language view with rule texts and technical terms.
• It attaches the uploaded invoice to the report, so the findings stand in their place in the document view.
• It offers the validator's unchanged report as report.xml for download.
• It limits the number of checks per visitor and calendar day, and the file size.
• On the settings page it checks whether the validator is ready to start, and with a checksum it watches whether the jar file is still the one you agreed to.
• It gives an invoice opened in the eInvoice Viewer the button Validate with Mustang.
• It ships translations for German and French; the source texts are English.

What the plugin does not do

• It checks nothing without the Mustang validator and without Java on the server.
• For a PDF it checks only the embedded invoice. The PDF file itself does not reach the server and is therefore not examined.
• It does not read an ordinary or scanned PDF; a PDF without an embedded invoice is rejected with a message.
• It stores neither invoices nor reports and keeps no list of earlier checks.
• It addresses the validator in only one way: as a Java process on the same server. It cannot address a remote validation service.

Requirements

2 · Installation

Uploading the ZIP file

1. Sign in to WordPress as an administrator.
2. Open "Plugins" and there "Add New Plugin".
3. Choose "Upload Plugin" and give the plugin's ZIP file.
4. Click "Install Now" and then "Activate Plugin".
5. Open "Settings" and there the entry "E-Invoice Validator Mustang".

Distribution through wordpress.org

Distribution through the wordpress.org plugin directory is planned, but the plugin has not been published there yet. Once it is there, you find it through the search under "Plugins" and "Add New Plugin".

Providing the validator

These steps are part of the installation, because without them the plugin checks nothing.

1. Make sure Java is installed on the server.
2. Download the file Mustang-CLI.jar from the Mustangproject website.
3. Put the file on your server, in a place the web server user can read.
4. On the settings page, enter the full path including the file name and save.
5. Check in the section "Systemcheck" whether all rows carry a green tick.
6. In the section "Integrity of the jar", click "Accept the file on disk".

Reaching the validator through a validation service

If your web space may not run Java or start programs, the plugin checks through a validation service. A validation service is one of two kinds of service that offer the same addresses:

• Validator Bridge: a small free service that runs Mustang on this or another computer and offers it over HTTP. Its manual comes with it.
• eInvoice API: a WordPress website with the plugin eInvoice API, which passes the check on to its own bridge and grants a key and a quota for it.

1. Start a Validator Bridge with Mustang, or note the REST address of a website with eInvoice API, for example https://example.com/wp-json/einvoice-api/v1. A bridge prints its address at its start, on your own computer for example http://127.0.0.1:8090.
2. On the settings page, choose "Validation service ( Validator Bridge or eInvoice API )" under "Way to the validator".
3. Enter the address under "Address of the validation service". If a bridge runs on a server, enter one of the keys of its settings file under "API key of the validation service"; for an eInvoice API, your API key of that website.
4. Save and check in the section "Systemcheck" that the rows "The validation service answers" and "Mustang is available in the validation service" carry a green tick. The first row names whether a Validator Bridge or an eInvoice API answers.

Path, Java binary and the integrity of the jar then concern the validation service and no longer this plugin.

Updating

You replace the plugin with the new version by uploading the new ZIP file. As long as the plugin is not on wordpress.org, WordPress does not announce a new version by itself. Your settings are kept. The plugin does not update the validator's jar file; you do that yourself (see chapter 6).

Removing

You deactivate and delete the plugin under "Plugins". The jar file and Java stay on the server, because neither belongs to the plugin. In the database the plugin creates the settings spmv_jar_path, spmv_java_bin, spmv_timeout_seconds, spmv_role_limits ( the table per role; until it is saved for the first time, the earlier single value spmv_daily_limit applies ), spmv_max_filesize_mb, spmv_trust_proxy and spmv_jar_sha256, plus the daily limit counters. The plugin does not clean up on deletion: the settings stay in the database. The counters expire by themselves after one day.

3 · First steps

1. Open "Settings" and "E-Invoice Validator Mustang". Enter the path at "Path to Mustang-CLI.jar" and save.
2. Look at the section "Systemcheck". Click "Test the validator". If "Ready — the validator can be started." appears, the validator is ready to start.

1. Under "Integrity of the jar", click "Accept the file on disk".
2. Create a new page and put the shortcode [spmv_mustang_validator] in it. Publish the page.

1. Open the page and drag an e-invoice onto the drop zone.
2. Read the report that appears below the drop zone.

4 · Working with the validator

Dropping an invoice

The visitor drags a file onto the drop zone, or clicks it and chooses a file. The zone can also be operated with the keyboard: Enter or Space opens the file selection. Files ending in .pdf or .xml are accepted. While the validator runs, the zone accepts no second file.

Having a PDF checked

A ZUGFeRD or Factur-X PDF carries the invoice inside it as an XML attachment. The plugin reads this attachment in the visitor's browser; meanwhile the message says that the invoice is being read from the PDF. Only the XML goes to the server. The scripts needed for this are only loaded when a PDF is actually dropped. If the PDF contains no invoice, the message says so explicitly.

Waiting for the report

Java starts afresh for every check. The first seconds are therefore start-up and not checking. For an ordinary invoice about two seconds in total were measured with Mustang-CLI 2.25.0. While the check runs, a note stands below the drop zone.

Reading the report

The report appears below the drop zone. The plugin shows it in a plain-language view: the validator's findings stand there with rule texts and technical terms, and the uploaded invoice is attached as the document, so every finding stands in its place in the document. If this view cannot be built, the plugin shows a simpler report view; the report stays readable in any case. The display is shielded from your theme's styling.

Downloading the report

Above the report is the button "Download report.xml", next to it the row "Validation report". The button saves the report exactly as the Mustang validator output it. The file name is made of the invoice's name and the suffix -report.xml, for example invoice-4711-report.xml.

Seeing the daily limit

Below the drop zone stands "Remaining uploads today: …" with the number of checks the visitor has left that day. The number falls after every check that delivered a report. A rejected file does not count. When the limit is reached, the visitor gets the message "You have reached the daily upload limit. Please try again tomorrow."

Watching the validator

The section "Systemcheck" of the settings page is computed anew every time the page loads and never cached. It has three rows: "PHP can start external processes ( proc_open )", "A Java runtime is reachable" and "Mustang-CLI.jar is where the settings say". Every row carries a green tick or a red cross, and with a cross the next step stands below it. The button "Test the validator" sums up the result in one line and, where applicable, names the checks still open.

Securing the jar file

Mustang-CLI.jar is executable third-party code on your server. The section "Integrity of the jar" therefore shows two SHA-256 checksums: under "Accepted" the file you agreed to, and under "On disk" the file that now lies at the path. With "Accept the file on disk" you take over the existing file. If both values later differ, checking stays blocked until you accept the file again or put back the earlier one. "Forget accepted hash" deletes the remembered checksum; afterwards any jar file lying at the path is started.

5 · Settings

You find the settings page under "Settings" and "E-Invoice Validator Mustang". You need the right to manage options for it.

Section "Mustang validator"

Section "Systemcheck"

Section "Integrity of the jar"

Shortcode

[spmv_mustang_validator]

The shortcode has no attributes. Everything adjustable is on the settings page and applies to every place where the shortcode stands.

6 · Special cases

The invoice names a newer edition than the one Mustang knows. When an invoice names XRechnung 4.0 or the standard EN 16931-1:2026 in BT-24, Mustang checks it with the rules of the older edition it knows and may call it valid. A yellow note above the report then says that Mustang does not know this edition yet and that its result applies only to the older edition. The note changes nothing in the report itself.

You want to bring the Mustang validator to a new version. Put the new jar file on the server. If it has a different file name, enter the new path and save. The checksums now differ and checking is blocked. Click "Accept the file on disk", and it runs again.

You want to offer the check only to a closed circle. Put the shortcode on a page you protect with WordPress means, for example with a password or as a private page. Logged-in users are counted by user for the daily limit.

You want to check internally without a daily limit. In "Daily uploads per role", empty the rows of the roles that should check. Only do this on a site that is not publicly reachable, because every check starts a Java process on your server.

Your site stands behind a reverse proxy. Then WordPress sees the proxy's address as the visitors' address. Switch on "Trust proxy header" so the daily limit counts per visitor. Leave the switch off if no trusted proxy stands in front, because otherwise the visitor can set the header themselves.

The shortcode stands not in the page content but in a template or widget. The plugin loads its files as soon as the shortcode is output. If you want to load the files earlier on particular pages, there is the filter spmv_force_enqueue for that (see chapter 10).

Java is not found although it is installed. The web server runs under a user of its own with a search path of its own. Enter the full path to the Java program under "Java binary".

7 · Working with other packages

The plugin is self-contained. It needs no other invoicePress package, and the plain-language report view is built in.

8 · Troubleshooting

9 · Privacy and security

What stays in the browser. A dropped PDF does not leave the visitor's browser. The plugin extracts the embedded XML there, and only this is sent. The report for download is created in the browser from the server's answer.

What goes to the server. The invoice's XML goes to your own WordPress site, that is to your server. With the local installation the plugin starts the Mustang validator there as a Java program; what the Mustangproject's jar file does in turn lies outside the plugin. With the validation service the plugin sends the invoice to the address you have entered, and nowhere else. With your own Validator Bridge it stays in your network. With the eInvoice API of another website it goes to that website's operator, and his privacy policy and terms of use apply.

What is stored. For the check the invoice is copied into a working directory of its own, which is deleted again after the run; the WordPress upload folder is not touched. Invoice and report are not kept. Stored are the settings, the remembered checksum of the jar file and the daily limit counters. For anonymous visitors the IP address is used only as a hash value, for logged-in users the user account counts.

How the plugin protects the server.

• The server accepts only XML and reads no PDF.
• Every check requires a fresh security token, which the page fetches separately; this also works with cached pages.
• File size and daily limit restrict how often and with what the Java process is started.
• The checksum blocks checking as soon as the jar file no longer matches the accepted one.
• The buttons on the settings page are only open to logged-in administrators.
• The report is displayed in a shielded area of the page.

10 · For developers

The shortcode's output stands in a <template> within <div class="spmv-host"> and is moved by the script into a shadow root. The theme's stylesheets therefore do not reach it. The text domain is einvoice-validator-for-mustang, the translations are in the folder languages.

11 · Versions

No change log is included with the plugin in this version. The source code shows the following:

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