XRechnung erzeugen mit PHP oder Node.js, ohne Java
Ab dem 1. Januar 2027 müssen deutsche Unternehmen mit mehr als 800.000 € Gesamtumsatz im Vorjahr ihren inländischen Geschäftskunden E-Rechnungen ausstellen (§ 27 Abs. 38 UStG). Wer ein PHP-Shop-Plugin, ein Node.js-SaaS oder eine andere Anwendung betreut, die Rechnungen erzeugt, kommt dann mit „PDF per E-Mail" bei diesen Kunden nicht mehr weit. An die Stelle tritt eine XRechnung.
Das XML zu schreiben ist nicht das Schwierige. Schwierig ist zu wissen, dass es stimmt. XRechnung ist EN 16931 plus deutsche Regeln, und die offizielle Prüfung besteht aus Schematron-Regeln, die der KoSIT-Validator in Java ausführt. Eine Datei kann das XML-Schema bestehen und trotzdem vom Portal einer Behörde abgelehnt werden, etwa weil die Leitweg-ID (BT-10) fehlt oder ein Betrag um einen Cent abweicht.
Für ein PHP- oder Node.js-Team ist deshalb die Frage, wo geprüft wird. Wir sehen diese Wege:
- Eine Open-Source-Bibliothek in Ihrer Sprache. Für PHP gibt es gute Bibliotheken für ZUGFeRD und XRechnung, für Node.js weniger. Eine Bibliothek baut das XML; das Ergebnis gegen die aktuellen offiziellen Regeln zu prüfen bleibt Ihre Aufgabe.
- Der KoSIT-Validator in der CI. Er ist die Referenz, braucht aber eine Java-Laufzeit und einen festgelegten Regelsatz, den Sie nach jeder Veröffentlichung aktualisieren.
- Eine HTTP-API, die in einem Aufruf erzeugt und prüft. Kein Java im Stack, Regel-Updates beim Dienst. Der Preis: Die Rechnungsdaten verlassen Ihr System, Sie brauchen also einen Auftragsverarbeitungsvertrag, und Sie hängen von der Verfügbarkeit des Dienstes ab.
Wir entwickeln Valinvo, also die dritte Art, und zeigen sie mit funktionierendem Code und offen mit ihrem Preis.
Die Rechnung
Die API nimmt eine Rechnung als JSON. Beträge, Mengen und Steuersätze sind Zeichenketten ("19.99"), nie Zahlen, damit unterwegs nichts per Gleitkomma gerundet wird. Ein gekürztes Beispiel:
{
"format": "xrechnung-ubl",
"invoice": {
"number": "RE-2026-0042",
"type": "invoice",
"issueDate": "2026-10-19",
"dueDate": "2026-11-18",
"currency": "EUR",
"buyerReference": "04011000-12345-34",
"seller": { "name": "Example Software GmbH", "vatId": "DE123456789",
"electronicAddress": { "scheme": "EM", "value": "invoices@example-software.de" },
"address": { "line1": "Musterstraße 1", "city": "Berlin", "postalCode": "10115", "countryCode": "DE" },
"contact": { "name": "Erika Mustermann", "phone": "+49 30 1234567", "email": "billing@example-software.de" } },
"buyer": { "name": "Beispiel Behörde",
"electronicAddress": { "scheme": "EM", "value": "rechnung@beispiel-behoerde.de" },
"address": { "line1": "Amtsweg 5", "city": "Hamburg", "postalCode": "20095", "countryCode": "DE" } },
"payment": { "meansCode": "58", "iban": "DE02120300000000202051", "accountName": "Example Software GmbH" },
"lines": [
{ "id": "1", "name": "Software subscription, October 2026", "quantity": "1", "unitCode": "C62",
"unitPrice": "99.00", "vat": { "category": "S", "rate": "19" } }
]
}
}
Die Feldnamen folgen dem EN-16931-Modell; GET /v1/formats listet die Formate, und ein Fehler nennt jedes fehlende Feld.
PHP
Die normale curl-Erweiterung, nichts zu installieren:
<?php
$ch = curl_init('https://valinvo.bmk-hub.com/v1/invoices');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => file_get_contents('invoice.json'),
CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'X-Accept-Terms: 1.0'],
CURLOPT_RETURNTRANSFER => true,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($status === 200) {
file_put_contents('invoice.xml', $body);
echo "Saved invoice.xml\n";
exit(0);
}
$error = json_decode($body, true);
echo "$status {$error['code']}: {$error['message']}\n";
foreach ($error['problems'] ?? [] as $problem) {
echo " {$problem['path']}: {$problem['message']}\n";
}
exit(1);
Node.js
Node 18 oder neuer hat fetch. Speichern als create-invoice.mjs:
import { readFile, writeFile } from 'node:fs/promises';
const res = await fetch('https://valinvo.bmk-hub.com/v1/invoices', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-Accept-Terms': '1.0' },
body: await readFile('invoice.json'),
});
if (res.ok) {
await writeFile('invoice.xml', Buffer.from(await res.arrayBuffer()));
console.log(`Saved invoice.xml: ${res.headers.get('x-validation-status')} (${res.headers.get('x-rule-set')})`);
} else {
const error = await res.json();
console.error(`${res.status} ${error.code}: ${error.message}`);
for (const p of error.problems ?? []) console.error(` ${p.path}: ${p.message}`);
process.exit(1);
}
Was zurückkommt
Mit dem Beispiel oben ist die Antwort die XRechnung-Datei und zwei Header: X-Validation-Status: valid und X-Rule-Set: xrechnung-3.0.2-ubl-invoice. Eine Rechnung, die die offiziellen Regeln nicht besteht, wird nie zurückgegeben; stattdessen kommt ein Fehler.
Ist die Rechnung fehlerhaft, kommt JSON, das auf das Feld zeigt. Wir haben die Länderkennung des Käufers entfernt, um das zu sehen:
{"code":"invalid_invoice","message":"The invoice has 1 problem. Fix it and try again.",
"problems":[{"path":"invoice.buyer.address.countryCode","message":"Required field 'countryCode' is missing."}]}
Das ist für ein Plugin der nützlichste Teil: Der Pfad stammt aus Ihrem JSON, Sie können Ihren Nutzern also zeigen, welches Feld zu korrigieren ist, statt einer Schematron-Regelnummer.
Vor dem Einsatz
- Zum Testen kein Konto.
X-Accept-Terms: 1.0akzeptiert die Nutzungsbedingungen. Ohne API-Schlüssel sind es 2 erzeugte Rechnungen pro Tag und IP-Adresse, testen Sie also mit Beispieldaten, nicht mit echten Rechnungen Ihrer Kunden. Beta-Schlüssel gibt es kostenlos auf Anfrage. - Es ist eine Beta, betrieben von einer kleinen Firma in Nordmazedonien (BMK HUB DOOEL). Es gibt einen Auftragsverarbeitungsvertrag und eine Liste der Unterauftragsverarbeiter.
- Die Rechnung wird nicht versendet. Der Versand (E-Mail, Portal, Peppol-Netzwerk) bleibt bei Ihnen oder Ihrem Access Point.
- Prüft auch vorhandene Dateien.
POST /v1/validatenimmt jede XRechnung, jedes Peppol BIS und jedes ZUGFeRD/Factur-X, Sie können also Ihren eigenen Generator behalten und die API als Prüfung in der CI nutzen. Dafür gibt es eine GitHub Action.
Code im November 2026 gegen die laufende API ausgeführt. Wir entwickeln Valinvo und sind beim API-Weg daher nicht neutral.
Schnellstart · XRechnung-Validator · ZUGFeRD-Validator · ZUGFeRD-csharp: Ihre Optionen · XRechnung mit PHP oder Node.js · XRechnung mit Python · XRechnung EndpointID (BT-34, BT-49) · Fehlercodes