ZUGFeRD ist das Akronym für “Zentraler User Guide des Forums elektronische Rechnung Deutschland”. Außerdem ist es ein elektronisches Rechnungsdatenformat für den Austausch von Rechnungen und damit ein Lösungsansatz für die Frage, wie man die Daten einer Rechnung auf einfache Weise für die Durchführung der Überweisung des berechneten Betrags verarbeiten kann. Genau genommen nutzt man hier eine Kombination aus einem auf spezielle Weise hergestellten PDF-Dokuments und eines XML-Dokuments, das die in der Rechnung enthaltenen Daten einmal optimiert für das menschliche Auge und einmal optimiert für die Datenverarbeitung enthält. In diesem ersten Teil einer kleinen Beitragsreihe zeigen wir, wie Sie die Open Source-Bibliothek von Konik in einer .NET-Lösung nutzen, um daraus eine DLL für den Zugriff auf Access heraus zu erstellen.
ZUGFeRD-Basics
Grundidee hinter ZUGFeRD ist es, ein einheitliches Format für den Austausch von Rechnungsdaten zu schaffen, das sowohl vom Menschen als auch vom Computer optimal gelesen werden kann.
Die üblichen Rechnungen sind durchaus so strukturiert, dass der Mensch die Daten für die zu tätigende Überweisung entnehmen kann – wenngleich hier eine weitere Vereinheitlichung bezüglich der Position der verschiedenen Informationen wünschenswert wäre.
Wenn Sie die Rechnung computergestützt verarbeiten wollen, wird es ohne Standardisierung umso schwieriger – Algorithmen brauchen halt genaue Informationen, wo sie was einlesen sollen, damit sie ihre Arbeit fehlerfrei verrichten. Das ist bei gedruckten und eingescannten Rechnungen oder auch bei Rechnungen im PDF-Format nicht zuverlässig möglich.
Also haben sich die Menschen hinter FeRD, dem Forum elektronische Rechnung Deutschland, etwas ausgedacht: Sie verwenden ein spezielles PDF-Format, nämlich das Format PDF/A-3, mit dem ein PDF-Dokument, das mit herkömmlichen PDF-Readern angezeigt werden kann, um ein XML-Dokument erweitert werden kann. Dieses enthält die gleichen Daten, die auch schon im PDF-Dokument angezeigt werden, nochmal im XML-Format – also in einem Format, das von Computern besser verarbeitet werden kann als ein einfaches PDF-Format.
Die Konik-Bibliothek
Die Firma Konik bietet unter https://konik.io/ eine Open Source-Bibliothek für Java und .NET an. Als Access-Entwickler schauen wir erstmal wieder in die Röhre, denn es gibt keine direkte Möglichkeit für uns, direkt auf die Bibliothek zuzugreifen. Wir müssen uns also selbst eine DLL bauen, welche diese Bibliothek nutzt, und auf diese von Access aus zugreifen. Wir werden dies aber in diesem Teil der Beitragsreihe und in den folgenden Teilen detailliert darstellen.
ZUGFeRD-Versionen
Es gibt verschiedene Versionen von ZUGFeRD. Die erste Version 1.0 stammt von 2014. Das ist die Version, die wir im vorliegenden Beitrag beschreiben.
Die neueste Version 2.01 liegt zum Zeitpunkt der Erstellung dieses Beitrags noch nicht in Form einer Open Source-Bibliothek vor.
Visual Studio installieren
Wenn Sie nicht bereits Visual Studio installiert haben, sollten Sie dies nachholen, sofern Sie die Beispiele dieses Beitrags nachvollziehen wollen. Sie können aber auch die hier erstellte DLL von Access aus verwenden.
Visual Studio können Sie in der aktuellen Version zumindest für private Zwecke und Testzwecke in der Community Edition kostenlos herunterladen und nutzen (weitere Informationen hierzu erhalten Sie in den jeweiligen Lizenzbedingungen).
Visual Studio als Administrator starten
Da die DLL nicht nur erstellt, sondern auch registriert werden muss, benötigen Sie später Administratorrechte. Daher starten Sie Visual Studio gleich mit diesen Rechten.
Dazu klicken Sie mit der rechten Maustaste auf den Eintrag für Visual Studio und wählen dort den Befehl Als Administrator öffnen aus. Dass Visual Studio mit Administratorrechten gestartet wurde, erkennen Sie daran, dass in der Titelzeile Administrator in Klammern ausgegeben wird.
DLL erstellen
Um eine geeignete DLL zu erstellen, öffnen Sie mit dem Menüpunkt Datei|Neu|Projekt… den Dialog Neues Projekt. Hier wählen Sie den Namen und den Speicherort des zu erstellenden Projekts aus.
Am wichtigsten ist jedoch die Wahl des richtigen Projekttyps, in diesem Fall Visual Basic|Windows Desktop|Klassenbibliothek (.NET Framework). Vor dem Erstellen des Projekts sieht der Dialog wie in Bild 1 aus.
Bild 1: Anlegen der Klassenbibliothek in Visual Studio
Vorbereitungen der DLL
Als Erstes benennen wir die automatisch hinzugefügte Klasse Class1 um, und zwar in ZUGFeRD_NET. Das erledigen Sie, indem Sie den entsprechenden Eintrag im Projektmappen-Explorer von Visual Studio ändern.
Wenn Sie das tun, fragt Visual Studio automatisch, ob Sie auch Verweise auf das Codeelement Class1 umbenennen wollen, was Sie bejahen sollten. Dadurch wird auch die Klasse entsprechend umbenannt:
Public Class ZUGFeRD_NET End Class
Danach erweitern wir den Inhalt der Datei ZUGFeRD_NET.vb wie folgt um einen Verweis auf den Namespace System.Runtime.InteropServices und einer Zusatzinformation:
Imports System.Runtime.InteropServices <ClassInterface(ClassInterfaceType.AutoDual)> Public Class ZUGFeRD_NET End Class
Sichtbarmachen der Klassen und Methoden
Damit wir die Klasse und die nachfolgend definierten Methoden im VBA-Editor finden können, müssen wir noch weitere Schritte durchführen.
Dazu klicken Sie doppelt auf den Eintrag My Project im Projektmappen-Explorer und zeigen so die Eigenschaften des Projekts an.
Hier wechseln Sie zum Bereich Anwendung, sofern dieser noch nicht angezeigt wird, und klicken dort auf die Schaltfläche Assemblyinformationen… (siehe Bild 2).
Bild 2: Anzeigen der Assemblyinformationen
Danach erscheint der Dialog Assemblyinformationen. Hier finden Sie im unteren Bereich den Eintrag Assembly COM-sichtbar machen, den Sie aktivieren (siehe Bild 3).
Bild 3: Assembly sichtbar für COM machen
Fehlt noch ein Schritt, den Sie in den Eigenschaften im Bereich Kompilieren erledigen – hier muss die Option Für COM-Interop registrieren aktiviert werden (siehe Bild 4).
Bild 4: Registrieren für COM-Interop
Schließlich fügen wir der Klasse ZUGFeRD_NET die folgende Funktion hinzu:
Public Function ZUGFeRDRechnungErstellen() As Boolean Return True End Function
Damit können wir das Projekt nun erstellen, indem wir den Menübefehl Erstellen|Projektmappe erstellen von Visual Studio aufrufen. Dadurch wird die DLL erstellt und die Registry wird um die Informationen ergänzt, die gleich beim Öffnen von Access eingelesen werden, damit dort die neue Bibliothek als Verweis zur Verfügung steht.
Verweis auf die neue ZUGFeRD-Bibliothek einbinden
Um den Verweis zu einem VBA-Projekt einer Access-Datenbank hinzuzufügen, öffnen Sie zunächst die Access-Datenbank, in der Sie die DLL verwenden wollen.
Dann zeigen Sie den VBA-Editor an, am schnellsten mit der Tastenkombination Strg + G, und öffnen dann mit dem Menüeintrag Extras|Verweise den Verweise-Dialog.
Hier finden Sie nun ganz unten den Eintrag ZUGFeRD, den Sie anhaken, bevor Sie den Dialog wieder schließen (siehe Bild 5).
Bild 5: Verweis auf die neue DLL hinzufügen
Wenn dies geschehen ist, können Sie ausprobieren, ob die einzige bisher angelegte Funktion bereits wie erwartet arbeitet. Diese sollte beim Aufruf der folgenden Prozedur den Wert True im Direktfenster ausgeben:
Public Sub ZUGFeRDTest() Dim objZUGFeRD As ZUGFeRD.ZUGFeRD_NET Set objZUGFeRD = New ZUGFeRD.ZUGFeRD_NET Debug.Print objZUGFeRD.ZUGFeRDRechnungErstellen End Sub
Dies gelingt wie erwartet, sodass wir uns nun der Programmierung zuwenden können.
ZUGFeRD-Paket zum VB-Projekt hinzufügen
Die Open Source-Bibliothek ZUGFeRD.NET der Firma Konik kommt als NuGet-Paket. Solche Pakete können Sie einfach zu einem VB-Projekt unter Visual Studio hinzufügen.
Dazu wählen Sie im Kontextmenü des Projekt-Elements im Projektmappen-Explorer unter Visual Studio den Eintrag NuGet-Pakete verwalten aus. Dies öffnet den NuGet-Paket-Manager. Hier geben Sie als Suchbegriff ZUGFeRD ein und wechseln dann zum Bereich Durchsuchen.
Wir suchen den Eintrag ZUGFeRD.NET der Firma Konik und fügen das entsprechende Paket durch einen Klick auf die Schaltfläche Installieren zum aktuellen VB-Projekt hinzu (siehe Bild 6).
Bild 6: Hinzufügen des NuGet-Pakets
Namespace-Verweise
Im Modul ZUGFeRD_NET.vb fügen Sie nun zunächst die folgenden Verweise auf die benötigen Namespaces hinzu:
Imports System.Runtime.InteropServices Imports java.io Imports org.apache.commons.lang3.time Imports com.neovisionaries.i18n Imports io.konik Imports io.konik.ZUGFeRD Imports io.konik.ZUGFeRD.entity Imports io.konik.ZUGFeRD.entity.trade Imports io.konik.ZUGFeRD.entity.trade.item Imports io.konik.ZUGFeRD.profile Imports io.konik.ZUGFeRD.unece.codes Imports io.konik.ZUGFeRD.unqualified Imports java.math Imports Country = com.neovisionaries.i18n.CountryCode Imports Currency = com.neovisionaries.i18n.CurrencyCode
Verschiedene Profile
Bevor wir in die Programmierung einsteigen, noch ein Hinweis auf die verschiedenen Profile für ZUGFeRD-Dateien.
Diese sehen wir folgt aus:
- BASIC: Für einfachste Rechnungen. Hier werden nur die relevantesten Daten im XML-Dokument berücksichtigt. Einzelne Rechnungspositionen etwa entfallen. Informationen wie die einzelnen Positionen werden in Textform im PDF-Teil der Rechnung übermittelt.
- COMFORT: Bietet mehr Möglichkeiten als das BASIC-Profil, aber nicht alle Möglichkeiten.
- EXTENDED: Ermöglicht die vollständige Abbildung des strukturierten Rechnungsaustauschs.
Eine bessere Unterscheidung ermöglicht die Betrachtung der verschiedenen Rechnungsarten.
Das BASIC-Profil unterstützt diese Rechnungsarten:
- Handelsrechnung (Rechnung für Waren und Dienstleistungen) mit dem Code 380
- Bescheide (z. B. Zahlungsaufforderung von Behörden) mit dem Code 380
- Kaufmännische Gutschrift (zum Beispiel Rechnungskorrektur/Storno) mit negativen Werten (Code 380)
Das COMFORT-Profil bietet folgende zusätzlichen Rechnungsarten:
- Wertbelastung/Wertrechnung ohne Warenbezug (Code 84)
- Wertgutschrift ohne Warenbezug mit negativen Werten (Code 84)
- Mit dem EXTENDED-Profil können außerdem diese Rechnungsarten verarbeitet werden:
- Selbst ausgestellte Rechnung (Steuerrechtliche Gutschrift/Gutschriftsverfahren, Code 389)
- Selbst ausgestellte Gutschrift mit negativen Werten (Code 389)
Die hier genannten Codes werden einer der Eigenschaften zugeordnet, die wir gleich über das Objektmodell der Bibliothek dem XML-Dokument zuweisen, das mit dem PDF-Dokument zusammengeführt werden soll.
Öffentliche Eigenschaften der DLL
Damit wir die im XML-Teil der Rechnung zu berücksichtigenden Informationen von Access aus an die DLL übergeben können, erstellen wir einige öffentliche Eigenschaften.
Deren Programmierung im Modul ZUGFeRD_NET.vb besteht aus zwei Teilen – der privaten Deklaration einer Variablen zum Speichern der zugewiesenen Werte sowie einer öffentlichen Eigenschaft mit Getter und Setter.
Die Namen der privaten Variablen beginnen allesamt mit dem Unterstrich und werden wie folgt deklariert:
Private _QuellPDF As String Private _ZielPDF As String Private _Rechnungsnummer As String Private _Verkaeufer_Name As String Private _Verkaeufer_PLZ As String Private _Verkaeufer_Strasse As String Private _Verkaeufer_Ort As String Private _Verkaeufer_Land As CountryCode Private _Bemerkung As String Private _Verkaeufer_UstIDNr As String Private _Kaeufer_Name As String Private _Kaeufer_PLZ As String Private _Kaeufer_Strasse As String Private _Kaeufer_Ort As String Private _Kaeufer_Land As CountryCode Private _Kaeufer_UstIDNr As String Private _Verkaeufer_IBAN As String Private _Verkaeufer_BIC As String Private _Nettobetrag As BigDecimal Private _Aufschlaege As Long Private _Abschlaege As Long Private _Mehrwertsteuerbetrag As Long Private _Bruttobetrag As Long Private _Zahlungsreferenz As String Private _Produkt As String Private _AnzahlProdukt As Long
Sie haben das Ende des frei verfügbaren Textes erreicht. Möchten Sie ...
Oder bist Du bereits Abonnent? Dann logge Dich gleich hier ein. Die Zugangsdaten findest Du entweder in der aktuellen Print-Ausgabe auf Seite U2 oder beim Online-Abo in der E-Mail, die Du als Abonnent regelmäßig erhältst:
