Profile

Zwei kleine Entscheidungen, beide mit einer Voreinstellung, die Sie selten ändern: welches Profil (profile: ZUGFeRD oder XRechnung) und welche XML-Syntax (CII oder UBL). Dieselbe Invoice speist alle - Sie wählen nur.

ZUGFeRD oder XRechnung?

renderZugferd(invoice); // ZUGFeRD (en16931) - die Voreinstellung
renderZugferd(invoice, { profile: "xrechnung" }); // deutsches B2G

ZUGFeRD (en16931) ist die Voreinstellung und das, was die meisten Rechnungen brauchen: Standard EN 16931, gültig im B2B in ganz Europa. Nichts einzustellen.

XRechnung (xrechnung) ist für Rechnungen an eine deutsche Behörde (B2G), dort ist sie Pflicht. Sie ist EN 16931 plus strengere deutsche Regeln - ein paar Felder mehr sind verpflichtend:

• die Leitweg-ID in buyerReference (die bekommen Sie von der Behörde),
• eine elektronische Adresse (electronicAddress) bei seller und buyer,
• ein vollständiger Kontakt des Verkäufers (seller.contact mit name, phone, email) sowie city und postCode,
• ein Fälligkeitsdatum (dueDate) oder Zahlungsbedingungen (payment.terms), und eine IBAN (payment.iban) für eine Überweisung.

Das Beruhigende daran: Sie müssen sich diese Liste nicht merken. Wählen Sie das Profil, und die Bibliothek prüft vorab - mit einem klaren Fehler, der das Feld nennt, falls etwas fehlt. Lange bevor ein Portal die Rechnung ablehnt.

// Leitweg-ID vergessen? Sie erfahren genau das, mit dem Feld, das Sie setzen müssen:
// Error: Invoice is not XRechnung-ready:
//   - XRechnung needs the Leitweg-ID - set invoice.buyerReference (BT-10).
await renderZugferd(invoice, { profile: "xrechnung" });

Die zusätzlichen Felder einer vollständigen XRechnung an einer Stelle:

const invoice: Invoice = {
  // ... die üblichen Felder ...
  buyerReference: "04011000-12345-34", // Leitweg-ID (BT-10)
  dueDate: "2026-07-05",
  seller: {
    name: "Northwind GmbH",
    vatId: "DE265013614",
    electronicAddress: "billing@northwind.de", // BT-34
    contact: { name: "A. Schmidt", phone: "+49 30 123456", email: "billing@northwind.de" },
    address: { line1: "Hauptstrasse 1", city: "Berlin", postCode: "10115", country: "DE" },
  },
  buyer: {
    name: "Bundesamt fuer Beschaffung",
    electronicAddress: "einkauf@behoerde.de", // BT-49
    address: { city: "Bonn", postCode: "53113", country: "DE" },
  },
  payment: { iban: "DE89370400440532013000", terms: "Zahlbar innerhalb von 30 Tagen." },
  // ... Positionen ...
};

Sie können die Prüfung auch selbst aufrufen, ohne zu rendern - etwa um ein Formular oder einen Speichern-Knopf freizugeben:

import { xrechnungProblems } from "@jasy/e-invoice";

const problems = xrechnungProblems(invoice); // string[] - leer heißt: alles bereit

CII oder UBL?

Die EN 16931 hat zwei gleichwertige XML-Syntaxen. Darüber müssen Sie fast nie nachdenken.

CII (Cross Industry Invoice) ist der Standard von ZUGFeRD und Factur-X, und genau das bettet renderZugferd ein und gibt es in .xml zurück. Das ist die Voreinstellung und das, was Sie wollen.

const { bytes, xml } = await renderZugferd(invoice); // xml ist das CII

Brauchen Sie das XML allein - etwa für ein Portal, das einen Datei-Upload will - oder ausdrücklich UBL (Universal Business Language, die andere Syntax der EN 16931, die manche Systeme bevorzugen)? Einmal berechnen, dann umwandeln:

import { computeInvoice, toCII, toUBL } from "@jasy/e-invoice";

const computed = computeInvoice(invoice);
const cii = toCII(invoice, computed); // dasselbe XML, das renderZugferd einbettet
const ubl = toUBL(invoice, computed, "xrechnung"); // UBL, XRechnung-CIUS

Beide nehmen das Profil an ("en16931" als Voreinstellung oder "xrechnung"), damit die Kennung der Spezifikation im XML zu dem passt, was Sie einreichen.