Valinvo

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:

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

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