@fin.cx/einvoice 8.1.0 → 8.2.1

package/ts/formats/cii/zugferd/zugferd.v1.decoder.ts

@@ -6,9 +6,16 @@ import type {
   TInvoiceDocument,
 } from '../../../interfaces/common.js';
 import { ZUGFERD_V1_NAMESPACES } from '../cii.types.js';
-import { business, finance } from '../../../plugins.js';
+import { business, finance, xpath } from '../../../plugins.js';
 import { EN16931Validator } from '../../validation/en16931.validator.js';
 
+/** XPath selection with the ZUGFeRD v1 namespaces */
+const zugferdV1Select = xpath.useNamespaces({
+  rsm: ZUGFERD_V1_NAMESPACES.RSM,
+  ram: ZUGFERD_V1_NAMESPACES.RAM,
+  udt: ZUGFERD_V1_NAMESPACES.UDT,
+});
+
 /**
  * Decoder for ZUGFeRD v1 invoice format
  */
@@ -28,6 +35,47 @@ export class ZUGFeRDV1Decoder extends CIIBaseDecoder {
     };
   }
 
+  /**
+   * Reads the issue date of the v1 header (`rsm:HeaderExchangedDocument`); a
+   * missing or invalid one is refused with an `EInvoiceParsingError`.
+   */
+  protected override extractIssueDate(): number {
+    const issueDatePath = '/rsm:CrossIndustryDocument/rsm:HeaderExchangedDocument/ram:IssueDateTime/udt:DateTimeString';
+    return this.parseRequiredCIIDate(this.v1Text(issueDatePath), this.v1Text(`${issueDatePath}/@format`));
+  }
+
+  /**
+   * Reads the payment due date of the v1 header payment terms; undefined when
+   * the document states none.
+   */
+  protected override extractDueDate(): number | undefined {
+    const dueDatePath =
+      '/rsm:CrossIndustryDocument/rsm:SpecifiedSupplyChainTradeTransaction/ram:ApplicableSupplyChainTradeSettlement/ram:SpecifiedTradePaymentTerms/ram:DueDateDateTime/udt:DateTimeString';
+    const dueDate = this.v1Text(dueDatePath);
+    return dueDate ? this.parseRequiredCIIDate(dueDate, this.v1Text(`${dueDatePath}/@format`)) : undefined;
+  }
+
+  /** The trimmed text of the first node a v1 path selects, or '' */
+  private v1Text(path: string): string {
+    return String(zugferdV1Select(`string(${path})`, this.doc)).trim();
+  }
+
+  /**
+   * Reads the actual delivery date of the v1 header delivery
+   * (`ram:ApplicableSupplyChainTradeDelivery`); undefined when the document
+   * does not state one.
+   */
+  protected override extractDeliveryDate(): number | undefined {
+    const deliveryDatePath =
+      '/rsm:CrossIndustryDocument/rsm:SpecifiedSupplyChainTradeTransaction/ram:ApplicableSupplyChainTradeDelivery/ram:ActualDeliverySupplyChainEvent/ram:OccurrenceDateTime/udt:DateTimeString';
+    const deliveryDate = String(zugferdV1Select(`string(${deliveryDatePath})`, this.doc)).trim();
+    if (!deliveryDate) {
+      return undefined;
+    }
+    const format = String(zugferdV1Select(`string(${deliveryDatePath}/@format)`, this.doc)).trim();
+    return this.parseRequiredCIIDate(deliveryDate, format);
+  }
+
   /**
    * Decodes a ZUGFeRD v1 credit note
    * @returns Promise resolving to a TCreditNote object
@@ -37,7 +85,7 @@ export class ZUGFeRDV1Decoder extends CIIBaseDecoder {
   }
 
   /**
-   * Decodes a ZUGFeRD v1 invoice document: an invoice, a debit note or a self-billed invoice
+   * Decodes a ZUGFeRD v1 invoice document: an invoice, a corrected invoice, a debit note or a self-billed invoice
    * @param accountingDocType The type the document type code stands for
    * @returns Promise resolving to the invoice document
    */
@@ -59,9 +107,7 @@ export class ZUGFeRDV1Decoder extends CIIBaseDecoder {
     const invoiceId = this.getText('//ram:ID');
 
     // Extract issue date
-    const issueDateStr = this.getText('//ram:IssueDateTime/udt:DateTimeString');
-    const issueDateFormat = this.getText('//ram:IssueDateTime/udt:DateTimeString/@format');
-    const issueDate = this.parseCIIDate(issueDateStr, issueDateFormat);
+    const issueDate = this.extractIssueDate();
 
     // Extract seller information
     const seller = this.extractParty('//ram:SellerTradeParty');
@@ -73,9 +119,8 @@ export class ZUGFeRDV1Decoder extends CIIBaseDecoder {
     const items = this.extractItems();
 
     // Extract due date
-    const dueDateStr = this.getText('//ram:SpecifiedTradePaymentTerms/ram:DueDateDateTime/udt:DateTimeString');
-    const dueDate = dueDateStr ? new Date(dueDateStr).getTime() : Date.now();
-    const dueInDays = Math.round((dueDate - issueDate) / (1000 * 60 * 60 * 24));
+    // no due date stated: `dueInDays` cannot express it yet (required field in @tsclass/tsclass); value unchanged: 0 days, what this decoder returned before it read the v1 dates
+    const dueInDays = this.dueInDaysOf(issueDate, this.extractDueDate(), 0);
 
     // Extract currency
     const currencyCode = this.getText('//ram:InvoiceCurrencyCode') || 'EUR';
@@ -99,6 +144,9 @@ export class ZUGFeRDV1Decoder extends CIIBaseDecoder {
       notes = allNotes.slice(1); // Remove subject from notes
     }
 
+    // Extract the actual delivery date, if stated
+    const deliveryDate = this.extractDeliveryDate();
+
     // Check for reverse charge
     const reverseCharge = this.exists('//ram:SpecifiedTradeAllowanceCharge/ram:ReasonCode[text()="62"]');
 
@@ -126,7 +174,8 @@ export class ZUGFeRDV1Decoder extends CIIBaseDecoder {
       reverseCharge: reverseCharge,
       currency: currencyCode as finance.TCurrency,
       notes: notes,
-      deliveryDate: issueDate,
+      // the day of supply as the document states it (BT-72), never the issue date in its place
+      ...(deliveryDate === undefined ? {} : { deliveryDate }),
       objectActions: []
     };
     

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

@@ -3,6 +3,9 @@ import type { TAccountingDoc, TCreditNote, TInvoiceDocument } from '../../../int
 import { UBLDocumentType } from '../ubl.types.js';
 import { DOMParser, XMLSerializer } from '../../../plugins.js';
 import { getDocumentTypeCode } from '../../utils/document.typecode.js';
+import { getPrecedingInvoiceReferences } from '../../utils/preceding.invoice.js';
+import { getWritableDueDate } from '../../utils/date.value.js';
+import { getPaymentTermsNote } from '../../utils/payment.terms.js';
 
 /**
  * UBL Encoder implementation
@@ -24,13 +27,15 @@ export class UBLEncoder extends UBLBaseEncoder {
     
     // Add credit note specific data
     this.addCreditNoteSpecificData(doc, creditNote);
+
+    this.orderRootElements(doc);
     
     // Serialize to string
     return new XMLSerializer().serializeToString(doc);
   }
   
   /**
-   * Encodes an invoice document (invoice, debit note or self-billed invoice) into UBL XML
+   * Encodes an invoice document (invoice, corrected invoice, debit note or self-billed invoice) into UBL XML
    * @param invoice Invoice document to encode
    * @returns UBL XML string
    */
@@ -44,6 +49,8 @@ export class UBLEncoder extends UBLBaseEncoder {
     
     // Add invoice specific data
     this.addInvoiceSpecificData(doc, invoice);
+
+    this.orderRootElements(doc);
     
     // Serialize to string
     return new XMLSerializer().serializeToString(doc);
@@ -71,16 +78,14 @@ export class UBLEncoder extends UBLBaseEncoder {
     this.appendElement(doc, root, 'cbc:ID', invoice.id);
     
     // Issue Date
-    this.appendElement(doc, root, 'cbc:IssueDate', this.formatDate(invoice.date));
+    this.appendElement(doc, root, 'cbc:IssueDate', this.formatDate(invoice.date, 'BT-2 invoice issue date'));
     
     // Due Date - the CreditNote schema has no DueDate element; its payment due date lives in cac:PaymentMeans
     if (documentType === UBLDocumentType.INVOICE) {
-      const issueTimestamp = typeof invoice.date === 'number' ? invoice.date : Date.now();
-      const dueDate = new Date(issueTimestamp);
-      dueDate.setDate(dueDate.getDate() + (invoice.dueInDays || 30));
-      this.appendElement(doc, root, 'cbc:DueDate', this.formatDate(dueDate.getTime()));
+      const dueDate = getWritableDueDate(invoice.date, invoice.dueInDays, 'ubl');
+      this.appendElement(doc, root, 'cbc:DueDate', this.formatDate(dueDate.getTime(), 'BT-9 payment due date'));
     }
-    // Document Type Code (380 invoice, 381 credit note, 383 debit note, 389 self-billed invoice; the element differs per schema)
+    // Document Type Code (380 invoice, 381 credit note, 383 debit note, 384 corrected invoice, 389 self-billed invoice; the element differs per schema)
     this.appendElement(
       doc,
       root,
@@ -104,12 +109,21 @@ export class UBLEncoder extends UBLBaseEncoder {
     
     // Document Currency Code
     this.appendElement(doc, root, 'cbc:DocumentCurrencyCode', invoice.currency);
+
+    // Invoicing period (BG-14), in schema order before the document references
+    this.addInvoicePeriod(doc, root, invoice);
+
+    // Preceding invoice references (BG-3)
+    this.addBillingReferences(doc, root, invoice);
     
     // Add accounting supplier party (seller)
     this.addParty(doc, root, 'cac:AccountingSupplierParty', invoice.from);
     
     // Add accounting customer party (buyer)
     this.addParty(doc, root, 'cac:AccountingCustomerParty', invoice.to);
+
+    // Actual delivery date (BT-72), in schema order after the parties
+    this.addDelivery(doc, root, invoice);
     
     // Add payment terms
     this.addPaymentTerms(doc, root, invoice);
@@ -127,6 +141,57 @@ export class UBLEncoder extends UBLBaseEncoder {
     this.preserveMetadata(doc, root, invoice);
   }
   
+  /**
+   * Writes the invoicing period (BG-14: BT-73 and BT-74) the document states.
+   * @param doc XML document
+   * @param root Document root
+   * @param invoice Accounting document
+   */
+  private addInvoicePeriod(doc: Document, root: Element, invoice: TAccountingDoc): void {
+    if (!invoice.periodOfPerformance) {
+      return;
+    }
+    const invoicePeriod = doc.createElement('cac:InvoicePeriod');
+    this.appendElement(doc, invoicePeriod, 'cbc:StartDate', this.formatDate(invoice.periodOfPerformance.from, 'BT-73 invoicing period start date'));
+    this.appendElement(doc, invoicePeriod, 'cbc:EndDate', this.formatDate(invoice.periodOfPerformance.to, 'BT-74 invoicing period end date'));
+    root.appendChild(invoicePeriod);
+  }
+
+  /**
+   * Writes one preceding invoice reference (BG-3) per invoice the document
+   * states it corrects: the number (BT-25) and, when stated, the issue date (BT-26).
+   * @param doc XML document
+   * @param root Document root
+   * @param invoice Accounting document
+   */
+  private addBillingReferences(doc: Document, root: Element, invoice: TAccountingDoc): void {
+    for (const reference of getPrecedingInvoiceReferences(invoice)) {
+      const billingReference = doc.createElement('cac:BillingReference');
+      const invoiceDocumentReference = doc.createElement('cac:InvoiceDocumentReference');
+      this.appendElement(doc, invoiceDocumentReference, 'cbc:ID', reference.documentId);
+      if (reference.issueDate !== undefined) {
+        this.appendElement(doc, invoiceDocumentReference, 'cbc:IssueDate', this.formatDate(reference.issueDate, 'BT-26 preceding invoice issue date'));
+      }
+      billingReference.appendChild(invoiceDocumentReference);
+      root.appendChild(billingReference);
+    }
+  }
+
+  /**
+   * Writes the actual delivery date (BT-72) the document states.
+   * @param doc XML document
+   * @param root Document root
+   * @param invoice Accounting document
+   */
+  private addDelivery(doc: Document, root: Element, invoice: TAccountingDoc): void {
+    if (invoice.deliveryDate === undefined) {
+      return;
+    }
+    const delivery = doc.createElement('cac:Delivery');
+    this.appendElement(doc, delivery, 'cbc:ActualDeliveryDate', this.formatDate(invoice.deliveryDate, 'BT-72 actual delivery date'));
+    root.appendChild(delivery);
+  }
+
   /**
    * Adds credit note specific data to the document
    * @param doc XML document
@@ -254,7 +319,7 @@ export class UBLEncoder extends UBLBaseEncoder {
     parentElement.appendChild(paymentTermsNode);
     
     // Payment terms note
-    this.appendElement(doc, paymentTermsNode, 'cbc:Note', `Due in ${invoice.dueInDays} days`);
+    this.appendElement(doc, paymentTermsNode, 'cbc:Note', getPaymentTermsNote(invoice.date, invoice.dueInDays, invoice.language, 'ubl'));
     
     // Add payment means if available
     if (invoice.paymentOptions) {
@@ -280,11 +345,9 @@ export class UBLEncoder extends UBLBaseEncoder {
     // Payment means code - default to credit transfer
     this.appendElement(doc, paymentMeansNode, 'cbc:PaymentMeansCode', '30');
     
-    // Payment due date - ensure invoice.date is a valid timestamp
-    const issueTimestamp = typeof invoice.date === 'number' ? invoice.date : Date.now();
-    const dueDate = new Date(issueTimestamp);
-    dueDate.setDate(dueDate.getDate() + (invoice.dueInDays || 30));
-    this.appendElement(doc, paymentMeansNode, 'cbc:PaymentDueDate', this.formatDate(dueDate.getTime()));
+    // Payment due date, counted from the issue date the document states
+    const dueDate = getWritableDueDate(invoice.date, invoice.dueInDays, 'ubl');
+    this.appendElement(doc, paymentMeansNode, 'cbc:PaymentDueDate', this.formatDate(dueDate.getTime(), 'BT-9 payment due date'));
     
     // Add payment channel code if available
     if (paymentOptions.description) {

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

@@ -89,7 +89,7 @@ export abstract class UBLBaseDecoder extends BaseDecoder {
   protected abstract decodeCreditNote(): Promise<TCreditNote>;
 
   /**
-   * Decodes a UBL invoice document: an invoice, a debit note or a self-billed invoice
+   * Decodes a UBL invoice document: an invoice, a corrected invoice, a debit note or a self-billed invoice
    * @param accountingDocType The type the document type code stands for
    * @returns Promise resolving to the invoice document
    */

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

@@ -1,6 +1,42 @@
 import { BaseEncoder } from '../base/base.encoder.js';
 import type { TAccountingDoc, TCreditNote, TInvoiceDocument } from '../../interfaces/common.js';
 import { UBLDocumentType, UBL_NAMESPACES } from './ubl.types.js';
+import { getWritableDate } from '../utils/date.value.js';
+
+/**
+ * The children of the document root in the order the UBL 2.1 schema requires
+ * them (UBL-Invoice-2.1.xsd and UBL-CreditNote-2.1.xsd, local names).
+ */
+const UBL_ROOT_SEQUENCES: Record<UBLDocumentType, readonly string[]> = {
+  [UBLDocumentType.INVOICE]: [
+    'UBLExtensions', 'UBLVersionID', 'CustomizationID', 'ProfileID', 'ProfileExecutionID', 'ID',
+    'CopyIndicator', 'UUID', 'IssueDate', 'IssueTime', 'DueDate', 'InvoiceTypeCode', 'Note',
+    'TaxPointDate', 'DocumentCurrencyCode', 'TaxCurrencyCode', 'PricingCurrencyCode',
+    'PaymentCurrencyCode', 'PaymentAlternativeCurrencyCode', 'AccountingCostCode', 'AccountingCost',
+    'LineCountNumeric', 'BuyerReference', 'InvoicePeriod', 'OrderReference', 'BillingReference',
+    'DespatchDocumentReference', 'ReceiptDocumentReference', 'StatementDocumentReference',
+    'OriginatorDocumentReference', 'ContractDocumentReference', 'AdditionalDocumentReference',
+    'ProjectReference', 'Signature', 'AccountingSupplierParty', 'AccountingCustomerParty',
+    'PayeeParty', 'BuyerCustomerParty', 'SellerSupplierParty', 'TaxRepresentativeParty', 'Delivery',
+    'DeliveryTerms', 'PaymentMeans', 'PaymentTerms', 'PrepaidPayment', 'AllowanceCharge',
+    'TaxExchangeRate', 'PricingExchangeRate', 'PaymentExchangeRate', 'PaymentAlternativeExchangeRate',
+    'TaxTotal', 'WithholdingTaxTotal', 'LegalMonetaryTotal', 'InvoiceLine',
+  ],
+  [UBLDocumentType.CREDIT_NOTE]: [
+    'UBLExtensions', 'UBLVersionID', 'CustomizationID', 'ProfileID', 'ProfileExecutionID', 'ID',
+    'CopyIndicator', 'UUID', 'IssueDate', 'IssueTime', 'TaxPointDate', 'CreditNoteTypeCode', 'Note',
+    'DocumentCurrencyCode', 'TaxCurrencyCode', 'PricingCurrencyCode', 'PaymentCurrencyCode',
+    'PaymentAlternativeCurrencyCode', 'AccountingCostCode', 'AccountingCost', 'LineCountNumeric',
+    'BuyerReference', 'InvoicePeriod', 'DiscrepancyResponse', 'OrderReference', 'BillingReference',
+    'DespatchDocumentReference', 'ReceiptDocumentReference', 'ContractDocumentReference',
+    'AdditionalDocumentReference', 'StatementDocumentReference', 'OriginatorDocumentReference',
+    'Signature', 'AccountingSupplierParty', 'AccountingCustomerParty', 'PayeeParty',
+    'BuyerCustomerParty', 'SellerSupplierParty', 'TaxRepresentativeParty', 'Delivery',
+    'DeliveryTerms', 'PaymentMeans', 'PaymentTerms', 'TaxExchangeRate', 'PricingExchangeRate',
+    'PaymentExchangeRate', 'PaymentAlternativeExchangeRate', 'AllowanceCharge', 'TaxTotal',
+    'LegalMonetaryTotal', 'CreditNoteLine',
+  ],
+};
 
 /**
  * Base encoder for UBL-based invoice formats
@@ -27,7 +63,7 @@ export abstract class UBLBaseEncoder extends BaseEncoder {
   protected abstract encodeCreditNote(creditNote: TCreditNote): Promise<string>;
 
   /**
-   * Encodes an invoice document (invoice, debit note or self-billed invoice) into UBL XML
+   * Encodes an invoice document (invoice, corrected invoice, debit note or self-billed invoice) into UBL XML
    * @param invoice Invoice document to encode
    * @returns UBL XML string
    */
@@ -47,20 +83,48 @@ export abstract class UBLBaseEncoder extends BaseEncoder {
   }
 
   /**
-   * Formats a date as an ISO string (YYYY-MM-DD)
-   * @param timestamp Timestamp to format
-   * @returns Formatted date string
+   * Puts the children of the document root into the order the schema requires.
+   * Elements are added in several passes (the generic encoder, a customization,
+   * preserved metadata), each inserting where it can; this final pass makes the
+   * result follow the schema sequence. The sort is stable, so repeated elements
+   * (notes, references, lines) keep their order, and an element the sequence
+   * does not name stays behind the element it followed.
+   * @param doc XML document
    */
-  protected formatDate(timestamp: number): string {
-    // Ensure timestamp is valid
-    if (!timestamp || isNaN(timestamp)) {
-      timestamp = Date.now();
+  protected orderRootElements(doc: Document): void {
+    const root = doc.documentElement;
+    const sequence = UBL_ROOT_SEQUENCES[root.localName as UBLDocumentType];
+    if (!sequence) {
+      return;
+    }
+    const children: Element[] = [];
+    for (let node = root.firstChild; node; node = node.nextSibling) {
+      if (node.nodeType === 1) {
+        children.push(node as Element);
+      }
     }
-    const date = new Date(timestamp);
-    // Check if date is valid
-    if (isNaN(date.getTime())) {
-      return new Date().toISOString().split('T')[0];
+    let lastRank = -1;
+    const ranked = children.map((element, position) => {
+      // an element made with createElement('cac:X') carries its prefix in localName as well
+      const rank = sequence.indexOf(element.nodeName.slice(element.nodeName.indexOf(':') + 1));
+      lastRank = rank === -1 ? lastRank : rank;
+      return { element, rank: lastRank, position };
+    });
+    ranked.sort((a, b) => a.rank - b.rank || a.position - b.position);
+    for (const { element } of ranked) {
+      root.appendChild(element);
     }
-    return date.toISOString().split('T')[0];
+  }
+
+  /**
+   * Formats a date as an ISO string (YYYY-MM-DD, UTC). A value that is no
+   * valid timestamp is refused with an `EInvoiceFormatError` naming the field;
+   * no date is put in its place.
+   * @param timestamp Timestamp to format
+   * @param field The business term the date is written as
+   * @returns Formatted date string
+   */
+  protected formatDate(timestamp: number, field: string): string {
+    return getWritableDate(timestamp, field, 'ubl').toISOString().split('T')[0];
   }
 }

package/ts/formats/ubl/ubl.types.ts

@@ -17,8 +17,14 @@ export enum UBLDocumentType {
   CREDIT_NOTE = 'CreditNote'
 }
 
-// UBL customization IDs for different formats
+// UBL customization IDs (specification identifier, BT-24) for different formats
 export const UBL_CUSTOMIZATION_IDS = {
-  XRECHNUNG: 'urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_2.0',
+  /**
+   * XRechnung 3.0 (CIUS), as the KoSIT XRechnung Schematron defines it (`XR-CIUS-ID` in
+   * common.sch: 'urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_' and
+   * the version '3.0'). XRechnung 1.x and 2.x used the prefix
+   * 'urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_'.
+   */
+  XRECHNUNG: 'urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0',
   PEPPOL_BIS: 'urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0'
 };

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

@@ -8,6 +8,10 @@ import type {
 import { business, finance } from '../../../plugins.js';
 import { UBLDocumentType } from '../ubl.types.js';
 import { EN16931Validator } from '../../validation/en16931.validator.js';
+import {
+  getPrecedingInvoiceFields,
+  type TPrecedingInvoiceReference,
+} from '../../utils/preceding.invoice.js';
 
 /**
  * Decoder for XRechnung (UBL) format
@@ -23,7 +27,7 @@ export class XRechnungDecoder extends UBLBaseDecoder {
   }
 
   /**
-   * Decodes a UBL invoice document: an invoice, a debit note or a self-billed invoice
+   * Decodes a UBL invoice document: an invoice, a corrected invoice, a debit note or a self-billed invoice
    * @param accountingDocType The type the document type code stands for
    * @returns Promise resolving to the invoice document
    */
@@ -56,14 +60,18 @@ export class XRechnungDecoder extends UBLBaseDecoder {
       const issueDate = this.parseRequiredUblDate(issueDateText);
       const currencyCode = this.getText('//cbc:DocumentCurrencyCode', this.doc) || 'EUR';
 
-      // Extract payment terms
-      let dueInDays = 30; // Default
-      const dueDateText = this.getText('//cac:PaymentTerms/cbc:PaymentDueDate', this.doc);
+      // The payment due date (BT-9): cbc:DueDate on an Invoice, cac:PaymentMeans/cbc:PaymentDueDate
+      // on a CreditNote, cac:PaymentTerms/cbc:PaymentDueDate as a last resort; the payment term in
+      // days is the calendar days from the issue date to it.
+      // no due date stated: `dueInDays` cannot express it yet (required field in @tsclass/tsclass); value unchanged: 30 days
+      let dueInDays = 30;
+      const dueDateText = (
+        this.getText('/*/cbc:DueDate', this.doc) ||
+        this.getText('/*/cac:PaymentMeans/cbc:PaymentDueDate', this.doc) ||
+        this.getText('/*/cac:PaymentTerms/cbc:PaymentDueDate', this.doc)
+      ).trim();
       if (dueDateText) {
-        const dueDateObj = new Date(dueDateText);
-        const issueDateObj = new Date(issueDate);
-        const diffTime = Math.abs(dueDateObj.getTime() - issueDateObj.getTime());
-        dueInDays = Math.ceil(diffTime / (1000 * 60 * 60 * 24));
+        dueInDays = Math.round((this.parseRequiredUblDate(dueDateText) - issueDate) / (1000 * 60 * 60 * 24));
       }
 
       // Extract items
@@ -168,10 +176,11 @@ export class XRechnungDecoder extends UBLBaseDecoder {
       const paymentTermsNote = this.getText('//cac:PaymentTerms/cbc:Note', this.doc);
       const discountPercent = this.getText('//cac:PaymentTerms/cbc:SettlementDiscountPercent', this.doc);
 
-      // Extract period information
-      const periodStart = this.getText('//cac:InvoicePeriod/cbc:StartDate', this.doc);
-      const periodEnd = this.getText('//cac:InvoicePeriod/cbc:EndDate', this.doc);
-      const deliveryDate = this.getText('//cac:Delivery/cbc:ActualDeliveryDate', this.doc);
+      // Extract the document level period (BG-14) and delivery date (BT-72); a line has
+      // an invoice period (BG-26) and a delivery of its own, which are not the document's
+      const periodStart = this.getText('/*/cac:InvoicePeriod/cbc:StartDate', this.doc);
+      const periodEnd = this.getText('/*/cac:InvoicePeriod/cbc:EndDate', this.doc);
+      const deliveryDate = this.getText('/*/cac:Delivery/cbc:ActualDeliveryDate', this.doc);
 
       // Extract notes (excluding PaymentTerms notes)
       const allNotes: string[] = [];
@@ -255,7 +264,18 @@ export class XRechnungDecoder extends UBLBaseDecoder {
         reverseCharge: false,
         currency: currencyCode as finance.TCurrency,
         notes: notes,
-        objectActions: []
+        objectActions: [],
+        // the day and the period of supply as the document states them (BT-72, BG-14)
+        ...(deliveryDate ? { deliveryDate: this.parseRequiredUblDate(deliveryDate) } : {}),
+        ...(periodStart && periodEnd
+          ? {
+              periodOfPerformance: {
+                from: this.parseRequiredUblDate(periodStart),
+                to: this.parseRequiredUblDate(periodEnd),
+              },
+            }
+          : {}),
+        ...getPrecedingInvoiceFields(accountingDocType, this.extractPrecedingInvoiceReferences()),
       };
 
       if (hasBusinessReferences || hasPaymentInformation || hasDateInformation) {
@@ -281,6 +301,29 @@ export class XRechnungDecoder extends UBLBaseDecoder {
     }
   }
 
+  /**
+   * Reads the preceding invoice references (BG-3): the number (BT-25) and,
+   * when stated, the issue date (BT-26) of each.
+   */
+  private extractPrecedingInvoiceReferences(): TPrecedingInvoiceReference[] {
+    const referenceNodes = this.select(
+      './cac:BillingReference/cac:InvoiceDocumentReference',
+      this.doc.documentElement,
+    );
+    const references: TPrecedingInvoiceReference[] = [];
+    for (const referenceNode of Array.isArray(referenceNodes) ? referenceNodes : []) {
+      const documentId = this.getText('./cbc:ID', referenceNode).trim();
+      if (!documentId) {
+        continue;
+      }
+      const issueDate = this.getText('./cbc:IssueDate', referenceNode).trim();
+      references.push(
+        issueDate ? { documentId, issueDate: this.parseRequiredUblDate(issueDate) } : { documentId },
+      );
+    }
+    return references;
+  }
+
   /**
    * Extracts party information from XML
    * @param partyPath XPath to the party element

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

@@ -1,6 +1,7 @@
 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';
 
 /**
  * Encoder for XRechnung (UBL) format
@@ -25,7 +26,7 @@ export class XRechnungEncoder extends UBLEncoder {
   }
   
   /**
-   * Encodes an invoice document (invoice, debit note or self-billed invoice) into XRechnung XML
+   * Encodes an invoice document (invoice, corrected invoice, debit note or self-billed invoice) into XRechnung XML
    * @param invoice Invoice document to encode
    * @returns XRechnung XML string
    */
@@ -52,10 +53,10 @@ export class XRechnungEncoder extends UBLEncoder {
     // Extract metadata if available
     const metadata = (invoice as any).metadata?.extensions;
     
-    // Update Customization ID to XRechnung 2.0
+    // Specification identifier (BT-24): XRechnung 3.0
     const customizationId = root.getElementsByTagName('cbc:CustomizationID')[0];
     if (customizationId) {
-      customizationId.textContent = 'urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_2.0';
+      customizationId.textContent = UBL_CUSTOMIZATION_IDS.XRECHNUNG;
     }
     
     // Add or update Buyer Reference (required for XRechnung)
@@ -73,15 +74,6 @@ export class XRechnungEncoder extends UBLEncoder {
       buyerRef.textContent = buyerReferenceValue;
     }
     
-    // Update payment terms to German
-    const paymentTermsNotes = root.getElementsByTagName('cac:PaymentTerms');
-    if (paymentTermsNotes.length > 0) {
-      const noteElement = paymentTermsNotes[0].getElementsByTagName('cbc:Note')[0];
-      if (noteElement && noteElement.textContent) {
-        noteElement.textContent = `Zahlung innerhalb von ${invoice.dueInDays || 30} Tagen`;
-      }
-    }
-    
     // Add electronic address for parties if available
     this.addElectronicAddressToParty(doc, 'cac:AccountingSupplierParty', invoice.from);
     this.addElectronicAddressToParty(doc, 'cac:AccountingCustomerParty', invoice.to);
@@ -114,6 +106,9 @@ export class XRechnungEncoder extends UBLEncoder {
     
     // Enhance line items with metadata
     this.enhanceLineItems(doc, invoice);
+
+    // the customizations above insert where they can; the schema order is restored last
+    this.orderRootElements(doc);
   }
   
   /**

package/ts/formats/utils/date.value.ts

@@ -0,0 +1,52 @@
+import { EInvoiceFormatError } from '../../errors.js';
+
+/**
+ * Calendar dates (BT-2, BT-7, BT-9, BT-26, BT-72, BT-73, BT-74) carry no time
+ * of day and no time zone: UBL writes them as `xsd:date`, CII in format 102
+ * (`YYYYMMDD`). In the accounting document envelope such a day is the UTC
+ * midnight of that day, which is what the decoders return. The encoders write
+ * it with the UTC fields of the date and count days in UTC, so the day
+ * written does not depend on the time zone of the machine that writes it.
+ */
+
+/**
+ * The date an encoder is about to write, as a `Date`. A value that is no
+ * finite timestamp, or lies outside the range of a JavaScript date, is refused
+ * with an `EInvoiceFormatError` naming the field: the encoders never write a
+ * date the document does not state, such as today in place of a missing one.
+ * @param timestamp The timestamp (milliseconds since the epoch) to write
+ * @param field The business term it is written as, for example `BT-2 invoice issue date`
+ * @param targetFormat The format being written
+ */
+export const getWritableDate = (timestamp: unknown, field: string, targetFormat: string): Date => {
+  const date = typeof timestamp === 'number' && Number.isFinite(timestamp) ? new Date(timestamp) : undefined;
+  if (!date || Number.isNaN(date.getTime())) {
+    throw new EInvoiceFormatError(`${field} is no valid date: ${String(timestamp)}`, {
+      targetFormat,
+      unsupportedFeatures: [field],
+    });
+  }
+  return date;
+};
+
+/**
+ * The payment due date (BT-9) a document states: its issue date plus
+ * `dueInDays` calendar days. `0` is due on the issue date. A `dueInDays` that
+ * is no whole number of days is refused with an `EInvoiceFormatError`; no other
+ * term is put in its place.
+ * @param issueTimestamp The issue date (BT-2)
+ * @param dueInDays The payment term in days, as the document states it
+ * @param targetFormat The format being written
+ */
+export const getWritableDueDate = (issueTimestamp: unknown, dueInDays: unknown, targetFormat: string): Date => {
+  const dueDate = getWritableDate(issueTimestamp, 'BT-2 invoice issue date', targetFormat);
+  if (typeof dueInDays !== 'number' || !Number.isInteger(dueInDays)) {
+    throw new EInvoiceFormatError(`BT-9 payment due date: dueInDays is no whole number of days: ${String(dueInDays)}`, {
+      targetFormat,
+      unsupportedFeatures: ['BT-9 payment due date'],
+    });
+  }
+  // calendar days counted in UTC: a calendar day is its UTC midnight, whatever the server's zone
+  dueDate.setUTCDate(dueDate.getUTCDate() + dueInDays);
+  return dueDate;
+};