node-zugferd
IntroductionInstallation

General

ParserTemplates

Exchange Networks

TRAFFIQX®

Validators

MustangXSD

Utilities

Magic BytesInstrumentation

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@beta

Add the plugin to your instance

Register the plugin next to every profile you want to parse. Detection considers the profiles in this list.

invoicer.ts
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

parse.ts
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

parse.ts
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.

parse.ts
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

ProfileIdSpecification identifier
Minimumminimumurn:factur-x.eu:1p0:minimum
Basic WLbasic-wlurn:factur-x.eu:1p0:basicwl
Basicbasicurn:cen.eu:en16931:2017#compliant#urn:factur-x.eu:1p0:basic
EN 16931en-16931urn:cen.eu:en16931:2017
Extendedextendedurn: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 typeParsed value
String, code, literalstring
Amount{value: number, currency?: string}
Quantity{value: number, unitCode?: string}
Percentage, unit pricenumber
Identifierstring, or {value, schemeId?, schemeVersion?} when a scheme attribute is present
Date{format: string, date: Date, value: string}
Booleanboolean
Binary objectFile
parse.ts
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. &amp; stays &amp; 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.

invoicer.ts
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 document
  • xml, the invoice XML as an object
  • pdf, the loaded PDF when the input was a PDF
  • context, the zugferd context
  • xpath, with querySelector and querySelectorAll for path queries against the XML object
  • decodeEntities, whether entity decoding is enabled
invoicer.ts
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.

invoicer.ts
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

 

llms.txt
Comfort

Templates

Register named templates and pass one to toPDF when you create an invoice.

Edit on GitHubPrivacyImprint

On this page

InstallationInstall the pluginAdd the plugin to your instanceBasic UsageFrom XMLFrom a PDFWith explicit profileSupported profilesParsed valuesValidationHooksCustom profilesOptionsFrom the CLI

How is this guide?