Der ZUGFeRD Extractor für docuvita stellt alle technischen Hilfsmittel zur Verfügung, um eingehende E-Rechnungen beim Import in docuvita automatisch auszulesen und auf ihre Konformität zu prüfen. Jede Rechnung wird bereits beim Archivieren gegen die offiziellen Regelwerke der Norm EN 16931 sowie gegen die deutschen Vorgaben (XRechnung-CIUS, § 14 UStG) validiert – noch bevor sie in die Freigabe oder Buchhaltung gelangt. Das Ergebnis dokumentiert ein PDF-Validierungsprotokoll, das alle Befunde, den SHA-256-Wert des geprüften XML und die verwendeten Regelversionen revisionssicher festhält.
Die ausgelesenen Rechnungsdaten stehen als Metadaten am archivierten Objekt zur Verfügung und lassen sich damit für Aktenstrukturen, Suchen, Wiedervorlagen und Workflows nutzen. Rechnungsnummer, Beträge, Verkäufer, Käufer, IBAN und der Validierungsstatus sind unmittelbar nach dem Import abfragbar, sodass sämtliche Informationen bei der digitalen Bearbeitung dokumentenbasierter Geschäftsprozesse bereitstehen.
Unterstützt werden ZUGFeRD / Factur-X (hybride PDF/A-3 mit eingebettetem XML sowie reines CII-XML) und XRechnung in beiden Syntaxen (CII und UBL).
Der ZUGFeRD Extractor ist ein Plugin der docuvita DocumentServices und wird automatisch geladen, sobald die DLL im Extractors-Verzeichnis liegt. Es übernimmt die Dateiendungen PDF und XML.
Eingangsdokument (PDF oder XML)
│
├─ keine gültige Lizenz / Objekttyp nicht freigegeben ──► weiterreichen wie „sonstiges PDF/XML"
│
├─ E-Rechnung erkannt ──► XML aus PDF/A-3 lösen ──► Format & Profil erkennen
│ ──► Daten auslesen (Z_-Felder)
│ ──► Prüfkette: XSD ► Schematron ► § 14 UStG ► eigene Prüfungen ► Rechnerische Prüfung
│ ──► PDF-Protokoll + Metadaten-Rückschreibung
│
├─ sonstiges PDF ─────────► unverändert an die eingebaute PDF-Auslese (inkl. OCR)
│
└─ sonstiges XML ─────────► Textauslese
| Eingang | Verhalten |
|---|---|
| Hybride PDF/A-3 mit eingebettetem Rechnungs-XML | Volle Prüfkette, Protokoll, Metadaten |
| Reines ZUGFeRD-/Factur-X-CII-XML | Volle Prüfkette, Protokoll, Metadaten; die Vorschau zeigt zusätzlich eine aus dem XML erzeugte Rechnungsansicht |
| XRechnung (CII oder UBL) | Volle Prüfkette inkl. XRechnung-CIUS, Protokoll, Metadaten, Rechnungsansicht |
| PDF ohne eingebettetes Rechnungs-XML | Wird 1:1 an die eingebaute PDF-Auslese übergeben (Volltext, OCR) |
| Sonstiges XML | Textauslese, ohne Prüfung |
Objekt eines nicht freigegebenen Objekttyps (nur mit EInvoiceFilter.ObjectTypes) |
Keine Prüfung; PDF unverändert an die eingebaute PDF-Auslese, XML nur als Text |
Der Dokumentenlauf bleibt immer unberührt
Weil das Plugin die Endungen PDF und XML hält, reicht es alles Fremde weiter. Auch bei fehlender Lizenz, einem nicht freigegebenen Objekttyp, fehlenden Regelwerken oder einem Prüffehler wird das Dokument normal archiviert – es entfällt lediglich die Prüfung, und der Grund steht im Log.
Installiert wird mit dem Installationspaket ZUGFeRDValidatorExtractor-Setup.msi. Es enthält das Plugin, die mitgelieferten Programmbibliotheken, die Regelwerke und Schemata (Validators\) und den Prüfläufer. Die Kundenlizenz ist nicht enthalten und wird danach von Hand abgelegt (siehe Lizenz).
Das MSI als Administrator auf dem docuvita-Server ausführen. Unbeaufsichtigt geht es auch per Befehlszeile:
msiexec /i ZUGFeRDValidatorExtractor-Setup.msi /qn
| Thema | Verhalten |
|---|---|
| Zielordner | wird aus der docuvita-Installation ermittelt (…\docuvita.DocumentServices\Extractors\) und lässt sich im Dialog ändern; unbeaufsichtigt mit INSTALLFOLDER="…\Extractors\" |
Dienst docuvita.DocumentServices |
wird vor dem Kopieren gestoppt und danach nur dann wieder gestartet, wenn er vorher lief |
Konfigurationsdatei ZUGFeRDValidatorExtractor.dll.config |
wird bei der Erstinstallation angelegt, danach nie überschrieben und auch bei der Deinstallation nicht entfernt – Ihre Einträge (API-Schlüssel, Objekttyp) bleiben erhalten |
Kundenlizenz *.lic, Aktivierungsschlüssel |
nicht enthalten, werden nie angefasst |
| Zonenmarkierung | aus dem MSI installierte Dateien sind nicht gesperrt, das Entsperren entfällt |
| Update | neues MSI einfach darüber installieren, auch bei gleicher Versionsnummer |
| Voraussetzungen | die Installation bricht mit einer Meldung ab, wenn docuvita Server 2.0 oder die .NET 8 Runtime (x64) fehlt |
Nach einem Update die Konfiguration prüfen
Weil die vorhandeneZUGFeRDValidatorExtractor.dll.configerhalten bleibt, kommen neue Einstellungen einer neuen Version nicht automatisch hinein – für sie gilt die eingebaute Vorgabe. Umgekehrt bleiben entfallene Einstellungen stehen; das Log meldet sie beim Start alsWARN„Konfigurationsschlüssel ohne Wirkung". Auch die*VersionLabel-Werte (siehe Regel-Update) passt das MSI nicht an.
Alle Bestandteile gehören in den Extractors-Ordner der DocumentServices; bis auf die Kundenlizenz legt das MSI sie dort ab:
C:\Program Files (x86)\docuvita\docuvita Server 2.0\docuvita.DocumentServices\Extractors\
| Bestandteil | Inhalt |
|---|---|
ZUGFeRDValidatorExtractor.dll |
Das Plugin selbst |
ZUGFeRDValidatorExtractor.dll.config |
Die Konfiguration (Pfade, Labels, API-Schlüssel) – wird nur angelegt, wenn sie fehlt |
ZUGFeRDValidatorExtractor.pdb |
Optional – liefert Stacktraces im Log |
fd.Licensing.dll, Licensing.Net.dll |
Lizenzprüfung – bei manueller Ablage entsperren, siehe Abschnitt Lizenz |
ZUGFeRDValidator.ltpl |
Lizenzvorlage (nur öffentlicher Schlüssel), wird mitgeliefert |
XXXXX-XXXXX-…-XXXXX.lic |
Ihre Kundenlizenz – Dateiname nicht ändern |
| Mitgelieferte Programmbibliotheken | Rechnungs-Auslese, PDF-Textauslese, Seitenrendering, PDF-Erzeugung |
Validators\ |
Regelwerke, Schemata und der Prüfläufer (siehe unten) |
Validators\)Unter Validators\ liegen die Regelwerke und der Prüfläufer. Ohne sie laufen nur die im Plugin eingebauten Prüfungen (Strukturprüfung, § 14 UStG, eigene Prüfungen, Rechnerische Prüfung) – XSD- und Schematron-Ebene entfallen, was das Protokoll ausweist.
| Ordner | Inhalt | Umfang |
|---|---|---|
Validators\Schematron\ |
Vorkompilierte Regelwerke: EN16931 (CII/UBL), XRechnung-CIUS (CII/UBL), Factur-X MINIMUM / BASIC-WL / EXTENDED – jeweils mit Begleitdatei *_codedb.xml |
10 Dateien |
Validators\Schemas\ |
XSD-Schemata: Factur-X (je Profil), generisches CII, UBL (maindoc\ + common\) |
ca. 170 Dateien |
Validators\SchematronRunner\ |
Der Prüfläufer ZUGFeRD.SchematronRunner.exe samt Laufzeit |
87 Dateien, ca. 81 MB |
Begleitdateien müssen neben ihrem Regelwerk liegen
JedeFACTUR-X_*.xsltlädt ihre Codelisten aus der DateiFACTUR-X_*_codedb.xmlrelativ zu sich selbst. Fehlt die Begleitdatei, meldet das ProtokollSCHEMATRON_ERROR– die Prüfung wird also nicht stillschweigend übersprungen, sondern schlägt sichtbar fehl.
Ebenso muss der OrdnerSchemas\UBL\common\vollständig vorliegen: fehlt eine Datei der Schemakette, lässt sich der gesamte UBL-Schemasatz nicht laden und die XSD-Ebene entfällt (im Protokoll alsXSD_LOAD_ERRORsichtbar).
Das MSI startet den Dienst docuvita.DocumentServices selbst wieder, wenn er vor der Installation lief; ein gestoppter Dienst bleibt gestoppt und wird von Hand gestartet. Wer die Dateien ausnahmsweise von Hand kopiert, stoppt den Dienst vorher (er sperrt die Plugin-DLL) und startet ihn danach. Ob das Plugin geladen wurde, zeigt das Log:
| Log-Stufe | Zeile |
|---|---|
DEBUG |
EInvoiceExtractor initialisiert (Plugin geladen). – erscheint nur, wenn das Log auf DEBUG steht |
INFO |
beim ersten verarbeiteten Dokument: ZUGFeRD/XRechnung-Validator aktiv für '<Datei>' … bzw. bei einem gewöhnlichen PDF … kein ZUGFeRD/XRechnung erkannt … → KEIN Protokoll, Delegation an eingebauten PdfExtractor. |
Altbestände entfernen
Ältere DateienEInvoiceExtractor.*entfernt das MSI selbst;ZUGFeRDExtractorValidator.*bitte von Hand aus dem Extractors-Ordner entfernen. Zwei Plugins für dieselbe Dateiendung führen zu unvorhersehbarem Verhalten, weil pro Endung nur genau eines zum Zug kommt.
Das Plugin arbeitet nur mit gültiger Lizenz. In den Extractors-Ordner gehören genau zwei Lizenzbestandteile:
| Datei | Herkunft | Hinweis |
|---|---|---|
ZUGFeRDValidator.ltpl |
wird mitgeliefert | Lizenzvorlage, enthält nur den öffentlichen Schlüssel |
XXXXX-XXXXX-…-XXXXX.lic |
erhalten Sie von uns je Kunde | Dateiname ist der Lizenzschlüssel – nicht umbenennen, Inhalt nicht ändern |
Es darf genau eine .lic-Datei im Ordner liegen; bei mehreren wählt das Plugin bewusst keine aus und meldet Mehrere Lizenzdateien wurden in '…' gefunden als ERROR.
Windows-Zonenmarkierung entsperren (nur bei manueller Ablage)
Mit dem MSI installierte Dateien sind nicht markiert. Kommenfd.Licensing.dllundLicensing.Net.dlldagegen per E-Mail oder Download und werden von Hand kopiert, sind sie von Windows markiert und dadurch nicht ladbar. Das Log zeigt dann eineFileLoadException 0x80131515– das sieht wie ein Programmfehler aus, ist aber keiner:Get-ChildItem "${env:ProgramFiles(x86)}\docuvita\docuvita Server 2.0\docuvita.DocumentServices\Extractors\*.dll" | Unblock-File
| Thema | Verhalten |
|---|---|
| Erste Prüfung | geht online (Aktivierung); danach liegt der Aktivierungsschlüssel lokal neben der Plugin-DLL unter …\Extractors\ZUGFeRDValidator_Activation.key (Dienstkonto braucht dort Schreibrecht) und die Prüfung läuft aus dem Zwischenspeicher |
| Verlängerung | neue .lic in den Ordner legen, alte entfernen – kein Dienst-Neustart nötig, die Änderung wird selbstständig erkannt |
| Lizenztausch | wird ein anderer Lizenzschlüssel eingelegt, verwirft das Plugin den gespeicherten Aktivierungsschlüssel selbst und aktiviert neu |
| Serverumzug / Hardwaretausch | …\Extractors\ZUGFeRDValidator_Activation.key löschen; meldet das Log weiterhin Lizenz ungültig: …, bei uns eine neu ausgestellte Lizenz anfordern |
| Ohne gültige Lizenz | keine Prüfung, kein Protokoll, keine Metadaten – je Datei ERROR-Zeilen im Log (Lizenz ungültig: … und Lizenz: '<Datei>' wird NICHT geprüft …). Das Dokument wird trotzdem normal archiviert (PDF über die eingebaute Auslese inkl. OCR, XML als Text) |
Keine Konfigurationsschlüssel für die Lizenz
Vorlage und Lizenzdatei liegen neben der Plugin-DLL, der Lizenzschlüssel ist der Dateiname der*.lic, auch der Aktivierungsschlüssel (ZUGFeRDValidator_Activation.key) liegt dort. In der Konfigurationsdatei gibt es dafür bewusst keine Einträge.
Schnellprüfung am Server:
$e = 'C:\Program Files (x86)\docuvita\docuvita Server 2.0\docuvita.DocumentServices\Extractors'
Get-ChildItem $e -Filter *.lic; Get-ChildItem $e -Filter *.ltpl # genau je eine Datei erwartet
Get-Content "$e\ZUGFeRDValidator_Activation.key" -ErrorAction SilentlyContinue
Konfiguriert wird über die Datei ZUGFeRDValidatorExtractor.dll.config im Extractors-Ordner.
Vorkonfiguriert ausgeliefert
Alle Pfade sind bereits auf die Standard-Ablage unterValidators\eingestellt. In der Regel müssen Sie nur den API-Schlüssel (EInvoiceDocuvita.SessionGuid), die Adresse (EInvoiceDocuvita.BaseUrl) und den Objekttyp (EInvoiceFilter.ObjectTypes,EInvoiceMetadata.ObjectTypeInternalName) eintragen.
Die Spalte Standard nennt den Wert der ausgelieferten Konfigurationsdatei. Fehlt ein Schlüssel ganz, gilt die eingebaute Vorgabe; wo sie abweicht, ist sie in der Beschreibung genannt.
Pfadauflösung: Relative Pfade werden gegen das Plugin-Verzeichnis aufgelöst, also gegen …\Extractors\. Absolute Pfade bleiben unverändert – die Prüfartefakte dürfen damit auch auf einem anderen Laufwerk liegen, solange das Dienstkonto dort Lesen/Ausführen darf.
Unbekannte Schlüssel: Ein Schlüssel ohne passende Einstellung wird als WARN gemeldet (Konfigurationsschlüssel ohne Wirkung (keine passende Einstellung): … – Tippfehler oder Überrest?). Tippfehler und Überreste alter Versionen fallen so auf, statt unbemerkt zu verschwinden. Ebenso als WARN gemeldet werden Werte, die sich nicht lesen lassen oder außerhalb des zulässigen Bereichs liegen – dann gilt die eingebaute Vorgabe.
EInvoiceValidator.*)| Schlüssel | Beschreibung | Standard |
|---|---|---|
SchematronRunnerExe |
Pfad zum Prüfläufer. Ist er gesetzt, hat er Vorrang vor SchematronRunnerDll |
Validators\SchematronRunner\ZUGFeRD.SchematronRunner.exe |
DotnetExecutable |
Programm, mit dem die Läufer-DLL gestartet wird (nur mit SchematronRunnerDll) |
dotnet |
SchematronRunnerDll |
Alternativ zur EXE: Pfad zur Läufer-DLL, wird mit DotnetExecutable gestartet. Wirkt nur, wenn SchematronRunnerExe leer ist |
leer |
CiiXsdPath |
Generisches CII-Schema (Einstieg für XRechnung-CII) | Validators\Schemas\CII\CrossIndustryInvoice_100pD22B.xsd |
FacturXMinimumXsdPath, FacturXBasicWlXsdPath, FacturXBasicXsdPath, FacturXEn16931XsdPath, FacturXExtendedXsdPath |
Profil-eigene Factur-X-Schemata | Validators\Schemas\FacturX\… |
UblInvoiceXsdPath, UblCreditNoteXsdPath |
UBL-Schemata für Rechnung und Gutschrift | Validators\Schemas\UBL\maindoc\… |
En16931CiiXsltPath, En16931UblXsltPath |
EN16931-Regelwerke | Validators\Schematron\EN16931-…-validation.xslt |
XRechnungCiiXsltPath, XRechnungUblXsltPath |
XRechnung-CIUS-Regelwerke | Validators\Schematron\XRechnung-…-validation.xslt |
FacturXExtendedCiiXsltPath, FacturXMinimumCiiXsltPath, FacturXBasicWlCiiXsltPath |
Profil-eigene Factur-X-Regelwerke | Validators\Schematron\FACTUR-X_….xslt |
En16931VersionLabel, XRechnungVersionLabel, FacturXExtendedVersionLabel, FacturXMinimumVersionLabel, FacturXBasicWlVersionLabel |
Versionsbezeichnungen der Regelwerke – erscheinen im PDF-Protokoll. Ohne Eintrag steht dort configured |
z. B. EN16931 1.3.16, XRechnung 3.0.2 / CIUS-Schematron 2.5.0 |
XRechnungRulesVersion |
Regelstand (Major.Minor), gegen den die im Dokument angegebene XRechnung-Version geprüft wird. Weicht sie ab, sind die Befunde des XRechnung-CIUS nur Warnungen (XRECHNUNG-VERSION-MISMATCH) |
3.0 |
TimeoutSeconds |
Zeitlimit für einen Prüflauf. Zulässig 5–300 | 60 |
MaxXmlCharacters |
Obergrenze des Rechnungs-XML in Zeichen (nicht Bytes); 0 = unbegrenzt. Riegel gegen XML-Bomben |
10485760 |
Versionsbezeichnungen mitpflegen
Die*VersionLabel-Werte werden nicht aus den Dateien ermittelt, sondern so übernommen, wie sie hier stehen. Nach einem Regel-Update die Labels mit anpassen – sie sind der Nachweis im Protokoll, gegen welchen Regelstand geprüft wurde.
EInvoiceDocuvita.*)Dies ist die einzige Stelle für Adresse, Anmeldung und Zeitlimit. Der Zugang wird für die Metadaten-Rückschreibung über REST und für den Objekttyp-Filter benötigt.
| Schlüssel | Beschreibung | Standard |
|---|---|---|
BaseUrl |
URL zu Ihrem docuvita-System (ohne Eintrag: leer) | https://localhost:443/server |
SessionGuid |
GUID des API-Benutzers (API-Schlüssel) | leer |
TimeoutSeconds |
Zeitlimit für die Anfragen. Zulässig 5–300 | 60 |
API-Benutzer
Die Anmeldung erfolgt ausschließlich über dieSessionGuid; Benutzername und Kennwort gibt es nicht. Stellen Sie sicher, dass der API-Benutzer die Objekte des konfigurierten Objekttyps bearbeiten darf.
Hier erfahren Sie, wie Sie einen API-Benutzer anlegen.
Der API-Schlüssel steht im Klartext
DieSessionGuidgehört nur in dieZUGFeRDValidatorExtractor.dll.configauf dem Server. Ohne sie unterbleibt die Metadaten-Rückschreibung über REST – mit einerERROR-Meldung im Log –, und ein gesetzter Objekttyp-Filter kann den Typ nicht prüfen (siehe unten). Meldet docuvita HTTP 401/403, weist das Log auf dieSessionGuidhin.
EInvoiceFilter.*)Die DocumentServices übergeben dem Plugin nur die ObjectId, nicht den Objekttyp. Soll nur ein bestimmter Objekttyp geprüft werden, fragt das Plugin den Typ je Dokument über die REST-Schnittstelle ab (getobjectproperties, Felder OBJ_OBJECTTYPE / OBJ_OBJECTTYPENAME).
| Schlüssel | Beschreibung | Standard |
|---|---|---|
ObjectTypes |
Zu prüfende Objekttypen als ID oder interner Name, mehrere durch ; (oder ,) getrennt. Zahlen werden mit der Typ-ID verglichen, Text mit dem internen Namen (Groß-/Kleinschreibung egal). Leer = alle Objekttypen, dann entfällt die Abfrage (auch die eingebaute Vorgabe ist leer) |
ZUGFeRD |
| Lage | Verhalten | Log |
|---|---|---|
| Einstellung leer | Jedes Dokument wird geprüft, keine zusätzliche Abfrage | – |
| Typ passt | Dokument wird geprüft | DEBUG |
| Typ passt nicht | keine Prüfung, kein Protokoll, keine Z_-Felder; PDF unverändert an die eingebaute PDF-Auslese, XML nur als Text | ERROR Objekttyp-Filter: … nicht in EInvoiceFilter.ObjectTypes … |
| Typ nicht ermittelbar (keine ObjectId, REST-Fehler, Felder fehlen in der Antwort) | wie „Typ passt nicht" | ERROR |
EInvoiceDocuvita.BaseUrl oder SessionGuid fehlt |
Typ nicht prüfbar → Dokument wird geprüft | WARN |
Ein zusätzlicher REST-Aufruf je Dokument
Ist der Filter gesetzt, wird er für jedes PDF und XML abgefragt – auch für gewöhnliche PDFs ohne Rechnungs-XML, und bevor feststeht, ob es eine E-Rechnung ist. Dokumente anderer Objekttypen erzeugen deshalb je eineERROR-Zeile im Log, obwohl sie ordnungsgemäß archiviert werden.
EInvoiceReport.*)| Schlüssel | Beschreibung | Werte | Standard |
|---|---|---|---|
Delivery |
Auslieferung des PDF-Protokolls. Unbekannte Werte gelten als Preview |
Preview = Vorschau zeigt Rechnung und Protokoll · None = kein Protokoll, die Vorschau zeigt das unveränderte Original |
Preview |
Language |
Sprache der Befundtexte im Protokoll. Ohne Eintrag oder bei unbekanntem Wert: both |
de · en · both |
de |
VisualizeXml |
Bei XML-Eingang der Vorschau eine aus dem XML erzeugte Rechnungsansicht voranstellen (nur mit Delivery=Preview) |
true · false |
true |
Der Download bleibt immer das Original
BeiPreviewwird das Protokoll nur an die Vorschau angehängt: Der Benutzer sieht in docuvita die Rechnungsseiten samt Protokollseiten, lädt aber unverändert das Originaldokument herunter. Das archivierte Primärdokument wird nicht verändert.
Bei reinem XML gibt es keine Rechnungsseiten; mitVisualizeXml=trueerzeugt das Plugin eine lesbare Rechnungsansicht (Kopfdaten, Positionen, Summen, Steueraufstellung, Zahlung) und stellt sie dem Protokoll voran. Sie trägt den Hinweis, dass rechtlich das XML maßgeblich ist.
EInvoiceMetadata.*)Schreibt die ausgelesenen Rechnungsdaten in die Felder des bereits importierten Objekts.
| Schlüssel | Beschreibung | Standard |
|---|---|---|
Mode |
Weg der Rückschreibung: off = keine Rückschreibung; both = dvImport, ohne vorhandenen AutoProfiler-Ordner REST; dvImport = nur dvImport (fehlt der Ordner, ERROR und keine Rückschreibung); REST = nur REST, auch wenn der Ordner vorhanden ist. Groß-/Kleinschreibung egal; ohne Eintrag oder bei unbekanntem Wert: both |
both |
DvImportFolder |
Quellordner des AutoProfilers. Ist der Ordner gesetzt und vorhanden, wird (außer bei Mode=REST) eine dvImport-Datei dort abgelegt; andernfalls erfolgt die Rückschreibung bei Mode=both über die REST-Schnittstelle (EInvoiceDocuvita.*) |
D:\docuvita\AutoProfiler\docuBaum\in |
ObjectTypeInternalName |
Interner Name des Objekttyps, der in der dvImport-Datei angegeben wird (nur dvImport; über REST wird das vorhandene Objekt direkt aktualisiert) | ZUGFeRD |
| Weg | Verhalten bei fehlenden Feldern | Log |
|---|---|---|
| dvImport | docuvita meldet beim Import einen Fehler für jedes referenzierte Feld, das der Objekttyp nicht hat | DEBUG bei Erfolg, ERROR wenn die Datei nicht geschrieben werden kann |
| REST | Felder, die das Objekt nicht hat oder die schreibgeschützt sind, werden übersprungen; ebenso ein Feld, zu dessen Feldtyp der Wert nicht passt | DEBUG mit „n von m Feldern" bzw. je übersprungenem Feld; WARN, wenn kein Feld geschrieben wurde (Objekttyp ohne Z_-Felder); ERROR bei REST-Fehlern |
Mode=dvImport, Ordner fehlt |
keine Rückschreibung | ERROR „… NICHT durchführbar: EInvoiceMetadata.Mode=dvImport …" |
| keiner von beiden konfiguriert | keine Rückschreibung | ERROR „Metadaten-Rückschreibung … NICHT durchführbar" |
Mode=off |
keine Rückschreibung | – |
Über REST schreibt das Plugin jeden Wert passend zum Feldtyp des Felds: Datumsfelder (DateTime) als Datum, Betragsfelder (Currency) als Betrag, numerische und boolesche Felder als Zahl bzw. Wahrheitswert, alle übrigen als Text. Deshalb die Feldtypen wie unter Objekttyp und Felder anlegen angegeben anlegen.
Umstieg von
EInvoiceMetadata.Enabled
Bis September 2026 hieß der SchalterEInvoiceMetadata.Enabled. Er wirkt nicht mehr – das Log meldet ihn als „Konfigurationsschlüssel ohne Wirkung". Weil das MSI eine vorhandene Konfigurationsdatei nicht überschreibt, die Zeile von Hand ersetzen:Enabled=false→Mode=off,Enabled=true→Mode=both(oder die Zeile löschen). Ebenso können alte EinträgeEInvoiceGenericXml.*gelöscht werden; die Prüfung für gewöhnliches XML gibt es nicht mehr.
Damit die Rückschreibung greift, im Objekttyp – standardmäßig ZUGFeRD – die folgenden Felder mit dem angegebenen Feldtyp anlegen: Datumsfelder als DateTime, Betragsfelder als Currency, alle übrigen als String. Groß-/Kleinschreibung des Feldnamens spielt keine Rolle. Leere Werte werden nicht geschrieben.
Maßgeblich ist die Objekttypdefinition docs/Fielddefinitions_ZUGFeRD.json (Objekttyp ZUGFeRD, ID 10007). Sie enthält zusätzlich die berechneten Anzeigefelder ZF_Status, ZF_14, ZF_check_netto, ZF_check_brutto und ZF_check_zahlbetrag (Autocalc) sowie einen berechneten Objektnamen; diese Felder schreibt das Plugin nicht, docuvita berechnet sie aus den Z_-Feldern. Die ZF_check_*-Felder rechnen mit den Beträgen und setzen deshalb Currency-Felder voraus.
Fehlende Felder erzeugen Fehler
Beim Weg über den AutoProfiler (dvImport) meldet docuvita einen Fehler, wenn ein referenziertes Feld im Objekttyp nicht existiert – es wird nicht still ignoriert. Über REST werden fehlende Felder übersprungen; fehlen alle, steht eineWARN-Zeile im Log. Legen Sie daher am besten alle unten gelisteten Felder an.
| Feldname | Feldtyp | Bedeutung |
|---|---|---|
BT-1_Z_INVOICENO |
String | Rechnungsnummer |
BT-2_Z_INVOICEDATE |
DateTime | Rechnungsdatum |
BT-3_Z_TYPE |
String | Rechnungsart als Klartext (z. B. Rechnung, Gutschrift, Rechnungskorrektur) |
BT-5_Z_CURRENCY |
String | Währung (ISO-Code, z. B. EUR) |
BT-10_Z_BUYERREFERENCE |
String | Leitweg-ID / Käuferreferenz |
BT-13_Z_ORDERNO |
String | Bestellnummer |
BT-12_Z_CONTRACTREFERENCEDDOCUMENT_ID |
String | Vertragsnummer |
BT-72_Z_ACTUALDELIVERYDATE |
DateTime | Lieferdatum |
BT-73_Z_BILLINGPERIODSTART |
DateTime | Abrechnungszeitraum (von) |
BT-74_Z_BILLINGPERIODEND |
DateTime | Abrechnungszeitraum (bis) |
BT-83_Z_PAYMENTREFERENCE |
String | Verwendungszweck |
| Feldname | Feldtyp | Bedeutung |
|---|---|---|
BT-106_Z_LINETOTALAMOUNT |
Currency | Summe aller Positionen (netto) |
BT-108_Z_CHARGETOTALAMOUNT |
Currency | Summe Zuschläge (netto) |
BT-109_Z_TAXBASISAMOUNT |
Currency | Gesamtsumme (netto) |
BT-110_Z_TAXTOTALAMOUNT |
Currency | Summe Umsatzsteuer |
BT-112_Z_GRANDTOTALAMOUNT |
Currency | Gesamtbetrag (brutto) |
BT-113_Z_TOTALPREPAIDAMOUNT |
Currency | Gezahlter Betrag / Anzahlung |
BT-115_Z_DUEPAYABLEAMOUNT |
Currency | Zahlbetrag |
| Feldname | Feldtyp | Bedeutung |
|---|---|---|
BT-27_Z_SELLER_NAME |
String | Verkäufer (Name) |
BT-35_Z_SELLER_STREET |
String | Straße / Hausnummer |
BT-38_Z_SELLER_POSTCODE |
String | PLZ |
BT-37_Z_SELLER_CITY |
String | Ort |
BT-40_Z_SELLER_COUNTRY |
String | Land |
BT-31_Z_SELLERTAXREGISTRATION_0_NO |
String | Umsatzsteuer-ID / Steuernummer |
| Feldname | Feldtyp | Bedeutung |
|---|---|---|
BT-44_Z_BUYER_NAME |
String | Käufer (Name) |
BT-50_Z_BUYER_STREET |
String | Straße / Hausnummer |
BT-53_Z_BUYER_POSTCODE |
String | PLZ |
BT-52_Z_BUYER_CITY |
String | Ort |
BT-55_Z_BUYER_COUNTRY |
String | Land |
BT-48_Z_BUYERTAXREGISTRATION_0_NO |
String | Umsatzsteuer-ID |
| Feldname | Feldtyp | Bedeutung |
|---|---|---|
BT-84_Z_CREDITORBANKACCOUNTS_0_IBAN |
String | IBAN |
BT-86_Z_CREDITORBANKACCOUNTS_0_BIC |
String | BIC |
BT-85_Z_CREDITORBANKACCOUNTS_0_NAME |
String | Kontoinhaber |
BT-81_Z_PAYMENTMEANS_TYPECODE |
String | Zahlungsart (Code) |
BT-9_Z_PAYMENTTERMS_DUEDATE |
DateTime | Fälligkeitsdatum |
BT-89_Z_PAYMENTMEANS_SEPAMANDATEREFERENCE |
String | SEPA-Mandatsreferenz |
BT-90_Z_PAYMENTMEANS_SEPACREDITORIDENTIFIER |
String | SEPA-Gläubiger-ID |
| Feldname | Feldtyp | Bedeutung |
|---|---|---|
Z_PROFILE |
String | Profil, wie die Auslesebibliothek es benennt: Minimum, BasicWL, Basic, Comfort (= EN16931), Extended, XRechnung |
Z_FORMAT |
String | Eingangsweg: ZUGFERD bei PDF mit eingebettetem XML, XRECHNUNG bei reinem XML |
Z_VALIDATION_STATUS |
String | Validierungsstatus (Accepted, AcceptedWithWarnings, Rejected, Unsupported, TechnicalError) |
Z_VALIDATION_ISSUES |
String | Anzahl der Befunde (alle Gewichte) |
Z_VALIDATOR_VERSION |
String | Versionsbezeichnungen der angewandten Regelwerke (nur wenn Schematron lief) |
Z_USTG14_FULFILLED |
String | Erfüllte § 14-Pflichtangaben von den anwendbaren (z. B. 8/8) |
Z_USTG14_MISSING |
String | Fehlende § 14-Nummern (z. B. 2,6), nur wenn etwas fehlt |
BT-1_Z_INVOICENO, BT-2_Z_INVOICEDATE, BT-5_Z_CURRENCY, BT-27_Z_SELLER_NAME, BT-44_Z_BUYER_NAME, BT-31_Z_SELLERTAXREGISTRATION_0_NO, BT-109_Z_TAXBASISAMOUNT, BT-110_Z_TAXTOTALAMOUNT, BT-112_Z_GRANDTOTALAMOUNT, BT-115_Z_DUEPAYABLEAMOUNT, BT-84_Z_CREDITORBANKACCOUNTS_0_IBAN, Z_FORMAT, Z_VALIDATION_STATUS.
Wiederholende Angaben
Geschrieben wird genau dieser feste Satz an Einzelfeldern. Wiederholende Gruppen – Positionen, Steuerzeilen, Notizen, Beleg-Zu- und -Abschläge – werden nicht in Felder geschrieben, weil ihre Anzahl je Rechnung variiert. Sie stehen im Volltext und im Protokoll.
| Ebene | Prüfung | Ausführung |
|---|---|---|
| 0 | Profil-Gate: MINIMUM und BASIC-WL sind keine gültige E-Rechnung nach § 14 UStG | im Prozess |
| 1 | Interne Strukturprüfung: profilabhängige Pflichtfelder | im Prozess, offline |
| 2 | XSD-Schemavalidierung gegen das profilgerechte Schema | im Prozess |
| 3 | Schematron: EN16931 bzw. Factur-X-Profilregeln, bei XRechnung zusätzlich der CIUS | im Prüfläufer |
| 4 | § 14 UStG: Pflichtangaben Nr. 1–10 | im Prozess |
| 5 | Eigene Prüfungen: Leitweg-ID, Prüfziffern (GTIN/GLN/USt-IdNr./IBAN), Plausibilität | im Prozess |
| 6 | Rechnerische Prüfung: Positionsbeträge (BT-131), Summenblock (BT-106 bis BT-115) und USt-Aufschlüsselung (BT-116/BT-117) werden selbst gerechnet, Toleranz 0,03 | im Prozess |
| Profil | XSD (Ebene 2) | Schematron (Ebene 3) |
|---|---|---|
| MINIMUM | Factur-X_1.09_MINIMUM.xsd |
FACTUR-X_MINIMUM.xslt (Ablehnung nach § 14 bleibt) |
| BASIC WL | Factur-X_1.09_BASICWL.xsd |
FACTUR-X_BASIC-WL.xslt (ebenso) |
| BASIC | Factur-X_1.09_BASIC.xsd |
EN16931-CII-validation.xslt |
| EN16931 | Factur-X_1.09_EN16931.xsd |
EN16931-CII-validation.xslt |
| EXTENDED | Factur-X_1.09_EXTENDED.xsd |
FACTUR-X_EXTENDED.xslt |
| XRechnung (CII) | CrossIndustryInvoice_100pD22B.xsd |
EN16931-CII + XRechnung-CII |
| XRechnung (UBL) | UBL-Invoice-2.1.xsd / UBL-CreditNote-2.1.xsd |
EN16931-UBL + XRechnung-UBL |
| Status | Im Protokoll | Bedeutung |
|---|---|---|
Accepted |
Angenommen (EN16931-konform) | Keine Fehler und keine Warnungen (Hinweise sind möglich) – die Rechnung ist konform |
AcceptedWithWarnings |
Angenommen mit Warnungen | Keine Fehler, aber Warnungen; die Rechnung ist konform, enthält aber Auffälligkeiten |
Rejected |
Abgelehnt | Mindestens ein Fehler – die Rechnung ist nicht konform |
Unsupported |
Nicht unterstütztes Format | Das Dokument wurde nicht als XRechnung oder ZUGFeRD erkannt |
TechnicalError |
Technischer Fehler | Die Prüfung konnte nicht vollständig durchlaufen; bereits erhobene Befunde bleiben erhalten |
Die Einordnung der Befunde bestimmt das Ergebnis:
| Befundart | Gewicht | Wirkung |
|---|---|---|
Fehlende § 14-Pflichtangabe (USTG14-ABS4-<Nr.>) |
Fehler | führt zu Rejected |
Als Leitweg-ID deklarierter Wert (schemeID 0204) mit falschem Format oder falscher Prüfziffer (LEITWEG-ID-INVALID) |
Fehler | führt zu Rejected |
Leitweg-ähnlicher Wert in der freien Käuferreferenz BT-10 mit falscher Prüfziffer (LEITWEG-ID-SUSPECT) |
Warnung | ändert das Ergebnis nicht |
Prüfziffer bei GTIN, GLN, USt-IdNr. oder IBAN falsch (GTIN-, GLN-, USTID-, IBAN-PRUEFZIFFER) |
Warnung | ändert das Ergebnis nicht |
XRechnung-Version im Dokument ≠ XRechnungRulesVersion (XRECHNUNG-VERSION-MISMATCH) |
Warnung | die Befunde des XRechnung-CIUS werden zu Warnungen; EN16931-Fehler bleiben Fehler |
ZUGFeRD-1.0-Kennung (BT-24) in einem CII-2.x-Dokument (GUIDELINE-SYNTAX-MISMATCH) |
Warnung | ändert das Ergebnis nicht; Daten werden trotzdem gelesen |
Plausibilität: leere Elemente (LEERES-ELEMENT), Zahlungsmittelcode 30 statt 58 bei IBAN (SEPA-ZAHLUNGSMITTELCODE) |
Hinweis | ändert das Ergebnis nicht |
Rechnerische Prüfung: berechneter Betrag weicht ab (NACHRECHNUNG-BT-…, Toleranz 0,03) |
Fehler | führt zu Rejected |
Rechnerische Prüfung: Positionsbetrag stimmt nur ohne Basismenge BT-149 (NACHRECHNUNG-BT-131) |
Warnung | ändert das Ergebnis nicht |
Eine ausgefallene Prüfebene sieht nie wie „bestanden" aus
Bricht der Prüfläufer ab – Zeitüberschreitung, Fehler im Regelwerk, fehlende Begleitdatei –, meldet das ProtokollSCHEMATRON_ERRORund das Ergebnis istTechnicalError, nie eine Annahme. Eine Ablehnung bleibt dagegen möglich: ein bereits gefundener Fehler bleibt ein Fehler.
Ist ein Regelwerk oder Schema konfiguriert, aber nicht vorhanden, entsteht eine Warnung (*_SKIPPED) mit dem Pfad – das Ergebnis ist dann höchstensAcceptedWithWarnings. Ist eine Ebene gar nicht konfiguriert, steht nur ein Hinweis im Protokoll; eine Annahme ist dann möglich, das Protokoll weist die fehlende Ebene aber aus.
Die ZUGFeRD-Profile MINIMUM und BASIC WL sind nach § 14 UStG keine gültige E-Rechnung, sondern nur Buchungshilfe bzw. Rechnungsdatenbericht. Sie erheben auch selbst keinen EN16931-Anspruch.
Beide Aussagen stehen deshalb im Protokoll nebeneinander: rechtlich abgelehnt, technisch bewertet.
| Aspekt | Verhalten |
|---|---|
| Ergebnis | immer Rejected mit dem Code PROFILE_NOT_EN16931 |
| Geprüft wird | gegen das profil-eigene Factur-X-Regelwerk, damit im Protokoll steht, ob das Dokument als Buchungshilfe technisch korrekt aufgebaut ist |
| EN16931-Regeln | werden nicht angewandt – sie erzeugten auf diesen Profilen nur Fehlerlawinen |
| Abhängigkeit | Die Ablehnung hängt nicht am Ergebnis der technischen Prüfung |
Geprüft werden die Pflichtangaben nach § 14 Abs. 4 Nr. 1–10. Jede Angabe erhält einen von vier Zuständen (Wortlaut und Farbe wie im Protokoll):
| Zustand | Bedeutung |
|---|---|
| erfüllt (grün) | Pflichtangabe vorhanden |
| nicht erfüllt (rot) | Pflichtangabe fehlt oder ist unvollständig → Fehler USTG14-ABS4-<Nr.>, führt zu Rejected |
| n. a. (grau) | im konkreten Fall nicht erforderlich, z. B. bei nicht steuerbarem Umsatz |
| zu prüfen (gelb) | aus dem Dokument nicht automatisch feststellbar → manuelle Sichtung, kein Befund |
Die Überschrift zählt nur die anwendbaren Angaben („§14 UStG – Pflichtangaben (Abs. 4): 8 von 8 erfüllt"); n. a. und zu prüfen bleiben außen vor.
§ 14 kennt keine weichen Pflichtangaben
Jede als nicht erfüllt ausgewiesene Angabe führt zur Ablehnung. Sachliche Ausnahmen stecken nicht in einer abgeschwächten Gewichtung, sondern im Prüfergebnis selbst: Positionen ohne Menge im Kopf-/Summenprofil ergeben zu prüfen, ein nicht steuerbarer Umsatz n. a. Nur nicht erfüllt bedeutet: das Gesetz verlangt es, das Dokument hat es nicht.
Das Plugin rechnet die Beträge aus dem Dokument selbst nach und stellt sie den angegebenen Werten gegenüber: jeden Positionsbetrag (BT-131 = Menge × Einzelpreis / Basismenge − Nachlässe + Zuschläge), den Summenblock (BT-106 bis BT-115) und die USt-Aufschlüsselung (BT-116/BT-117). Die Rundungstoleranz beträgt 0,03 je Prüfpunkt, bei Summen 0,03 je Summand.
| Zustand | Bedeutung |
|---|---|
| erfüllt (grün) | berechneter Wert = Wert im Dokument (im Rahmen der Toleranz) |
| nicht erfüllt (rot) | Abweichung → Fehler NACHRECHNUNG-BT-…, führt zu Rejected |
| zu prüfen (gelb) | Der Positionsbetrag stimmt nur, wenn man die angegebene Basismenge (BT-149) weglässt → Warnung NACHRECHNUNG-BT-131 |
| n. a. (grau) | Wert nicht angegeben oder nicht berechenbar, z. B. Kopf-/Summenprofil ohne Positionen |
Die rechnerischen EN16931-Regeln (BR-CO-10 bis BR-CO-17) prüft zusätzlich das Schematron; die Rechnerische Prüfung greift auch dort, wo kein Schematron rechnet (z. B. MINIMUM, Positionsbeträge).
Jede Validierung erzeugt ein PDF-Protokoll – auch bei Ablehnung oder technischem Fehler, denn gerade dann dokumentiert es die Ursachen. Es enthält:
| Abschnitt | Inhalt |
|---|---|
| Kopf | Titel „E-Rechnungs-Validierungsprotokoll", Erstellzeitpunkt, Validator und Regelversionen |
| Gesamtergebnis | Validierungsstatus im Klartext, farblich hervorgehoben |
| Dokument | Dateiname, Format, Profil, docuvita ObjectId / VersionId, SHA-256 des geprüften XML |
| Rechnungsdaten | Rechnungsnummer, Datum, Verkäufer, Käufer, Währung, Gesamt- und Zahlbetrag |
| Befunde | Überschrift mit der Zählung („1 Fehler, 2 Warnungen, 0 Hinweise"); je Befund Gewicht, Code, Meldung und Fundstelle, nach Gewicht sortiert. Die Meldungen der Regelwerke erscheinen je nach EInvoiceReport.Language deutsch, englisch oder beides |
| § 14 UStG | Die zehn Pflichtangaben mit Status (erfüllt / nicht erfüllt / zu prüfen / n. a.) und Fundstelle |
| Rechnerische Prüfung | Je Prüfpunkt: Rechenweg, berechneter Wert, Wert im Dokument, Abweichung und Status (erfüllt / nicht erfüllt / zu prüfen / n. a.). Rundungstoleranz 0,03 je Prüfpunkt, bei Summen 0,03 je Summand |
Nachvollziehbarkeit
Die Rohausgabe der Schematron-Prüfung wird bewusst nicht aufbewahrt. Den Nachweis trägt das Protokoll selbst: alle Befunde, der SHA-256-Wert des geprüften XML und die Versionsbezeichnungen der verwendeten Regelwerke.
Die Regelwerke werden jährlich aktualisiert. Neue Regelwerke kommen in der Regel mit einem neuen MSI; die Schritte 2 und 3 sind trotzdem nötig, weil das MSI die vorhandene Konfigurationsdatei nicht verändert. Beim Einspielen:
*.xslt samt Begleitdateien *_codedb.xml nach Validators\Schematron\ legen (entfällt mit dem MSI).*VersionLabel-Werte in der Konfiguration auf den neuen Stand setzen.XRechnungRulesVersion anpassen.Diese Codes zeigen keinen Mangel der Rechnung, sondern einen Zustand der Installation:
| Code | Bedeutung |
|---|---|
EXTERNAL_VALIDATION_SKIPPED |
Kein Prüfläufer bzw. keine passenden Regelwerke konfiguriert – es liefen nur XSD und die eingebauten Prüfungen |
XSD_SKIPPED |
Das Schema der XSD-Ebene fehlt oder ist nicht konfiguriert |
EN16931_VALIDATION_SKIPPED, CIUS_VALIDATION_SKIPPED, EXTENDED_VALIDATION_SKIPPED, MINIMUM_VALIDATION_SKIPPED, BASICWL_VALIDATION_SKIPPED |
Das jeweilige Regelwerk fehlt oder ist nicht konfiguriert |
SCHEMATRON_ERROR |
Das Regelwerk ließ sich nicht ausführen oder der Prüfläufer überschritt TimeoutSeconds – häufigste Ursache: die Begleitdatei *_codedb.xml fehlt neben dem XSLT. Ergebnis: TechnicalError |
XSD_LOAD_ERROR |
Der Schemasatz ließ sich nicht laden – häufigste Ursache: der Ordner Schemas\UBL\common\ ist unvollständig |
PDF_WITHOUT_XML |
Die PDF enthält kein eingebettetes Rechnungs-XML |
XML_NOT_WELL_FORMED |
Das XML ist nicht wohlgeformt |
PROFILE_NOT_EN16931 |
Profil MINIMUM oder BASIC WL – keine gültige E-Rechnung nach § 14 UStG |
Die *_SKIPPED-Codes sind ein Hinweis, wenn nichts konfiguriert ist, und eine Warnung mit dem Pfad, wenn der konfigurierte Pfad nicht existiert.
Das Log enthält dieselbe Information wie das Protokoll:
| Lage | Log-Stufe |
|---|---|
Abschlusszeile ZUGFeRD/XRechnung-Validator fertig für '<Datei>' (ObjectId=…): Gesamtergebnis …, Befunde: n Fehler, n Warnungen, n Hinweise |
INFO; bei Rejected WARN |
Prüfung nicht möglich (TechnicalError, Unsupported, Ausnahme) – '<Datei>' konnte NICHT validiert werden |
ERROR |
je Befund eine Zeile Befund <Gewicht> in '<Datei>' (ObjectId=…): <Code> – <Text> (Fundstelle: …), höchstens 50, danach ein Hinweis auf das Protokoll |
Fatal ERROR, Fehler/Warnung WARN, Hinweis INFO |
| Datenauslese hat das Dokument umgedeutet (z. B. ZUGFeRD-1.0-Kennung in CII-2.x) | WARN |
| Thema | Anforderung |
|---|---|
| Dateinamen | Unverändert lassen – die Konfiguration verweist namentlich darauf |
| Temporäres Verzeichnis | Das Dienstkonto braucht ein beschreibbares %TEMP%; die Prüfausgabe wird dort abgelegt und wieder gelöscht |
| Rechte | Das Dienstkonto braucht Lesen/Ausführen auf Validators\ und Schreibrecht im Extractors-Ordner (Aktivierungsschlüssel, siehe Lizenz) |
| Laufzeit | .NET 8 Runtime (x64) muss auf der Maschine vorhanden sein; der Prüfläufer bringt sie nicht mit |
| Netzwerk | Bei gesetztem EInvoiceFilter.ObjectTypes oder REST-Rückschreibung muss EInvoiceDocuvita.BaseUrl vom Dienst aus erreichbar sein |



| Version | Anmerkung |
|---|---|
| 26.10.20 | /server wird nicht mehr fest an docuvita URL geschrieben |
| 26.10.05 | Hex definierte Anhänge in ZUGFeRD werden zuverlässig erkannt |
| 26.10.01 | Bugfix Update Metadaten per REST |
| 26.9.29 | Initiales Release |