DEV Community

Nicolas Sage
Nicolas Sage

Posted on Edited on

How a Factur-X invoice hides its XML inside a PDF, and how to read it in the browser

Since September 2026, every business in France must be able to receive electronic invoices, and Germany has required it since January 2025. The most common format on both sides of the Rhine is Factur-X (called ZUGFeRD in Germany): a PDF that looks like any invoice, with a structured XML copy of the same invoice embedded inside it.

If you've ever opened one in a PDF reader, you saw the human-readable page and nothing else. The machine-readable part is an attachment. Here's how to get it out with plain JavaScript, in the browser, without sending the file anywhere.

Where the XML lives

A Factur-X file is a PDF/A-3 document. PDF/A-3 allows embedded files, and Factur-X uses that to attach the invoice XML, usually named factur-x.xml (zugferd-invoice.xml or xrechnung.xml in some German files). The attachment is referenced in two places:

  • the document's /Names dictionary, under /EmbeddedFiles, a name tree mapping file names to file specifications;
  • the catalog's /AF (associated files) array, which PDF/A-3 requires, with an /AFRelationship of Alternative for the invoice XML.

Each file specification has an /EF dictionary whose /F entry is the embedded stream, usually Flate-compressed.

Reading it with pdf-lib

import { PDFDocument, PDFName, PDFDict, PDFArray, PDFRawStream, decodePDFRawStream } from "pdf-lib";

export async function embeddedXml(bytes) {
  const doc = await PDFDocument.load(bytes, { ignoreEncryption: true, updateMetadata: false });
  const ctx = doc.context;
  const specs = [];

  // 1. The EmbeddedFiles name tree (Names / Kids, recursively)
  const walk = (node) => {
    if (!(node instanceof PDFDict)) return;
    const names = ctx.lookup(node.get(PDFName.of("Names")));
    if (names instanceof PDFArray) for (let i = 1; i < names.size(); i += 2) specs.push(names.get(i));
    const kids = ctx.lookup(node.get(PDFName.of("Kids")));
    if (kids instanceof PDFArray) for (let i = 0; i < kids.size(); i++) walk(ctx.lookup(kids.get(i)));
  };
  const names = ctx.lookup(doc.catalog.get(PDFName.of("Names")));
  if (names instanceof PDFDict) walk(ctx.lookup(names.get(PDFName.of("EmbeddedFiles"))));

  // 2. The /AF array of the catalog
  const af = ctx.lookup(doc.catalog.get(PDFName.of("AF")));
  if (af instanceof PDFArray) for (let i = 0; i < af.size(); i++) specs.push(af.get(i));

  for (const ref of specs) {
    const spec = ctx.lookup(ref);
    const ef = spec instanceof PDFDict && ctx.lookup(spec.get(PDFName.of("EF")));
    const stream = ef instanceof PDFDict && ctx.lookup(ef.get(PDFName.of("F")));
    if (!(stream instanceof PDFRawStream)) continue;
    const text = new TextDecoder().decode(decodePDFRawStream(stream).decode());
    if (text.includes("CrossIndustryInvoice") || text.includes("<Invoice")) return text;
  }
  return null;
}
Enter fullscreen mode Exit fullscreen mode

Two details matter in practice: some generators only fill one of the two places, so read both and de-duplicate; and name trees can be nested through /Kids, so walk them recursively.

From XML to an invoice

The XML is either UN/CEFACT CII (rsm:CrossIndustryInvoice, what Factur-X uses) or OASIS UBL (Invoice / CreditNote, common with Peppol and XRechnung). Both carry the same EN 16931 semantic model, so a small mapping gets you far. In CII, the totals sit in ram:SpecifiedTradeSettlementHeaderMonetarySummation (ram:TaxBasisTotalAmount, ram:TaxTotalAmount, ram:GrandTotalAmount, ram:DuePayableAmount); in UBL, in cac:LegalMonetaryTotal. Parse with DOMParser, query by local name to avoid namespace prefix surprises, and you have everything needed to render the invoice.

Sanity checks worth doing

Once parsed, a few checks catch most real-world mistakes: the sum of line amounts against the tax basis, VAT recomputed per rate, grand total minus prepaid amount against the amount due, and the IBAN mod-97 checksum. For French invoices, the SIREN has a Luhn key and the French VAT number a key derived from the SIREN. These are not a replacement for the official Schematron validation, but they flag the invoice you shouldn't pay yet.

Try it

I packaged this into Factur-X Viewer, a free reader that runs entirely in the browser: https://facturxviewer.fr/en/reader (there is also a Chrome extension with no permissions). Drop a Factur-X PDF or an XML invoice on it and you get a readable invoice and the checks above. I'm the author; feedback and broken sample files are welcome.

Here is what it looks like, in 24 seconds:

Top comments (0)