API-Dokumentation

Eunormia.Sdk — die Offline-.NET-Bibliothek Beta

Dieselbe Engine wie die Online-API, eingebettet in Ihre Anwendung: E-Rechnungen erzeugen, lesen und validieren — komplett offline. Die Java-Engine samt getrimmter Laufzeit steckt im NuGet-Paket; Ihre Rechnungsdaten verlassen Ihr Haus nie.

Beta: Das Paket ist noch nicht auf nuget.org veröffentlicht — Zugang über das Pilotprogramm.

Installation & Voraussetzungen

Installation	`dotnet add package Eunormia.Sdk`
Frameworks	`net8.0` und `netstandard2.0` (damit auch .NET Framework 4.6.1+)
Plattformen	win-x64 (weitere folgen)
Abhängigkeiten	keine — kein Java, kein Docker, kein Netzzugriff
Paketgröße	~130 MB je Plattform (Engine, Fonts, ICC-Profile, Prüfregeln inkl. KoSIT & FR-CTC)

Die drei Klassen

`EunormiaConverter`	erzeugen: JSON (+ optionales PDF) → validiertes ZUGFeRD/Factur-X. Gleiche Gates wie online; optional signiertes Konformitäts-Zertifikat (`EmitCertificate`).
`EunormiaReader`	empfangen: PDF → vollständiges Rechnungs-JSON (gleiches Schema wie beim Erzeugen) + rohes CII-XML.
`EunormiaValidator`	empfangen: PDF → Gate-Ergebnisse (veraPDF, EN 16931, optional `KositValidation`/`FrCtcValidation`).

Performance

UseDaemon = true hält die Engine als warmen Prozess: erster Aufruf ~3–4 s (Kaltstart), danach ~250 ms pro Konvertierung, Lesen ~30 ms. Empfohlen ab mehr als einem Aufruf pro Prozesslebensdauer.

Lizenzierung

Ohne Lizenz ist das SDK voll funktionsfähig — Ergebnisse tragen ein Muster-Wasserzeichen. Eine gültige Lizenz (Konto → POST /v1/license/offline, dann als LicenseKey oder ENV EUNORMIA_LICENSE) schaltet das Wasserzeichen ab. Zwei Typen:

dev	kurzlebig (Standard 45 Tage), für Entwicklung/CI; wird bei aktiver Subscription erneuert.
runtime	langlebig, wird in Ihre ausgelieferte Software eingebettet. Läuft beim Endkunden weiter — auch nach Kündigung. Neue eunormia-Versionen brauchen eine aktive Subscription (Versionsbindung).

Die Prüfung erfolgt offline (Ed25519-Signatur) — kein Phone-Home, keine Telemetrie.

Fehlerbehandlung

Fachliche und technische Fehler kommen als EunormiaException mit Status (422 fachlich), Stage und lokalisierten Details — dieselben verständlichen Meldungen wie die Online-API.

FAQ

Braucht es installiertes Java?	Nein — die Laufzeit ist im Paket gebündelt und für Sie unsichtbar.
Telefoniert das SDK nach Hause?	Nein. Keine Telemetrie, keine Online-Lizenzprüfung.
Was passiert bei Kündigung?	Ausgelieferte Software mit runtime-Lizenz läuft unverändert weiter; nur neue Versionen und Dev-Builds brauchen eine aktive Subscription.
Warum so groß?	Das Paket enthält die komplette Validierungssubstanz: Fonts, Farbprofile, EN-16931-/KoSIT-/FR-CTC-Regelwerke und die Engine. Genau das erspart Ihnen jede Infrastruktur.

Code

// Erzeugen / create
var converter = new EunormiaConverter(new EunormiaOptions {
    LicenseKey = Environment.GetEnvironmentVariable("EUNORMIA_LICENSE"),
    Profile    = ZugferdProfile.EN16931,
    UseDaemon  = true
});
EunormiaResult r = await converter.ConvertAsync(invoiceJson, pdfBytes);
File.WriteAllBytes(r.FileName, r.Pdf);

// Empfangen: lesen / receive: read
ReadResult data = await new EunormiaReader().ReadAsync(incomingPdf);
Console.WriteLine(data.Header?.Number);        // Kurzform / header
var fullJson = data.Invoice;                   // volles InvoiceRequest-JSON

// Empfangen: validieren / receive: validate
var v = await new EunormiaValidator(new EunormiaOptions {
    KositValidation = true, FrCtcValidation = true
}).ValidateAsync(incomingPdf);
Console.WriteLine($"{v.Valid} {v.VeraPdf.Passed} {v.En16931.Passed} {v.Kosit?.Passed}");