Seitenhistorie

Releases

Überblick

Das Nuclet ermöglicht die Erzeugung elektronischer Rechnungen im XML- oder PDF-Format, deren offizielle Validierung und deren Darstellung in einer HTML-Datei.

Unterstützt wir wird das Format XRechnung in der Version 3.0.2 (20.06.2024) in der XML-Syntax Universal Business Language (UBL) der OASIS in der Version 2.1 und der XML-Syntax Cross Industry Invoice(CII) der UN/CEFACT in der VersionD16B.
Weiterhin wird die Spezifikation ZUGFeRD in der Version 2.2 abdeckt3.2 (15.11.2024) abgedeckt.

Zur Erzeugung der Dateien stehen folgende Möglichkeiten zur Verfügung:

1. Die Regel org.nuclet.xrechnung.ErzeugeERechnung, die in einem geeigneten Layout eingebunden werden kann und wie bisher (Version 1) eine XRechnung (UBL) erstellt.
2. Eine eigene Regel, die org.nuclet.xrechnung.ErzeugeERechnung#erzeugeERechnung(org.nuclet.xrechnung.Rechnungen, boolean, org.nuclos.api.common.NuclosFile) mit geeigeneten Parametern (siehe weiter unten) aufruft und verarbeitet.
3. Eine eigene Regel, die org.nuclet.xrechnung.ErzeugeERechnung#erzeugeERechnung(org.nuclet.xrechnung.XRechnung, boolean, org.nuclos.api.common.NuclosFile) mit geeigenetem Objekt (siehe weiter unten) aufruft und verarbeitet.

Dabei werden abhängig von der jeweiligen Konfiguration folgende Dateien erzeugt, zurückgegeben und in einem geeigneten Unterformular abgelegt.

• XML-Datei gemäß Standard XRechnung oder PDF-Datei gemäß Standard ZUGFeRD (je nach Methodenaufruf)
• HTML-Datei als Vorschau auf die erzeugten Daten
• HTML-Datei mit Ergebnissen der XML-Validierung
• Falls die Validierung der PDF-Datei nicht erfolgreich war: TXT-Datei mit Ergebnissen der PDF-Validierung
• LOG-Datei mit Ergebnissen der Rechnungserzeugung

Optional ist außerdem eine Validierung der Leitweg-ID im Nuclet enthalten.

Ein Beispiel ist im angehängten angehängten Beispiel-Nuclet verfügbar.

Hinweise

zu Version 2.0.0

Hinweise zur Methode public static List<XRechnung.XRechnungFile> erzeugeERechnung(Rechnungen rechnungen, boolean formatUbl, NuclosFile pdfFile):

• rechnungen: die jeweilige Rechnung als org.nuclet.xrechnung.Rechnungen (Integrationspunkt); muss eine ID und eine Rechnungsnummer haben

• formatUbl: steuert die XML-Syntax (bei false: CII)

• pdfFile: vorab erzeugte PDF-Datei im Format PDF-A1, in das die XML-Datei eingebettet werden soll - falls angegeben muss das Format CII gewählt werden

• Rückgabewert: Liste der erzeugten Dateien inkl. Validierungsergebnissen

Hinweise zur Methode public static List<XRechnung.XRechnungFile> erzeugeERechnung(XRechnung xRechnung, boolean formatUbl, NuclosFile pdfFile):

• xRechnung: Java-Objekt, das die entsprechende Konfiguration (siehe Tabelle) für die Erstellung der elektronischen Rechnung vorgibt

• formatUbl: wie oben

• pdfFile: wie oben

• Rückgabewert: wie oben

Methode	Hinweis	Standardwert
setFileNameBase(String fileNameBase)	Basisname für erzeugte Dateien	Wird automatisch aus der Rechnungsnr. bzw. Rechnungs-ID ohne Sonderzeichen erzeugt, bspw. "123456"
setDsClassMain(Class<? extends Datasource> dsClassMain)	Hauptdatenquelle für Rechnungen	AusgangsrechnungXRechnungDS.class
setDsClassPosition(Class<? extends Datasource> dsClassPosition)	Datenquelle für Rechnungspositionen	AusgangsrechnungXRechnungPositionenDS.class
setDsClassComment(Class<? extends Datasource> dsClassComment)	Datenquelle für Rechnungskommentare	AusgangsrechnungXRechnungKommentareDS.class
setDsClassVatBreakdown(Class<? extends Datasource> dsClassVatBreakdown)	Datenquelle für Umsatzsteueraufschlüsselung	AusgangsrechnungXRechnungUmsatzsteueraufschluesselungDS.class (dynamisch wegen Abwärtskompatibilität)
setXRechnungDocument(XRechnungDocument<? extends Modifiable<Long>> xRechnungDocument)	BO für Rechnungsdokumente	Gemäß Integrationspunkt-Konfiguration (Rechnungsdokumente)
setXRechnungGeneralDocument()	Falls aufgerufen, wird nuclos_generalsearchdocument als BO für Rechnungsdokumente verwendet (nur mit Statusmodell möglich)	Nicht gesetzt
setValidateXml(boolean validateXml)	Gibt an, ob die erzeugte xml-Datei validiert werden soll	true
setGenerateHtml(boolean generateHtml)	Gibt an, ob die html-Ansicht erstellt werden soll	true
setxRechnungPrefix(String xRechnungPrefix)	Präfix für XRechnungs-Dateien	"XRechnung_"
setZugferdPrefix(String zugferdPrefix)	Präfix für ZUGFeRD-Dateien	"ZUGFeRD_"
setAddDefaultNamespaceURI(boolean addDefaultNamespaceURI)	Gibt an, ob die Hauptelemente der XML-Struktur NameSpace-Präfixe haben	false (Präfixe werden genannt)
setParameterMap(Map<String, Object> parameterMap)	Erlaubt die Übergabe weiterer Parameter an die Datenquellen	Ein Eintrag "intid" mit INTID der Rechnung
setZfPdfMetaFilename(String zfPdfMetaFilename)	PDF-Metadaten für ZUGFeRD	"xrechnung.xml"
setZfPdfMetaDescription(String zfPdfMetaDescription)		"ZUGFeRD XML invoice"
setZfPdfMetaNamespaceURI(String zfPdfMetaNamespaceURI)		"urn:zugferd:pdfa:CrossIndustryDocument:invoice:2p0#"
setZfPdfMetaNamespacePrefix(String zfPdfMetaNamespacePrefix)		"zf"
setZfPdfMetaConformanceLevel(String zfPdfMetaConformanceLevel)		"EN 16931"
setZfPdfMetaDocumentType(String zfPdfMetaDocumentType)		"INVOICE"
setZfPdfMetaVersion(String zfPdfMetaVersion)		"2p0"

Nuclet-Struktur

Es werden zwei Nuclets benötigt:

• org.nuclet.xrechnung: Haupt-Nuclet zur Erzeugung von elektronischen Rechnungen
• org.nuclet.xrechnung.datenquellen: Nuclet zur Definition der Datenquellen, die je Projekt anpasst werden sollten. Dieses Nuclet wird von ersterem benötigt und sollte einmalig als Vorlage importiert werden.
  
  

Hinweis
Sollte beim Nuclet-Import bereits eine vorherige Version 1 mit projektspezifisch angepassten Datenquellen im Zielsystem vorhanden sein, müssen diese vorab gesichert und im Anschluss an den Import erneut geändert werden. Für zukünftige Aktualisierungen genügt dann der Import des Haupt-Nuclets, bei dem die Datenquellen unverändert bleiben.

Hinweis
title Version 2.1.2
In der Version 2.1.2 ist eine (optionale) Datenquelle für die Umsatzsteueraufschlüsselung ("Ausgangsrechnung XRechnung Umsatzsteueraufschlüsselung") hinzugekommen. Bei Bedarf kann diese z.B. per Import mit vorheriger Sicherung der bisherigen Datenquellen-Inhalte hinzugefügt werden.

PDF-Erzeugung über ein Formular für ZUGFeRD

Das in Nuclos integrierte JasperReports ermöglicht die Erzeugung von PDF-Dateien im Format PDF-A1. Dafür müssen folgende Einstellungen in der Vorlage vorgenommen werden - Schriftart und ICC-Profil sind bereits im Haupt-Nuclet enthalten.

Codeblock
language xml
<property name="net.sf.jasperreports.export.pdfa.conformance" value="pdfa1a" /> <property name="net.sf.jasperreports.export.pdfa.icc.profile.path" value="org/xre/icc/sRGB2014.icc" /> <style name="default" isDefault="true" fontName="xreLibSans"/>

Hinweis

Beim Erstellen der Jasper-Vorlage sollte darauf geachtet werden, dass keine Schriftarten vorgegeben werden, die nicht eingebettet werden können. So führt beispielweise folgende Angabe zu einem Fehler bei der Erzeugung von PDF-Dateien im Format PDF-A1. <fontsize="10"isBold="true"pdfFontName="Helvetica-Bold"/> Diese sollte wie folgt ersetzt werden (die mitgelieferten Schriftarten werden über den default-Stil automatisch eingebettet). <fontsize="10"isBold="true"/>

Integration

Die Integration nach erfolgtem Nucletimport (siehe Nuclet Import) ist wie folgt vorzunehmen.

Schritt	Beschreibung	Screenshot
1	Nach Import beider Nuclets muss die Serverinstanz neu gestartet werden, da das Haupt-Nuclet eigene Extensions enthält.
2	Es werden drei Businessobjekte benötigt, die unter Konfiguration → Integrationspunkt eingebunden werden müssenkönnen Rechnung Rechnungsdokument [optional] Rechnungsempfänger (Kunde) [optional] Dokumente (generalsearchdocument) [optional]	Image Removed Image Added Image Added
3	Außerdem muss es noch ein Businessobjekt für die Rechnungspositionen geben, dieses wird aber nicht für die Integrationspunkte benötigt.
4	Das zweite Nuclet enthält außerdem drei vier Datenquellen (Konfiguation → Datenquellen → Report & Formular), die noch an die jeweiligen Gegebenheiten angepasst werden müssen. Ausgangsrechnung XRechnung Ausgangsrechnung XRechnung Positionen Ausgangsrechnung XRechnung Kommentare Ausgangsrechnung XRechnung Umsatzsteueraufschlüsselung (optional ab 2.1.2) Diese liefern die eigentlichen Daten zur Erzeugung der elektronischen Rechnung. Ein Beispiel ist im angehängten angehängten Beispiel-Nuclet verfügbar. Die Zuordnung der Datenfelder zu den Inhalten der elektronischen Rechnung erfolgt gemäß Standard XRechnung, es wird jedoch nur ein Teil der verfügbaren Felder unterstützt (siehe Datenquellen bzw. Testfallgruppe_01.xlsx).	Image RemovedImage Added
5	Danach kann die Regel ErzeugeERechnung oder eine eigene Implementierung (hier: ErzeugeBeispielERechnung) mit dem entsprechenden Businessobjekt verknüpft (Konfiguration → Server Regelmanager) und über einen Knopf (Button) im Layout (Konfiguration → Layout) eingebunden werden. Die Regeln zur Validierung der Leitweg-ID werden automatisch mit dem Businessojekt Rechnungsempfänger verknüpft.
6	Im Falle valider Daten werden über den Knopf die oben beschriebenen vier Dateien erzeugt und das Ergebnis in einer Meldung präsentiert.