JavaScript-Bibliothek agorum.electronic.invoicing/js/lib/e-invoice

Diese JavaScript-Bibliothek bietet eine umfassende Lösung zur Verarbeitung und Erstellung von elektronischen Rechnungen. Sie ermöglicht das Parsen von Rechnungsdaten in PDFs und XML-Dateien, die Validierung von XRechnungen gegen XML-Schemas und die Erstellung von Rechnungsdokumenten aus normalisierten Daten. Mithilfe dieser Bibliothek können Sie selbst bestimmen, wie E-Rechnungen verarbeitet werden.

Für einen Überblick zu möglichen Einsatzszenarien siehe Mit agorum core electronic invoicing arbeiten.

Verwendung

---

Binden Sie die Bibliothek stets am Anfang eines Skripts ein:

let eInvoice = require('/agorum/roi/customers/agorum.electronic.invoicing/js/lib/e-invoice');

Funktionen

---

check

Die Funktion prüft, ob es sich bei dem übergebenen Objekt um eine elektronische Rechnung handelt. Wenn es sich um eine E-Rechnung handelt, bestimmt die Funktion außerdem das E-Rechnungsformat. Das Ergebnis ist ein CheckResult-Objekt, das die Validität und ggf. den Typ der Rechnung beschreibt.

Syntax

check(object)

Parameter

Parameter	Beschreibung	Pflicht	Standard
object	Das zu überprüfende Objekt.	ja	–

Beispiel

let objects = require('common/objects');
let eInvoice = require('/agorum/roi/customers/agorum.electronic.invoicing/js/lib/e-invoice');
let PDF_INVOICE = '/agorum/roi/customers/agorum.electronic.invoicing/test/data/Rechnung-12345678-12983760.pdf';

eInvoice.check(objects.find(PDF_INVOICE));

Rückgabewert

Ist das übergebene Objekt keine E-Rechnung, ist das Ergebnis:

{
  "valid" : false
}

Wenn das übergebene Objekt eine E-Rechnung ist, wird zusätzlich das Format bestimmt und das Ergebnis ist etwa:

{
  "valid" : true,
  "type" : "zugferd_cii"
}

Das CheckResult-Objekt enthält:

• valid: Boolean, ob die Rechnung gültig ist.
• type: Typ der Rechnung (xrechnung_ubl, xrechnung_cii, zugferd_cii).

createInvoice

Die Funktion generiert eine elektronische Rechnung. Dazu überführt die Funktion die eingehende Struktur der normalisierten Rechnungsdaten in das angegebene E-Rechnungsformat. Folgende Daten/Angaben sind erforderlich:

• Eingangsdaten: normalisierte Rechnungsdaten
• Format: Angabe des Formats, das erzeugt werden soll: ZUGFeRD V2.2 (CII), XRechnung V3.0 (CII), XRechnung V3.0 (UBL) oder Peppol BIS3 Invoice
• PDF-Dokument, wenn die XRechnung als Anhang in das Dokument integriert werden soll (ZUGFeRD)

Syntax

createInvoice({
  data: data,
  format: 'zugferd_cii',
  attachments: [file],
});

Parameter

Parameter	Beschreibung	Pflicht	Standard
config	Die Funktion erwartet ein Konfigurationsobjekt mit folgenden Angaben: data: Die normalisierten Rechnungsdaten in JSON-Format. format: Das zu erzeugende E-Rechnungsformat xrechnung_ubl, xrechnung_cii, zugferd_cii oder peppol_ubl. attachments: Bei ZUGFeRD-Erzeugung muss die PDF-Datei angegeben werden, die als Grundlage für die Erstellung der ZUGFeRD-Rechnung verwendet werden soll. (Datei, in die die XRechnung eingebettet wird.)	ja	–

Beispiel

let objects = require('common/objects');
let eInvoice = require('/agorum/roi/customers/agorum.electronic.invoicing/js/lib/e-invoice');

let DATA = '/agorum/roi/customers/agorum.electronic.invoicing/test/data/completeDataStructure.json';
let SAMPLE_INVOICE = '/agorum/roi/customers/agorum.electronic.invoicing/test/data/Rechnung-12345678-12983760.pdf';

let sampleInvoice = objects.find(SAMPLE_INVOICE);
let copy = objects.copy(sampleInvoice, sampleInvoice.firstParent);

let data = JSON.parse(objects.find(DATA).contentString);
let invoice = eInvoice.createInvoice({
  data: data,
  format: 'zugferd_cii',
  attachments: [copy],
});

Rückgabewert

Die Funktion gibt die E-Rechnung im angegeben Format zurück (PDF oder XML).

createInvoiceRaw

Die Funktion generiert eine XRechnung. Dazu überführt die Funktion die eingehende Struktur der normalisierten Rechnungsdaten in das angegebene XRechnungs-Format. Folgende Daten/Angaben sind erforderlich:

• Eingangsdaten: normalisierte Rechnungsdaten
• Format: Angabe des Formats, das erzeugt werden soll: ZUGFeRD V2.2 (CII), XRechnung V3.0 (CII) oder XRechnung V3.0 (UBL) oder Peppol BIS3 Invoice
• Attachments: Dateien, die als Anhänge (base64-codiert) in die XML-Datei geschrieben werden

Syntax

createInvoiceRaw({
  data: data,
  format: 'zugferd_cii',
  attachments: [file],
});

Parameter

Parameter	Beschreibung	Pflicht	Standard
config	Die Funktion erwartet ein Konfigurationsobjekt mit folgenden Angaben: data: Die normalisierten Rechnungsdaten in JSON-Format. format: Das zu erzeugende E-Rechnungsformat xrechnung_ubl, xrechnung_cii, zugferd_cii oder peppol_ubl. attachments: Dateien, die als Anhänge (base64-codiert) in die XML-Datei geschrieben werden.	ja	–

Beispiel

let objects = require('common/objects');
let eInvoice = require('/agorum/roi/customers/agorum.electronic.invoicing/js/lib/e-invoice');

let DATA = '/agorum/roi/customers/agorum.electronic.invoicing/test/data/completeDataStructure.json';
let SAMPLE_INVOICE = '/agorum/roi/customers/agorum.electronic.invoicing/test/data/Rechnung-12345678-12983760.pdf';

let sampleInvoice = objects.find(SAMPLE_INVOICE);
let copy = objects.copy(sampleInvoice, sampleInvoice.firstParent);

let data = JSON.parse(objects.find(DATA).contentString);
let invoice = eInvoice.createInvoiceRaw({
  data: data,
  format: 'xrechnung_ubl',
  attachments: [copy],
});

Rückgabewert

Die Funktion gibt die E-Rechnung im angegebenen Format zurück (XML im CII-Format oder im UBL-Format).

createView

Die createView-Funktion generiert ein Dokument aus Rechnungsdaten unter Verwendung einer angegebenen Dokumentvorlage. Dazu sind die Angabe der Parameter data (Rechnungsdaten in der normalisierten Form) und template (Angaben zur Verwendung des Dokumenttemplates) erforderlich. Wenn die Parameter festlegen, dass ein PDF erzeugt werden soll, wird ein PDF-Dokument erzeugt, andernfalls ein Word-Dokument (in docx-Format). Die Datei, in die das PDF oder DOCX geschrieben werden soll, muss dafür angegeben werden.

Für weitere Informationen zum Rechnungstemplate siehe Beispielvorlage als Grundlage für eigene Dokumentvorlagen verwenden.

Syntax

createView({
  data: data,
  template: {
    outputDoc: outputDoc,
    templateDoc: templateDoc, 
    createPdf: true,
    datePattern: 'dd-MM-yyyy',
    numberFormat: 'de-CH',
  },
})

Parameter

Parameter	Beschreibung	Pflicht	Standard
data	Rechnungsdaten in normalisierter Form	ja	–
template	Angaben für das zu verwendende Dokumenttemplate zur Rechnungsanzeige, bestehend aus: outputDoc: Pfad oder ID des Ausgabedokuments. templateDoc: Pfad oder ID des Templates. createPdf: Angabe, ob ein PDF erzeugt werden soll (true) oder ein DOCX (false). datePattern: Datumsformat für die generierte Rechnungsdarstellung (optional, Standard ist die Trennung mit Punkten). numberFormat: Angabe eines Gebietsschemas für das Zahlenformat, wenn der Standard de-DE überschrieben werden soll, für eine Liste der möglichen Werte siehe Gebietsschema: Sprachcodes und Ländercodes.	ja	-

Beispiel

let objects = require('common/objects');
let eInvoice = require('/agorum/roi/customers/agorum.electronic.invoicing/js/lib/e-invoice');

let doc = objects.find('/agorum/roi/customers/agorum.electronic.invoicing/test/data/Invoice_UBL_Generated.xml');
let result = eInvoice.parse(doc);
let data = result.data;

let outputDoc = objects.create('file', {
  name: 'test-123.pdf',
  target: objects.find('home:MyFiles'),
});

eInvoice.createView({
  data: data,
  template: {
    outputDoc: outputDoc,
    templateDoc: '8ee9db31-69c1-11ef-94e4-02420a0a0010',
    createPdf: true,
    datePattern: 'dd-MM-yyyy',
    numberFormat: 'de-CH',
  },
});

Rückgabewert

Die createView-Funktion gibt die ID des generierten Objekts zurück, etwa:

1678804

parse

Die Funktion parst das übergebene Objekt basierend auf seiner Dateiendung (PDF oder XML) und erstellt ein ParseResult-Objekt, das die geparsten Daten in normalisierter Form und Dateianhänge enthält. Die parse-Funktion überführt die Daten in das normalisierte agorum-Format und bereitet damit die Möglichkeit zur weiteren Verwendung oder Anzeige der Daten vor.

Die parse-Funktion extrahiert bei PDF-Dateien zunächst den XML-Anhang. Die übergebene XML-Datei oder der extrahierte XML-Anhang wird auf das verwendete XRechnungs-Format überprüft. Abhängig vom erkannten XRechnungs-Format erfolgt die Konvertierung in die normalisierten agorum-Daten. Wenn die XRechnung eingebettete Dateien enthält, werden diese in ihrem Ursprungsformat als Anhänge in den angegebenen Zielordner geschrieben. Wenn die Eingangsdatei ein ZUGFeRD-PDF war, wird die PDF-Datei als Attachment hinterlegt.

Wenn es sich bei dem übergebenen Objekt nicht um ein PDF- oder XML-Format handelt, das XML nicht wohlgeformt ist, wird ein Fehler geworfen. Das passiert auch, wenn das XML-Wurzelelement nicht eines der bekannten Wurzelelemente von CII (CrossIndustryInvoice) oder UBL (Invoice oder CreditNote) ist oder ein ZUGFeRD 1.0-Rechnungsdokument (alte CII-Version) erkannt wird.

Syntax

parse(object)

Parameter

Parameter	Beschreibung	Pflicht	Standard
object	Das E-Rechnungs-Objekt mit den zu normalisierenden Daten.	ja	–
config	Ein Konfigurationsobjekt, das zusätzliche Angaben für das Parsen der Daten enthält: target dient zur Angabe des Zielordners für die extrahierten Anhänge. Wenn kein Zielpfad angegeben ist, werden die Anhänge nicht extrahiert. validate ist ein Boolean-Parameter, der bestimmt, ob die extrahierten Daten validiert werden sollen. Der Standardwert ist false. Wenn der Wert true ist, wird die Funktion validateInvoice auf das Objekt angewendet.	nein	-

Beispiel

let objects = require('common/objects');
let eInvoice = require('/agorum/roi/customers/agorum.electronic.invoicing/js/lib/e-invoice');

let CII = '/agorum/roi/customers/agorum.electronic.invoicing/test/data/Invoice_CII_Generated.xml';

let data = eInvoice.parse(objects.find(CII), {
  target: '/agorum/roi/test',
  validate: true,
});

data;

Rückgabewert

Die parse-Funktion gibt ein ParseResult-Objekt zurück, das folgende Daten enthält:

{
  "attachments" : [ 1678369 ],
  "data" : { 
    "agorum_accounting_document_delivery_postcalcode" : "54321",
    "agorum_accounting_document_due_date" : "2023-12-31T11:00:00.000Z",
    "agorum_accounting_document_total_tax_rate_1" : 19.0,
    …
  },
  "raw" : { },
  "source" : 1584276,
  "validation" : {
    "structure" : [ ],
    "content" : { }
  }
}

Das Ergebnis des Parsens besteht aus:

• data: Das Ergebnis des Parses: die normalisierten Daten.
• raw: Die Eingangsdaten, die XML-Struktur konvertiert nach JSON.
• attachments: Liste der IDs von extrahierten Attachments.
• source: ID des übergebenen Dokumentobjekts.
• validation: Optional das Ergebnis der Validierung.

validate

Die Funktion überprüft, ob eine gegebene XML-Struktur eine gültige XRechnung ist.

Die übergebene XML-Struktur wird gegen die aktuell vorhandenen, offiziellen Definitionen der verschiedenen Formate validiert. Die offiziellen Definitionen sind:

• XML Schema für XRechnung CII (CrossIndustryInvoice_100pD16B.xsd)
• XML Schema für XRechnung UBL (UBL-Invoice-2.1.xsd)

Der Knoten erkennt, um welches XML-Format es sich handelt.

Wenn es sich bei dem übergebenen Objekt nicht um ein XML-Format handelt, das XML nicht wohlgeformt ist oder ein XML in einem anderen Format als den unterstützten XRechnungs-Formaten ist, wird ein Fehler geworfen.

Syntax

validate(object)

Parameter

Parameter	Beschreibung	Pflicht	Standard
object	Das zu validierende Objekt.	ja	–

Beispiel

let objects = require('common/objects');
let eInvoice = require('/agorum/roi/customers/agorum.electronic.invoicing/js/lib/e-invoice');
let SAMPLE_INVOICE = '/agorum/roi/customers/agorum.electronic.invoicing/test/data/INVOICE_ubl_XBUND.xml';
let sampleInvoice = objects.find(SAMPLE_INVOICE);
let validation = eInvoice.validate(sampleInvoice);

validation;

Rückgabewert

Wenn die Prüfung erfolgreich ist, ist das Ergebnis:

[]

Sonst wird ein Array von ValidationError-Objekten zurückgegeben, die Validierungsfehler beschreiben.

[ {
  "level" : "Error",
  "line" : 1,
  "column" : 768,
  "message" : "cvc-complex-type.2.4.a: Invalid content was found starting with element 'rsm:SupplyChainTradeTransaction'. One of '{\"urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100\":ExchangedDocument}' is expected."
}, {
  "level" : "Error",
  "line" : 1,
  "column" : 369413,
  "message" : "cvc-complex-type.2.4.a: Invalid content was found starting with element 'ram:SpecifiedTradeSettlementPaymentMeans'. One of '{\"urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100\":SpecifiedFinancialAdjustment, \"urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100\":InvoiceReferencedDocument, \"urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100\":ProFormaInvoiceReferencedDocument, \"urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100\":LetterOfCreditReferencedDocument, \"urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100\":FactoringAgreementReferencedDocument, \"urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100\":FactoringListReferencedDocument, \"urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100\":PayableSpecifiedTradeAccountingAccount, \"urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100\":ReceivableSpecifiedTradeAccountingAccount, \"urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100\":PurchaseSpecifiedTradeAccountingAccount, \"urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100\":SalesSpecifiedTradeAccountingAccount, \"urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100\":SpecifiedTradeSettlementFinancialCard, \"urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100\":SpecifiedAdvancePayment, \"urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100\":UltimatePayeeTradeParty}' is expected."
} ]

Die Beschreibung eines Validierungsfehlers besteht aus:

• level: Schweregrad des Fehlers (Warning, Error oder FatalError)-
• line: Zeilennummer des Fehlers.
• column: Spaltennummer des Fehlers.
• message: Beschreibung des Fehlers. Die Beschreibung enthält die Fehlerbeschreibung der XML-Validierung.

validateInvoice

Die Funktion überprüft, ob ein gegebenes Objekt eine gültige elektronische Rechnung ist. Das übergebene Objekt kann ein PDF- oder ein XML-Format sein.

Die übergebene XML-Struktur wird gegen die aktuell vorhandenen, offiziellen Definitionen der verschiedenen Formate validiert. Die offiziellen Definitionen sind:

• XML Schema für XRechnung CII (CrossIndustryInvoice_100pD16B.xsd)
• XML Schema für XRechnung UBL (UBL-Invoice-2.1.xsd)

Die Funktion erkennt, um welches XML-Format es sich handelt.

Zusätzlich zur Schema-Validierung führt die Funktion validateInvoice auch eine rudimentäre inhaltliche Validierung durch (Geschäftslogik). Die inhaltliche Validierung umfasst:

• Fehlende oder unzulässige Felder: Sicherstellen, dass alle erforderlichen Felder vorhanden sind und dass keine unzulässigen Felder existieren.
• Numerische Konsistenz: Überprüfen der Konsistenz von numerischen Feldern wie Netto- und Bruttobeträge, Steuersätze und Mengen. etwa Überprüfung, ob net_price * quantity innerhalb einer Toleranz von net_amount liegt.
• Datumsvalidierung: Überprüfen von Datumsfeldern auf korrektes Format und logische Konsistenz (etwa invoice_period_from_date muss vor invoice_period_until_date liegen).

Wenn es sich bei dem übergebenen Objekt nicht um ein PDF- oder XML-Format handelt, das XML nicht wohlgeformt ist oder ein XML in einem anderen Format als den unterstützten XRechnungs-Formaten ist, wird ein Fehler geworfen.

Syntax

validateInvoice(object)

Parameter

Parameter	Beschreibung	Pflicht	Standard
object	Das zu validierende Objekt.	ja	–

Beispiel

let objects = require('common/objects');
let eInvoice = require('/agorum/roi/customers/agorum.electronic.invoicing/js/lib/e-invoice');

let SAMPLE_INVOICE = '/agorum/roi/customers/agorum.electronic.invoicing/test/data/Rechnung-12345678-12983760.pdf';
let sampleInvoice = objects.find(SAMPLE_INVOICE);
let validation = eInvoice.validateInvoice(sampleInvoice);

validation;

Rückgabewert

Wenn die Prüfung erfolgreich ist, ist das Ergebnis:

[]

Sonst wird ein Array von ValidationError-Objekten zurückgegeben, die Validierungsfehler beschreiben.

[ { "level": "Error", "line": 2, "column": 122, "message": "cvc-complex-type.2.4.a: Invalid content was found starting with element 'cac:DespatchDocumentReference'. One of '{\"urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2\":AdditionalDocumentReference, \"urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2\":ProjectReference, \"urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2\":Signature, \"urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2\":AccountingSupplierParty}' is expected." } ]

Die Beschreibung eines Validierungsfehlers besteht aus:

• level: Schweregrad des Fehlers (Warning, Error oder FatalError)
• line: Zeilennummer des Fehlers.
• column: Spaltennummer des Fehlers.
• message: Beschreibung des Fehlers. Die Beschreibung enthält die Fehlerbeschreibung der XML-Validierung.

Weitere Hilfsfunktionen

Die Bibliothek enthält auch mehrere Hilfsfunktionen, die intern von den anderen Funktionen verwendet werden, um spezifische Aufgaben wie das Parsen von XML- bzw. PDF-Inhalten oder die Konvertierung von Daten von einem Format in ein anderes durchzuführen:

• getType(data): Bestimmt das Rechnungsformat anhand der XML-Root-Elemente.
• getInvoiceType(object, data): Bestimmt das spezifische Rechnungsformat basierend auf dem Objekt und den extrahierten Daten.
• convertPositionItems(positions, data): Konvertiert Positionsdaten in einer Rechnung.
• convertOptionalItems(invoiceData): Konvertiert optionale Rechnungsdaten.
• convertTaxRates(invoiceData): Konvertiert bestehende Steuersätze zu einem Array für die Rechnungsdokumente.
• parseDate(dateValue): Parsed ein Datum in ein bestimmtes Format.
• validatePositionData(positions): Validiert die Positionsdaten innerhalb einer Rechnung und stellt sicher, dass sie den Anforderungen entsprechen.
• validateInvoiceData(data): Führt die Validierung der gesamten Rechnungsdaten durch.