PHPackages                             normbill/xrechnung - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. normbill/xrechnung

ActiveLibrary

normbill/xrechnung
==================

PHP client for the normbill e-invoicing API: generate, validate and parse XRechnung, ZUGFeRD/Factur-X and Peppol BIS Billing 3.0 invoices. Every validation error maps to the exact field in your request, with a plain-language fix.

v0.1.1(1mo ago)01MITPHPPHP >=8.1

Since Jul 17Pushed 1mo agoCompare

[ Source](https://github.com/MichaelGorski/xrechnung-php)[ Packagist](https://packagist.org/packages/normbill/xrechnung)[ Docs](https://normbill.com)[ RSS](/packages/normbill-xrechnung/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (2)Versions (3)Used By (0)

normbill/xrechnung
==================

[](#normbillxrechnung)

**XRechnung mit PHP erzeugen — in einem API-Aufruf, KoSIT-validiert.** Rechnungsdaten als JSON-Array rein, konforme XRechnung (UBL oder CII), ZUGFeRD/Factur-X oder Peppol BIS 3.0 raus. Schlägt die Validierung fehl, bekommen Sie keinen kryptischen Schematron-Code, sondern das exakte Feld in *Ihrem* Request samt Klartext-Erklärung und konkretem Fix — z. B. `invoice.buyer_reference` statt `[BR-DE-15] cbc:BuyerReference`. Validierung ist im Rahmen der Fair-Use-Grenzen kostenlos; ein großzügiger Gratis-Tarif reicht für Integration, Tests und den Start. API-Key auf [normbill.com](https://normbill.com).

PHP client for the [normbill](https://normbill.com) e-invoicing API. Plain PHP ≥ 8.1 with `ext-curl` — no framework, no XML libraries, no Java toolchain.

normbill vs. horstoeko/zugferd (honest comparison)
--------------------------------------------------

[](#normbill-vs-horstoekozugferd-honest-comparison)

[horstoeko/zugferd](https://github.com/horstoeko/zugferd) is an excellent open-source library — if you want to own XML generation, use it. The difference:

**horstoeko generates the XML. normbill generates it, validates it against the official KoSIT validator (the legal reference implementation), tells you which field in your request to fix when a rule fails, and tracks spec version bumps (XRechnung 4.0 is expected late 2026) for you.**

With a library, Schematron validation, error interpretation and every future XRechnung/ZUGFeRD version bump stay on your roadmap. With normbill they are the product.

Install
-------

[](#install)

```
composer require normbill/xrechnung
```

Quickstart
----------

[](#quickstart)

```
use Normbill\Xrechnung\NormbillClient;

$normbill = new NormbillClient(getenv('NORMBILL_API_KEY'));

$result = $normbill->generate([
    'format'  => 'xrechnung-3.0',
    'invoice' => [
        'number'          => 'INV-2026-0001',
        'issue_date'      => '2026-06-15',
        'due_date'        => '2026-07-15',
        'buyer_reference' => '04011000-1234512345-06', // Leitweg-ID
        'seller' => [
            'name'    => 'Muster Lieferant GmbH',
            'vat_id'  => 'DE123456789',
            'address' => ['country' => 'DE', 'city' => 'Berlin', 'postal_code' => '10115'],
            'contact' => ['name' => 'Erika Muster', 'phone' => '+49 30 1234567', 'email' => 'billing@lieferant.example'],
        ],
        'buyer' => [
            'name'    => 'Beispiel Kunde AG',
            'address' => ['country' => 'DE', 'city' => 'Hamburg', 'postal_code' => '20095'],
            'contact' => ['email' => 'ap@kunde.example'],
        ],
        'payment' => ['iban' => 'DE89370400440532013000'],
        'lines'   => [
            ['name' => 'Beratungsleistung', 'qty' => 10, 'unit_price' => 100, 'vat' => 19],
        ],
    ],
]);

$xml    = $result['xml'];        // KoSIT-validated XRechnung 3.0 (UBL 2.1)
$report = $result['validation']; // full validation report
```

When validation fails, you know what to fix
-------------------------------------------

[](#when-validation-fails-you-know-what-to-fix)

```
use Normbill\Xrechnung\Exception\ValidationFailedException;

try {
    $normbill->generate($request);
} catch (ValidationFailedException $e) {
    foreach ($e->getIssues() as $issue) {
        // $issue['rule']    => 'BR-DE-15'
        // $issue['path']    => 'invoice.buyer_reference'   ← a field in YOUR request
        // $issue['message'] => 'The buyer reference (Leitweg-ID) is missing.'
        // $issue['fix']     => 'Set invoice.buyer_reference, e.g. "04011000-1234512345-06".'
        error_log(sprintf('%s @ %s: %s', $issue['rule'], $issue['path'], $issue['message']));
    }
}
```

API
---

[](#api)

MethodEndpointWhat it does`generate(array $request, ?string $idempotencyKey = null)``POST /v1/invoices/generate`Invoice JSON → validated e-invoice (XML; base64 PDF for hybrid formats)`validate(string $content, ?string $format = null)``POST /v1/invoices/validate`Existing XML → validation report with reverse-mapped fixes. **Free within fair use.**`parse(string $content)``POST /v1/invoices/parse`Inbound XRechnung/ZUGFeRD XML → invoice array (the receive side of the mandate)`validate()` always returns the report — an invalid document is a result, not an exception. Check `$report['valid']`.

### Formats

[](#formats)

`format`SyntaxValidation`xrechnung-3.0`UBL 2.1official KoSIT validator`xrechnung-cii-3.0`CII (UN/CEFACT D16B)official KoSIT validator`peppol-bis-3.0`UBL 2.1 (BIS Billing 3.0)structural tier`zugferd-2.x` / `facturx-1.0`CII in hybrid PDF/A-3structural tier, paid plans### Retry-safe generation (idempotency)

[](#retry-safe-generation-idempotency)

Pass an idempotency key and retries can never double-generate or double-bill — same key + same body replays the original result (honoured for 24 hours):

```
$normbill->generate($request, 'order-' . $orderId);
```

### Quota warnings

[](#quota-warnings)

From 80% usage every response carries an `X-Quota-Warning` header:

```
$quota = $normbill->getLastQuota();
// ['limit' => 50, 'remaining' => 9, 'warning' => '82% of monthly documents used']
```

### Exceptions

[](#exceptions)

All exceptions extend `Normbill\Xrechnung\Exception\NormbillException`:

ClassWhen`ValidationFailedException`422 — `getReport()` / `getIssues()` (rule, path, message, fix)`AuthenticationException`401 — missing/invalid API key`RateLimitException`429 — quota or burst limit; `getRetryAfter()``ApiException`any other non-2xx; `getStatus()` / `getProblem()` (RFC 9457)`ConnectionException`network failure / timeoutPrivacy
-------

[](#privacy)

normbill never persists invoice content — payloads are request-scoped, processed in the EU, and gone when the response is sent.

Tests
-----

[](#tests)

```
composer install
composer test
```

The test suite stubs the HTTP transport (no network, no API key needed). It is not executed in this repository's CI yet — run it locally or wire it into your pipeline.

Links
-----

[](#links)

- **[normbill.com](https://normbill.com)** — create a free API key
- **[API reference](https://normbill.com/docs)** — full docs, rule catalog, playground

MIT © VIBOA UG (haftungsbeschränkt)

###  Health Score

34

—

LowBetter than 74% of packages

Maintenance90

Actively maintained with recent releases

Popularity1

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity33

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

45d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/8994411?v=4)[Michael Sathya Gorski](/maintainers/MichaelGorski)[@MichaelGorski](https://github.com/MichaelGorski)

---

Top Contributors

[![MichaelGorski](https://avatars.githubusercontent.com/u/8994411?v=4)](https://github.com/MichaelGorski "MichaelGorski (1 commits)")

---

Tags

ZUGFeRDfactur-xxrechnungE-InvoiceublpeppolciiEN16931e-rechnungkosit

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/normbill-xrechnung/health.svg)

```
[![Health](https://phpackages.com/badges/normbill-xrechnung/health.svg)](https://phpackages.com/packages/normbill-xrechnung)
```

###  Alternatives

[easybill/e-invoicing

A package to read and create EN16931 e-invoices or CIUS like: XRechnung, ZUGFeRD etc.

16177.2k](/packages/easybill-e-invoicing)[horstoeko/zugferd

A library for creating and reading european electronic invoices

4357.1M41](/packages/horstoeko-zugferd)[horstoeko/zugferdublbridge

Convert Factur-X/ZUGFeRD (CII-Syntax) to PEPPOL (UBL-Syntax) and visa versa

16206.8k13](/packages/horstoeko-zugferdublbridge)[num-num/ubl-invoice

A modern object-oriented PHP library to create and read valid UBL and EN 16931/Peppol BIS 3.0 files

1391.0M](/packages/num-num-ubl-invoice)[josemmo/einvoicing

Library for reading and creating European-compliant electronic invoices (EN 16931)

177414.5k6](/packages/josemmo-einvoicing)[easybill/zugferd-php

ZUGFeRD PHP SDK (Factur-X, XRechnung) - Convert PHP Objects to XML and back.

103352.4k11](/packages/easybill-zugferd-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)