Durchsuchbare Dokumentation aufrufen | Zurück zur Dokumentationsübersicht

Navigation: Dokumentationen agorum core > agorum core electronic invoicing

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) oder XRechnung V3.0 (UBL)
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 oder zugferd_cii. 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)
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 oder zugferd_cii. 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:

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 oder ein XML in einem anderen Format als den unterstützten XRechnungs-Formaten ist, wird ein Fehler geworfen.

Syntax

parse(object)

Parameter

Parameter	Beschreibung	Pflicht	Standard
object	Das E-Rechnungs-Objekt mit den zu normalisierenden Daten.	ja	–
config	Die Property target dient zur Angabe des Zielordners für die extrahierten Anhänge. Wenn kein Zielpfad angegeben ist, werden die Anhänge nicht extrahiert.	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',
});

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
}

Das Ergebnis des Parsens besteht aus:

data: Das Ergebnis des Parses: die normalisierten Daten.
raw: Die Eingangsdaten, die XML-Struktur.
attachments: Liste der IDs von extrahierten Attachments.
source: ID des übergebenen Dokumentobjekts.

validate

Die Funktion überprüft, ob ein gegebenes XML-Objekt 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.

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.

Open Source DokumentenmanagementDokumentation

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

Verwendung

Funktionen

check

createInvoice

createInvoiceRaw

createView

parse

validate

validateInvoice

Open Source Dokumentenmanagement
Dokumentation