@fin.cx/einvoice 8.3.1 → 10.0.0

package/ts/formats/semantic/semantic.validator.ts

@@ -3,7 +3,8 @@
  * Validates invoices against EN16931 Business Terms and Business Groups
  */
 
-import { findInvalidItemAmounts, getTotalsSkippedResult } from '../utils/document.totals.js';
+import { computeDocumentTotals, findInvalidItemAmounts, getTotalsSkippedResult } from '../utils/document.totals.js';
+import { findPaymentProblem } from '../utils/paid.amount.js';
 import type { ValidationResult } from '../validation/validation.types.js';
 import type { EN16931SemanticModel, BusinessTerms, BusinessGroups } from './bt-bg.model.js';
 import type { EInvoice } from '../../einvoice.js';
@@ -57,6 +58,21 @@ export class SemanticModelValidator {
       return results;
     }
     
+    // The amount due (BT-115) follows from the paid amount; a paid amount that cannot be written
+    // (more decimals than the currency has, or advance payments that do not add up to it) is
+    // reported and the model rules are skipped, as for a line amount that is no number
+    const paymentProblem = findPaymentProblem(invoice, computeDocumentTotals(invoice));
+    if (paymentProblem) {
+      results.push({
+        ruleId: paymentProblem.ruleId,
+        source: 'SEMANTIC',
+        severity: 'error',
+        message: paymentProblem.message,
+        field: paymentProblem.field,
+      });
+      return results;
+    }
+
     // Convert to semantic model
     const model = this.adapter.toSemanticModel(invoice);
     

package/ts/formats/ubl/en16931.ubl.validator.ts

@@ -148,76 +148,17 @@ export class EN16931UBLValidator extends UBLBaseValidator {
       valid = false;
     }
 
+    // BR-CO-26: the seller states a seller, legal registration or VAT identifier
+    valid = this.validateSellerIdentifier() && valid;
+
     // BR-23: every line has a unit code
     valid = this.validateLineUnitCodePresence() && valid;
 
     // BR-CL-23: unit codes of UN/ECE Recommendation 20 with the Recommendation 21 extension
     valid = this.validateUnitCodes() && valid;
 
-    // Validate calculation rules if we have the necessary data
-    if (this.exists('//cac:LegalMonetaryTotal/cbc:LineExtensionAmount')) {
-      valid = this.validateCalculationRules() && valid;
-    }
-
-    return valid;
-  }
-
-  /**
-   * Validates calculation rules (BR-CO-*)
-   */
-  private validateCalculationRules(): boolean {
-    let valid = true;
-
-    // BR-CO-10: Sum of Invoice line net amount = Σ Invoice line net amount.
-    const lineExtensionAmount = this.getNumber('//cac:LegalMonetaryTotal/cbc:LineExtensionAmount');
-    const lines = this.select('//cac:InvoiceLine | //cac:CreditNoteLine', this.doc) as Node[];
-    
-    let calculatedSum = 0;
-    for (const line of lines) {
-      const lineAmount = this.getNumber('.//cbc:LineExtensionAmount', line);
-      calculatedSum += lineAmount;
-    }
-
-    // Allow for small rounding differences (0.01)
-    if (Math.abs(lineExtensionAmount - calculatedSum) > 0.01) {
-      this.addError(
-        'BR-CO-10', 
-        `Sum of Invoice line net amount (${lineExtensionAmount}) must equal sum of line amounts (${calculatedSum})`,
-        '//cac:LegalMonetaryTotal/cbc:LineExtensionAmount'
-      );
-      valid = false;
-    }
-
-    // BR-CO-13: Invoice total amount without VAT = Σ Invoice line net amount - Sum of allowances on document level + Sum of charges on document level.
-    const taxExclusiveAmount = this.getNumber('//cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount');
-    const allowanceTotal = this.getNumber('//cac:LegalMonetaryTotal/cbc:AllowanceTotalAmount') || 0;
-    const chargeTotal = this.getNumber('//cac:LegalMonetaryTotal/cbc:ChargeTotalAmount') || 0;
-    
-    const calculatedTaxExclusive = lineExtensionAmount - allowanceTotal + chargeTotal;
-    
-    if (Math.abs(taxExclusiveAmount - calculatedTaxExclusive) > 0.01) {
-      this.addError(
-        'BR-CO-13',
-        `Invoice total amount without VAT (${taxExclusiveAmount}) must equal calculated amount (${calculatedTaxExclusive})`,
-        '//cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount'
-      );
-      valid = false;
-    }
-
-    // BR-CO-15: Invoice total amount with VAT = Invoice total amount without VAT + Invoice total VAT amount.
-    const taxInclusiveAmount = this.getNumber('//cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount');
-    const totalTaxAmount = this.getNumber('//cac:TaxTotal/cbc:TaxAmount') || 0;
-    
-    const calculatedTaxInclusive = taxExclusiveAmount + totalTaxAmount;
-    
-    if (Math.abs(taxInclusiveAmount - calculatedTaxInclusive) > 0.01) {
-      this.addError(
-        'BR-CO-15',
-        `Invoice total amount with VAT (${taxInclusiveAmount}) must equal calculated amount (${calculatedTaxInclusive})`,
-        '//cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount'
-      );
-      valid = false;
-    }
+    // BR-CO-10 to BR-CO-17: the stated totals, VAT breakdown and line amounts agree with each other
+    valid = this.validateStatedTotals() && valid;
 
     return valid;
   }

package/ts/formats/ubl/generic/ubl.encoder.ts

@@ -7,8 +7,10 @@ import { getPrecedingInvoiceReferences } from '../../utils/preceding.invoice.js'
 import { getWritableDueDate } from '../../utils/date.value.js';
 import { getPaymentTermsNote } from '../../utils/payment.terms.js';
 import { computeDocumentTotals } from '../../utils/document.totals.js';
+import { getPaymentTotals } from '../../utils/paid.amount.js';
 import { toPlainDecimalString } from '../../utils/number.text.js';
 import { resolveCountryCode } from '../../utils/country.code.js';
+import { getPartyIdentifiers } from '../../utils/party.identifier.js';
 
 /**
  * UBL Encoder implementation
@@ -113,6 +115,12 @@ export class UBLEncoder extends UBLBaseEncoder {
     // Document Currency Code
     this.appendElement(doc, root, 'cbc:DocumentCurrencyCode', invoice.currency);
 
+    // Buyer reference (BT-10), as the buyer gave it
+    const buyerReference = invoice.buyerReference?.trim();
+    if (buyerReference) {
+      this.appendElement(doc, root, 'cbc:BuyerReference', buyerReference);
+    }
+
     // Invoicing period (BG-14), in schema order before the document references
     this.addInvoicePeriod(doc, root, invoice);
 
@@ -228,6 +236,18 @@ export class UBLEncoder extends UBLBaseEncoder {
     
     const partyNode = doc.createElement('cac:Party');
     partyElement.appendChild(partyNode);
+
+    // Party identifiers (BT-29 seller, BT-46 buyer), before the name in the schema order
+    for (const identifier of getPartyIdentifiers(party)) {
+      const partyIdentificationNode = doc.createElement('cac:PartyIdentification');
+      partyNode.appendChild(partyIdentificationNode);
+      const idNode = doc.createElement('cbc:ID');
+      if (identifier.scheme) {
+        idNode.setAttribute('schemeID', identifier.scheme);
+      }
+      idNode.textContent = identifier.value;
+      partyIdentificationNode.appendChild(idNode);
+    }
     
     // Party name
     const partyNameNode = doc.createElement('cac:PartyName');
@@ -481,10 +501,19 @@ export class UBLEncoder extends UBLBaseEncoder {
     taxInclusiveAmountElement.textContent = amount(totals.grandTotal);
     legalMonetaryTotalNode.appendChild(taxInclusiveAmountElement);
     
-    // Payable amount
+    // Paid amount (BT-113), before the payable amount in the schema order
+    const payment = getPaymentTotals(invoice, totals);
+    if (payment.paidAmount) {
+      const prepaidAmountElement = doc.createElement('cbc:PrepaidAmount');
+      prepaidAmountElement.setAttribute('currencyID', invoice.currency);
+      prepaidAmountElement.textContent = amount(payment.paidAmount);
+      legalMonetaryTotalNode.appendChild(prepaidAmountElement);
+    }
+
+    // Payable amount (BT-115)
     const payableAmountElement = doc.createElement('cbc:PayableAmount');
     payableAmountElement.setAttribute('currencyID', invoice.currency);
-    payableAmountElement.textContent = amount(totals.duePayable);
+    payableAmountElement.textContent = amount(payment.duePayable);
     legalMonetaryTotalNode.appendChild(payableAmountElement);
   }
   
@@ -892,29 +921,6 @@ export class UBLEncoder extends UBLBaseEncoder {
       }
     }
     
-    // Add additional identifiers
-    if (partyData.additionalIdentifiers && Array.isArray(partyData.additionalIdentifiers)) {
-      for (const identifier of partyData.additionalIdentifiers) {
-        const partyId = doc.createElement('cac:PartyIdentification');
-        const id = doc.createElement('cbc:ID');
-        if (identifier.scheme) {
-          id.setAttribute('schemeID', identifier.scheme);
-        }
-        id.textContent = identifier.value;
-        partyId.appendChild(id);
-        
-        // Insert after EndpointID or at beginning
-        const endpoint = party.getElementsByTagName('cbc:EndpointID')[0];
-        if (endpoint && endpoint.nextSibling) {
-          party.insertBefore(partyId, endpoint.nextSibling);
-        } else if (party.firstChild) {
-          party.insertBefore(partyId, party.firstChild);
-        } else {
-          party.appendChild(partyId);
-        }
-      }
-    }
-    
     // Add contact information from metadata if not already present
     const contactInfo = partyData.metadata?.contactInformation;
     if (contactInfo) {

package/ts/formats/ubl/ubl.decoder.ts

@@ -4,6 +4,8 @@ import { UBLDocumentType, UBL_NAMESPACES } from './ubl.types.js';
 import { DOMParser, xpath } from '../../plugins.js';
 import { EInvoiceParsingError } from '../../errors.js';
 import { getAccountingDocType } from '../utils/document.typecode.js';
+import { readUblStatedValues } from '../utils/stated.values.js';
+import type { IEInvoiceStatedValues } from '../../interfaces/stated.values.js';
 
 const ublParser = new DOMParser();
 const ublNamespaces = {
@@ -37,11 +39,21 @@ export abstract class UBLBaseDecoder extends BaseDecoder {
     return this.doc;
   }
 
+  /** The values the document states, read by `decode` */
+  private statedValues?: IEInvoiceStatedValues;
+
+  public override getStatedValues(): IEInvoiceStatedValues | undefined {
+    return this.statedValues;
+  }
+
   /**
    * Decodes UBL XML into an accounting document
    * @returns Promise resolving to the accounting document
    */
   public async decode(): Promise<TAccountingDoc> {
+    // the values the document states, read first: an amount that is no number is refused
+    this.statedValues = this.assertStatedValuesReadable(readUblStatedValues(this.doc), 'ubl');
+
     // a CreditNote root is a credit note whatever its type code says
     if (this.getDocumentType() === UBLDocumentType.CREDIT_NOTE) {
       return this.decodeCreditNote();

package/ts/formats/ubl/ubl.encoder.ts

@@ -3,6 +3,10 @@ import type { TAccountingDoc, TCreditNote, TInvoiceDocument } from '../../interf
 import { UBLDocumentType, UBL_NAMESPACES } from './ubl.types.js';
 import { getWritableDate } from '../utils/date.value.js';
 import { assertVatCategoryWritable } from '../utils/vat.category.js';
+import { assertSellerIdentified } from '../utils/seller.identifier.js';
+import { assertPartyIdentifiersWritable } from '../utils/party.identifier.js';
+import { computeDocumentTotals } from '../utils/document.totals.js';
+import { getPaymentTotals } from '../utils/paid.amount.js';
 
 /**
  * The children of the document root in the order the UBL 2.1 schema requires
@@ -51,11 +55,15 @@ export abstract class UBLBaseEncoder extends BaseEncoder {
   public async encode(invoice: TAccountingDoc): Promise<string> {
     // a reverse charge document that lacks what EN 16931 requires of one is refused (BR-AE-02, BR-AE-05)
     assertVatCategoryWritable(invoice, 'ubl');
+    // a buyer identifier with the SEPA scheme is refused (BR-CL-10)
+    assertPartyIdentifiersWritable(invoice, 'ubl');
+    // a paid amount the advance payments do not add up to, or with more decimals than the currency has, is refused
+    getPaymentTotals(invoice, computeDocumentTotals(invoice));
     // a credit note is a CreditNote document; an invoice, a debit note and a self-billed invoice are Invoice documents that differ in their type code
-    if (invoice.accountingDocType === 'creditnote') {
-      return this.encodeCreditNote(invoice);
-    }
-    return this.encodeInvoice(invoice);
+    const xml = invoice.accountingDocType === 'creditnote' ? await this.encodeCreditNote(invoice) : await this.encodeInvoice(invoice);
+    // a seller the written document does not identify is refused (BR-CO-26), never written silently
+    assertSellerIdentified(xml, 'ubl', 'ubl');
+    return xml;
   }
 
   /**

package/ts/formats/ubl/ubl.validator.ts

@@ -4,6 +4,8 @@ import type { ValidationResult } from '../../interfaces/common.js';
 import { UBLDocumentType, UBL_NAMESPACES } from './ubl.types.js';
 import { DOMParser, xpath } from '../../plugins.js';
 import { meetsUnitCodeRule } from '../utils/unit.codes.js';
+import { BR_CO_26_TEXT, ublSellerMeetsBrCo26 } from '../utils/seller.identifier.js';
+import { findStatedValueDisagreements, readUblStatedValues } from '../utils/stated.values.js';
 
 const ublValidatorParser = new DOMParser();
 const ublValidatorNamespaces = {
@@ -105,6 +107,33 @@ export abstract class UBLBaseValidator extends BaseValidator {
    */
   protected abstract validateStructure(): boolean;
 
+  /**
+   * BR-CO-10 to BR-CO-17: the document totals, the VAT breakdown, the line
+   * amounts and the document level allowances and charges the document states
+   * agree with each other, as the CEN artefacts check them
+   * @returns True if they do
+   */
+  protected validateStatedTotals(): boolean {
+    const findings = findStatedValueDisagreements(readUblStatedValues(this.doc), 'ubl');
+    for (const finding of findings) {
+      this.addError(finding.ruleId, finding.message, finding.location);
+    }
+    return findings.length === 0;
+  }
+
+  /**
+   * BR-CO-26: the seller states a seller identifier (BT-29), a legal
+   * registration identifier (BT-30) or a VAT identifier (BT-31).
+   * @returns True if it does
+   */
+  protected validateSellerIdentifier(): boolean {
+    if (ublSellerMeetsBrCo26(this.doc)) {
+      return true;
+    }
+    this.addError('BR-CO-26', BR_CO_26_TEXT, '/*/cac:AccountingSupplierParty');
+    return false;
+  }
+
   /**
    * BR-23: every invoice or credit note line has a unit code on its invoiced or credited quantity.
    * @returns True if every line has one

package/ts/formats/ubl/xrechnung/xrechnung.decoder.ts

@@ -12,6 +12,7 @@ import {
   getPrecedingInvoiceFields,
   type TPrecedingInvoiceReference,
 } from '../../utils/preceding.invoice.js';
+import { readPaidAmount } from '../../utils/paid.amount.js';
 
 /**
  * Decoder for XRechnung (UBL) format
@@ -240,6 +241,9 @@ export class XRechnungDecoder extends UBLBaseDecoder {
       const hasPaymentInformation = Object.values(paymentInformation).some(value => Boolean(value));
       const hasDateInformation = Object.values(dateInformation).some(value => Boolean(value));
 
+      // the paid amount (BT-113); the amount due (BT-115) follows from it and the totals
+      const paidAmount = readPaidAmount(this.getText('/*/cac:LegalMonetaryTotal/cbc:PrepaidAmount'), 'ubl');
+
       // Create the common invoice data with metadata only when the source XML actually contains it.
       const invoiceData: any = {
         type: 'accounting-doc' as const,
@@ -267,6 +271,8 @@ export class XRechnungDecoder extends UBLBaseDecoder {
         currency: currencyCode as finance.TCurrency,
         notes: notes,
         objectActions: [],
+        // the buyer reference (BT-10), when stated
+        ...(buyerReference.trim() ? { buyerReference: buyerReference.trim() } : {}),
         // the day and the period of supply as the document states them (BT-72, BG-14)
         ...(deliveryDate ? { deliveryDate: this.parseRequiredUblDate(deliveryDate) } : {}),
         ...(periodStart && periodEnd
@@ -278,18 +284,25 @@ export class XRechnungDecoder extends UBLBaseDecoder {
             }
           : {}),
         ...getPrecedingInvoiceFields(accountingDocType, this.extractPrecedingInvoiceReferences()),
+        ...(paidAmount === undefined ? {} : { paidAmount }),
       };
 
+      // the specification identifier (BT-24), which the validators read to tell an XRechnung, a
+      // PEPPOL or a Factur-X document
+      const customizationId = this.getText('/*/cbc:CustomizationID', this.doc).trim();
       if (hasBusinessReferences || hasPaymentInformation || hasDateInformation) {
         invoiceData.metadata = {
           format: 'xrechnung' as any,
           version: '1.0.0',
+          ...(customizationId ? { customizationId } : {}),
           extensions: {
             ...(hasBusinessReferences ? { businessReferences } : {}),
             ...(hasPaymentInformation ? { paymentInformation } : {}),
             ...(hasDateInformation ? { dateInformation } : {}),
           }
         };
+      } else if (customizationId) {
+        invoiceData.metadata = { customizationId };
       }
       
       // Validate mandatory EN16931 fields unless validation is skipped

package/ts/formats/ubl/xrechnung/xrechnung.encoder.ts

@@ -2,6 +2,32 @@ import { UBLEncoder } from '../generic/ubl.encoder.js';
 import type { TAccountingDoc, TCreditNote, TInvoiceDocument } from '../../../interfaces/common.js';
 import { DOMParser, XMLSerializer } from '../../../plugins.js';
 import { UBL_CUSTOMIZATION_IDS } from '../ubl.types.js';
+import { getPartyContact } from '../../utils/party.contact.js';
+import { EInvoiceFormatError } from '../../../errors.js';
+
+/**
+ * The buyer reference (BT-10) an XRechnung document states: the envelope's
+ * `buyerReference`, or the one a decoded UBL document keeps in
+ * `metadata.extensions.businessReferences`. XRechnung requires it (BR-DE-15,
+ * "Das Element \"Buyer reference\" (BT-10) muss übermittelt werden."), and it is
+ * the buyer's: the buyer gives the seller an identifier of its choice, a
+ * Leitweg-ID for a public buyer. Without one the export is refused; a document
+ * for a buyer that gave none can be written as EN 16931 UBL (`ubl`), where
+ * BT-10 is optional.
+ * @param invoice The document
+ */
+const getXRechnungBuyerReference = (invoice: TAccountingDoc): string => {
+  const kept: unknown = (invoice as { metadata?: { extensions?: { businessReferences?: { buyerReference?: unknown } } } }).metadata
+    ?.extensions?.businessReferences?.buyerReference;
+  const buyerReference = invoice.buyerReference?.trim() || (typeof kept === 'string' ? kept.trim() : '');
+  if (!buyerReference) {
+    throw new EInvoiceFormatError(
+      "BR-DE-15: an XRechnung document states the buyer reference (BT-10), buyerReference is missing. It is the identifier the buyer gave for routing the invoice (a Leitweg-ID for a public buyer) and cannot be put in place by the seller; without one, export the document as EN 16931 UBL ('ubl'), where BT-10 is optional",
+      { targetFormat: 'xrechnung', unsupportedFeatures: ['BR-DE-15'] },
+    );
+  }
+  return buyerReference;
+};
 
 /**
  * Encoder for XRechnung (UBL) format
@@ -59,9 +85,11 @@ export class XRechnungEncoder extends UBLEncoder {
       customizationId.textContent = UBL_CUSTOMIZATION_IDS.XRECHNUNG;
     }
     
-    // Add or update Buyer Reference (required for XRechnung)
+    // The buyer reference (BT-10), which XRechnung requires (BR-DE-15): the identifier the buyer
+    // gave the seller for routing the invoice, a Leitweg-ID for a public buyer. It comes from the
+    // buyer, so there is none to put in place of a missing one.
+    const buyerReferenceValue = getXRechnungBuyerReference(invoice);
     let buyerRef = root.getElementsByTagName('cbc:BuyerReference')[0];
-    const buyerReferenceValue = (invoice as any).buyerReference || metadata?.businessReferences?.buyerReference || invoice.id;
     if (!buyerRef) {
       // Find where to insert it (after DocumentCurrencyCode)
       const currencyCode = root.getElementsByTagName('cbc:DocumentCurrencyCode')[0];
@@ -70,7 +98,7 @@ export class XRechnungEncoder extends UBLEncoder {
         buyerRef.textContent = buyerReferenceValue;
         currencyCode.parentNode!.insertBefore(buyerRef, currencyCode.nextSibling);
       }
-    } else if (!buyerRef.textContent || buyerRef.textContent.trim() === '') {
+    } else {
       buyerRef.textContent = buyerReferenceValue;
     }
     
@@ -151,29 +179,6 @@ export class XRechnungEncoder extends UBLEncoder {
       }
     }
     
-    // Add PartyIdentification for additional identifiers
-    if (party.additionalIdentifiers) {
-      for (const identifier of party.additionalIdentifiers) {
-        const partyId = doc.createElement('cac:PartyIdentification');
-        const id = doc.createElement('cbc:ID');
-        if (identifier.scheme) {
-          id.setAttribute('schemeID', identifier.scheme);
-        }
-        id.textContent = identifier.value;
-        partyId.appendChild(id);
-        
-        // Insert after EndpointID or at beginning
-        const endpoint = partyElement.getElementsByTagName('cbc:EndpointID')[0];
-        if (endpoint && endpoint.nextSibling) {
-          partyElement.insertBefore(partyId, endpoint.nextSibling);
-        } else if (partyElement.firstChild) {
-          partyElement.insertBefore(partyId, partyElement.firstChild);
-        } else {
-          partyElement.appendChild(partyId);
-        }
-      }
-    }
-    
     // Add company registration number to PartyLegalEntity
     if (party.registrationDetails?.registrationId) {
       let legalEntity = partyElement.getElementsByTagName('cac:PartyLegalEntity')[0];
@@ -444,27 +449,10 @@ export class XRechnungEncoder extends UBLEncoder {
    */
   private enhancePartyInformation(doc: Document, invoice: TAccountingDoc): void {
     // Enhance supplier party
-    this.addContactToParty(doc, 'cac:AccountingSupplierParty', this.contactInformationOf(invoice.from));
+    this.addContactToParty(doc, 'cac:AccountingSupplierParty', getPartyContact(invoice.from));
     
     // Enhance customer party
-    this.addContactToParty(doc, 'cac:AccountingCustomerParty', this.contactInformationOf(invoice.to));
-  }
-
-  /**
-   * The contact block of a party: explicit contact metadata first, otherwise
-   * the party's own email and phone (BR-DE-11 and BR-DE-12 require both for
-   * the seller).
-   * @param party Party data
-   */
-  private contactInformationOf(party: any): { name?: string; phone?: string; email?: string } | undefined {
-    const explicit = party?.metadata?.contactInformation;
-    if (explicit && (explicit.name || explicit.phone || explicit.email)) {
-      return explicit;
-    }
-    if (party?.email || party?.phone) {
-      return { name: party.name, phone: party.phone, email: party.email };
-    }
-    return undefined;
+    this.addContactToParty(doc, 'cac:AccountingCustomerParty', getPartyContact(invoice.to));
   }
 
   /**