node-zugferd
IntroductionInstallation

General

ParserTemplates

Exchange Networks

TRAFFIQX®

Validators

MustangXSD

Utilities

Magic BytesInstrumentation

Mustang

Validate invoice XML with the Mustang CLI.

The Mustang plugin checks an invoice against the Mustang CLI. It writes the XML to a temporary file, runs java -jar, and reads the CLI report. A valid document resolves with no value. An invalid document throws ZugferdError.

Installation

Install the plugin

The machine that runs validation needs a Java runtime, with java on your PATH. When JAVA_HOME is set, setup looks in JAVA_HOME/bin. You can download a runtime from the official Java website.

npm install @node-zugferd/validator-mustang@beta

Installing the package downloads Mustang-CLI.jar. Run the installer again if that download did not finish:

Terminal
npx node-zugferd-mustang

Add the plugin to your instance

invoicer.ts
import { zugferd } from "node-zugferd";
import { en16931 } from "@node-zugferd/en-16931";
import { mustang } from "@node-zugferd/validator-mustang";

export const invoicer = zugferd({
  profiles: [en16931],
  plugins: [
    mustang(), 
  ],
  // ...
});

macOS temporary directory

The default temporary directory on macOS can be a symlink, and the Mustang CLI can fail when it receives that path. Set tempDir to a real absolute directory.

Automatic validation

autoRun defaults to true. create then validates the XML it just built, and a Mustang failure rejects that call. An afterXMLBuild hook on your zugferd() options still runs after this check.

invoice.ts
import { invoicer } from "./invoicer";
import { data } from "./data";

await invoicer.create("en-16931", data);

With the parser plugin on the same instance, parse also runs Mustang on the XML before it maps fields. Set autoRun: false to keep invoicer.mustang.validate available and skip both of those automatic checks.

invoicer.ts
import { zugferd } from "node-zugferd";
import { en16931 } from "@node-zugferd/en-16931";
import { mustang } from "@node-zugferd/validator-mustang";
import { parser } from "@node-zugferd/parser";

export const invoicer = zugferd({
  profiles: [en16931],
  plugins: [
    parser(),
    mustang({
      autoRun: false,
    }),
  ],
});

Manual validation

invoicer.mustang.validate takes a profile id and the invoice XML or PDF. The id may also be an object with an id field and has to be one of the supported profiles. Mustang then reads the rules from the bytes itself.

validate.ts
import { readFile } from "node:fs/promises";
import { ZugferdError } from "@node-zugferd/core/error";
import { invoicer } from "./invoicer";

try {
  await invoicer.mustang.validate(
    "en-16931",
    await readFile("invoice.pdf"),
  );
} catch (error) {
  if (error instanceof ZugferdError) {
    console.error(error.message);
  } else {
    throw error;
  }
}

Any other profile id logs a warning and the call resolves, leaving the XML unchecked.

Supported profiles

  • Minimum
  • Basic WL
  • Basic
  • EN 16931
  • Extended
  • XRechnung
  • Order-X Basic
  • Order-X

validate and the automatic checks accept these ids. create passes the id of the profile it built.

Findings

Mustang prints an XML report. This plugin treats that report as follows:

  • Errors and exceptions are joined with a blank line and thrown as a ZugferdError. error.message is that text.
  • Warnings are written with the zugferd logger. A warning on its own leaves the document valid.
  • Notice-level findings are omitted.
  • A report that cannot be parsed throws ZugferdError with the message Failed to parse Mustang validation output.

Compared to XSD

Mustang is slower than the XSD validator. Each check starts a Java process and runs the CLI, while XSD validates in-process in JavaScript.

Mustang also requires a Java runtime, which XSD does not. In return, Mustang checks more than the XML schema. It also applies the business rules of each profile and checks PDF/A compliance, so it reports errors that XSD alone does not catch.

Options

Prop

Type


 

llms.txt
TRAFFIQX®

Send and receive electronic invoices through the TRAFFIQX® Invoice API (TIA).

XSD

Validate invoice XML against an XML Schema in-process.

Edit on GitHubPrivacyImprint

On this page

InstallationInstall the pluginAdd the plugin to your instanceAutomatic validationManual validationSupported profilesFindingsCompared to XSDOptions

How is this guide?