DEV Community: Seya

Validating XRechnung and ZUGFeRD without Java: how the KoSIT validator works, and how to do it in TypeScript

Seya — Wed, 14 Oct 2026 13:41:33 +0000

In Germany every business has to be able to receive e-invoices since 1 January 2025. The obligation to issue them follows in steps: until the end of 2026 paper and PDF are still allowed for everyone, in 2027 only businesses with a prior-year turnover of up to EUR 800,000 may still use them, and from 1 January 2028 the e-invoice is the rule. (The IHK overview has the details and exceptions.) A plain PDF is no longer an invoice in the sense of the law. A structured file in the European standard EN 16931 is, either as pure XML (XRechnung) or as a PDF with the XML embedded (ZUGFeRD, called Factur-X in France).

For developers this means a new kind of bug: an invoice that your system produces or receives looks fine on screen and is still rejected, by a customer's accounting software, by a public buyer's portal or by your own audit later. The way to find out before they do is to validate. This article explains what validation really involves, because most of the confusion comes from not knowing which checks exist.

Valid in which sense?

An e-invoice can be wrong on four levels, and each needs a different check:

Not well-formed XML. A parser finds this immediately.
Not valid against the XML Schema (XSD). Elements in the wrong order or in the wrong place, a missing required element, a misspelt name, a date written as 04.04.2016, an amount with a comma. No business logic is needed to see this, but a normal XML parser does not check it unless you give it the schema.
Not valid against the business rules. EN 16931 defines hundreds of rules in Schematron, for example that the invoice total with VAT must equal the total without VAT plus the VAT amount. XRechnung adds German rules on top, such as the mandatory buyer reference (Leitweg-ID for public buyers) or contact details of the seller.
Not consistent as a ZUGFeRD PDF. The PDF has to contain the XML as an attachment, and the profile declared in the PDF metadata has to match the profile of the XML.

The reference implementation for the first three levels in Germany is the KoSIT validator, published by the Koordinierungsstelle für IT-Standards. It works in two steps: first the XSD, then the Schematron rules. Public buyers and many accounting systems effectively use the same rule sets, so "passes KoSIT" is the practical definition of "valid XRechnung".

Why Schematron is the hard part

Schematron is a rule language that expresses a rule as an XPath expression in a context. A rule from EN 16931 looks like this:

<assert id="BR-CO-15" flag="fatal"
  test="every $Currency in cbc:DocumentCurrencyCode satisfies
    (count(cac:TaxTotal/xs:decimal(cbc:TaxAmount[@currencyID=$Currency])) eq 1)
    and (cac:LegalMonetaryTotal/xs:decimal(cbc:TaxInclusiveAmount) =
      round((cac:LegalMonetaryTotal/xs:decimal(cbc:TaxExclusiveAmount)
        + cac:TaxTotal/xs:decimal(cbc:TaxAmount[@currencyID=$Currency])) * 10 * 10) div 100)">
  Invoice total amount with VAT (BT-112) = Invoice total amount without VAT (BT-109)
  + Invoice total VAT amount (BT-110).
</assert>

The catch: the official rule sets use XPath 2.0, not 1.0. The rule above already shows it: an every ... satisfies quantifier, xs:decimal casts and the eq operator. Other rules use sequences, regular expressions with matches() and functions such as distinct-values(). Most XPath engines available in JavaScript implement 1.0 only, so the standard route is to run the validator on the JVM (the KoSIT validator is a Java application, often started as a daemon or a Docker container).

That is a reasonable choice for a back-office batch. It is a poor fit if your product is a Node.js service, a serverless function, an edge worker or a browser app where a user drops an invoice file and wants an answer immediately. Then you either run a second runtime next to your application or you skip validation.

The same two steps in TypeScript

Summand is an MIT-licensed library that implements both steps without Java: it compiles the official XML Schemas (UBL 2.1 and UN/CEFACT CII D16B) and the official Schematron rule sets (CEN EN 16931 1.3.16 and KoSIT XRechnung 2.6.0 for XRechnung 3.0) and ships its own XPath 2.0 and Schematron engine written in TypeScript. It has no dependencies and is about 135 KB gzipped with all rule sets, schemas and both message languages.

pnpm add @sweberdev/summand

import { readFile } from "node:fs/promises";
import { validateInvoice } from "@sweberdev/summand";

// XML string, XML bytes or a ZUGFeRD PDF
const result = validateInvoice(await readFile("invoice.pdf"));

result.valid;            // false
result.profile?.label;   // "XRechnung 3.0"
result.errors[0];        // { id: "BR-CO-15", severity: "error", message: "…",
                         //   location: "/Invoice/cac:LegalMonetaryTotal", line: 214 }
result.schemas[0]?.id;   // "ubl-2.1" (the XML Schema was checked first)
result.summary?.number;  // "RE-2026-0042"

Every finding carries the rule id, the severity, the XPath and the line, which is what you need to show a user or to hand to the people who fix the invoice template. Messages are available in English and German ({ lang: "de" }), for every rule: accountants do not read English Schematron texts.

For ZUGFeRD and Factur-X, the PDF is opened, the embedded XML is found and validated, and the profile in the PDF metadata is compared with the profile of the XML.

In CI

The command line tool returns a non-zero exit code when an invoice is invalid, so a template change that breaks the output fails the build:

npx @sweberdev/summand validate invoices/*.xml invoices/*.pdf
npx @sweberdev/summand validate invoice.xml --lang de --json

If your system produces invoices, keep a handful of representative ones in the repository (a normal invoice, a credit note, one with a discount, one with several VAT rates, one reverse charge) and validate them on every commit. This one test catches most regressions in invoice generation.

In the browser

Because there is no JVM and no server, the same call runs in the browser. A drop zone that tells an accountant "valid" or "invalid because of rule X on line 214" without uploading the file anywhere is useful in itself, and it is also a privacy argument: invoices contain personal and commercial data. There is a live demo that works that way.

How we know it gives the same answer as the official validator

A validator that is almost right is worse than none, because people trust it. So correctness is the actual product here, and it was tested against the references rather than against our own expectations:

All 1,142 expectations of the CEN EN 16931 unit test suite pass.
All reference invoices of the KoSIT XRechnung test suite are valid against schema and rules.
The XML Schema check was compared with Xerces, the schema validator that the KoSIT validator uses, on all test invoices and on about 2,800 deliberately modified ones (elements removed, reordered, duplicated, values changed). The verdict (valid or invalid) was the same for every document.

Messages differ on purpose: Xerces stops looking at an element's content at its first problem and reports it as cvc-complex-type.2.4.a. Summand reports each problem it finds, in plain language, so you see all problems at once instead of fixing one layer after the other.

What the library does not do is equally important. It validates; it does not decide whether an invoice is correct in a tax sense. It also does not replace the legal advice or your accountant's view on archiving requirements. The rule sets keep their licences (EUPL-1.2 for the EN 16931 artefacts, Apache-2.0 for the XRechnung Schematron), which are documented in the package's NOTICE file.

A practical approach for your system

Receive. Every business can already receive e-invoices. Validate incoming files at the point where they enter your system, and keep the report next to the file. If an invoice is invalid, you want to know before the payment run, not during an audit.
Issue. Validate every invoice you generate before it leaves the system, as a hard gate in the code path, not as an optional step.
Test. Put sample invoices into CI so that a template change cannot silently break the format.
Archive. An e-invoice has to be stored unchanged, complete and verifiably. A validation report stored together with the file is cheap evidence that it was valid when you received or sent it.

The documentation has guides on the schema check, Schematron, profiles, the Leitweg-ID check digit and ZUGFeRD PDFs. For teams that process invoices in volume, Summand Pro adds a typed invoice object, a readable HTML or PDF view with the validation report, watching a folder or a mailbox, duplicate detection and an export for DATEV.

This article describes software and public standards, not tax or legal advice. Check your own obligations with your tax adviser.

Disclosure: I maintain the library mentioned in this article. The requirements and code samples stand on their own.

The withdrawal button (§ 356a BGB): what the law asks for, and how to build it

Seya — Wed, 07 Oct 2026 15:32:18 +0000

If you run an online shop, a SaaS product or a booking app for consumers in Germany, you have had a new item on your list since 19 June 2026: a withdrawal button. It comes from EU directive 2023/2673 (a new Article 11a in the Consumer Rights Directive) and Germany implemented it as § 356a BGB.

Most articles about it are written for shop owners. This one is written for the person who has to build it. It lists what the law asks for, where implementations usually go wrong, and ends with working code. It is not legal advice: for your own case, ask a lawyer or your trade association.

What the law asks for

The statute is short. Reduced to what affects the implementation:

A function labelled "Vertrag widerrufen" or an equivalent, unambiguous wording, for every contract concluded through an online interface (a website or an app).
Available for the whole withdrawal period and, in the wording of the directive, prominent and easy to access. In practice: a link in the footer of every page, not buried in the terms.
No login required. The consumer may not have an account, or may have lost the password.
Two steps. The first step collects the declaration: who is withdrawing, from which contract, and an electronic address for the acknowledgement. The second step is a button labelled "Widerruf bestätigen" (or equivalent) that actually submits it.
An acknowledgement of receipt without delay on a durable medium (in practice: e-mail), containing the content of the declaration and the date and time it was received.
In time if used in time. A withdrawal submitted through the function before the period ends is in time, whatever happens afterwards.

The 14-day withdrawal period itself did not change. Neither did the way it is calculated, which matters more than it seems (see below).

The mistakes that make a button non-compliant

We went through the requirements and the first generation of shop pages, and the same problems come up again and again.

The label is creative. "Widerrufen", "Retoure starten" or "Rückgabe" are not the same as "Vertrag widerrufen". A returns portal is a different function: returning goods and withdrawing from a contract are legally different things. The two button labels are the one place where you should not be clever.

The link leads to a login page. If the consumer has to sign in to the customer area first, the function is not accessible without login. Guest checkouts are the obvious case. Offer a login-free form and, if you like, prefill the order number from the link in your order e-mail.

One click withdraws, or three clicks are needed. The directive describes exactly two steps. A single click without a review step risks accidental withdrawals; a wizard with extra pages makes the function harder to use than the statute allows.

The time of receipt comes from the browser. The date and time in the acknowledgement are the trader's evidence. If you copy them from the client, they can be wrong or manipulated. Set receivedAt on the server, in one place, and nowhere else.

The acknowledgement is just "thanks". It has to contain the content of the declaration (who, which contract, what was declared) and the date and time of receipt. Consumers should be able to keep it as proof.

Rejecting declarations with an unknown order number. A withdrawal with a typo in the order number is still a declaration you received. Validate the format of the fields, not whether the number exists, and sort out the assignment yourself afterwards.

Wrong deadline arithmetic. The period starts the day after the event (§ 187 BGB), and when it ends on a Saturday, Sunday or public holiday it moves to the next working day (§ 193 BGB). If you were not properly informed about the right of withdrawal, the period is extended by up to 12 months. If you show "withdraw by …" in the customer area, calculate it the same way.

A related rule: the cancellation button

German subscription businesses have had to offer a cancellation button ("Verträge hier kündigen", § 312k BGB) since 1 July 2022. In July 2026 the Federal Court of Justice (BGH, I ZR 200/25) made one point very clear: the confirmation page of the cancellation flow must be focused on submitting the cancellation. Offers to keep the customer, such as a discount or a pause, do not belong on that page. Win-back is allowed, but outside the cancellation flow, for example in the follow-up e-mail.

If you implement one function, it is worth implementing both with the same building blocks.

Implementation: the minimum that works

You need three things: a form with two steps, an endpoint, and an acknowledgement e-mail. This is the core of the endpoint in plain TypeScript with the Fetch API, which runs in Next.js route handlers, Remix, Hono and SvelteKit:

// POST /api/withdrawal
export async function POST(request: Request): Promise<Response> {
  const body = await request.json().catch(() => null);
  const name = String(body?.name ?? "").trim();
  const contractRef = String(body?.contractRef ?? "").trim();
  const email = String(body?.email ?? "").trim();

  const errors: Record<string, string> = {};
  if (name.length < 2) errors.name = "Name is required";
  if (contractRef.length < 1) errors.contractRef = "Contract or order number is required";
  if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) errors.email = "A valid e-mail address is required";
  if (Object.keys(errors).length) return Response.json({ errors }, { status: 422 });

  // The server sets the time of receipt. Never trust the client.
  const receivedAt = new Date();

  await db.withdrawal.create({ data: { name, contractRef, email, receivedAt } });

  await mailer.send({
    to: email,
    subject: "Eingangsbestätigung Ihres Widerrufs",
    text: [
      `Wir haben Ihren Widerruf erhalten.`,
      ``,
      `Name: ${name}`,
      `Vertrag / Bestellung: ${contractRef}`,
      `Eingegangen am: ${receivedAt.toLocaleString("de-DE", { timeZone: "Europe/Berlin" })}`,
    ].join("\n"),
  });

  return Response.json({ ok: true, receivedAt: receivedAt.toISOString() });
}

Three details are easy to get wrong in this sketch, so decide on them deliberately:

Store first, mail second. If the e-mail provider is down, you still have the declaration and can send the acknowledgement later. If you send first and the database write fails, the consumer holds a confirmation for a declaration you do not have.
Time zone. Show the receipt time in the time zone of your customers, but store it in UTC.
Rate limiting and double submits. A public, login-free endpoint will be hit by bots and by people who double-click. Add a rate limit and treat two identical submissions within a few seconds as one, otherwise you send two acknowledgements.

On the page, build the two steps as one form with a review state: step one collects the fields and has a button "Weiter" (or similar); step two shows the entered data and a single button, "Widerruf bestätigen". Link to the page from the footer with the text "Vertrag widerrufen", on every page where a contract can be concluded.

And the deadline, as a pure function you can test:

function addDays(isoDate: string, days: number): string {
  const d = new Date(`${isoDate}T12:00:00Z`);
  d.setUTCDate(d.getUTCDate() + days);
  return d.toISOString().slice(0, 10);
}

function withdrawalDeadline(start: string, isHoliday: (iso: string) => boolean = () => false): string {
  let end = addDays(start, 14); // the day of the event does not count (§ 187 BGB)
  for (;;) {
    const weekday = new Date(`${end}T12:00:00Z`).getUTCDay(); // 0 = Sunday, 6 = Saturday
    if (weekday !== 0 && weekday !== 6 && !isHoliday(end)) return end; // § 193 BGB
    end = addDays(end, 1);
  }
}

withdrawalDeadline("2026-10-03"); // "2026-10-19": 17 October is a Saturday, so it moves to Monday

Pass a holiday function that knows the public holidays of the state your business is in.

Testing it like a visitor

The most common failure is not in the endpoint but on the page: the link is missing on the checkout page, hidden behind a login, or labelled differently on mobile. Check the rendered HTML of your live pages the way a logged-out visitor sees them:

npx @sweberdev/inverse check https://shop.example.com --kind both

The command loads each page without cookies, looks at every link, button and role="button" element, and reports missing or mislabelled controls. It exits with a non-zero code when something fails, so you can add it to CI and block a deployment that removes the footer link. A button that is only rendered in the browser after hydration is not seen, because the check reads the HTML the server sends.

Or use a package for the boring parts

If you would rather not maintain validation, receipts in several languages and deadline arithmetic yourself, Inverse packages exactly what is described above. It is MIT-licensed, has no backend and no tracking, and you keep your own database and e-mail provider:

// app/api/inverse/route.ts
import { createInverseHandler } from "@sweberdev/inverse";

export const POST = createInverseHandler({
  company: { name: "Acme GmbH", email: "hallo@acme.de" },
  onDeclaration: (record) => db.declaration.create({ data: record }),
  sendReceipt: (receipt) => mailer.send(receipt),
});

<InverseLink kind="withdrawal" href="/widerruf" />     {/* Vertrag widerrufen */}
<WithdrawalForm endpoint="/api/inverse" />

The handler validates the fields the law asks for, sets the time of receipt on the server, stores the record through your callback and sends the acknowledgement in German, English, French, Italian, Dutch, Spanish or Polish. For sites without React there is a framework-free form and a single <script> tag for WordPress, Shopify or static pages. Try the live demo or read the docs.

A paid add-on, Inverse Pro, covers what agencies and larger operators need on top: a tamper-evident log of declarations, a site-wide audit with a report for clients and a weekly digest of open cases.

A checklist to take away

The footer link on every page reads "Vertrag widerrufen" (and "Verträge hier kündigen" if you sell subscriptions).
The form works without login and has exactly two steps; the second button reads "Widerruf bestätigen".
The server sets the time of receipt; the declaration is stored before the e-mail is sent.
The acknowledgement contains the content of the declaration, the date and the time.
The deadline follows §§ 187, 188 and 193 BGB.
The cancellation confirmation page contains nothing but the cancellation.
A CI check fails when the link disappears.
Your withdrawal information (Widerrufsbelehrung) mentions the new function.

This article is software documentation, not legal advice. Check your case with a lawyer.

Disclosure: I maintain the library mentioned in this article. The requirements and code samples stand on their own.