Seitenhistorie

Herzlich Willkommen auf der Online-Dokumentationsseite des ZUGFeRD-Moduls!

Hier finden Sie alle Informationen zum ZUGFeRD-Modul.

Die Realisierung des ZUGFeRD-Standards für profiforms Produkte geschieht in einem ZUGFeRD-Modul, dass in mehreren Produkten Anwendung findet. Das ZUGFeRD-Modul ist eine Klassenbibliothek, mit allen Klassen, die der ZUGFeRD-Standard für ein CrossIndustryDocument vorsieht inkl. der dazugehörigen Hierarchie. Das oberste Element ist dabei das CrossIndustryDocument selbst, das als internes CrossIndustryDocument im RAM gehalten wird. Dabei besitzt das ZUGFeRD-Modul zwei Schnittstellen zur Interaktion mit dem internen CrossIndustryDocument:

1. Die XML-Datei
2. Eine Kommandosprache

Weiterhin kann das interne CrossIndustryDocument noch validiert bzw. auf einfache Weise auf bestimmte Eigenschaften abgefragt werden.

Folgende Funktionen sind realisiert bzw. in Arbeit:  

1. Lesen einer ZUGFeRD-XML-Datei in ein internes CrossIndustryDocument (in Arbeit)
2. Schreiben einer ZUGFeRD-XML-Datei aus einem internen CrossIndustryDocument (realisiert)
3. Setzen von Werten des internen CrossIndustryDocument über Kommandosprache (realisiert)
4. Lesen von Werten vom internen CrossIndustryDocument über Kommandosprache (in Arbeit)
5. Validieren des internen CrossIndustryDocument (realisiert)

Adressieren von Elementen der internen ZUGFeRD-XML-Datei

Die Element-Namen der ZUGFeRD-XML-Datei werden nicht in dieser Dokumentation beschrieben, da es davon Hunderte gibt. Für diesen Zweck gibt es die „Technische Dokumentation“ die als Arbeitsmittel unentbehrlich ist. In der vorliegenden Implementierung wird ein Element-Name über einen Path beschrieben, der den genauen Ort des Elements beschreibt. Dabei werden die Element-namen ohne NameSpace-Angaben durch einen Punkt aneinander gereiht.

CrossIndustryDocument.SpecifiedSupplyChainTradeTransaction.ApplicableSupplyChainTradeSettlement.SpecifiedTradeSettlementMonetarySummation.ChargeTotalAmount

Handelt es sich bei der Ortsangabe um eine Array, dann erfolgt die Angabe des Array-Elements mit eckigen Klammern und dem Index-Angabe dazwischen. Das erste Element eines Array hat als Index-Nummer die Nummer 0.  Wird ein Array-Index angesprochen, das ein nicht existierendes Element bezeichnet, so wird mit dem Befehl das fehlende Element und alle davor fehlende Elementen hinzugefügt.  

CrossIndustryDocument.SpecifiedSupplyChainTradeTransaction.IncludedSupplyChainTradeLineItem[0]

Da die Pfadnamen sehr lang werden können, gibt es mehrere Wege der Vereinfachung. Zu allererst ist es zulässig den ersten Namen CrossIndustryDocument wegfallen zu lassen, da grundsätzlich jeder Pfad-Name mit CrossIndustryDocument beginnt und er damit selbsterklärend ist.

Weiterhin gibt es Möglichkeit über IDs zu arbeiten. Jedes Element besitzt eine ID über die es angesprochen werden kann. Der Set-Befehl liefert zum entsprechenden Pfad immer die ID zurück. Zukünfige Zugriffe können dann auch über die ID erfolgen.

1. Set-Befehl

Pfad: CrossIndustryDocument.SpecifiedSupplyChainTradeTransaction

Rückgabewert: 4

2. Set-Befehl

Pfad: 4.IncludedSupplyChainTradeLineItem[0]

Rückgabewert: 5

Durch die Kombination aus ID und Pfad kann auf die Unterelemente zugegriffen werden.

Neben dem Adressieren von Elementen kann der Pfad auch für Befehle verwendet werden, die im Zusammenhang mit der Adressierung zu sehen sind.

Anstelle eine Element lassen sich zwei Befehle verwenden AddNew() und Last().

4.IncludedSupplyChainTradeLineItem.AddNew()

Fügt dem Element IncludedSupplyChainTradeLineItem ein neues Array-Element hinzu.

4.IncludedSupplyChainTradeLineItem.Last()

Adressiert das letzte Array-Element von IncludedSupplyChainTradeLineItem.

Setzen von Werten des internen CrossIndustryDocument über Kommandosprache

Das ZUGFeRD-Modul bietet einen Set-Befehl, der sehr universell verwendet werden kann.

Der Set-Befehl hat folgende Parameter:

1 ID

2 Path

n Values (0-N)

Die beiden Übergabeparamter ID und Path dienen zum Adressieren eines Elements. Die ID wird selbständig zum übergebenen Pfad hinzugefügt. Alles anderen Übergabeparamter sind Values und definieren den Inhalt des Elements bzw. den Inhalt seiner Unterelemente.

Pfad: 8.ApplicableTradeTax[0]

Value1: “19,00 €,” (CalculatedAmount)

Value2: "VAT"( TypeCode)

Value3: “100,00 €” (BasisAmount)

Value4: “19%” (ApplicablePercent)

Mit einem Set-Befehl werden gleich vier Unterelemente von ApplicableTradeTax gesetzt.

Natürlich kann auch jeder der vier Werte in einem separaten Set-Befehl gesetzt werden. Durch die Angabe spezieller Operatoren mit mehreren Werten spart man jedoch erheblich Schreibarbeit.

Dafür ist es jetzt schwerer zu verstehen, welcher Value welchen Wert setzt.

Die folgende Auflistung beschreibt, welche Element Operatoren mit mehreren Werten besitzen und der wievielte Value welches Unterelement setzt.

GuidelineSpecifiedDocumentContextParameter

1 ID

BusinessProcessSpecifiedDocumentContextParameter

1 ID

SpecifiedExchangedDocumentContext

1 GuidelineSpecifiedDocumentContextParameter.ID

2 TestIndicator

3 BusinessProcessSpecifiedDocumentContextParameter.ID

IncludedNote

1 SubjectCode

2 ContentCode

3 Content[0]

EffectiveSpecifiedPeriod

1 CompleteDateTime

HeaderExchangedDocument

1 ID

2 Name

3 TypeCode

4 IssueDateTime

5 CopyIndicator

n LanguageID[N]

SpecifiedTaxRegistration

1 ID

2 ID.setSchemeID

PostalTradeAddress

Bei einem Parameter

1 Normale Adresse mit mehreren Zeilen (komplette Adresse)

Bei mehr als einem Parameter

1 LineOne

2 LineTwo

3 PostcodeCode

4 CityName

5 CountryID

DefinedTradeContact

1 PersonName

2 DepartmentName

3 TelephoneUniversalCommunication.CompleteNumber

4 FaxUniversalCommunication.CompleteNumber

5 EmailURIUniversalCommunication.URIID

TelephoneUniversalCommunication

1 CompleteNumber

FaxUniversalCommunication

1 CompleteNumber

EmailURIUniversalCommunication

1 URIID

TradeParty

1 Name

2 ID

ApplicableTradeDeliveryTerms

1 DeliveryTypeCode

ApplicableSupplyChainTradeAgreement

1 BuyerReference

ActualDeliverySupplyChainEvent

1 OccurrenceDateTime

SpecifiedLogisticsTransportMovement

1 ModeCode

2 ID

Indicator

1 YES|NO

DateTime

1 German or ISO-Date

DateMandatoryDateTime

1 German or ISO-Date

schemeIDType

bei einem Parameter

1 ID[,schemeID]

bei mehr als einem Parameter

1 ID

2 schemeID

schemeAgencyID

bei einem Paramter

1 ID[,schemeAgencyID] 

bei mehr als einem Paramter

1 ID

2 schemeAgencyID

QuantityType

bei einem Paramter

1 SignValueUnit

bei mehr als einem Paramter

1 SignValue

2 Unit

MeasureType

bei einem Paramter

1 SignValueUnit

bei mehr als einem Paramter

1 SignValue

2 Unit

ClassCode

bei einem Parameter

1 Value[,listID[,listVersionID]]

bei zwei Paramter

1 Value

2 listID

bei mehr als zwei Parametern

1 Value

2 listID

3 listVersionID

ApplicableTradeTax

1 CalculatedAmount

2 TypeCode

3 BasisAmount

4 ApplicablePercent

5 ExemptionReason

6 LineTotalBasisAmount

7 AllowanceChargeBasisAmount

8 CategoryCode

TradeTax

1 TypeCode

2 CategoryCode

3 ApplicablePercent

BillingSpecifiedPeriod

1 StartDateTime

2 EndDateTime

PayeeSpecifiedCreditorFinancialInstitution

1 BICID

2 GermanBankleitzahlID

3 Name

PayeePartyCreditorFinancialAccount

1 IBANID

2 AccountName

3 ProprietaryID

PayerSpecifiedDebtorFinancialInstitution

1 BICID

2 GermanBankleitzahlID

3 Name

PayerPartyDebtorFinancialAccount

1 IBANID

2 ProprietaryID

SpecifiedTradeSettlementPaymentMeans

1 TypeCode

2 ID

n Information[N]

SpecifiedTradeSettlementMonetarySummation

1 LineTotalAmount

2 ChargeTotalAmount

3 AllowanceTotalAmount

4 TaxBasisTotalAmount

5 TaxTotalAmount

6 GrandTotalAmount

7 TotalPrepaidAmount

8 DuePayableAmount

TradeAllowanceCharge

1 ChargeIndicator

2 SequenceNumeric

3 CalculationPercent

4 BasisAmount

5 BasisQuantity

6 ActualAmount

7 ReasonCode

8 Reason

SpecifiedLogisticsServiceCharge

1 AppliedAmount

n Description[N]

ReceivableSpecifiedTradeAccountingAccount

1 ID

ApplicableSupplyChainTradeSettlement

1 PaymentReference

2 InvoiceCurrencyCode

ApplicableTradePaymentPenaltyTerms

1 BasisDateTime

2 BasisPeriodMeasure

3 BasisAmount

4 CalculationPercent

5 ActualPenaltyAmount

ApplicableTradePaymentDiscountTerms

1 BasisDateTime

2 BasisPeriodMeasure

3 BasisAmount

4 CalculationPercent

5 ActualDiscountAmount

SpecifiedTradePaymentTerms

1 DueDateDateTime

2 PartialPaymentAmountSet[0]

n Description[N]

AssociatedDocumentLineDocument

1 LineID

ReferencedDocument

1 IssueDateTime

2 LineID

3 ID

4 ReferenceTypeCode

GrossPriceProductTradePrice

1 ChargeAmount

2 BasisQuantity

NetPriceProductTradePrice

1 ChargeAmount

2 BasisQuantity

SpecifiedSupplyChainTradeDelivery

1 BilledQuantity

2 ChargeFreeQuantity

3 PackageQuantity

SpecifiedTradeAccountingAccount

1 ID

ApplicableProductCharacteristic

1 TypeCode

2 ValueMeasure

3 Value

n Description[N]

DesignatedProductClassification

1 ClassCode

2 ClassName[0]

IncludedReferencedProduct

1 SellerAssignedID

2 BuyerAssignedID

Country

1 ID

SpecifiedTradeProduct

1 GlobalID

2 SellerAssignedID

3 BuyerAssignedID

4 Name

5 Description

Setzen der Locale-Angaben für ZUGFeRD-XML

Das ZUGFeRD-XML-Format stellt Zahlen, Maßeinheiten und Datumsangeben nicht-lokalisiert dar.

Das bedeutet, dass die ZUGFeRD-XML-Datei von jedem interpretiert werden kann ohne Wissen über lokale Darstellungs- und Formatierungseigenheiten. Dafür fällt dem ZUGFeRD-Modul die Arbeit zu, von der lokalisierten Form und die nicht-lokalisiert zu überführen und umgekehrt.

Da die profiforms-Produkte bereits über Lokalisierungs-Funktionen verfügen, ist es lediglich erforderlich das entsprechende Locale  per Befehl zu setzen.

SetLocale(locale)

Bsp:

SetLocal("de_DE")

Zahlen und Einheiten werden auf deutsche Sprache und Deutschland umgestellt.

Validieren einer ZUGFeRD-XML

Im ZUGFeRD-Modul ist ein Validierer enthalten, der es erlaubt, das interne CrossIndustryDocument zu validieren. Der Validierer ist demnach kein XML-Validiere, der über eine XSD-Schemaprüfung arbeitet. Ganz im Gegenteil wurde auf die XSD-Schemaprüfung bewusst verzichtet, da der interne Validierer diese Aufgabe mit übernimmt.

Der Validierer prüft als erstes die in der technischen Dokumentation aufgeführte Kardinalität, die unabhängig von Status ist.

Dann ermittelt der Validierer das Profile, BASIC, COMFORT bzw. EXTENDED, aus dem internen CrossIndustryDocument.

Dem Validierer wird mit dem Validierungsbefehl ein Status zur Validierung übergebe.

Bei der Validierung wird nun überprüft, die Elemente mit Status und Profil existieren müssen und ob deren Wert korrekt ist.

Dabei sind folgende Status-Werte möglich:

REQUIRED bzw. R

ADVISED bzw. A

OPTIONAL bzw. O

DEPENDING bzw. D (noch nicht implementiert)

Das Ergebnis der Valisierung ist entweder ein Wert 0 oder 1 dafür, ob die Validierung erfolgreich war oder ein Validierungsprotokoll, dass nur einen Inhalt hat, wenn die Validierung nicht erfolgreich war.

Es wird dringend empfohlen jedes interne CrossIndustryDocument vor dem Wandeln in einen XML-String bzw. eine XML-Datei es zu validieren. Das verhindert die Weitergabe ungültiger ZUGFeRD-XML-Dateien und den daraus resultieren Stress mit den Konsumenten dieser ungültigen ZUGFeRD-XML-Dateien. Um die Validierung beim Export zu erleichtern, ist es möglich, im Schreibebefehl die Validierung mit durchzuführen. Gibt es Fehler beim Validieren, so wird die ZUGFeRD-XML-Dateie bzw. der ZUGFeRD-XML-String nicht erzeugt.    

...