Parser
Read Factur-X and ZUGFeRD invoices from XML or PDF/A-3.
Experimental
Parsing is currently experimental, and the API is subject to change. XRechnung and Order-X profiles are not supported yet.
The parser plugin reads an invoice and returns the data described by a profile schema. Pass the XML as a string or as UTF-8 bytes, or pass a PDF/A-3 file. For a PDF, the plugin reads the embedded factur-x.xml attachment.
Detection uses the specification identifier in the XML. On a PDF it also checks that the Factur-X extension metadata names the same conformance level as the profile. Only profiles registered on your zugferd() instance are considered, and the first match is the one that gets parsed.
Installation
Install the plugin
npm install @node-zugferd/parser@betaAdd the plugin to your instance
Register the plugin next to every profile you want to parse. Detection considers the profiles in this list.
import { zugferd } from "node-zugferd";
import { en16931 } from "@node-zugferd/en-16931";
import { parser } from "@node-zugferd/parser";
export const invoicer = zugferd({
profiles: [en16931],
plugins: [
parser(),
],
// ...
});Basic Usage
parser() adds parse to the invoicer instance. Call it with the file contents. Omit the profile id to detect it, or pass an id when you already know which profile the document uses.
From XML
import { readFile } from "node:fs/promises";
import { invoicer } from "./invoicer";
const xml = await readFile("factur-x.xml", "utf-8");
const invoice = await invoicer.parse(xml);
invoice.exchangedDocument.invoiceNumber;A Uint8Array or ArrayBuffer of UTF-8 XML works the same way as a string.
From a PDF
import { readFile } from "node:fs/promises";
import { invoicer } from "./invoicer";
const pdf = await readFile("invoice.pdf");
const invoice = await invoicer.parse(pdf);The attachment name comes from the profile. Factur-X profiles embed factur-x.xml. Parsing throws when that file is missing.
With explicit profile
Pass the profile id first when you want to skip detection. The document is still checked against that profile, and parsing throws when it does not match.
import { readFile } from "node:fs/promises";
import { invoicer } from "./invoicer";
const xml = await readFile("factur-x.xml", "utf-8");
const invoice = await invoicer.parse("en-16931", xml);The id has to be one of the profiles registered on the instance. parse throws when the id is unknown, when no registered profile matches, or when the named profile rejects the document.
Supported profiles
| Profile | Id | Specification identifier |
|---|---|---|
| Minimum | minimum | urn:factur-x.eu:1p0:minimum |
| Basic WL | basic-wl | urn:factur-x.eu:1p0:basicwl |
| Basic | basic | urn:cen.eu:en16931:2017#compliant#urn:factur-x.eu:1p0:basic |
| EN 16931 | en-16931 | urn:cen.eu:en16931:2017 |
| Extended | extended | urn:cen.eu:en16931:2017#conformant#urn:factur-x.eu:1p0:extended |
Field names on the result follow that profile's schema, the same names you use with create.
Parsed values
Each schema field is read from the XML. Absent fields are left off the object. Some values come back wrapped, including fields that create accepts as a plain number or Date.
| Schema type | Parsed value |
|---|---|
| String, code, literal | string |
| Amount | {value: number, currency?: string} |
| Quantity | {value: number, unitCode?: string} |
| Percentage, unit price | number |
| Identifier | string, or {value, schemeId?, schemeVersion?} when a scheme attribute is present |
| Date | {format: string, date: Date, value: string} |
| Boolean | boolean |
| Binary object | File |
const lineTotal =
invoice.transaction.line[0]?.billing?.itemTotals?.lineTotalAmount?.value;Dates use the UN/EDIFACT format code stored on the XML element. When the code is missing, the parser reports 102. Format 102 is a calendar date at UTC midnight, and raw keeps the original text such as 20240305.
Text and identifier values keep XML entities as they appear in the file. & stays & until you set decodeEntities to true, which decodes &, <, >, ", and '.
Validation
When the XSD or Mustang plugin is registered on the same instance, the parser validates the XML before it maps fields. XSD runs first, then Mustang. A validation error stops parsing. Set autoRun: false on a validator to keep it available for manual checks without running it on every parse call.
import { zugferd } from "node-zugferd";
import { en16931 } from "@node-zugferd/en-16931";
import { parser } from "@node-zugferd/parser";
import { xsd } from "@node-zugferd/validator-xsd";
export const invoicer = zugferd({
profiles: [en16931],
plugins: [
parser(),
xsd(),
],
});Hooks
hooks run around the profile parser. beforeParse runs after validation and before fields are read. afterParse runs once the data object exists and receives it as data. Both may be async.
The parse context also includes:
profile, the profile selected for this documentxml, the invoice XML as an objectpdf, the loaded PDF when the input was a PDFcontext, the zugferd contextxpath, withquerySelectorandquerySelectorAllfor path queries against the XML objectdecodeEntities, whether entity decoding is enabled
import { parser } from "@node-zugferd/parser";
parser({
hooks: {
beforeParse: async ({ profile }) => {
console.log(profile.id);
},
afterParse: async ({ data }) => {
console.log(data);
},
},
});Custom profiles
profileMap replaces the built-in match and parse functions for the profile ids you list. Other built-in profiles stay in place. Each entry needs both functions. match should return true when the document belongs to that profile. parse should return the data object.
match receives two helpers. matchesSpecificationIdentifier compares the specification id in the XML and accepts one id or a list. matchesExtensionSchemaProfile checks the Factur-X extension metadata on a PDF, and returns true for XML input.
import { parser } from "@node-zugferd/parser";
parser({
profileMap: {
"en-16931": {
match: (ctx) =>
ctx.matchesExtensionSchemaProfile() &&
ctx.matchesSpecificationIdentifier("urn:cen.eu:en16931:2017"),
parse: (ctx) => {
return {
// Map ctx.xml into the profile data shape.
};
},
},
},
});A custom entry is the full match and parse implementation for that profile. A new profile id is checked after the built-in profiles, and that profile still has to be registered on the instance.
Options
Prop
Type
From the CLI
The CLI reads an invoice file and prints the parsed data as JSON. It uses @node-zugferd/parser, and runs Mustang or XSD when those packages are installed. See the CLI reference for the flags.
npx @node-zugferd/cli@beta parse