@fin.cx/einvoice 8.0.0 → 8.2.0

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);
 
@@ -599,7 +603,10 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
         const deliveryElement = doc.createElement('ram:SpecifiedLineTradeDelivery');
         const quantityElement = doc.createElement('ram:BilledQuantity');
         quantityElement.textContent = item.unitQuantity.toString();
-        quantityElement.setAttribute('unitCode', item.unitType);
+        // a line without a unit is written without one, so that BR-23 reports it
+        if (item.unitType) {
+          quantityElement.setAttribute('unitCode', item.unitType);
+        }
         deliveryElement.appendChild(quantityElement);
         lineItemElement.appendChild(deliveryElement);
 
@@ -652,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: []
     };
     
@@ -206,7 +233,8 @@ export class ZUGFeRDV1Decoder extends CIIBaseDecoder {
         const name = this.getText('ram:SpecifiedTradeProduct/ram:Name', itemNode);
         const articleNumber = this.getText('ram:SpecifiedTradeProduct/ram:SellerAssignedID', itemNode);
         const unitQuantity = this.getNumber('ram:SpecifiedLineTradeDelivery/ram:BilledQuantity', itemNode);
-        const unitType = this.getText('ram:SpecifiedLineTradeDelivery/ram:BilledQuantity/@unitCode', itemNode) || 'EA';
+        // an absent unit code (BT-130) stays absent, so that BR-23 reports it
+        const unitType = this.getText('ram:SpecifiedLineTradeDelivery/ram:BilledQuantity/@unitCode', itemNode);
         const unitNetPrice = this.getNumber('ram:SpecifiedLineTradeAgreement/ram:NetPriceProductTradePrice/ram:ChargeAmount', itemNode);
         const vatPercentage = this.getNumber('ram:SpecifiedLineTradeSettlement/ram:ApplicableTradeTax/ram:RateApplicablePercent', itemNode);
 

package/ts/formats/cii/zugferd/zugferd.validator.ts

@@ -24,8 +24,9 @@ export class ZUGFeRDValidator extends CIIBaseValidator {
    * @returns True if business validation passed
    */
   protected validateBusinessRules(): boolean {
-    // Implement ZUGFeRD-specific business rules
-    // For now, we'll just use the base CII validation
-    return true;
+    // BR-23: every line has a unit code
+    const linesHaveUnits = this.validateLineUnitCodePresence();
+    // BR-CL-23: unit codes of UN/ECE Recommendation 20 with the Recommendation 21 extension
+    return this.validateUnitCodes() && linesHaveUnits;
   }
 }

package/ts/formats/converters/xml-to-einvoice.converter.ts

@@ -100,7 +100,8 @@ export class XMLToEInvoiceConverter {
             position: i,
             name: this.getElementTextFromNode(line, 'cbc:Name') || `Item ${i + 1}`,
             unitQuantity: parseFloat(this.getElementTextFromNode(line, 'cbc:InvoicedQuantity') || '1'),
-            unitType: 'C62',
+            // the unit code (BT-130) the document states, or none, which BR-23 reports
+            unitType: this.getAttributeFromNode(line, 'cbc:InvoicedQuantity', 'unitCode'),
             unitNetPrice: parseFloat(this.getElementTextFromNode(line, 'cbc:PriceAmount') || '100'),
             vatPercentage: parseFloat(this.getElementTextFromNode(line, 'cbc:Percent') || '19')
           };
@@ -118,6 +119,15 @@ export class XMLToEInvoiceConverter {
     return mockInvoice as unknown as EInvoice;
   }
   
+  /**
+   * Helper to get an attribute of the first matching element below a node, or '' when the element
+   * or the attribute is absent
+   */
+  private getAttributeFromNode(node: Element, tagName: string, attributeName: string): string {
+    const element = node.getElementsByTagName(tagName)[0];
+    return element?.getAttribute(attributeName) ?? '';
+  }
+
   /**
    * Helper to get element text from a node
    */

package/ts/formats/semantic/semantic.adapter.ts

@@ -442,7 +442,7 @@ export class SemanticModelAdapter {
       identifier: (index + 1).toString(),
       note: (item as any).description || (item as any).text || '',
       invoicedQuantity: item.unitQuantity,
-      invoicedQuantityUnitOfMeasureCode: item.unitType || 'C62',
+      invoicedQuantityUnitOfMeasureCode: item.unitType,
       lineExtensionAmount: item.unitNetPrice * item.unitQuantity,
       purchaseOrderLineReference: (item as any).purchaseOrderLineRef,
       buyerAccountingReference: (item as any).buyerAccountingRef,

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

@@ -148,6 +148,12 @@ export class EN16931UBLValidator extends UBLBaseValidator {
       valid = false;
     }
 
+    // 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;

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) {
@@ -459,7 +523,10 @@ export class UBLEncoder extends UBLBaseEncoder {
       
       // Invoiced quantity
       const quantityElement = doc.createElement(creditNote ? 'cbc:CreditedQuantity' : 'cbc:InvoicedQuantity');
-      quantityElement.setAttribute('unitCode', item.unitType);
+      // a line without a unit is written without one, so that BR-23 reports it
+      if (item.unitType) {
+        quantityElement.setAttribute('unitCode', item.unitType);
+      }
       quantityElement.textContent = item.unitQuantity.toString();
       invoiceLineNode.appendChild(quantityElement);
       

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.validator.ts

@@ -3,6 +3,7 @@ import { ValidationLevel } from '../../interfaces/common.js';
 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';
 
 const ublValidatorParser = new DOMParser();
 const ublValidatorNamespaces = {
@@ -104,6 +105,52 @@ export abstract class UBLBaseValidator extends BaseValidator {
    */
   protected abstract validateStructure(): boolean;
 
+  /**
+   * 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
+   */
+  protected validateLineUnitCodePresence(): boolean {
+    // BR-23: every invoice or credit note line (BG-25) has an invoiced quantity unit of measure code (BT-130)
+    const lines = this.select('//cac:InvoiceLine | //cac:CreditNoteLine', this.doc) as Element[];
+    let valid = true;
+    for (const line of lines) {
+      if (!this.exists('./cbc:InvoicedQuantity/@unitCode | ./cbc:CreditedQuantity/@unitCode', line)) {
+        this.addError(
+          'BR-23',
+          'An Invoice line (BG-25) shall have an Invoiced quantity unit of measure code (BT-130)',
+          this.locationOf(line)
+        );
+        valid = false;
+      }
+    }
+    return valid;
+  }
+
+  /**
+   * BR-CL-23: every unit code of an invoiced, credited or base quantity (BT-130, BT-150) is a
+   * code of UN/ECE Recommendation 20 with the Recommendation 21 extension.
+   * @returns True if every unit code passed
+   */
+  protected validateUnitCodes(): boolean {
+    const quantities = this.select(
+      '//cbc:InvoicedQuantity[@unitCode] | //cbc:CreditedQuantity[@unitCode] | //cbc:BaseQuantity[@unitCode]',
+      this.doc
+    ) as Element[];
+    let valid = true;
+    for (const quantity of quantities) {
+      const unitCode = quantity.getAttribute('unitCode') ?? '';
+      if (!meetsUnitCodeRule(unitCode)) {
+        this.addError(
+          'BR-CL-23',
+          `Unit code MUST be coded according to the UN/ECE Recommendation 20 with Rec 21 extension; found "${unitCode}"`,
+          `${this.locationOf(quantity)}/@unitCode`
+        );
+        valid = false;
+      }
+    }
+    return valid;
+  }
+
   /**
    * Gets a text value from an XPath expression
    * @param xpath XPath expression