Durchsuchbare Dokumentation aufrufen | Zurück zur Dokumentationsübersicht

Navigation: Dokumentationen agorum core > agorum core JavaScript-API

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

Hinweis: Diese Dokumentation bezieht sich auf die aktuellste Version des Plugins. Aktualisieren Sie das hier beschriebene Plugin, um die Dokumentation verwenden zu können.

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 andere offizielle Validatoren 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:

checkRequiredFields

Die Funktion checkRequiredFields prüft JSON-Daten darauf, ob alle Pflichtfelder für das angegebene E-Rechnungsformat enthalten sind. Die Funktion hilft dabei, JSON-Daten für die Generierung von E-Rechnungen zusammenzustellen. Folgende Daten/Angaben sind erforderlich:

 

Syntax

checkRequiredFields(data, type)

 

Parameter

Parameter Beschreibung Pflicht Standard
data Die normalisierten Daten für die E-Rechnung in JSON-Format. ja -
type Das E-Rechnungsformat, gegen das die Daten geprüft werden sollen: xrechnung_ubl, xrechnung_cii oder  zugferd_cii ja -

 

Beispiel

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

let SAMPLE_DATA = '/agorum/roi/customers/agorum.electronic.invoicing/test/data/completeDataStructure.json';

let check = eInvoice.checkRequiredFields(objects.find(SAMPLE_DATA), 'xechnung_cii');

check;

 

Rückgabewert

Wenn die JSON-Daten alle Pflichtfelder enthalten, gibt die Funktion ein leeres Array zurück.

  "checkResult" : [ ]

Enthalten die JSON-Daten nicht alle erforderlichen Informationen, gibt die Funktion Informationen über die fehlenden Daten zurück. Beispiel:

Error: agorum.api.common.exceptions.server.ApiInternalServerErrorException: Metadata field 'agorum_accounting_document_customer_endpoint_id' cannot be found. Please check if it exists.

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:

 

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 angegebenen Format zurück (PDF oder XML).

Es wird ein Fehler geworfen, wenn die erforderlichen Daten nicht zur Verfügung stehen. Wenn die JSON-Daten nicht den Anforderungen für die Erstellung einer XRechnung genügen, wird eine detaillierte Fehlermeldung zurückgegeben. Beispiel:

Error: Invoice cannot be generated due to necessary information: [
  {
    "key": "agorum_accounting_document_version_id",
    "label": "Dokumentversions-ID - Wert fehlt"
  },
  {
    "key": "agorum_accounting_document_function_code",
    "label": "Dokumentfunktions-Code - Wert fehlt"
  }
]

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:

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).

Es wird ein Fehler geworfen, wenn die erforderlichen Daten nicht zur Verfügung stehen. Wenn die JSON-Daten nicht den Anforderungen für die Erstellung einer XRechnung genügen, wird eine detaillierte Fehlermeldung zurückgegeben. Beispiel:

Error: Invoice cannot be generated due to necessary information: [
  {
    "key": "agorum_accounting_document_version_id",
    "label": "Dokumentversions-ID - Wert fehlt"
  },
  {
    "key": "agorum_accounting_document_function_code",
    "label": "Dokumentfunktions-Code - Wert fehlt"
  }
]

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/UBL_AE.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 oder 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, config)


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:

Das Validierungsergebnis enthält im Abschnitt structure das Ergebnis der formalen Überprüfung der Daten in Hinblick auf die Vollständigkeit und die Datenstruktur. Beispiel:

{
      "level" : "error",
      "information" : "Invalid content found for unknown element. Value is missing or other value is expected: .",
      "message" : "[BR-S-01]-An Invoice that contains an Invoice line (BG-25), a Document level allowance (BG-20) or a Document level charge (BG-21) where the VAT category code (BT-151, BT-95 or BT-102) is \"Standard rated\" shall contain in the VAT breakdown (BG-23) at least one VAT category code (BT-118) equal with \"Standard rated\"."
    },

Im Abschnitt content finden Sie zusätzliche Hinweise zum Dateninhalt, die das Ergebnis einfacher Plausibilitätsprüfungen sind.

  "item" : [ {
        "itemId" : "d8a0cce0-b89b-4c80-8439-cb9e97dca4a9",
        "name" : "Position 2",
        "errors" : [ {
          "level" : "ERROR",
          "message" : "net_price (6000) multiplied with quantity (2) is differing more than one cent from net_amount: 6000"
        } ]

Zusätzlich zur formalen Validierung werden auch einige rudimentäre inhaltliche Validierungen durchgeführt (Geschäftslogik). Die inhaltliche Validierung umfasst:

validate

Die Funktion überprüft, ob ein XML-Datenstrom eine gültige XRechnung ist.

Der übergebene XML-Datenstrom wird gegen den aktuellen verfügbaren KoSIT-Validator geprüft. Die Funktion 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(xmlData, config)


Parameter

Parameter Beschreibung Pflicht Standard
xmlData Der zu validierende Datenstrom. ja –
config

Eine optionale Konfiguration, die spezifiziert, ob zusätzliche Inhalte wie ein HTML-Bericht erstellt werden sollen.

createHtmlReport (boolean):
Wenn true, wird ein HTML-Bericht über die Validierung erstellt. Dieser Bericht enthält detaillierte Informationen über die Fehler und Warnungen.

 nein -


Beispiel

let objects = require('common/objects');
let eInvoice = require('/agorum/roi/customers/agorum.electronic.invoicing/js/lib/e-invoice');
let xmlData =
  '<?xml version="1.0" encoding="UTF-8"?>\n<rsm:CrossIndustryInvoice xmlns:a="urn:un:unece:uncefact:data:standard:QualifiedDataType:100" xmlns:qdt="urn:un:unece:uncefact:data:standard:QualifiedDataType:10" xmlns:ram="urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100" xmlns:rsm="urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100" xmlns:udt="urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100" xmlns:xs="http://www.w3.org/2001/XMLSchema">\n  
  …
   <rsm:CrossIndustryInvoice>\n';
let validation = eInvoice.validate(xmlData, { createHtmlReport: true });
validation;


Rückgabewert

Wenn der Parameter config gesetzt ist und angibt, dass ein HTML-Report erzeugt werden soll, wird zusätzlich die ID des erzeugten HTML-Reports zurückgegeben. Sonst wird nur das Validierungsresultat und eine Liste der Fehlermeldungen als Array zurückgegeben.

Im Falle einer erfolgreichen Prüfung ist das:

{
  "valid" : true,
  "validation" : [ ]
}

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

{
  "valid" : false,
  "validation" : [ {
    "level" : "error",
    "information" : "Invalid content found for unknown element. Value is missing or other value is expected: .",
    "message" : "[BR-AE-01]-An Invoice that contains an Invoice line (BG-25), a Document level allowance (BG-20) or a Document level charge (BG-21) where the VAT category code (BT-151, BT-95 or BT-102) is \"Reverse charge\" shall contain in the VAT Breakdown (BG-23) exactly one VAT category code (BT-118) equal with \"VAT reverse charge\"."
  } ] 
}


Die Beschreibung eines Validierungsfehlers besteht aus:

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. Zusätzlich können Sie optional angeben, wenn das Validierungsergebnis als HTML-Bericht ausgegeben werden soll.

Das XML der Rechnung wird gegen den aktuellen verfügbaren KoSIT-Validiator validiert.  Die Funktion erkennt, um welches XML-Format es sich handelt.

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, config)


Parameter

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

Eine optionale Konfiguration, die spezifiziert, ob zusätzliche Inhalte wie ein HTML-Bericht erstellt werden sollen.

createHtmlReport (boolean):
Wenn true, wird ein HTML-Bericht über die Validierung erstellt. Dieser Bericht enthält detaillierte Informationen über die Fehler und Warnungen.

 nein -


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 der Parameter config gesetzt ist und angibt, dass ein HTML-Report erzeugt werden soll, wird zusätzlich der HTML-Report zurückgegeben. Sonst wird nur das Validierungsresultat und eine Liste der Fehlermeldungen als Array zurückgegeben.

Im Falle einer erfolgreichen Prüfung ist das:

{
  "valid" : true,
  "validation" : [ ]
}

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

{
  "valid" : false,
  "validation" : [ {
    "level" : "error",
    "information" : "Invalid content found for unknown element. Value is missing or other value is expected: .",
    "message" : "[BR-AE-01]-An Invoice that contains an Invoice line (BG-25), a Document level allowance (BG-20) or a Document level charge (BG-21) where the VAT category code (BT-151, BT-95 or BT-102) is \"Reverse charge\" shall contain in the VAT Breakdown (BG-23) exactly one VAT category code (BT-118) equal with \"VAT reverse charge\"."
  } ] 
}

Die Beschreibung eines Validierungsfehlers besteht aus: