@e-rechnung-inbox/xrechnung-core

Stateless TypeScript helpers for XRechnung, ZUGFeRD / Factur-X, and the EN 16931 European e-invoice standard. Parsing, structural validation, and DATEV SKR03/SKR04 export helpers — no I/O, no persistence, no auth.

Powers e-rechnung-inbox.de and the companion MCP server.

Install

npm install @e-rechnung-inbox/xrechnung-core

Use

import {
  parseInvoiceXml,
  validateInvoiceData,
  extractXmlFromPdfBase64,
  generateDatevCsv,
} from "@e-rechnung-inbox/xrechnung-core";

const xml = "<Invoice>...</Invoice>";
const { parsed, lineItems } = parseInvoiceXml(xml);
const { issues, validationStatus } = validateInvoiceData(
  parsed,
  lineItems,
  "xrechnung",
);

console.log(validationStatus); // "valid" | "warning" | "invalid"
console.log(issues.length);    // number of structural issues found

What it does

• parseInvoiceXml(xml) — walks UBL and CII flavored XRechnung trees defensively. Returns normalized ParsedInvoiceData + InvoiceLineItem[].
• validateInvoiceData(parsed, lineItems, format) — structural checks (totals reconciliation, required-field coverage, tax breakdown sanity). Produces human-readable codes you can map to your own i18n strings.
• extractXmlFromPdf(buffer) / extractXmlFromPdfBase64(base64) — pulls the Factur-X XML out of a ZUGFeRD PDF. Simple substring scanner — good enough for ~95% of real-world PDFs; a proper PDF walker is on the roadmap.
• generateDatevCsv(invoices, frame, creditorStart) — emits the exact 20-column DATEV "Standard-Buchungsstapel" CSV the German tax-advisor tooling expects, CP1252-ready.
• buSchluesselFromTaxBreakdown / kreditorAccountFor — the subtle SKR03/SKR04 account-mapping logic that keeps imports clean.

What it deliberately doesn't do

• No KoSIT reference-implementation validation — that's a Java daemon; this package stays zero-runtime-dependency. Pair it with the @e-rechnung-inbox/xrechnung-mcp server or your own KoSIT deployment for reference parity.
• No persistence, no auth, no i18n strings. Error codes are stable identifiers like missing_invoice_number; map them to user-facing text in your own layer.
• No network calls. Pure data transformations.

Types

All shapes are exported. The canonical ones are Invoice, ParsedInvoiceData, InvoiceLineItem, InvoiceTaxBreakdownItem, and ValidationIssue. See src/types.ts.

Versioning

This package is still pre-1.0. Breaking changes in the parser shape or validation codes will bump the minor version until we cross 1.0.

License

MIT.