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:
- Die XML-Datei
- 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:
- Lesen einer ZUGFeRD-XML-Datei in ein internes CrossIndustryDocument (in Arbeit)
- Schreiben einer ZUGFeRD-XML-Datei aus einem internen CrossIndustryDocument (realisiert)
- Setzen von Werten des internen CrossIndustryDocument über Kommandosprache (realisiert)
- Lesen von Werten vom internen CrossIndustryDocument über Kommandosprache (in Arbeit)
- 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.
Befehl | Pfad | Rückgabewert |
|---|---|---|
| 1. Set-Befehl | CrossIndustryDocument.SpecifiedSupplyChainTradeTransaction | 4 |
| 2. Set-Befehl | 4.IncludedSupplyChainTradeLineItem[0] | 0 |
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 eines Elements lassen sich zwei Befehle verwenden AddNew() und Last():
Befehl | Auswirkung |
|---|---|
| 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:
Befehl | Parameter |
|---|---|
| 1 | ID |
| 2 | Path |
| n | Value (0-N) |
Die beiden Übergabeparameter ID und Path dienen zum Adressieren eines Elements. Die ID wird selbständig zum übergebenen Pfad hinzugefügt. Alles anderen Übergabeparameter sind Values und definieren den Inhalt des Elements bzw. den Inhalt seiner Unterelemente:
Pfad: 8.ApplicableTradeTax[0]
Value | Beispiel |
|---|---|
| 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.
Objekt | Stellungsparameter | Unterobjekt |
|---|---|---|
| GuidelineSpecifiedDocumentContextParameter | 1 | ID |
| BusinessProcessSpecifiedDocumentContextParameter | 1 | ID |
| SpecifiedExchangedDocumentContext | 1 | GuidelineSpecifiedDocumentContextParameter.ID |
| IncludedNote | 1 2 3 | SubjectCode ContentCode Content[0] |
| EffectiveSpecifiedPeriod | 1 | CompleteDateTime |
| HeaderExchangedDocument | 1 2 3 4 5 n | ID Name TypeCode IssueDateTime CopyIndicator LanguageID[N] |
| SpecifiedTaxRegistration | 1 2 | ID ID.setSchemeID |
| PostalTradeAddress | Bei einem Parameter: 1 Bei mehr als einem Parameter: 1 2 3 4 5 |
Normale Adresse mit mehreren Zeilen (komplette Adresse) LineOne LineTwo PostcodeCode CityName CountryID |
| DefinedTradeContact | 1 2 3 4 5 | PersonName DepartmentName TelephoneUniversalCommunication.CompleteNumber FaxUniversalCommunication.CompleteNumber EmailURIUniversalCommunication.URIID |
| TelephoneUniversalCommunication | 1 | CompleteNumber |
| FaxUniversalCommunication | 1 | CompleteNumber |
| EmailURIUniversalCommunication | 1 | URIID |
| TradeParty | 1 2 | Name ID |
| ApplicableTradeDeliveryTerms | 1 | DeliveryTypeCode |
| ApplicableSupplyChainTradeAgreement | 1 | BuyerReference |
| ActualDeliverySupplyChainEvent | 1 | OccurrenceDateTime |
| SpecifiedLogisticsTransportMovement | 1 2 | ModeCode ID |
| Indicator | 1 | YES|NO |
| DateTime | 1 | German or ISO-Date |
| DateMandatoryDateTime | 1 | German or ISO-Date |
| schemeIDType | Bei einem Parameter: 1
Bei mehr als einem Parameter: 1 2 |
ID[,schemeID] ID schemeID |
| schemeAgencyID | Bei einem Parameter: 1
Bei mehr als einem Parameter: 1 2 |
D[,schemeAgencyID] ID schemeAgencyID |
| QuantityType | Bei einem Parameter: 1
Bei mehr als einem Parameter: 1 2 |
SignValueUnit SignValue Unit |
| MeasureType | Bei einem Parameter: 1
Bei mehr als einem Parameter: 1 2 |
SignValueUnit SignValue Unit |
| ClassCode | Bei einem Parameter: 1
Bei zwei Parametern: 1 2
Bei mehr als zwei Parametern: 1 2 3 |
Value[,listID[,listVersionID]] Value listID Value listID listVersionID |
| ApplicableTradeTax | 1 2 3 4 5 6 7 8 | CalculatedAmount TypeCode BasisAmount ApplicablePercent ExemptionReason LineTotalBasisAmount AllowanceChargeBasisAmount CategoryCode |
| TradeTax | 1 2 3 | TypeCode CategoryCode ApplicablePercent |
| BillingSpecifiedPeriod | 1 2 | StartDateTime EndDateTime |
| PayeeSpecifiedCreditorFinancialInstitution | 1 2 3 | BICID GermanBankleitzahlID Name |
| PayeePartyCreditorFinancialAccount | 1 2 3 | IBANID AccountName ProprietaryID |
| PayerSpecifiedDebtorFinancialInstitution | 1 2 3 | BICID GermanBankleitzahlID Name |
| PayerPartyDebtorFinancialAccount | 1 2 | IBANID ProprietaryID |
| SpecifiedTradeSettlementPaymentMeans | 1 2 n | TypeCode ID Information[N] |
| SpecifiedTradeSettlementMonetarySummation | 1 2 3 4 5 6 7 8 | LineTotalAmount ChargeTotalAmount AllowanceTotalAmount TaxBasisTotalAmount TaxTotalAmount GrandTotalAmount TotalPrepaidAmount DuePayableAmount |
| TradeAllowanceCharge | 1 2 3 4 5 6 7 8 | ChargeIndicator SequenceNumeric CalculationPercent BasisAmount BasisQuantity ActualAmount ReasonCode Reason |
| SpecifiedLogisticsServiceCharge | 1 n | AppliedAmount Description[N] |
| ReceivableSpecifiedTradeAccountingAccount | 1 | ID |
| ApplicableSupplyChainTradeSettlement | 1 2 | PaymentReference InvoiceCurrencyCode |
| ApplicableTradePaymentPenaltyTerms | 1 2 3 4 5 | BasisDateTime BasisPeriodMeasure BasisAmount CalculationPercent ActualPenaltyAmount |
| ApplicableTradePaymentDiscountTerms | 1 2 3 4 5 | BasisDateTime BasisPeriodMeasure BasisAmount CalculationPercent ActualDiscountAmount |
| SpecifiedTradePaymentTerms | 1 2 n | DueDateDateTime artialPaymentAmountSet[0] Description[N] |
| AssociatedDocumentLineDocument | 1 | |
| ReferencedDocument | 1 2 3 4 | IssueDateTime LineID ID ReferenceTypeCode |
| GrossPriceProductTradePrice | 1 2 | ChargeAmount BasisQuantity |
| NetPriceProductTradePrice | 1 2 | ChargeAmount BasisQuantity |
| SpecifiedSupplyChainTradeDelivery | 1 2 3 | BilledQuantity ChargeFreeQuantity PackageQuantity |
| SpecifiedTradeAccountingAccount | 1 | ID |
| ApplicableProductCharacteristic | 1 2 3 n | TypeCode ValueMeasure Value Description[N] |
| DesignatedProductClassification | 1 2 | ClassCode ClassName[0] |
| IncludedReferencedProduct | 1 2 | SellerAssignedID BuyerAssignedID |
| Country | 1 | ID |
| SpecifiedTradeProduct | 1 2 3 4 5 | GlobalID SellerAssignedID BuyerAssignedID Name 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.
Überblick
Inhalte