HCL Domino · ZUGFeRD · XRechnung · API-Engine
ZUGFeRD und XRechnung direkt in HCL Domino verarbeiten
Elektronische Rechnungen enthalten strukturierte Daten, die sich automatisiert auslesen und weiterverarbeiten lassen. Mit der SL Net-Solutions Domino API-Engine können Rechnungsinformationen aus ZUGFeRD-Dokumenten und XML-Rechnungen in bestehende Domino-Prozesse übernommen werden.
Ein neues Beispiel im API-Engine V12.12 Evaluation Package zeigt den technischen Weg anhand einer ZUGFeRD-Rechnung: Das PDF wird als BINBUFFER gelesen, das eingebettete Rechnungs-XML wird direkt im Speicher extrahiert und anschließend mit XML- und XPath-Funktionen ausgewertet. Ausgewählte Informationen werden im Domino-Dokument gespeichert.
PDF → XML → XPath → Domino. Für diesen Ablauf muss das eingebettete XML nicht erst über eine temporäre Datei oder einen externen Konvertierungsdienst bereitgestellt werden. Eine bereits als XML vorliegende XRechnung kann direkt beim XML-Schritt beginnen.
Grundlagen
Unterschiedliche Verpackung, strukturierte Rechnungsdaten
ZUGFeRD und XRechnung werden häufig gemeinsam genannt. Für die technische Verarbeitung ist jedoch wichtig, zwischen dem Dokumentcontainer, der XML-Syntax und den fachlichen Vorgaben zu unterscheiden.
PDF mit eingebettetem XML
Das hybride Format kombiniert eine visuell lesbare PDF/A-3-Rechnung mit strukturierten XML-Daten. Die Rechnungsdaten verwenden UN/CEFACT Cross Industry Invoice (CII).
XML als Rechnungsdokument
XRechnung konkretisiert die EN 16931 für den deutschen Einsatz. Die XML-Daten können in UBL oder CII vorliegen und benötigen grundsätzlich keinen PDF-Container.
Gemeinsames Datenmodell
Die europäische Norm beschreibt die fachlichen Rechnungsinformationen. Das konkrete XML-Layout und die zulässigen Regeln hängen von Syntax und verwendetem Profil ab.
Wichtig für das Beispiel: Die folgende Demo verarbeitet CII-XML, wie es in einer ZUGFeRD-Rechnung enthalten ist. Eine XRechnung in CII-Syntax lässt sich nach demselben XML-Prinzip auswerten; bei UBL sind andere Elementnamen, Namespaces und XPath-Ausdrücke erforderlich.
Verarbeitungsweg
Von der PDF-Rechnung zu Domino-Items
Der gesamte Beispielablauf kann innerhalb eines serverseitigen API-Engine-Prozesses ausgeführt werden. Die Quelle des PDF-BINBUFFERs ist dabei nicht auf Notes-Anhänge beschränkt.
PDF als BINBUFFER
als BINBUFFER
Namespaces · Feldwerte
Währung · Beträge
Bei einer reinen XML-Rechnung entfällt der PDF-Extraktionsschritt. Ab dem XML-Parser ist der weitere Ablauf prinzipiell derselbe.
Praktisches Beispiel
Wenige Felder, nachvollziehbarer Ablauf
Das Evaluation-Beispiel arbeitet bewusst mit einer kleinen Zahl von Rechnungsdokumenten. Es geht nicht darum, eine komplette Buchhaltungs- oder E-Rechnungsplattform nachzubilden, sondern die Schnittstelle zwischen einem Rechnungsdokument und einer Domino-Datenbank zu demonstrieren.
Das Beispiel beschränkt sich bewusst auf ausgewählte Rechnungs-Kopfdaten. Grundsätzlich können jedoch sämtliche im Rechnungs-XML enthaltenen Informationen ausgelesen und weiterverarbeitet werden. Dazu gehören beispielsweise einzelne Rechnungspositionen, Artikelnummern, Mengen, Einzelpreise, Steuerinformationen, Zahlungsbedingungen, Bankverbindungen und Referenzen auf Bestellungen oder Lieferscheine.
Auch komplexere und wiederkehrende XML-Strukturen lassen sich mithilfe der XML-Funktionen und XPath gezielt auswerten. Welche Daten übernommen werden, hängt somit von den Anforderungen der jeweiligen Domino-Anwendung ab.
InvoiceNumberDie eindeutige Rechnungskennung aus dem CII-Dokument.
InvoiceDateRawDas ursprüngliche Rechnungsdatum aus dem XML, vor einer möglichen Formatumwandlung.
SellerDer Name des liefernden oder leistenden Unternehmens.
BuyerDer im Rechnungsdokument angegebene Käufer.
CurrencyDer ISO-Währungscode der Rechnung, beispielsweise EUR.
GrandTotalDer Gesamtrechnungsbetrag aus der monetären Summierung.
DueAmountDer laut Rechnungsdaten noch zu zahlende Betrag.
XML-Beispiel
So sehen die Rechnungsdaten im CII-XML aus
Die eigentlichen Informationen werden nicht aus dem sichtbaren PDF-Text erkannt, sondern aus den strukturierten XML-Elementen gelesen. Nachfolgend ein verkürzter Ausschnitt mit den für das Beispiel relevanten Elementen:
<rsm:CrossIndustryInvoice
xmlns:rsm="urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100"
xmlns:ram="urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100"
xmlns:udt="urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100">
<rsm:ExchangedDocument>
<ram:ID>471102</ram:ID>
<ram:IssueDateTime>
<udt:DateTimeString format="102">20241115</udt:DateTimeString>
</ram:IssueDateTime>
</rsm:ExchangedDocument>
<rsm:SupplyChainTradeTransaction>
<ram:ApplicableHeaderTradeAgreement>
<ram:SellerTradeParty>
<ram:Name>Beispiel GmbH</ram:Name>
</ram:SellerTradeParty>
<ram:BuyerTradeParty>
<ram:Name>Musterkunde AG</ram:Name>
</ram:BuyerTradeParty>
</ram:ApplicableHeaderTradeAgreement>
<ram:ApplicableHeaderTradeSettlement>
<ram:InvoiceCurrencyCode>EUR</ram:InvoiceCurrencyCode>
<ram:SpecifiedTradeSettlementHeaderMonetarySummation>
<ram:GrandTotalAmount>529.87</ram:GrandTotalAmount>
<ram:DuePayableAmount>529.87</ram:DuePayableAmount>
</ram:SpecifiedTradeSettlementHeaderMonetarySummation>
</ram:ApplicableHeaderTradeSettlement>
</rsm:SupplyChainTradeTransaction>
</rsm:CrossIndustryInvoice>Stark verkürzter, illustrativer CII-XML-Ausschnitt mit Beispieldaten. Er ist kein vollständiges, validierbares ZUGFeRD- oder XRechnung-Dokument.
Namespaces beachten: Bei CII gehören Elemente wie
ram:ID oder ram:GrandTotalAmount zu
definierten XML-Namensräumen. XPath-Ausdrücke müssen diese
korrekt zuordnen; ein bloßer Vergleich mit unqualifizierten
Elementnamen reicht nicht zuverlässig aus.
Technischer Ablauf
Was das Demo-Skript Schritt für Schritt macht
Eine kleine Anzahl von Domino-Testdokumenten wird für die Verarbeitung herangezogen.
Im Beispiel stammt das PDF aus einem Domino-Anhang. Ebenso denkbar sind Datei- oder REST-basierte Quellen.
@PDFExtractInvoiceXML liest das eingebettete Rechnungs-XML aus dem PDF-BINBUFFER und liefert einen XML-BINBUFFER zurück.
@XMLParse erstellt ein XML-Dokument-Handle. Die weitere Navigation erfolgt über dessen Root-Node.
@XMLSelectSingleNode sucht die relevanten Elemente unter Berücksichtigung der Namespaces; @XMLGetContent liefert die Inhalte.
Die extrahierten Werte werden in Domino-Items übernommen. XML-Handles und temporäre Buffer werden anschließend freigegeben.
API-Engine XML-Funktionen
Vom XML-Handle zum Rechnungsfeld
Nach der PDF-Extraktion behandelt die API-Engine die Rechnung als reguläres XML-Dokument. Für das Lesen einer Rechnungsnummer sind beispielsweise die folgenden Funktionen relevant:
PDF-BINBUFFER
|
+-- @PDFExtractInvoiceXML(PDFBuffer)
|
v
Rechnungs-XML (BINBUFFER)
|
+-- @XMLParse(InvoiceXML; 1)
|
+-- @XMLGetRoot(Doc)
|
+-- @XMLSelectSingleNode(
Root; XPath; Prefixes; Namespaces)
|
+-- @XMLGetContent(Node)
|
+-- Domino-Item schreiben
Aufraeumen: @XMLRelease(Doc), @DestroyBuffer(...)Schematische Funktionsfolge, kein unmittelbar ausführbares Skript. Das vollständige Beispiel mit Datenbankzugriff, Parametern und Fehlerbehandlung befindet sich im Evaluation Package.
Für die Rechnungsnummer verwendet die CII-Struktur beispielsweise diesen XPath:
/rsm:CrossIndustryInvoice
/rsm:ExchangedDocument
/ram:IDZur besseren Lesbarkeit umgebrochen; im Skript steht der XPath in einer Zeile.
Die Beträge stehen an anderer Stelle im Dokument, unterhalb von
ram:ApplicableHeaderTradeSettlement und
ram:SpecifiedTradeSettlementHeaderMonetarySummation.
Die Zuordnung der Präfixe rsm, ram und bei
Datumsangaben udt ist Bestandteil der XML-Abfrage.
Das vollständige Beispielskript ansehen
Wie sieht die Verarbeitung in einem echten API-Engine-Skript aus? Das vollständige Beispiel zeigt die Extraktion der XML-Rechnungsdaten aus einem ZUGFeRD-PDF, die anschließende XML-Auswertung und die Übernahme ausgewählter Rechnungsfelder in HCL Domino.
Ergebnis
Strukturierte Daten direkt im Domino-Dokument
Aus dem gezeigten XML-Ausschnitt ergeben sich beispielsweise die folgenden Werte. Sie können als Notes-Items gespeichert und danach in Views, Workflows oder weiteren Integrationsschritten verwendet werden.
| Domino-Item | Beispielwert |
|---|---|
InvoiceNumber | 471102 |
InvoiceDateRaw | 20241115 |
Seller | Beispiel GmbH |
Buyer | Musterkunde AG |
Currency | EUR |
GrandTotal | 529.87 |
DueAmount | 529.87 |
Illustrative Ausgabewerte zum vorstehenden gekürzten XML-Ausschnitt.
Abgrenzung
XML auslesen ist nicht dasselbe wie eine Rechnung validieren
Das Beispiel zeigt die technische Extraktion und Auswertung von Rechnungsdaten. Ob eine Rechnung die Anforderungen ihres Profils, der EN 16931 und der einschlägigen Geschäftsregeln erfüllt, ist eine zusätzliche Fragestellung.
Das Demo-Skript ist kein vollständiger E-Rechnungsvalidator. Das erfolgreiche Auslesen einzelner XML-Felder bedeutet nicht, dass eine ZUGFeRD- oder XRechnung-Datei fachlich und formal gültig ist. Für entsprechende Prüfungen sind geeignete Schema- und Geschäftsregelvalidatoren erforderlich, beispielsweise mit den offiziellen XRechnung-Validierungsartefakten der KoSIT.
Für eine produktive Verarbeitung kommen je nach Einsatzfall weitere Aufgaben hinzu: Unterstützung unterschiedlicher Rechnungsprofile, UBL- und CII-Mapping, Fehlerbehandlung, Betrags- und Datumsprüfung, Dublettenerkennung, Protokollierung sowie die eigentliche Übergabe an Buchhaltung oder ERP-Systeme.
Integration
Warum dieser Ansatz für bestehende Domino-Anwendungen interessant ist
Rechnungsdaten müssen nicht zwingend in einer separaten Anwendung verarbeitet werden. Das Beispiel zeigt, wie sich die XML-Auswertung in einen bestehenden Domino-Prozess integrieren lässt.
Ohne temporäre XML-Dateien
Die eingebetteten Rechnungsdaten können direkt aus einem PDF-Buffer gewonnen und als XML-Buffer weiterverarbeitet werden.
Gezielte Datenextraktion
XML-Handles und namespacefähige XPath-Abfragen ermöglichen den direkten Zugriff auf einzelne Rechnungsfelder.
Verarbeitung im selben Prozess
Die Ergebnisse können unmittelbar in NSF-Dokumente und darauf aufbauende Geschäftsprozesse übernommen werden.
Technische Einordnung
ZUGFeRD und XRechnung mit LotusScript, Java oder API-Engine?
Die Verarbeitung von XML-Rechnungsdaten ist in Domino keineswegs nur mit der API-Engine möglich. Sowohl LotusScript als auch Java bieten etablierte Möglichkeiten, XML-Dokumente zu lesen und Rechnungsinformationen in NSF-Dokumente zu übernehmen. Die Unterschiede liegen vor allem darin, wie PDF-Anhänge, XML-Auswertung und die weitere Verarbeitung miteinander verbunden werden.
XML mit Domino-Bordmitteln
Mit NotesDOMParser, NotesSAXParser und
NotesStream lassen sich XML-Daten unmittelbar in
LotusScript verarbeiten. Für reine XML-Rechnungen kann das bereits
ausreichen. Die Extraktion eingebetteter Rechnungs-XML-Daten aus
ZUGFeRD-PDFs erfordert hingegen eine zusätzliche geeignete Lösung.
XML, XPath und PDF-Bibliotheken
Java stellt mit DOM, SAX und XPath leistungsfähige Werkzeuge zur XML-Verarbeitung bereit. Mit einer PDF-Bibliothek wie Apache PDFBox lassen sich auch eingebettete Dateien aus PDF-Dokumenten extrahieren. Dafür sind die entsprechenden Bibliotheken und ihre Einbindung in die jeweilige Domino-Laufzeitumgebung zu berücksichtigen.
Durchgängige Verarbeitung im Engine-Skript
Im gezeigten Beispiel übernimmt @PDFExtractInvoiceXML
die Extraktion des eingebetteten XML aus einem PDF-BINBUFFER.
Anschließend können die XML-Funktionen die Rechnungsdaten per
XPath auswerten und die Ergebnisse innerhalb desselben Skripts
direkt in Domino weiterverarbeiten.
Der Vorteil liegt nicht darin, dass LotusScript oder Java diese Aufgabe grundsätzlich nicht lösen könnten. Die API-Engine bündelt im gezeigten Szenario PDF-Extraktion, XML-Auswertung und Domino-Verarbeitung in einer einheitlichen Skriptumgebung. Liegt eine XRechnung bereits als reine XML-Datei vor, entfällt der Schritt der PDF-Extraktion unabhängig von der verwendeten Technologie.
Evaluation Package
Das ZUGFeRD-Beispiel selbst ausprobieren
Das aktuelle API-Engine V12.12 Evaluation Package enthält das Beispielskript und die zugehörigen Testdaten für die Verarbeitung elektronischer Rechnungsdaten in HCL Domino.
ZUGFeRD / XRechnung – Beispielskript
Das Beispiel demonstriert das Einlesen eines PDF-Anhangs, die
Extraktion des eingebetteten CII-XML mit @PDFExtractInvoiceXML,
die Auswertung per XML/XPath sowie das Schreiben ausgewählter
Rechnungsinformationen in Domino-Items.
Die Beispiele sind für eine kontrollierte Test- oder Entwicklungsumgebung vorgesehen und stellen keine vollständige produktive Rechnungsverarbeitung dar.
Fazit
E-Rechnungen als Datenquelle für Domino-Prozesse
ZUGFeRD und XRechnung sind nicht nur Dokumentformate. Ihr strukturierter XML-Inhalt ermöglicht es, Rechnungsinformationen automatisiert für bestehende Anwendungen nutzbar zu machen.
Die API-Engine verbindet dabei den Zugriff auf das Eingangsdokument mit der XML-Auswertung und der Verarbeitung in Domino: vom BINBUFFER über namespacefähige XPath-Abfragen bis zum Speichern der Ergebnisse in einer NSF.
Das gezeigte Beispiel konzentriert sich bewusst auf wenige Rechnungsfelder. Der Ansatz lässt sich anschließend um weitere XML-Inhalte, Prüfungen, Datenbankabgleiche und Schnittstellen zu vorhandenen Systemen ergänzen.
Technische Referenzen
Standards und weiterführende Informationen
FeRD – ZUGFeRD / Factur-X · FeRD – FAQ · KoSIT – Validator-Konfiguration XRechnung