XRechnung in Ihr ERP integrieren — an einem Nachmittag

Dieses Tutorial zeigt, wie Sie XRechnung-Validierung mit der xingen REST-API in einen Node.js-Rechnungsservice einbauen. Am Ende haben Sie eine Funktion, die einen Rechnungs-XML-Buffer entgegennimmt, validiert und entweder die konvertierte ZUGFeRD-Ausgabe zurückgibt oder einen typisierten Fehler mit feldgenauen Details wirft.

Voraussetzungen

• Node.js 18+
• Ein xingen API-Key (xgn_live_…) — kostenlos holen
• Vorhandener Code, der UBL 2.1 oder CII XML erzeugt

Schritt 1 — xingen.js erstellen

const BASE_URL = "https://api.xingen.de";
const API_KEY  = process.env.XINGEN_API_KEY;

export async function validiereRechnung(xmlBuffer) {
  const res = await fetch(`${BASE_URL}/v1/validate`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/xml",
    },
    body: xmlBuffer,
  });

  if (!res.ok) {
    const err = await res.json();
    throw new Error(`xingen API-Fehler: ${err.error.message}`);
  }

  return res.json(); // { valid, format, errors, warnings }
}

export async function konvertiereZuZugferd(xmlBuffer) {
  const res = await fetch(`${BASE_URL}/v1/convert`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/xml",
      "X-Target-Format": "zugferd-2.3",
    },
    body: xmlBuffer,
  });

  if (!res.ok) {
    const err = await res.json();
    throw new Error(`xingen Konvertierungsfehler: ${err.error.message}`);
  }

  return res.json();
}

Schritt 2 — Im Rechnungsflow einsetzen

import { validiereRechnung, konvertiereZuZugferd } from "./xingen.js";

export async function rechnungAusstellen(rechnungXml) {
  // 1. Vor dem Versand validieren
  const { valid, errors } = await validiereRechnung(rechnungXml);

  if (!valid) {
    throw new RechnungsValidierungsFehler(errors);
    // errors[0] → { code, severity, message, path, line, suggestion }
  }

  // 2. Für Kunden, die PDF+XML bevorzugen, konvertieren
  const { output } = await konvertiereZuZugferd(rechnungXml);

  await anKundenSenden(output);
}

Schritt 3 — Fehler in der UI anzeigen

errors.forEach(err => {
  // err.path = "/Invoice/AccountingCustomerParty/Party/..."
  const feldName = pfadZuFeldName(err.path);
  setFeldFehler(feldName, err.message);
  // err.suggestion als Tooltip anzeigen
});

Schritt 4 — Smoke-Test in der CI

// rechnung.test.js
import { validiereRechnung } from "./xingen.js";
import { readFileSync } from "fs";

test("Fixture-Rechnung ist gültige XRechnung", async () => {
  const xml = readFileSync("fixtures/gueltige-xrechnung.xml");
  const result = await validiereRechnung(xml);
  expect(result.valid).toBe(true);
  expect(result.format).toBe("xrechnung-3.0");
});

Die Endpunkte-Referenz enthält alle verfügbaren Parameter, die Fehler-Referenz die vollständige Liste der zu behandelnden Validierungscodes.