@fin.cx/einvoice 8.1.0 → 8.2.0

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

@@ -7,6 +7,7 @@ import type {
 } from '../../../interfaces/common.js';
 import { business, finance } from '../../../plugins.js';
 import { EN16931Validator } from '../../validation/en16931.validator.js';
+import { getPrecedingInvoiceFields } from '../../utils/preceding.invoice.js';
 
 /**
  * Decoder for ZUGFeRD invoice format
@@ -21,7 +22,7 @@ export class ZUGFeRDDecoder extends CIIBaseDecoder {
   }
 
   /**
-   * Decodes a ZUGFeRD invoice document: an invoice, a debit note or a self-billed invoice
+   * Decodes a ZUGFeRD 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
    */
@@ -83,6 +84,9 @@ export class ZUGFeRDDecoder 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"]');
 
@@ -110,8 +114,10 @@ export class ZUGFeRDDecoder extends CIIBaseDecoder {
       reverseCharge: reverseCharge,
       currency: currencyCode as finance.TCurrency,
       notes: notes,
-      deliveryDate: issueDate,
-      objectActions: []
+      // the day of supply as the document states it (BT-72)
+      ...(deliveryDate === undefined ? {} : { deliveryDate }),
+      objectActions: [],
+      ...getPrecedingInvoiceFields(accountingDocType, this.extractPrecedingInvoiceReferences()),
     };
     
     // Validate mandatory EN16931 fields unless validation is skipped

package/ts/formats/cii/zugferd/zugferd.encoder.ts

@@ -4,6 +4,7 @@ import { ZUGFERD_PROFILE_IDS } from './zugferd.types.js';
 import { CIIProfile } from '../cii.types.js';
 import { DOMParser, XMLSerializer } from '../../../plugins.js';
 import { getDocumentTypeCode } from '../../utils/document.typecode.js';
+import { getWritableDate } from '../../utils/date.value.js';
 
 /**
  * Encoder for ZUGFeRD invoice format
@@ -35,7 +36,7 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
   }
 
   /**
-   * Encodes an invoice document (invoice, debit note or self-billed invoice) into ZUGFeRD XML
+   * Encodes an invoice document (invoice, corrected invoice, debit note or self-billed invoice) into ZUGFeRD XML
    * @param invoice Invoice document to encode
    * @returns ZUGFeRD XML string
    */
@@ -43,7 +44,7 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
     // Create base XML
     const xmlDoc = this.createBaseXml();
 
-    // Set document type code (380 invoice, 383 debit note, 389 self-billed invoice)
+    // Set document type code (380 invoice, 383 debit note, 384 corrected invoice, 389 self-billed invoice)
     this.setDocumentTypeCode(xmlDoc, getDocumentTypeCode(invoice.accountingDocType));
 
     // Add common invoice data
@@ -149,7 +150,7 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
     const issueDateElement = doc.createElement('ram:IssueDateTime');
     const dateStringElement = doc.createElement('udt:DateTimeString');
     dateStringElement.setAttribute('format', '102'); // YYYYMMDD format
-    dateStringElement.textContent = this.formatDateYYYYMMDD(invoice.date);
+    dateStringElement.textContent = this.formatDateYYYYMMDD(invoice.date, 'BT-2 invoice issue date');
     issueDateElement.appendChild(dateStringElement);
     documentElement.appendChild(issueDateElement);
 
@@ -187,6 +188,9 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
     // Add settlement section with payment terms and totals
     this.addSettlementSection(doc, transactionElement, invoice);
 
+    // Add the preceding invoice references (BG-3) the document states
+    this.addPrecedingInvoiceReferences(doc, invoice);
+
     // Add line items
     this.addLineItems(doc, transactionElement, invoice);
   }
@@ -316,12 +320,12 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
     transactionElement.appendChild(deliveryElement);
 
     // Add delivery date if available
-    if (invoice.deliveryDate) {
+    if (invoice.deliveryDate !== undefined) {
       const deliveryDateElement = doc.createElement('ram:ActualDeliverySupplyChainEvent');
       const occurrenceDateElement = doc.createElement('ram:OccurrenceDateTime');
       const dateStringElement = doc.createElement('udt:DateTimeString');
       dateStringElement.setAttribute('format', '102'); // YYYYMMDD format
-      dateStringElement.textContent = this.formatDateYYYYMMDD(invoice.deliveryDate);
+      dateStringElement.textContent = this.formatDateYYYYMMDD(invoice.deliveryDate, 'BT-72 actual delivery date');
       occurrenceDateElement.appendChild(dateStringElement);
       deliveryDateElement.appendChild(occurrenceDateElement);
       deliveryElement.appendChild(deliveryDateElement);
@@ -332,21 +336,21 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
       const periodElement = doc.createElement('ram:BillingSpecifiedPeriod');
       
       // Start date
-      if (invoice.periodOfPerformance.from) {
+      if (invoice.periodOfPerformance.from !== undefined) {
         const startDateElement = doc.createElement('ram:StartDateTime');
         const startDateStringElement = doc.createElement('udt:DateTimeString');
         startDateStringElement.setAttribute('format', '102'); // YYYYMMDD format
-        startDateStringElement.textContent = this.formatDateYYYYMMDD(invoice.periodOfPerformance.from);
+        startDateStringElement.textContent = this.formatDateYYYYMMDD(invoice.periodOfPerformance.from, 'BT-73 invoicing period start date');
         startDateElement.appendChild(startDateStringElement);
         periodElement.appendChild(startDateElement);
       }
       
       // End date
-      if (invoice.periodOfPerformance.to) {
+      if (invoice.periodOfPerformance.to !== undefined) {
         const endDateElement = doc.createElement('ram:EndDateTime');
         const endDateStringElement = doc.createElement('udt:DateTimeString');
         endDateStringElement.setAttribute('format', '102'); // YYYYMMDD format
-        endDateStringElement.textContent = this.formatDateYYYYMMDD(invoice.periodOfPerformance.to);
+        endDateStringElement.textContent = this.formatDateYYYYMMDD(invoice.periodOfPerformance.to, 'BT-74 invoicing period end date');
         endDateElement.appendChild(endDateStringElement);
         periodElement.appendChild(endDateElement);
       }
@@ -391,7 +395,7 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
     const dueDate = new Date(invoice.date);
     dueDate.setDate(dueDate.getDate() + invoice.dueInDays);
 
-    dateStringElement.textContent = this.formatDateYYYYMMDD(dueDate.getTime());
+    dateStringElement.textContent = this.formatDateYYYYMMDD(dueDate.getTime(), 'BT-9 payment due date');
     dueDateElement.appendChild(dateStringElement);
     paymentTermsElement.appendChild(dueDateElement);
 
@@ -655,8 +659,8 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
    * @param timestamp Timestamp to format
    * @returns Formatted date string
    */
-  private formatDateYYYYMMDD(timestamp: number): string {
-    const date = new Date(timestamp);
+  private formatDateYYYYMMDD(timestamp: number, field: string): string {
+    const date = getWritableDate(timestamp, field, 'cii');
     const year = date.getFullYear();
     const month = (date.getMonth() + 1).toString().padStart(2, '0');
     const day = date.getDate().toString().padStart(2, '0');

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,22 @@ export class ZUGFeRDV1Decoder extends CIIBaseDecoder {
     };
   }
 
+  /**
+   * 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 +60,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
    */
@@ -99,6 +122,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 +152,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,8 @@ 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 { getWritableDate } from '../../utils/date.value.js';
 
 /**
  * UBL Encoder implementation
@@ -24,13 +26,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 +48,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 +77,15 @@ 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);
+      const dueDate = getWritableDate(invoice.date, 'BT-2 invoice issue date', 'ubl');
       dueDate.setDate(dueDate.getDate() + (invoice.dueInDays || 30));
-      this.appendElement(doc, root, 'cbc:DueDate', this.formatDate(dueDate.getTime()));
+      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
@@ -280,11 +345,10 @@ 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);
+    // Payment due date, counted from the issue date the document states
+    const dueDate = getWritableDate(invoice.date, 'BT-2 invoice issue date', 'ubl');
     dueDate.setDate(dueDate.getDate() + (invoice.dueInDays || 30));
-    this.appendElement(doc, paymentMeansNode, 'cbc:PaymentDueDate', this.formatDate(dueDate.getTime()));
+    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/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
    */
@@ -168,10 +172,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 +260,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 +297,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

@@ -25,7 +25,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
    */
@@ -114,6 +114,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,21 @@
+import { EInvoiceFormatError } from '../../errors.js';
+
+/**
+ * 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;
+};

package/ts/formats/utils/document.typecode.ts

@@ -7,6 +7,7 @@ import { EInvoiceFormatError } from '../../errors.js';
  */
 const DOCUMENT_TYPE_CODES: Record<TAccountingDocType, string> = {
   'invoice': '380',
+  'corrected-invoice': '384',
   'creditnote': '381',
   'debitnote': '383',
   'self-billed-invoice': '389',
@@ -42,9 +43,9 @@ export const getDocumentTypeCode = (accountingDocType: TAccountingDocType): stri
 };
 
 /**
- * The accounting document type of a decoded type code. 383 and 389 have a
- * type of their own; the remaining credit note related codes are credit
- * notes; everything else is an invoice, which covers 380, 384 and the other
+ * The accounting document type of a decoded type code. 383, 384 and 389 have
+ * a type of their own; the remaining credit note related codes are credit
+ * notes; everything else is an invoice, which covers 380 and the other
  * invoice related codes (326, 386, 875, ...) the envelope has no name for.
  * A missing or unlisted code stays an invoice as well: the document is an
  * invoice document, and reporting the code is the validators' job (BR-04,
@@ -55,6 +56,9 @@ export const getAccountingDocType = (typeCode: string): TAccountingDocType => {
   if (code === DOCUMENT_TYPE_CODES['debitnote']) {
     return 'debitnote';
   }
+  if (code === DOCUMENT_TYPE_CODES['corrected-invoice']) {
+    return 'corrected-invoice';
+  }
   if (code === DOCUMENT_TYPE_CODES['self-billed-invoice']) {
     return 'self-billed-invoice';
   }