CIB ZUGFeRD SDK technischer Leitfaden

1. ZUGFeRD – der neue Standard

Mit dem einheitlichen Datenformat-Standard ZUGFeRD (Zentraler User Guide des Forum elektronische Rechnung Deutschland) können elektronische Rechnungen zwischen Unternehmen sowie zwischen Unternehmen und der öffentlichen Verwaltung schnell, komfortabel und einfach ausgetauscht werden. Durch den Standard ist der Austausch ohne vorherige Absprachen möglich.

Der ZUGFeRD-Standard basiert auf der Rechnung im PDF/A3 Format, in die eine XML-Datei mit Namen „ZUGFeRD-invoice.xml“ eingebettet ist. Diese XML-Datei enthält die Rechnungsparameter, die für das jeweilige ZUGFeRD-Profil erforderlich sind.

Es gibt die Versionen ZUGFeRD 1.0 bis ZUGFeRD 2.1. Hierbei ist zu beachten, dass die Versionen zwar ineinander überführbar, jedoch nicht vollständig kompatibel sind.

Es gibt die Profile BASIC, COMFORT/EN16931 und EXTENDED.

Das Basic-Profil reduziert die Anforderungen an die Übermittlung strukturierter Daten, um vom Aufbau her einfachste Rechnungen abbilden zu können. Die für die Buchung sowie die Einleitung des Zahlungsverkehrs erforderlichen Daten stehen in strukturierter Form zur Verfügung. Im Wesentlichen handelt es sich dabei um Kopf- und Fußdaten sowie reduzierte Positionsdaten.

Im Comfort-Profil können alle Daten in strukturierter Form übermittelt werden, die für eine überwiegende Zahl versendeter Rechnungen eine automatisierte, systemgestützte Rechnungsbearbeitung auf Empfängerseite zu ermöglichen. Unterstützt werden dabei insbesondere die Prozesse Buchung, Zahlung und Rechnungsprüfung. Ab ZUGFeRD Version 2.0, entspricht das Comfort-Profil zudem dem europaweiten EN16931 Standard. Das Profil wurde dementsprechend in EN16931 umbenannt.

Im Extended-Profil werden alle im ZUGFeRD-Datenmodell abgebildeten Daten in strukturierter Form bzw. als qualifiziertes Textfeld abgebildet. Die Auswahl der tatsächlich verwendeten Datenfelder hängen von dem jeweiligen Geschäftsprozess ab. Damit deckt das Extended-Profil die branchenübergreifenden Anforderungen an den strukturierten Rechnungsdatenaustausch möglichst vollständig ab.

Damit ist eine automatische Verarbeitung von Eingangsrechnungen möglich ohne dass eine erneute Datenerfassung erforderlich ist.

2. Das ZUGFeRD SDK (Software Development Kit)

Das SDK dient dazu, die grundsätzliche Kompatibilität eines PDF-Dokuments zum ZUGFeRD-Standard zu prüfen und den XML-Rechnungsdatensatz aus der PDF-Datei zu extrahieren. Die extrahierten XML-Daten stehen dann zur weiteren Verarbeitung z.B. durch ein ERP-System zur Verfügung. So können Sie die extrahierte XML-Datei in ein existierendes PDF einbetten. Das CIB ZUGFeRD SDK bietet die folgenden drei API Funktionen, sowohl als Unicode, UTF-8 und auch als ANSI-Variante an.

2.1. Prüfen eines PDF-Dokuments als ZUGFeRD-Konform

int32_t CibZugferdSDKIsZugferd (const char* pdfFile);
int32_t CibZugferdSDKIsZugferdUtf8 (const char* pdfFile);
int32_t CibZugferdSDKIsZugferdW(const wchar_t* pdfFile)

Die Funktionen CibZugferdSDKIsZugferd* prüfen, ob das angegebene Dokument dem ZUGFeRD-Standard entspricht und eine Rechnung mit ZUGFeRD Informationen vorliegt.

Rückgabewerte:

Wenn es innerhalb des SDK zu einer Fehlersituation gekommen ist, wird ein anderer ERR_ZUGFERD–Wert zurückgegeben. Die Fehlerwerte und ihre Bedeutung entnehmen Sie der Datei CibZugferdSDK.h.

2.2. Extrahieren eines ZUGFeRD-XML

int32_t CibZugferdSDKExtraxt(const char* inputPdfFile, const char* outputXmlFile);
int32_t CibZugferdSDKExtraxtUtf8(const char* inputPdfFile, const char* outputXmlFile);
int32_t CibZugferdSDKExtraxtW(const wchar_t* inputPdfFile, const wchar_t* outputXmlFile);

Die Funktionen CibZugferdSDKExtraxt* extrahieren aus einem angegebenen Dokument das XML des ZUGFeRD-Standards. Es werden keine Ausgabedateien überschrieben, wenn diese bereits vorhanden sein sollten.

Rückgabewert:

Wenn es innerhalb des SDK zu einer Fehlersituation gekommen ist, wird ein anderer ERR_ZUGFERD–Wert zurückgegeben. Die Fehlerwerte und ihre Bedeutung entnehmen Sie der Datei CibZugferdSDK.h.

2.3. Einbetten eines ZUGFeRD-XML

int32_t CibZugferdSDKEmbed(const char* inputPdfFile, const char* inputXmlFile, const char* outputpdfFile, const char* description);
int32_t CibZugferdSDKEmbedUtf8(const char* inputPdfFile, const char* inputXmlFile, const char* outputpdfFile, const char* description);
int32_t DoCibZugferdSDKEmbedW(const wchar_t* inputpdfFile, const wchar_t* inputXmlFile, const wchar_t* outputpdfFile, const wchar_t* description)

Die Funktionen CibZugferdSDKEmbed* betten in einem angegebenen Dokument die existierende XML-Datei des ZUGFeRD-Standards ein. Es werden keine Ausgabedateien überschrieben, wenn diese bereits vorhanden sein sollten.

Rückgabewert:

Wenn es innerhalb des SDK zu einer Fehlersituation gekommen ist, wird ein anderer ERR_ZUGFERD–Wert zurückgegeben. Die Fehlerwerte und ihre Bedeutung entnehmen Sie der Datei CibZugferdSDK.h.

2.4. Mögliche Rückgabewerte

In der nachfolgenden Tabelle sind die in ZUGFeRD vorhandenen Rückgabewerte, Fehlercodes und ihre Bedeutung aufgelistet:

2.5. Testprogramm zum Testen des SDK

Im Lieferumfang ist ein Testprogramm enthalten, dass das SDK testet. Wenn Sie das Testprogramm mit dem Parameter –? aufrufen, erhalten Sie eine Beschreibung der möglichen Aufrufparameter.

2.6. Programmiersprachen und Systeme

Das CIB ZUGFeRD SDK bietet ein C-Programmierinterface an. Für Java und C# werden Programmierschnittstellen mitgeliefert. Das SDK ist in 32 bit und 64 bit für Windows erhältlich.

Weitere Informationen zu anderen Programmiersprachen und Systemen (Linux / Android) erhalten Sie beim CIB Support.

3. Die Power-PDF Library hinter dem CIB ZUGFeRD SDK

Das CIB ZUGFeRD SDK nutzt die CIB pdf toolbox, um Informationen über das PDF auszulesen und Bearbeitungen am PDF durchzuführen.

Folgende Punkte machen die CIB pdf toolbox einzigartig:

• Hohe Verarbeitungsgeschwindigkeit und niedriger Ressourcenverbrauch
• Tolle Kompression von PDFs
• Hochwertiges Rendering von PDFs
• Sehr gute Konvertierung in archiv-ready PDF/A* Formate. Jedes PDF kann darin ohne Fehler konvertiert werden.
• PDF 2.0 ready
• KI basierte Texterkennung auf Bildinhalten in PDFs
• Einfache API macht das technische Integrieren sehr leicht
• Toller technischer Support
• Hoher Featurereichtum. Ersetzen sie viele PDF Libraries, die sie für unterschiedliche Einsatzzwecke benutzen durch ein Allzwecktool. Es wird eine 3 Stellige Anzahl von technischen Usecases unterstützt, die nun hier nicht alle erwähnt werden können.