PDFTool/README.md

PDF Tool — ZUGFeRD E-Rechnungs-Konverter

Spring Boot + Vaadin Flow Anwendung, die ein herkömmliches B2B-Rechnungs-PDF in eine rechtskonforme ZUGFeRD-E-Rechnung umwandelt (PDF/A-3 mit eingebettetem EN16931-XML, Profil EN 16931 / Factur-X), das Ergebnis mit dem Mustang-Validator prüft und als ZIP-Datei bereitstellt.

Verwendet wird Mustangproject (Apache-2.0), die Open-Source-Referenzimplementierung von ZUGFeRD, inklusive des Mustang-Validators (XSD + EN16931-Schematron für das XML, veraPDF für die PDF/A-3-Konformität).

Hinweis zur Rechtskonformität: ZUGFeRD "signiert" nicht kryptografisch. Rechtskonform im Sinne der deutschen B2B-E-Rechnungspflicht (§ 14 UStG, seit 01.01.2025) ist eine Rechnung im strukturierten EN16931-Format — genau das erzeugt dieses Tool. Eine qualifizierte elektronische Signatur ist seit 2011 nicht mehr erforderlich.

Voraussetzungen

• Java 21+
• Maven 3.9+

Starten

mvn spring-boot:run

Die Weboberfläche ist dann unter http://localhost:8083 erreichbar: PDF hochladen, Rechnungsdaten ausfüllen, "E-Rechnung erzeugen" klicken, ZIP herunterladen.

Produktions-Build:

mvn clean package -Pproduction
java -jar target/pdf-tool-1.0.0-SNAPSHOT.jar

REST-API

E-Rechnung erzeugen

POST /api/invoices/sign (multipart/form-data) mit zwei Parts:

Part	Inhalt
file	das Rechnungs-PDF
metadata	Rechnungsdaten als JSON (siehe unten)

Antwort: application/zip mit <Rechnungsnummer>-zugferd.pdf, factur-x.xml und validation-report.xml (Mustang-Prüfbericht). Der Header X-Zugferd-Valid: true|false meldet das Validierungsergebnis. Bei Fehlern: HTTP 400 mit {"error": "..."}.

Häufigste Ursache für X-Zugferd-Valid: false: Das Quell-PDF bettet seine Schriften nicht ein. Das kann die Konvertierung nicht reparieren — das PDF muss dann mit eingebetteten Schriften neu erzeugt werden (Standard bei den meisten ERP-/Reporting-Systemen konfigurierbar).

Bestehende E-Rechnung prüfen

POST /api/invoices/validate (multipart/form-data, Part file = ZUGFeRD-PDF oder Factur-X-XML). Antwort: der Mustang-Prüfbericht als XML — HTTP 200 bei gültiger, HTTP 422 bei ungültiger Rechnung, ebenfalls mit X-Zugferd-Valid-Header.

curl -X POST http://localhost:8083/api/invoices/validate \
  -F "file=@rechnung-zugferd.pdf"

Beispiel

curl -X POST http://localhost:8083/api/invoices/sign \
  -F "file=@rechnung.pdf" \
  -F "metadata=@metadata.json;type=application/json" \
  -o rechnung-zugferd.zip

metadata.json:

{
  "invoiceNumber": "RE-2026-0815",
  "issueDate": "2026-07-08",
  "deliveryDate": "2026-07-01",
  "dueDate": "2026-07-22",
  "currency": "EUR",
  "paymentTerms": "Zahlbar innerhalb von 14 Tagen ohne Abzug.",
  "sender": {
    "name": "Assecutor GmbH",
    "street": "Musterstrasse 1",
    "zip": "20095",
    "city": "Hamburg",
    "countryCode": "DE",
    "vatId": "DE123456789"
  },
  "recipient": {
    "name": "Kunde AG",
    "street": "Beispielweg 2",
    "zip": "10115",
    "city": "Berlin",
    "countryCode": "DE"
  },
  "items": [
    {
      "description": "Beratungsleistung",
      "quantity": 1,
      "unitPriceNet": 1500.00,
      "vatPercent": 19
    }
  ]
}

Pflichtfelder: invoiceNumber, issueDate, sender (inkl. Adresse), recipient, mindestens ein Eintrag in items. deliveryDate fällt auf das Rechnungsdatum zurück, dueDate auf Rechnungsdatum + 14 Tage, currency auf EUR.

Architektur

• ZugferdService — Kernlogik: PDF → PDF/A-3 + EN16931-XML (Mustangproject), Validierung, Verpackung als ZIP. Nicht-PDF/A-Eingaben (der Normalfall) werden tolerant konvertiert.
• ZugferdValidationService — Mustang-Validator (XSD + Schematron + veraPDF), liefert Status und XML-Prüfbericht
• InvoiceSigningController — REST-Endpunkte /sign und /validate
• MainView — Vaadin-Weboberfläche
• InvoiceMetadata — DTO für die Rechnungsdaten

Tests

mvn test

ZugferdServiceTest erzeugt ein Test-PDF, konvertiert es und prüft, dass das ZIP ein PDF/A-3 mit eingebettetem factur-x.xml (EN16931-Profil) enthält.