Documentazione API

Eunormia.Sdk — la libreria .NET offline Beta

Lo stesso motore dell'API online, incorporato nella tua applicazione: creare, leggere e convalidare fatture elettroniche — completamente offline. Il motore e un runtime ridotto sono inclusi nel pacchetto NuGet; i tuoi dati di fatturazione non lasciano mai la tua azienda.

Beta: il pacchetto non è ancora pubblicato su nuget.org — accesso tramite il programma pilota.

Installazione & requisiti

Installazione	dotnet add package Eunormia.Sdk
Framework	net8.0 e netstandard2.0 (quindi anche .NET Framework 4.6.1+)
Piattaforme	win-x64 (altre in arrivo)
Dipendenze	nessuna — niente Java, niente Docker, nessun accesso di rete
Dimensione	~130 MB per piattaforma (motore, font, profili ICC, regolamenti incl. KoSIT & FR-CTC)

Le tre classi

EunormiaConverter	creare: JSON (+ PDF opzionale) → ZUGFeRD/Factur-X convalidato. Stessi gate dell'online; certificato di conformità firmato opzionale (EmitCertificate).
EunormiaReader	ricevere: PDF → JSON di fattura completo (stesso schema della creazione) + XML CII grezzo.
EunormiaValidator	ricevere: PDF → risultati dei gate (veraPDF, EN 16931, opzionalmente KositValidation/FrCtcValidation).

Prestazioni

UseDaemon = true mantiene il motore come processo caldo: prima chiamata ~3–4 s (avvio a freddo), poi ~250 ms per conversione, lettura ~30 ms.

Licenza

Senza licenza l'SDK è pienamente funzionante — i risultati portano una filigrana campione. Una licenza valida (account → POST /v1/license/offline, poi come LicenseKey o ENV EUNORMIA_LICENSE) rimuove la filigrana. Due tipi:

dev	breve durata (45 giorni di default), per sviluppo/CI; rinnovata finché l'abbonamento è attivo.
runtime	lunga durata, incorporata nel software che consegni. Continua a funzionare presso i tuoi clienti — anche dopo la disdetta. Le nuove versioni di eunormia richiedono un abbonamento attivo.

La verifica è offline (firma Ed25519) — nessun phone-home, nessuna telemetria.

Gestione degli errori

Gli errori di merito e tecnici arrivano come EunormiaException con Status (422 per il merito), Stage e Details localizzati — gli stessi messaggi comprensibili dell'API online.

FAQ

Serve Java installato?	No — il runtime è incluso nel pacchetto e invisibile per te.
L'SDK telefona a casa?	No. Nessuna telemetria, nessuna verifica di licenza online.
Cosa succede in caso di disdetta?	Il software consegnato con licenza runtime continua a funzionare; solo le nuove versioni e i build di sviluppo richiedono un abbonamento attivo.
Perché così grande?	Il pacchetto contiene tutta la sostanza di convalida: font, profili colore, regolamenti EN 16931/KoSIT/FR-CTC e il motore. È esattamente ciò che ti risparmia ogni infrastruttura.

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}");