Daten im internen Format sind Ausgangspunkt für die Generierung von E-Rechnungen in allen unterstützten Ausgabeformaten. Dadurch brauchen sich Benutzerinnen und Benutzer der Software nicht mit allen Details anderer Formate beschäftigen und können sich dadurch auf lediglich eins fokussieren.
Kenntnisse über JSON sind definitiv ein Plus beim Lesen dieser Dokumentation. XML-Know-How ist auch ein Plus, aber weniger wichtig.
Tatsächlich gibt es gerade einmal zwei mögliche Syntaxen für E-Rechnungen, die dem Europäischen Standard EN16931 entsprechen, nämlich UBL und CII. UBL wurde gewählt, weil die Syntax gut dokumentiert und im Vergleich zu CII weniger komplex ist.
Nachteil der Sache ist, dass es zur Zeit nicht möglich ist, Informationen zu übermitteln, die in CII aber nicht in UBL vorgesehen sind. Das kann sich möglicherweise in der Zukunft noch ändern.
Mit der Universal Business Language UBL kann eine Vielzahl von Geschäftsdokumenten ausgedrückt werden. Eine dieser Dokumenttypen sind UBL-Rechnungen. Der UBL-Standard wird von der Organisation OASIS Open gepflegt.
Peppol (Pan-European Public Procurement OnLine) ist eine Initiative der Europäischen Union, die die Standardisierung grenzüberschreitender Beschaffungsprozesse zum Zeil hat. Peppol gibt die Business Interoperability Specifications (BIS), aktuell in der Version 3.0 heraus. Eine dieser Spezifikationen ist die für UBL-Rechnungen.
Die Spezifikation basiert auf der obengenannten UBL-Spezifikation von OASIS Open ist aber nicht identisch. Diese Dokumente bezeichnet daher die Peppol-BIS UBL-Rechnungen als Peppol UBL.
Die Dokumentation der UBL-Rechnung steht sowohl als einzelne HTML-Seite als auch als mehrseitiger, klilckbarer Baum zur Verfügung.
Die Einzelseite eignet sich gut zum Suchen, während die mehrseitige Version leichter zu benutzen und zu verstehen ist.
Da es sich bei UBL um ein XML-Format handelt, ist das zugrundeliegende Denkmodell das Document Object Model (DOM). Die Software E-Invoice-EU setzt allerdings stattdessen auf JSON. Der wichtigste strukturelle Unterschied zu XML - jedenfalls im Kontext von Peppol UBL - ist die Verfügbarkeit von Arrays (Listen) in JSON.
Die Struktur von Peppol UBL besteht aus Knoten, also Elementen, die Unterelemente haben und Blättern, also Elementen, die keine Unterelemente haben.
Knoten haben ein Namespace-Präfix cac, zum Beispiel das Element
cac:AccountingSupplierParty, das die Ausstellerin einer Rechnung beschreibt. Innerhalb der Definition findet sich die Postadresse der Lieferantin und als Teil davon das Element für die Stadt cbc:CityName, bei dem es sich um ein Blatt handelt, weil es keine Unterlemente hat. Wie alle anderen Blätter hat es ein Namespace-Präfix cbc.
Die Dokumentation von Peppol UBL gibt für jedes Element eine Kardinalität an. Die Kardinalität bestimmt, wie oft ein bestimmtes Element an einer bestimmten Stelle erscheinen darf. Die Kardinalität wird mit zwei durch zwei Punkten getrennten Ganzzahlen angegeben, zum Beispiel 0..2. Die erste Zahl gibt die Mindestanzahl und die zweite Zahl die Höchstzahl an Vorkommen an. Ist die zweite Zahl der Buchstabe n, wie zum Beispiel in 0..n, ist eine beliebige Anzahl von Vorkommen erlaubt.
Die folgende Tabelle listet typische Kardinalitäten auf.
| Kardinalität | Bedeutung |
|---|---|
1..1 |
Ein Pflichtelement, zum Beispiel die zu zahlende Summe einer Rechnung. |
0..1 |
Ein optionales Element, zum Beispiel eine Anzahlung. |
1..n |
Eine Liste als Pflichtelement mit einer beliebigen Anzahl an Elementen, zum Beispiel die Rechnungspositionen |
0..n |
Eine optionale Liste mit einer beliebigen Anzahl an Elementen, zum Beispiel die Zu- und Abschläge auf Dokumentenebene |
1..2 |
Eine Liste als Pflichtelement mit maximal zwei Elementen, zum Beispiel die Steuersummen |
0..2 |
Eine optionale Liste mit maximal zwei Elementen, zum Beispiel die Steuerschemata einer Rechnungspartei |
Daumenregeln: Ist die erste Zahl 0 handelt es sich um ein optionales Element, ansonsten ist es obligatorisch, also ein Pflichtelement. Ist die zweite Zahl größer oder gleich 2 oder ist sie n, haben wir es mit einer Liste zu tun.
XML-Elemente können Attribute besitzen, welche den Wert des Elements weiter beschreiben. Zum Beispiel hat die fällige Summe einer Rechnung das obligatorische Attribut @currencyID, das die abgekürzte Währungsbezeichnung der Summe angbit. In der Spalte „Use“ des Abschnitts „attributes“ in der Dokumentation gibt der Buchstabe M an, dass es sich um ein obligatorisches Attribut handelt, es also angegeben werden muss.
Die Firmen-ID hat ein optionales Attribute schemeID. Dies wird durch den Buchstaben O in der Spalte „Use“ angegeben.
Viele Felder können keine beliebigen Werte aufnehmen sondern sind auf eine Auswahl aus einer Liste beschränkt. Diese Listen werden als Code-Listen bezeichnet. So muss zum Beispiel der [zu zahlende Rechnungsbetrag(https://docs.peppol.eu/poacc/billing/3.0/syntax/ubl-invoice/cac-LegalMonetaryTotal/cbc-PayableAmount/) eine Währungsbezeichnung haben und der Wert des entsprechenden Attributs @currencyID ist auf die Code-Liste ISO 4217 Currency codes beschränkt. Diese Information kann man erhalten, indem man erst auf den Element- oder Attributnamen und dann auf Namen der Code-Liste im Abschnitt „Code lists“ klickt. Die Seite der Code-Liste listet die möglichen Werte im Abschnitt „Codes“. Oft ist ees so, dass man ein wenig scrollen muss, um zur Werteliste zu gelangen.
Weil E-Invoice-EU JSON und nicht XML benutzt, muss das Peppol UBL in JSON transformiert werden.
Die Transformation von XML nach JSON in E-Invoice-EU ist logisch und unkompliziert, und schwerer zu erklären als zu verstehen.
Die XML-Struktur wird durch die Befolgung einfacher Regeln vorgenommen:
Die Angabe des Namens der Ausstellerin einer Rechnung im folgenden unvollständige Fragment einer UBL-Rechnung als XML-Dokument mag das verdeutlichen:
<ubl:Invoice>
<cac:AccountingSupplierParty>
<cac:Party>
<cbc:PartyName>
Acme Ltd.
</cbc:PartyName>
</cac:Party>
</cac:AccountingSupplierParty>
</ubl:Invoice>In JSON stellt sich der gleiche Sachverhalt so dar:
{
"ubl:Invoice": {
"cac:AccountingSupplierParty": {
"cac:Party": {
"cbc:PartyName": "Acme Ltd."
}
}
}
}Jedes XML-Element wird eine Eigenschaft des JSON-Objekts und die Hierarchie bleibt unverändert. Der Textinhalt von <cbc:PartyName wird zur Zeichenkette „Acme Ltd.“ in JSON.
In XML fehlt das Konzept von Listen bzw. Arrays. Stattdessen werden Elemente einfach wiederholt. Das lässt sich an Rechnungspositionen zeigen:
<ubl:Invoice>
<cac:InvoiceLine>
<cbc:ID>1</cbc:ID>
<cbc:AccountingCost>100:1</cbc:AccountingCost>
</cac:InvoiceLine>
<cac:InvoiceLine>
<cbc:ID>2</cbc:ID>
<cbc:AccountingCost>200:2</cbc:AccountingCost>
</cac:InvoiceLine>
<cac:InvoiceLine>
<cbc:ID>3</cbc:ID>
<cbc:AccountingCost>300:3</cbc:AccountingCost>
</cac:InvoiceLine>
</ubl:Invoice>Es gibt drei Element cac:InvoiceLine. Es handelt sich also um eine Liste.
Die Transformierung nach JSON ist logisch:
{
"ubl:Invoice": {
"cac:InvoiceLine": [
{
"cbc:ID": "1",
"cbc:AccountingCost": "100:1",
},
{
"cbc:ID": "2",
"cbc:AccountingCost": "200:3",
},
{
"cbc:ID": "3",
"cbc:AccountingCost": "300:3",
},
]
}
}Weil cac:InvoiceLine ein Array ist (es hat eine Kardinalität von 1..n), wird es auch in JSON als Array dargestellt. Und die Listenelemente sind einfach die Unterknoten von cac:InvoiceLine.
Selbst wenn es nur ein einziges Listenelement gibt, muss dennoch ein JSON-Array verwendet werden. Einzelwerte werden nicht automatisch in Array konvertiert. Dies ist inbesonde dann wichtig, wenn es auf den ersten Blick überraschend ist, dass ein Feld ein Array ist. Das ist zum Beispiel bei der Steuersummierung einer Rechnung der Fall.
Einige Elemente haben Attribute:
<ubl:Invoice>
<cac:LegalMonetaryTotal>
<cbc:PayableAmount currencyID="EUR">23.04</cbc:PayableAmount>
</cac:LegalMonetaryTotal>
</ubl:Invoice>JSON kennt keine Attribute. Stattdessen wird an den Namen des Elements ein Klammeraffer @ und der Name des Attributs angehangen:
{
"ubl:Invoice": {
"cac:LegalMonetaryTotal": {
"cbc:PayableAmount": "23.04"
"cbc:PayableAmount@currencyID": "EUR"
}
}
}Es ist wichtig, dass für alle Werte Strings verwendet werden müssen, selbst, wenn es sich um Zahlen handelt. Das lässt sich aus den obigen Beispielen ersehen.
Es ist nicht wichtig, sich exakt an alle Details zu erinnern. Der Service steigt mit einer Fehlermeldung aus, wenn die Struktur der Eingabedaten nicht dem Schema entsprechen.
Wer mit JSON Schema vertraut ist, kann auch auf die Schemadefinition zurückgreifen. Sie ist im GitHub-Repository E-Invoice-EU oder als REST-Endpunkt /api/schema/invoice verügbar.
Die einzigen Unterschiede zu Peppol UBL sind zur Zeit, dass die Felder
cbc:CustomizationID
und
cbc:ProfileID optional sind. Der Grund dafür ist, dass sie aus dem Ausgabeformat geschlossen werden können. Sie müssen nur angegeben werden, wenn man die eingebauten Vorgabewerte für sie überschreiben will.