Initialer Stand des PDF Tools
ZUGFeRD-E-Rechnungs-Konverter mit Vaadin-UI: E-Rechnung aus PDF oder Rechnungstemplate erzeugen, Template-Designer, Adressbuch und speicherbare Formulareingaben (MongoDB). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
137
README.md
Normal file
137
README.md
Normal file
@@ -0,0 +1,137 @@
|
||||
# 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](https://www.mustangproject.org/) (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
|
||||
|
||||
```bash
|
||||
mvn spring-boot:run
|
||||
```
|
||||
|
||||
Die Weboberfläche ist dann unter <http://localhost:8080> erreichbar:
|
||||
PDF hochladen, Rechnungsdaten ausfüllen, "E-Rechnung erzeugen" klicken, ZIP herunterladen.
|
||||
|
||||
Produktions-Build:
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/invoices/validate \
|
||||
-F "file=@rechnung-zugferd.pdf"
|
||||
```
|
||||
|
||||
### Beispiel
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/invoices/sign \
|
||||
-F "file=@rechnung.pdf" \
|
||||
-F "metadata=@metadata.json;type=application/json" \
|
||||
-o rechnung-zugferd.zip
|
||||
```
|
||||
|
||||
`metadata.json`:
|
||||
|
||||
```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](src/main/java/de/assecutor/pdftool/zugferd/ZugferdService.java) — Kernlogik:
|
||||
PDF → PDF/A-3 + EN16931-XML (Mustangproject), Validierung, Verpackung als ZIP.
|
||||
Nicht-PDF/A-Eingaben (der Normalfall) werden tolerant konvertiert.
|
||||
- [ZugferdValidationService](src/main/java/de/assecutor/pdftool/zugferd/ZugferdValidationService.java) — Mustang-Validator
|
||||
(XSD + Schematron + veraPDF), liefert Status und XML-Prüfbericht
|
||||
- [InvoiceSigningController](src/main/java/de/assecutor/pdftool/api/InvoiceSigningController.java) — REST-Endpunkte `/sign` und `/validate`
|
||||
- [MainView](src/main/java/de/assecutor/pdftool/ui/MainView.java) — Vaadin-Weboberfläche
|
||||
- [InvoiceMetadata](src/main/java/de/assecutor/pdftool/invoice/InvoiceMetadata.java) — DTO für die Rechnungsdaten
|
||||
|
||||
## Tests
|
||||
|
||||
```bash
|
||||
mvn test
|
||||
```
|
||||
|
||||
[ZugferdServiceTest](src/test/java/de/assecutor/pdftool/zugferd/ZugferdServiceTest.java) 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.
|
||||
Reference in New Issue
Block a user