Rechnungen mit ZUGFeRD 1.0, Teil 1: .NET

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

Ende des frei verfügbaren Teil. Wenn Du mehr lesen möchtest, hole Dir ...

den kompletten Artikel im PDF-Format mit Beispieldatenbank

diesen und alle anderen Artikel mit dem Jahresabo