CIB ZUGFeRD SDK technischer Leitfaden

Site: CIB eLearning
Course: CIB ZUGFeRD SDK
Book: CIB ZUGFeRD SDK technischer Leitfaden
Printed by: Guest user
Date: Saturday, 13 April 2024, 10:59 AM

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.

Mehr Informationen zu ZUGFeRD finden Sie auf der Website von FeRD, http://www.ferd-net.de/.

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:

Wert

Bedeutung

ERR_ZUGFERD_OK_HAS_ZUGFERD1

Die vorliegende PDF Datei ist ZUGFeRD 1.0 kompatibel.

ERR_ZUGFERD_OK_HAS_ZUGFERD2

Die vorliegende PDF Datei ist ZUGFeRD 2.* kompatibel.

ERR_ZUGFERD_OK_NO_ZUGFERD

Die vorliegende PDF Datei ist nicht ZUGFeRD kompatibel.

 

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:

Wert

Bedeutung

ERR_ZUGFERD_OK

Aus der vorliegenden PDF Datei wurde das XML des ZUGFeRD-Standards erfolgreich extrahiert.

 

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:

Wert

Bedeutung

ERR_ZUGFERD_OK

Aus der vorliegenden PDF Datei wurde das XML des ZUGFeRD-Standards erfolgreich eingebettet.

 

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:

Rückgabewerte

Meldung

Bedeutung

0

ERR_ZUGFERD_OK

Kein Fehler aufgetreten.

1

ERR_ZUGFERD_OK_HAS_ZUGFERD1

Kein Fehler aufgetreten. PDF ist ZUGFeRD 1 kompatibel.

2

ERR_ZUGFERD_OK_HAS_ZUGFERD2

Kein Fehler aufgetreten. PDF ist ZUGFeRD 2 kompatibel.

100

ERR_ZUGFERD_UNSPECIFIC

Nichtspezifizierter Fehler aufgetreten.

101

ERR_ZUGFERD_OUTPUTFILE_EXITS

Angegebene Ausgabedatei ist bereits vorhanden und kann nicht überschrieben werden.

102

ERR_ZUGFERD_READ

Fehler beim Lesen aufgetreten.

103

ERR_ZUGFERD_INPUT

Fehler bei den Eingabeparametern aufgetreten.

104

ERR_ZUGFERD_NO_PDFA3_INPUT

Es wurde keine PDF/A3-Datei beim Einbetten angegeben.

105

ERR_ZUGFERD_ALREADY_EMBEDDED

Eine bereits eingebettete ZUGFeRD-XML wurde erneut in die Datei eingebettet.

106

ERR_ZUGFERD_EXTRACTING

Fehler beim Extrahieren.


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.

Informieren Sie sich unter: CIB pdf toolbox technischer Leitfaden