Durchsuchbare Dokumentation aufrufen | Zurück zur Dokumentationsübersicht

Navigation: Dokumentationen agorum core > agorum core für Entwickler > agorum core JavaScript-API


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 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 E-Rechnungen mit Dokument | E-Rechnung verarbeiten. Welche Formate, Versionen und Profile die Funktionen lesen und erzeugen, beschreibt E-Rechnungsformate, Versionen und Profile; eine Schritt-für-Schritt-Anleitung zum Erstellen finden Sie in E-Rechnungen erstellen.

Alle Funktionen verwenden dieselben Format-IDs:

Format-ID Format
xrechnung_ubl XRechnung 3.0 in der Syntax UBL
xrechnung_cii XRechnung 3.0 in der Syntax CII
zugferd_cii ZUGFeRD / Factur-X (PDF/A-3 mit eingebetteter CII-XML), Profil EXTENDED oder EN 16931
peppol_ubl Peppol BIS Billing 3.0 (UBL)

Verwendung


Binden Sie die Bibliothek stets am Anfang eines Skripts ein:

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

Tipp: Sie können die Beispiele auf dieser Seite in der Skript-Konsole ausprobieren (Hauptmenü Development > Skript-Konsole). Die Beispiele verwenden Testdateien aus dem Plugin-Ordner und legen ihre Ergebnisse in Ihren eigenen Dateien (home:MyFiles) bzw. im Arbeitsordner des Plugins ab. Die Beispieldaten completeDataStructure.json zeigen alle Felder, sind aber rechnerisch nicht stimmig; eine damit erzeugte Rechnung ist ungültig. Einen geprüften Datensatz finden Sie unter E-Rechnungen erstellen.

Funktionen


check

Die Funktion prüft, ob es sich bei dem übergebenen Objekt um eine elektronische Rechnung in einem unterstützten Format handelt. Wenn es sich um eine E-Rechnung handelt, bestimmt die Funktion außerdem das E-Rechnungsformat. Das Ergebnis ist ein CheckResult-Objekt.

Geprüft werden PDF- und XML-Dateien. Bei PDF-Dateien sucht die Funktion nach einer eingebetteten Datei factur-x.xml, zugferd-invoice.xml, ZUGFeRD-invoice.xml oder xrechnung.xml. check prüft nicht, ob die Rechnung inhaltlich gültig ist; dafür verwenden Sie validateInvoice.

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/auto_test_documents/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 ein ZUGFeRD 1.0-Dokument erkannt wird, ist das Ergebnis ebenfalls valid: false, und message enthält den Hinweis: No supported e-invoicing format found. The given invoice is ZUGFeRD 1.0. ZUGFeRD 2.0 and newer are supported. Die Funktionen parse und validateInvoice werfen in diesem Fall einen Fehler mit derselben Meldung.

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:

Für die CII-Formate (xrechnung_cii, zugferd_cii) sind auf Rechnungsebene zusätzlich das Fälligkeitsdatum, die BIC und die elektronischen Adressen von Verkäufer und Käufer Pflicht; auf Positionsebene verlangt dagegen nur UBL zusätzlich net_amount. Die vollständige Liste finden Sie im Vergleich der Pflichtfelder in den E-Rechnungsformaten.

Hinweis: Die Funktion prüft nur, ob ein Feld vorhanden ist, nicht ob der Wert plausibel ist. Von den Positionen wird nur die erste geprüft. Die vollständige Prüfung gegen Schema und Geschäftsregeln erfolgt mit validate.

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, zugferd_cii oder peppol_ubl  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 data = JSON.parse(objects.find(SAMPLE_DATA).contentString);
let check = eInvoice.checkRequiredFields(data, 'xrechnung_cii');

check;

 

Rückgabewert

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

[ ]

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

[ {
  "label" : "Steuersatz 1 - Wert fehlt",
  "key" : "agorum_accounting_document_total_tax_rate_1"
}]

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:

Vor der Erstellung prüft die Funktion die Pflichtfelder wie checkRequiredFields, sofern skipPreValidation nicht gesetzt ist.

Syntax

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


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 Pflicht: Liste mit der PDF-Datei als erstem Eintrag, in die die CII-XML eingebettet wird.
  • profile (ab Version 1.1.0): Profil für zugferd_cii, extended oder en16931. Ohne Angabe gilt der MetaDB-Eintrag MAIN_MODULE_MANAGEMENT/customers/agorum.electronic.invoicing/settings/zugferdProfile, ist auch dieser nicht gesetzt, extended. Groß-/Kleinschreibung ist egal; ein unbekannter Wert führt bei allen CII-Formaten zu einem Fehler. Bei xrechnung_cii und den UBL-Formaten hat das Profil sonst keine Wirkung. Siehe Profilsteuerung für ZUGFeRD.
  • skipPreValidation (Boolean, Standard false): Wenn true, wird die Prüfung der Pflichtfelder vor der Erstellung übersprungen.
ja –

Achtung: Bei ZUGFeRD wird das übergebene PDF-Objekt selbst zur E-Rechnung (PDF/A-3b mit eingebetteter Datei factur-x.xml) umgewandelt und zurückgegeben. Übergeben Sie eine Kopie, wenn das Original unverändert bleiben soll. Ist das PDF noch nicht PDF/A-3b und ein PDF/A-Konverter eingerichtet, wird es vorher konvertiert.

Im Profil en16931 werden Angaben, die das EN-16931-Schema nicht zulässt, ausgelassen, protokolliert und im übergebenen Konfigurationsobjekt unter suppressed zurückgemeldet (Liste von Feldnamen und Hinweisen, oder null). Dasselbe gilt für weitere ausgelassene Angaben, etwa zusätzliche Bezugsrechnungen. suppressed wird nur bei den CII-Formaten gefüllt:

let config = { data: data, format: 'zugferd_cii', profile: 'en16931', attachments: [copy] };
let invoice = eInvoice.createInvoice(config);

config.suppressed; // ausgelassene Angaben


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/auto_test_documents/Rechnung-12345678-12983760.pdf';

let sampleInvoice = objects.find(SAMPLE_INVOICE);
let copy = objects.copy(sampleInvoice, objects.find('home:MyFiles'));

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 als agorum-Objekt zurück: bei xrechnung_ubl, xrechnung_cii und peppol_ubl eine neu angelegte XML-Datei, bei zugferd_cii das übergebene PDF.

Hinweis: Die XML-Datei entsteht im Arbeitsordner des Plugins (/agorum/roi/workspace/agorum.electronic.invoicing/work/<Jahr>/<Monat>/<Tag>/) und trägt eine UUID als Namen, etwa e912308f-….xml. Verschieben oder kopieren Sie sie an ihren Zielort und vergeben Sie einen sprechenden Namen, etwa mit der Rechnungsnummer. createInvoice prüft die Rechnung nicht mit dem Validator; prüfen Sie das Ergebnis mit validateInvoice.

Es wird ein Fehler geworfen, wenn Pflichtfelder fehlen oder – im CII-/ZUGFeRD-Format – ein Datumsfeld einen unbrauchbaren Wert enthält. Die Fehlermeldung nennt die fehlenden Schlüssel. Beispiel:

Error: Invoice cannot be generated due to necessary information: [
  {
    "key": "agorum_accounting_document_buyer_reference_number",
    "label": "Käuferreferenz - Wert fehlt"
  },
  {
    "key": "agorum_accounting_document_total_tax_rate_1",
    "label": "Steuersatz 1 - Wert fehlt"
  }
]

createInvoiceRaw

Die Funktion erzeugt das XML einer E-Rechnung als Zeichenkette, ohne eine Datei anzulegen. Sie eignet sich, um die Rechnung vor der eigentlichen Erstellung mit validate zu prüfen, oder wenn Sie das XML selbst weiterverarbeiten wollen. Folgende Daten/Angaben sind erforderlich:

Syntax

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


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 (zusätzliche Dokumente, BG-24). Die Größe ist standardmäßig auf 25 MB je Anhang begrenzt.
  • profile (ab Version 1.1.0): Profil für zugferd_cii, extended oder en16931; Voreinstellung wie bei createInvoice.
  • skipPreValidation (Boolean, Standard false): Wenn true, wird die Prüfung der Pflichtfelder vor der Erstellung übersprungen.
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/auto_test_documents/Rechnung-12345678-12983760.pdf';

let sampleInvoice = objects.find(SAMPLE_INVOICE);
let copy = objects.copy(sampleInvoice, objects.find('home:MyFiles'));

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


Rückgabewert

Die Funktion gibt das XML der E-Rechnung als Zeichenkette zurück (CII oder UBL).

Es wird ein Fehler geworfen, wenn Pflichtfelder fehlen oder – im CII-/ZUGFeRD-Format – ein Datumsfeld einen unbrauchbaren Wert enthält. Die Fehlermeldung nennt die fehlenden Schlüssel. Beispiel:

Error: Invoice cannot be generated due to necessary information: [
  {
    "key": "agorum_accounting_document_buyer_reference_number",
    "label": "Käuferreferenz - Wert fehlt"
  },
  {
    "key": "agorum_accounting_document_total_tax_rate_1",
    "label": "Steuersatz 1 - 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 Office-Dokument. Die Datei, in die das PDF oder das Office-Dokument geschrieben werden soll, muss dafür angegeben werden.

Für weitere Informationen zum Rechnungstemplate siehe Beispielvorlage als Grundlage für eigene Dokumentvorlagen verwenden. Für die Umwandlung in PDF und das Füllen der Vorlage wird LibreOffice benötigt.

Syntax

createView({
  data: data,
  additionalAttachments: [attachmentDoc],
  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 (Pflicht): Ausgabedokument (Objekt, Pfad oder ID). Bei createPdf: true muss es eine PDF-Datei sein, sonst ein Word- oder OpenDocument-Dokument (etwa .docx oder .odt).
  • templateDoc (Pflicht): Pfad oder ID der Dokumentvorlage.
  • createPdf: Angabe, ob ein PDF erzeugt werden soll (true) oder ein Office-Dokument (false).
  • labels: optional, eigene Texte für die Beschriftungen der Vorlage als Objekt oder JSON-Zeichenkette. Unbekannte Schlüssel führen zu einem Fehler.
  • datePattern: optional, Datumsformat für die Rechnungsdarstellung, Standard dd.MM.yyyy.
  • numberFormat: optional, Gebietsschema für das Zahlenformat, optional mit Muster, Standard de-DE|#,##0.00; für eine Liste der möglichen Werte siehe Gebietsschema: Sprachcodes und Ländercodes.
ja -
additionalAttachments  Liste (Array) zusätzlicher Anhänge für die Ansicht, jeder Eintrag muss ein agorum.Object sein: 
additionalAttachments: [objects.find('6ee1f520-6935-11ef-9d89-02420a0a0011')]
nein -


Beispiel 1 - Erstellung eines Anzeige-PDFs ohne zusätzliche Anhänge

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/Workflow_and_Other_Example_Documents/Demo_UBL_EN16931.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: '/agorum/roi/customers/agorum.electronic.invoicing/template/Invoice_Template_Complete_All_Keys.docx',
    createPdf: true,
    datePattern: 'dd-MM-yyyy',
    numberFormat: 'de-CH',
  },
});


Beispiel 2 - Erstellung eines Anzeige-PDFs mit zusätzlichen Anhängen

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/Workflow_and_Other_Example_Documents/Demo_CII_EN16931.xml');
let result = eInvoice.parse(doc);
let data = result.data;
// Anhänge, die an die Ansicht gehängt werden sollen, etwa Stundennachweise
let attachments = [
  objects.find('home:MyFiles/Stundennachweis.pdf'),
];

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

eInvoice.createView({
  data: data,
  additionalAttachments: attachments,
  template: {
    outputDoc: outputDoc,
    templateDoc: '/agorum/roi/customers/agorum.electronic.invoicing/template/Invoice_Template_Complete.docx',
    createPdf: true,
  },
});

 

Rückgabewert

Die createView-Funktion gibt das gefüllte Ausgabedokument (outputDoc) zurück. Zusätzliche Anhänge aus additionalAttachments werden als Anhang an das Ausgabedokument gehängt.

Hinweis: Die Ansicht beruht ausschließlich auf den XML-Daten. Sie ist eine Lesehilfe und ersetzt nicht das Original der E-Rechnung, das unverändert aufbewahrt werden muss.

Zusätzlich zu den normalisierten Daten stellt createView der Vorlage aufbereitete Werte bereit, etwa formatierte Beträge und Datumsangaben sowie die Bezeichnung des Rechnungstyps im Platzhalter agorum_accounting_document_type_code_description (z. B. Rechnung für den Typ-Code 380). Die Bezeichnung wird über die Liste der Dokumenttyp-Codes des Plugins aufgelöst; ist für einen Code keine Übersetzung hinterlegt, erscheint der Code selbst.

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 in der XML base64-codierten Anhänge nicht extrahiert.
  • validate ist ein Boolean-Parameter, der bestimmt, ob die Rechnung zusätzlich geprüft werden soll. Der Standardwert ist false. Wenn der Wert true ist, wird die Funktion validateInvoice auf das Objekt angewendet (Ergebnis in validation.structure) und die Positionen werden auf Plausibilität geprüft (Ergebnis in validation.content).
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/Workflow_and_Other_Example_Documents/Demo_CII_EN16931.xml';

let data = eInvoice.parse(objects.find(CII), {
  target: objects.find('home:MyFiles'),
  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:

Hinweis: parse speichert die normalisierten Daten nicht als Metadaten am Dokument. Wenn Sie die Daten am Dokument brauchen, speichern Sie data in einem eigenen Schritt. Enthält ein ZUGFeRD-PDF neben der Rechnungs-XML weitere eingebettete Dateien, werden diese als Anhang an das Original-PDF gehängt.

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"
        } ]

Wenn ein ZUGFeRD 1.0-Dokument erkannt wird, wird folgender Fehler geworfen: No supported e-invoicing format found. The given invoice is ZUGFeRD 1.0. ZUGFeRD 2.0 and newer are supported.

Zusätzlich zur Prüfung mit dem KoSIT-Validator (Pflichtfelder, Codelisten, Summen und Datumsangaben nach den Regeln der EN 16931 und des jeweiligen Formats) prüft parse die Positionen auf Plausibilität. Diese Prüfung ergänzt den Validator um Betragsabweichungen, die er nicht meldet, und umfasst folgende Regeln:

Regel Beschreibung Fehlermeldung
net_price ↔ net_amount Abhängigkeit Wenn net_price gesetzt ist, muss auch net_amount vorhanden sein (und umgekehrt). net_amount is missing although net_price is set.
Brutto ≠ Netto bei Steuersatz > 0 Wenn ein Steuersatz > 0% angegeben ist, dürfen net_amount und gross_amount nicht identisch sein. net_amount and gross_amount are same value. This is not valid because tax_rate is X%. Please check if there are allowance for the position.
Berechnungskonsistenz (1-Cent-Toleranz) quantity × net_price muss innerhalb von ±0,01 (1 Cent) dem net_amount entsprechen. net_price (X) multiplied with quantity (Y) is differing more than one cent from net_amount: Z

Die Validierungsergebnisse werden im Abschnitt content des Validierungsobjekts zurückgegeben. Beispiel:

"content": {
  "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"
    }]
  }]
}

validate

Die Funktion überprüft, ob ein XML-Datenstrom (Zeichenkette oder Stream) eine gültige E-Rechnung ist, etwa das Ergebnis von createInvoiceRaw.

Geprüft wird mit dem KoSIT-Validator, den das Plugin mitbringt. Die Funktion erkennt das Format und wählt das Prüfszenario an der Spezifikationskennung (BT-24): XRechnung, Peppol BIS Billing 3.0, ZUGFeRD (Kaskade über die ZUGFeRD-Versionen) oder EN 16931. Details siehe Prüfszenarien des Validators.

Wenn das XML nicht wohlgeformt ist oder kein unterstütztes Format hat, wird ein Fehler geworfen.

Syntax

validate(xmlData, config)


Parameter

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

Eine optionale Konfiguration:

createHtmlReport (boolean):
Wenn true, wird ein HTML-Prüfbericht erstellt und unter htmlReport zurückgegeben. Dieser Bericht enthält detaillierte Informationen über die Fehler und Warnungen und eine Empfehlung, ob die Rechnung angenommen werden kann.

strict (boolean):
Wenn true, werden ZUGFeRD-Rechnungen gegen die strengen Varianten der ZUGFeRD-Prüfszenarien geprüft (für ZUGFeRD 2.2.0 gibt es keine strenge Variante). Ohne Wirkung bei anderen Formaten.

nein -


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/EN16931_COMPLIANT/minimal_json.json';

let data = JSON.parse(objects.find(DATA).contentString);
// XML erzeugen, ohne eine Datei anzulegen
let xmlData = eInvoice.createInvoiceRaw({ data: data, format: 'xrechnung_cii' });
let validation = eInvoice.validate(xmlData, { createHtmlReport: true });
validation;


Rückgabewert

Die Funktion gibt ein Objekt mit dem Ergebnis valid und der Liste der Meldungen validation zurück. Mit createHtmlReport: true enthält es zusätzlich htmlReport, das HTML-Dokument mit dem Prüfbericht.

Im Falle einer erfolgreichen Prüfung ist das:

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

Im Fehlerfall ist valid false, und validation enthält die Meldungen:

{
  "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 einer Meldung besteht aus:

Ob die Rechnung als gültig gilt (valid), entscheidet die Annahme-Empfehlung des Prüfszenarios. Meldungen, die das Szenario nur als Information einstuft, machen die Rechnung nicht ungültig. Prüfen Sie valid ausdrücklich auf true.

validateInvoice

Die Funktion überprüft, ob ein agorum-Objekt eine gültige elektronische Rechnung ist. Das Objekt kann eine XML-Datei oder ein ZUGFeRD-PDF sein; bei einem PDF wird die eingebettete XML geprüft. Optional erzeugt die Funktion einen HTML-Prüfbericht.

Geprüft wird wie bei validate mit dem KoSIT-Validator; das Prüfszenario richtet sich nach der Spezifikationskennung der Rechnung.

Achtung: Eine ZUGFeRD-Rechnung im Profil EXTENDED wird gegen die ZUGFeRD-Prüfszenarien geprüft, in denen die Regeln des eingeschränkten EN-16931-Schemas nicht mitlaufen. Ein gültiges Ergebnis bedeutet daher nicht, dass ein Empfänger mit EN-16931-Prüfung die Rechnung annimmt. Siehe Profilsteuerung für ZUGFeRD.

Wenn es sich bei dem übergebenen Objekt nicht um eine PDF- oder XML-Datei handelt, das XML nicht wohlgeformt ist oder kein unterstütztes Format hat, wird ein Fehler geworfen.


Syntax

validateInvoice(object, config)


Parameter

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

Eine optionale Konfiguration mit denselben Angaben wie bei validate:

createHtmlReport (boolean):
Wenn true, wird ein HTML-Prüfbericht erstellt und unter htmlReport zurückgegeben.

strict (boolean):
Wenn true, werden ZUGFeRD-Rechnungen gegen die strengen Varianten der ZUGFeRD-Prüfszenarien geprüft (für ZUGFeRD 2.2.0 gibt es keine strenge Variante).

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/auto_test_documents/Rechnung-12345678-12983760.pdf';
let sampleInvoice = objects.find(SAMPLE_INVOICE);
let validation = eInvoice.validateInvoice(sampleInvoice, { createHtmlReport: true });

validation;


Rückgabewert

Die Funktion gibt wie validate ein Objekt mit valid, validation und bei createHtmlReport: true zusätzlich htmlReport zurück.

Im Falle einer erfolgreichen Prüfung ist das:

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

Im Fehlerfall ist valid false, und validation enthält die Meldungen:

{
  "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\"."
  } ] 
}

Der Aufbau der Meldungen ist bei validate beschrieben.

Wenn ein ZUGFeRD 1.0-Dokument erkannt wird, wird folgender Fehler geworfen: No supported e-invoicing format found. The given invoice is ZUGFeRD 1.0. ZUGFeRD 2.0 and newer are supported.