From 1 January 2027, German businesses with a turnover above 800,000 euros must send e-invoices to other businesses, and from 2028 all of them must. Invoices to public buyers already have to be XRechnung. If your Laravel app bills German customers, it will soon write XML that the receiver checks against the official rules before anyone reads it, and an invoice that fails goes back to you.
A library such as horstoeko/zugferd writes a well-formed XRechnung from what you give it. Whether the result passes depends on that data: an empty field in your database becomes an invoice the rules reject. The library can't see that, but your tests can. This post sets it up in a few minutes: write the invoice in a test, send it to the same rules the receiver uses, and fail the build when one breaks.
Everything below was run for this post. The messages are what the rules report, KoSIT's XRechnung 3.0 configuration with the EN 16931 rules 1.3.16.
The invoice
A two-line invoice from a German software company to a city administration, written as XRechnung 3.0 in CII syntax:
use horstoeko\zugferd\ZugferdDocumentBuilder;
use horstoeko\zugferd\ZugferdProfiles;
$document = ZugferdDocumentBuilder::createNew(ZugferdProfiles::PROFILE_XRECHNUNG_3);
$document
->setDocumentInformation('2026-0042', '380', new DateTime('2026-11-16'), 'EUR')
->setDocumentSupplyChainEvent(new DateTime('2026-11-13'))
->setDocumentBuyerReference('04011000-12345-34')
->setDocumentSeller('Muster Software GmbH')
->addDocumentSellerVATRegistrationNumber('DE123456789')
->setDocumentSellerAddress('Hauptstraße 1', null, null, '10115', 'Berlin', 'DE')
->setDocumentSellerContact('Anna Schmidt', null, '+49 30 1234567', null, 'billing@muster-software.de')
->setDocumentSellerCommunication('EM', 'billing@muster-software.de')
->setDocumentBuyer('Stadtverwaltung Musterstadt')
->setDocumentBuyerAddress('Rathausplatz 1', null, null, '20095', 'Hamburg', 'DE')
->setDocumentBuyerCommunication('EM', 'rechnungseingang@musterstadt.de')
->addDocumentPaymentMeanToCreditTransfer('DE02120300000000202051', 'Muster Software GmbH')
->addDocumentPaymentTerm('Payable within 30 days', new DateTime('2026-12-16'));
$document->addNewPosition('1')
->setDocumentPositionProductDetails('Support plan, November 2026')
->setDocumentPositionNetPrice(249.00)
->setDocumentPositionQuantity(1, 'C62')
->addDocumentPositionTax('S', 'VAT', 19)
->setDocumentPositionLineSummation(249.00);
$document->addNewPosition('2')
->setDocumentPositionProductDetails('On-site training')
->setDocumentPositionNetPrice(95.00)
->setDocumentPositionQuantity(3.5, 'HUR')
->addDocumentPositionTax('S', 'VAT', 19)
->setDocumentPositionLineSummation(332.50);
$document
->addDocumentTax('S', 'VAT', 581.50, 110.49, 19)
->setDocumentSummation(691.99, 691.99, 581.50, 0.0, 0.0, 581.50, 110.49);
$xml = $document->getContent();
This one passes every rule. In an app the strings and amounts come from your models, and that is where it goes wrong.
What the rules catch
I took the invoice above and changed one thing at a time, each a mistake that happens when the data behind it is incomplete. The lines are written the way the Laravel package prints a finding.
No buyer reference. Public buyers route invoices by their Leitweg-ID, and XRechnung requires the buyer reference on every invoice, public buyer or not. A customer record without one gives setDocumentBuyerReference(null):
Line 2: [BR-DE-15] The buyer reference (BT-10) must be given.
No phone number for the seller contact. XRechnung wants a contact with a name, a phone number and an email address. A company profile with an empty phone field:
Line 75: [BR-DE-6] The seller contact telephone number (BT-42) must be given.
A warning, BR-DE-27, follows it: the number should contain at least three digits.
No electronic address. Pass null as the seller's address to setDocumentSellerCommunication() and the library still writes an empty <ram:URIUniversalCommunication/>. That is three errors for one empty field:
Line 2: [BR-62] The Seller electronic address (BT-34) shall have a Scheme identifier.
Line 73: [PEPPOL-EN16931-R020] Seller electronic address MUST be provided
Line 90: [PEPPOL-EN16931-R008] Document MUST not contain empty elements.
No payment instructions. An invoice paid by direct debit, card or a marketplace still needs a payment means. Leave out addDocumentPaymentMeanToCreditTransfer():
Line 2: [BR-DE-1] An invoice must contain payment instructions (BG-16).
A cent off in the VAT total. The VAT total and the VAT breakdown are often computed in two places: one sums the lines, the other rounds the total. When they differ by 0.01:
Line 144: [BR-CO-14] Invoice total VAT amount (BT-110) = Σ VAT category tax amount (BT-117).
No date of supply. Without the delivery date, setDocumentSupplyChainEvent(), the invoice still passes, with a warning:
[BR-DE-TMP-32] An invoice should give the date of supply: the actual delivery date (BT-72), the invoicing period (BG-14) or an invoice line period (BG-26) on every line.
None of these is a bug in the library. Each one is a field your app filled from its data, or didn't. KoSIT writes the German rules' messages in German, so the API also gives an English rendering. The package prints that one; the German text is in the finding's message.
The test
Install the Laravel package:
composer require xmlvalid/xmlvalid-laravel
Make an API key under Dashboard → API keys (the free plan has 100 validations a month) and put it in .env.testing or your CI's secrets:
XMLVALID_API_KEY=xv_…
Then a test that writes an invoice from a factory and checks it. Here XRechnungWriter stands for your own class that turns an Invoice into XML with the builder, and forPublicBuyer() for a factory state of yours:
use App\Invoicing\XRechnungWriter;
use App\Models\Invoice;
use Xmlvalid\Document;
use Xmlvalid\Laravel\Facades\Xmlvalid;
it('writes an XRechnung that passes the official rules', function () {
$invoice = Invoice::factory()->forPublicBuyer()->create();
$xml = app(XRechnungWriter::class)->write($invoice);
$validation = Xmlvalid::validate(
Document::string($xml, "{$invoice->number}.xml"),
schema: 'xrechnung-3-cii',
);
expect(array_map('strval', $validation->errors()))->toBe([]);
})->group('xrechnung')->skip(fn () => ! config('xmlvalid.key'), 'XMLVALID_API_KEY is not set');
xrechnung-3-cii is the catalog entry with the XSD and both rule sets; xrechnung-3-ubl is its UBL twin. Comparing the errors as strings makes a failure readable in the test output:
Failed asserting that two arrays are identical.
--- Expected
+++ Actual
@@ @@
-Array &0 []
+Array &0 [
+ 0 => 'Line 2: [BR-DE-15] The buyer reference (BT-10) must be given.',
+]
Write one test per kind of invoice your app sends: a public buyer, a business customer, a credit note, a foreign customer with reverse charge. Each factory state is a set of fields that can go missing.
To fail on warnings too, check $validation->warnings() the same way. Warnings don't get an invoice rejected, but some receivers read them.
If your test suite blocks real HTTP calls with Http::preventStrayRequests(), this test is the exception: it has to reach the API. For tests that should stay offline, XmlvalidFake answers in the API's shape:
use Illuminate\Support\Facades\Http;
use Xmlvalid\Laravel\Testing\XmlvalidFake;
Http::fake(['xmlvalid.com/*' => XmlvalidFake::invalid(
['line' => 2, 'rule' => 'BR-DE-15', 'message' => 'Das Element "Buyer reference" (BT-10) muss übermittelt werden.'],
)]);
In CI
Each run of the test is one validation per invoice. To keep that low, run the group in CI and leave it out locally with --exclude-group=xrechnung:
name: Tests
on: [push, pull_request]
jobs:
xrechnung:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2
with:
php-version: '8.4'
- run: composer install --no-interaction --prefer-dist
- run: vendor/bin/pest --group=xrechnung
env:
XMLVALID_API_KEY: ${{ secrets.XMLVALID_API_KEY }}
Pull requests from forks get no secrets, so the test skips itself there instead of failing.
Another way is golden files: a test compares the writer's output with XML files committed to the repository, and the GitHub Action checks those files only when they change. The test stays offline, and the API sees an invoice only when its XML does change:
on:
pull_request:
paths: ['tests/fixtures/xrechnung/**']
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: xmlvalid/validate-action@v1
with:
files: tests/fixtures/xrechnung/*.xml
schema: auto
api-key: ${{ secrets.XMLVALID_API_KEY }}
With schema: auto each file is checked against the profile it names, so XRechnung, ZUGFeRD and Peppol files can share a folder. The failing lines are marked in the pull request.
Invoices you receive
The same rules work in the other direction. Since 2025 every German business must be able to receive e-invoices, and a supplier's file is as likely to break a rule as yours. The package has a validation rule for uploads:
use Xmlvalid\Laravel\Rules\ValidXml;
$request->validate([
'invoice' => ['required', 'file', 'max:10240', ValidXml::schema('auto')],
]);
An invalid invoice fails the field with its first error, so the supplier can be told what to fix before the invoice enters your books.
When there is no API key
To look at a single invoice, drop it on the validator: it runs the same rules in the browser, without an account, and the invoice isn't uploaded. The rule pages explain each id above, with the XPath it tests. For XRechnung without Laravel, the CLI and the PHP, Python and JavaScript clients work the same way.