Durchsuchbare Dokumentation aufrufen | Zurück zur Dokumentationsübersicht
Navigation: Dokumentationen agorum core > agorum core für Entwickler > agorum core JavaScript-API
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) |
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.
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:
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"
}]
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:
|
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"
}
]
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:
|
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"
}
]
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:
|
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.
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:
|
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"
}]
}]
}
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 ( strict ( |
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.
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 ( strict ( |
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.