Zum Inhalt springen
Invoapi

Integrationen · PHP-SDK

ZUGFeRD und XRechnung in PHP

ZUGFeRD und XRechnung in PHP, ohne eigenes XML-Mapping: Das PHP-SDK für PHP 8.1 und neuer — nur ext-curl und ext-json, keine weiteren Abhängigkeiten. Für Shops, ERP-Erweiterungen und eigene Anwendungen: jede erzeugte Rechnung ist vom offiziellen Validator geprüft, Tempolimits werden automatisch abgewartet.

Installieren

Das Paket liegt auf Packagist, der Quellcode offen auf GitHub:

Terminal
composer require invoapi/invoapi-php

Version 0.1.0, getestet mit PHP 8.1 bis 8.5. Den API-Schlüssel legen Sie im Dashboard an.

XRechnung in PHP erzeugen

PHP
<?php
require 'vendor/autoload.php';

$invoapi = new Invoapi\Client(getenv('INVOAPI_API_KEY'));

$rechnung = $invoapi->generate([
    'invoice_number'  => 'RE-2026-0001',
    'issue_date'      => '2026-10-28',
    'due_date'        => '2026-11-27',
    'currency'        => 'EUR',
    'buyer_reference' => '04011000-12345-34',
    'seller' => [
        'name' => 'Muster GmbH', 'street' => 'Musterstraße 1', 'postal_code' => '10115',
        'city' => 'Berlin', 'country_code' => 'DE', 'vat_id' => 'DE123456789',
        'email' => 'rechnung@muster.de', 'phone' => '+49 30 1234567',
    ],
    'buyer' => [
        'name' => 'Beispiel GmbH', 'street' => 'Teststraße 10', 'postal_code' => '20095',
        'city' => 'Hamburg', 'country_code' => 'DE', 'email' => 'kreditoren@beispiel.de',
    ],
    'items' => [
        ['name' => 'Beratung', 'quantity' => 8, 'unit' => 'HUR', 'unit_price' => 145, 'vat_rate' => 19],
    ],
    'payment' => ['means_code' => '58', 'iban' => 'DE02120300000000202051'],
], format: 'xrechnung');

if ($rechnung->isValid()) {
    $rechnung->saveTo($rechnung->filename());   // RE-2026-0001.xml
}

ZUGFeRD-PDF in PHP erstellen

Dieselben Daten ergeben mit format zugferd und output pdf ein hybrides ZUGFeRD-2.5-PDF: ein PDF/A-3 mit eingebetteter factur-x.xml, geprüft mit KoSIT, veraPDF und den ZUGFeRD-Profilregeln. Factur-X ist derselbe Standard unter französischem Namen.

PHP
$pdf = $invoapi->generate($daten, format: 'zugferd', output: 'pdf', profile: 'en16931');

if ($pdf->isValid()) {
    $pdf->saveTo($pdf->filename());   // RE-2026-0001.pdf, PDF/A-3 mit factur-x.xml
}

Eingangsrechnung prüfen

PHP
$bericht = $invoapi->validate(file_get_contents('eingang.xml'));   // XML oder ZUGFeRD-PDF

if (!$bericht->isValid()) {
    foreach ($bericht->errors() as $fehler) {
        echo "{$fehler['rule']}: {$fehler['message']}\n";
    }
}

isValid() ist nur dann wahr, wenn ein offizielles Regelwerk tatsächlich gelaufen ist.

Alles Weitere

PHP
$pdf    = $invoapi->generate($daten, format: 'zugferd', output: 'pdf');  // ZUGFeRD PDF/A-3
$daten  = $invoapi->parse($xmlOderPdf);                                   // Rechnung als Array
$format = $invoapi->detect($xmlOderPdf);                                  // Standard, Syntax, Version
$cii    = $invoapi->convert($ublXml, 'xml', format: 'xrechnung', syntax: 'cii');
$html   = $invoapi->render($xmlOderPdf, 'html');                         // Lesefassung
$summen = $invoapi->calculate($daten)['totals'];                          // kostenlos

Fehler

Jede Ablehnung wirft eine Ausnahme mit der verständlichen Meldung der API. Alle erben von Invoapi\Exception\InvoapiException.

InvalidRequestExceptionRechnung oder Dokument fehlerhaft; getDetails() nennt die Felder
AuthenticationExceptionSchlüssel falsch, E-Mail unbestätigt oder Konto gesperrt
QuotaExhaustedExceptionGratis-Kontingent aufgebraucht
RateLimitExceptionZu viele Aufrufe; getRetryAfter() nennt die Wartezeit
ServiceUnavailableExceptionDienst kurz nicht erreichbar

PHP-Bibliothek oder API?

Für ZUGFeRD in PHP gibt es auch Open-Source-Bibliotheken wie horstoeko/zugferd. Sie bauen das XML in Ihrem Code; für die offizielle KoSIT-Prüfung brauchen Sie zusätzlich Java. Das SDK verlagert beides auf den Server:

PHP-Bibliothekinvoapi PHP-SDK
XML-Mappingim eigenen Code, je Formatein Array für alle Formate
KoSIT-PrüfungJava-Validator selbst betreibenin jedem Aufruf enthalten
ZUGFeRD-PDFeigenes PDF/A-3 erzeugen und XML einbettenfertiges PDF mit Logo und Design
Neue VersionenBibliothek und Regelwerke aktualisierenserverseitig, ohne Update
Kostenkostenlos, eigener Aufwand100 Rechnungen kostenlos, dann ab 24 €/Monat

Mehr zu den Formaten: ZUGFeRD API · XRechnung API

Häufige Fragen zu ZUGFeRD und XRechnung in PHP

Wie erstelle ich eine ZUGFeRD-Rechnung in PHP?
Installieren Sie das SDK mit composer require invoapi/invoapi-php und rufen Sie generate() mit format zugferd und output pdf auf. Sie erhalten ein fertiges ZUGFeRD-PDF (PDF/A-3 mit eingebetteter factur-x.xml), das bereits gegen die offiziellen Regeln geprüft ist.
Wie erzeuge ich eine XRechnung mit PHP?
Mit generate() und format xrechnung. Das SDK sendet Ihre Rechnungsdaten als JSON an die API und gibt die XRechnung 3.0.2 zurück, wahlweise in UBL oder CII, geprüft mit dem KoSIT-Validator. Für Behörden gehört die Leitweg-ID in buyer_reference.
Welche PHP-Version brauche ich?
PHP 8.1 oder neuer mit den Erweiterungen curl und json. Getestet ist das SDK mit PHP 8.1 bis 8.5. Weitere Composer-Abhängigkeiten gibt es nicht.
Brauche ich Java für die Prüfung?
Nein. Der offizielle KoSIT-Validator läuft in Java, aber auf unseren Servern. Ihr PHP-Server braucht weder Java noch Schematron-Dateien; die Prüfung ist in jedem Aufruf enthalten.
Was kostet das PHP-SDK?
Das SDK selbst ist kostenlos und MIT-lizenziert. Die API enthält 100 Rechnungen kostenlos, danach ab 24 € im Monat für 500 Rechnungen (zzgl. USt.), monatlich kündbar.
ZUGFeRD & XRechnung in PHP: E-Rechnung-SDK für PHP 8.1+ · Invoapi