Valinvo

Create a valid XRechnung from PHP or Node.js without Java

From 1 January 2027, German companies with more than €800,000 total turnover in the previous year must issue e-invoices to German business customers (§ 27 (38) UStG). If you maintain a PHP shop plugin, a Node.js SaaS or any app that makes invoices, "a PDF by email" stops being enough for those customers, and an XRechnung file takes its place.

Writing the XML is not the hard part. Knowing it is right is. XRechnung is EN 16931 plus German rules, and the official check is a set of Schematron rules that the KoSIT validator runs on Java. A file can pass the XML schema and still be rejected by a public buyer's portal, for example because the buyer reference (BT-10, "Leitweg-ID") is missing or one amount is off by a cent.

So the question for a PHP or Node.js team is where the checking happens. These are the ways we see:

We make Valinvo, which is the third kind, so we show that one with working code and are upfront about the trade-off.

The invoice

The API takes one JSON invoice. Amounts, quantities and VAT rates are strings ("19.99"), never numbers, so nothing is rounded by floating point on the way. A shortened example:

{
  "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" } }
    ]
  }
}

The field names follow the EN 16931 model; GET /v1/formats lists the formats, and an error names any field you leave out.

PHP

Plain curl extension, nothing to install:

<?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 or newer has fetch. Save as 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);
}

What comes back

With the example above the answer is the XRechnung file and two headers: X-Validation-Status: valid and X-Rule-Set: xrechnung-3.0.2-ubl-invoice. An invoice that fails the official rules is never returned; you get an error instead.

If the invoice is broken, you get JSON that points at the field. We removed the buyer's country code to see what happens:

{"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."}]}

That is the part we find most useful for a plugin: the path is the one in your JSON, so you can show the user which field to fix instead of a Schematron rule number.

Things to know before you use it

Code run against the live API in November 2026. We make Valinvo, so we are not neutral on the API route.

Quickstart · XRechnung validator · Peppol validator · ZUGFeRD / Factur-X validator · ZUGFeRD-csharp: your options · XRechnung from PHP or Node.js · XRechnung in Python · XRechnung EndpointID (BT-34, BT-49) · Error codes