@fin.cx/einvoice 8.1.0 → 8.2.1

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

@@ -4,12 +4,14 @@ import { CII_NAMESPACES, CIIProfile } from './cii.types.js';
 import { DOMParser, xpath } from '../../plugins.js';
 import { EInvoiceParsingError } from '../../errors.js';
 import { getAccountingDocType } from '../utils/document.typecode.js';
+import type { TPrecedingInvoiceReference } from '../utils/preceding.invoice.js';
 
 const ciiParser = new DOMParser();
 const ciiNamespaces = {
   rsm: CII_NAMESPACES.RSM,
   ram: CII_NAMESPACES.RAM,
   udt: CII_NAMESPACES.UDT,
+  qdt: CII_NAMESPACES.QDT,
 };
 const ciiSelect = xpath.useNamespaces(ciiNamespaces);
 
@@ -91,7 +93,7 @@ export abstract class CIIBaseDecoder extends BaseDecoder {
   protected abstract decodeCreditNote(): Promise<TCreditNote>;
 
   /**
-   * Decodes a CII invoice document: an invoice, a debit note or a self-billed invoice
+   * Decodes a CII 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 +101,77 @@ export abstract class CIIBaseDecoder extends BaseDecoder {
     accountingDocType: TInvoiceDocument['accountingDocType'],
   ): Promise<TInvoiceDocument>;
 
+  /**
+   * Reads the preceding invoice references (BG-3) of the header settlement:
+   * the number (BT-25) and, when stated, the issue date (BT-26) of each.
+   */
+  protected extractPrecedingInvoiceReferences(): TPrecedingInvoiceReference[] {
+    const referenceNodes = this.select(
+      '/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeSettlement/ram:InvoiceReferencedDocument',
+      this.doc,
+    );
+    const references: TPrecedingInvoiceReference[] = [];
+    for (const referenceNode of Array.isArray(referenceNodes) ? referenceNodes : []) {
+      const documentId = this.getText('./ram:IssuerAssignedID', referenceNode as Node).trim();
+      if (!documentId) {
+        continue;
+      }
+      const issueDate = this.getText('./ram:FormattedIssueDateTime/qdt:DateTimeString', referenceNode as Node).trim();
+      const issueDateFormat = this.getText('./ram:FormattedIssueDateTime/qdt:DateTimeString/@format', referenceNode as Node).trim();
+      references.push(
+        issueDate
+          ? { documentId, issueDate: this.parseRequiredCIIDate(issueDate, issueDateFormat) }
+          : { documentId },
+      );
+    }
+    return references;
+  }
+
+  /**
+   * Reads the invoice issue date (BT-2); a missing or invalid one is refused
+   * with an `EInvoiceParsingError`, as no other date can stand in for it.
+   */
+  protected extractIssueDate(): number {
+    const issueDatePath = '/rsm:CrossIndustryInvoice/rsm:ExchangedDocument/ram:IssueDateTime/udt:DateTimeString';
+    return this.parseRequiredCIIDate(this.getText(issueDatePath), this.getText(`${issueDatePath}/@format`).trim());
+  }
+
+  /**
+   * Reads the payment due date (BT-9) of the header payment terms; undefined
+   * when the document states none.
+   */
+  protected extractDueDate(): number | undefined {
+    const dueDatePath =
+      '/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeSettlement/ram:SpecifiedTradePaymentTerms/ram:DueDateDateTime/udt:DateTimeString';
+    const dueDate = this.getText(dueDatePath).trim();
+    if (!dueDate) {
+      return undefined;
+    }
+    return this.parseRequiredCIIDate(dueDate, this.getText(`${dueDatePath}/@format`).trim());
+  }
+
+  /**
+   * The payment term in days from the issue date to the stated due date, or
+   * `absentDueInDays` when the document states no due date.
+   */
+  protected dueInDaysOf(issueDate: number, dueDate: number | undefined, absentDueInDays: number): number {
+    return dueDate === undefined ? absentDueInDays : Math.round((dueDate - issueDate) / (1000 * 60 * 60 * 24));
+  }
+
+  /**
+   * Reads the actual delivery date (BT-72) of the header delivery; undefined
+   * when the document does not state one.
+   */
+  protected extractDeliveryDate(): number | undefined {
+    const deliveryDatePath =
+      '/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeDelivery/ram:ActualDeliverySupplyChainEvent/ram:OccurrenceDateTime/udt:DateTimeString';
+    const deliveryDate = this.getText(deliveryDatePath).trim();
+    if (!deliveryDate) {
+      return undefined;
+    }
+    return this.parseRequiredCIIDate(deliveryDate, this.getText(`${deliveryDatePath}/@format`).trim());
+  }
+
   /**
    * Gets a text value from an XPath expression
    * @param xpath XPath expression

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

@@ -1,5 +1,8 @@
 import { BaseEncoder } from '../base/base.encoder.js';
 import type { TAccountingDoc, TCreditNote, TInvoiceDocument } from '../../interfaces/common.js';
+import { EInvoiceFormatError } from '../../errors.js';
+import { getPrecedingInvoiceReferences } from '../utils/preceding.invoice.js';
+import { getWritableDate } from '../utils/date.value.js';
 import { CII_NAMESPACES, CIIProfile } from './cii.types.js';
 
 /**
@@ -22,6 +25,13 @@ export abstract class CIIBaseEncoder extends BaseEncoder {
    * @returns CII XML string
    */
   public async encode(invoice: TAccountingDoc): Promise<string> {
+    // MINIMUM has no preceding invoice reference (BG-3): a reference the document states cannot be written there
+    if (this.profile === CIIProfile.MINIMUM && getPrecedingInvoiceReferences(invoice).length > 0) {
+      throw new EInvoiceFormatError(
+        'The MINIMUM profile has no preceding invoice reference (BG-3); a document that refers to a preceding invoice needs a profile that carries it',
+        { targetFormat: 'cii', unsupportedFeatures: ['BG-3 in profile MINIMUM'] },
+      );
+    }
     // CII has one root for every document; the two paths differ in the type code they write
     if (invoice.accountingDocType === 'creditnote') {
       return this.encodeCreditNote(invoice);
@@ -37,7 +47,7 @@ export abstract class CIIBaseEncoder extends BaseEncoder {
   protected abstract encodeCreditNote(creditNote: TCreditNote): Promise<string>;
 
   /**
-   * Encodes an invoice document (invoice, debit note or self-billed invoice) into CII XML
+   * Encodes an invoice document (invoice, corrected invoice, debit note or self-billed invoice) into CII XML
    * @param invoice Invoice document to encode
    * @returns CII XML string
    */
@@ -51,17 +61,63 @@ export abstract class CIIBaseEncoder extends BaseEncoder {
     return `<?xml version="1.0" encoding="UTF-8"?>
 <rsm:CrossIndustryInvoice xmlns:rsm="${CII_NAMESPACES.RSM}"
   xmlns:ram="${CII_NAMESPACES.RAM}"
-  xmlns:udt="${CII_NAMESPACES.UDT}">
+  xmlns:udt="${CII_NAMESPACES.UDT}"
+  xmlns:qdt="${CII_NAMESPACES.QDT}">
 </rsm:CrossIndustryInvoice>`;
   }
 
   /**
-   * Formats a date as an ISO string (YYYY-MM-DD)
+   * 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). In the header settlement they follow the monetary summation, as
+   * the CII schema orders them.
+   * @param doc XML document
+   * @param invoice Accounting document
+   */
+  protected addPrecedingInvoiceReferences(doc: Document, invoice: TAccountingDoc): void {
+    const references = getPrecedingInvoiceReferences(invoice);
+    if (references.length === 0) {
+      return;
+    }
+    const settlement = doc.getElementsByTagName('ram:ApplicableHeaderTradeSettlement')[0];
+    if (!settlement) {
+      throw new EInvoiceFormatError('The document has no header trade settlement to carry its preceding invoice reference', {
+        targetFormat: 'cii',
+        unsupportedFeatures: ['BG-3'],
+      });
+    }
+    let summation: Element | undefined;
+    for (let node = settlement.firstChild; node; node = node.nextSibling) {
+      if (node.nodeType === 1 && node.nodeName === 'ram:SpecifiedTradeSettlementHeaderMonetarySummation') {
+        summation = node as Element;
+      }
+    }
+    const anchor = summation ? summation.nextSibling : null;
+    for (const reference of references) {
+      const referencedDocument = doc.createElement('ram:InvoiceReferencedDocument');
+      const issuerAssignedId = doc.createElement('ram:IssuerAssignedID');
+      issuerAssignedId.textContent = reference.documentId;
+      referencedDocument.appendChild(issuerAssignedId);
+      if (reference.issueDate !== undefined) {
+        const formattedIssueDateTime = doc.createElement('ram:FormattedIssueDateTime');
+        const dateTimeString = doc.createElement('qdt:DateTimeString');
+        dateTimeString.setAttribute('format', '102');
+        dateTimeString.textContent = this.formatDate(reference.issueDate, 'BT-26 preceding invoice issue date').replace(/-/g, '');
+        formattedIssueDateTime.appendChild(dateTimeString);
+        referencedDocument.appendChild(formattedIssueDateTime);
+      }
+      settlement.insertBefore(referencedDocument, anchor);
+    }
+  }
+
+  /**
+   * 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.
    * @param timestamp Timestamp to format
+   * @param field The business term the date is written as
    * @returns Formatted date string
    */
-  protected formatDate(timestamp: number): string {
-    const date = new Date(timestamp);
-    return date.toISOString().split('T')[0];
+  protected formatDate(timestamp: number, field: string): string {
+    return getWritableDate(timestamp, field, 'cii').toISOString().split('T')[0];
   }
 }

package/ts/formats/cii/cii.types.ts

@@ -6,7 +6,8 @@
 export const CII_NAMESPACES = {
   RSM: 'urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100',
   RAM: 'urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100',
-  UDT: 'urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100'
+  UDT: 'urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100',
+  QDT: 'urn:un:unece:uncefact:data:standard:QualifiedDataType:100'
 };
 
 // ZUGFeRD v1 namespaces

package/ts/formats/cii/facturx/facturx.decoder.ts

@@ -8,6 +8,7 @@ import type {
 import { FACTURX_PROFILE_IDS } from './facturx.types.js';
 import { business, finance, general } from '../../../plugins.js';
 import { EN16931Validator } from '../../validation/en16931.validator.js';
+import { getPrecedingInvoiceFields } from '../../utils/preceding.invoice.js';
 
 /**
  * Decoder for Factur-X invoice format
@@ -22,7 +23,7 @@ export class FacturXDecoder extends CIIBaseDecoder {
   }
 
   /**
-   * Decodes a Factur-X invoice document: an invoice, a debit note or a self-billed invoice
+   * Decodes a Factur-X 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
    */
@@ -66,10 +67,8 @@ export class FacturXDecoder extends CIIBaseDecoder {
     const items = this.extractItems();
 
     // Extract due date
-    const dueDateStr = this.getText('//ram:SpecifiedTradePaymentTerms/ram:DueDateDateTime/udt:DateTimeString');
-    const dueDateFormat = this.getText('//ram:SpecifiedTradePaymentTerms/ram:DueDateDateTime/udt:DateTimeString/@format');
-    const dueDate = dueDateStr ? this.parseCIIDate(dueDateStr, dueDateFormat) : issueDate;
-    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
+    const dueInDays = this.dueInDaysOf(issueDate, this.extractDueDate(), 0);
 
     // Extract currency
     const currencyCode = this.getText('//ram:InvoiceCurrencyCode') || 'EUR';
@@ -92,6 +91,9 @@ export class FacturXDecoder 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"]');
 
@@ -119,8 +121,10 @@ export class FacturXDecoder 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/facturx/facturx.encoder.ts

@@ -6,6 +6,7 @@ import { Decimal } from '../../utils/decimal.js';
 import { DecimalCurrencyCalculator } from '../../utils/currency.calculator.decimal.js';
 import { getCurrencyMinorUnits } from '../../utils/currency.utils.js';
 import { getDocumentTypeCode } from '../../utils/document.typecode.js';
+import { getWritableDate, getWritableDueDate } from '../../utils/date.value.js';
 
 /**
  * Encoder for Factur-X invoice format
@@ -31,7 +32,7 @@ export class FacturXEncoder extends CIIBaseEncoder {
   }
 
   /**
-   * Encodes an invoice document (invoice, debit note or self-billed invoice) into Factur-X XML
+   * Encodes an invoice document (invoice, corrected invoice, debit note or self-billed invoice) into Factur-X XML
    * @param invoice Invoice document to encode
    * @returns Factur-X XML string
    */
@@ -39,7 +40,7 @@ export class FacturXEncoder 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
@@ -101,7 +102,7 @@ export class FacturXEncoder extends CIIBaseEncoder {
   /**
    * Sets the document type code in the XML document
    * @param doc XML document
-   * @param typeCode Document type code (380 invoice, 381 credit note, 383 debit note, 389 self-billed invoice)
+   * @param typeCode Document type code (380 invoice, 381 credit note, 383 debit note, 384 corrected invoice, 389 self-billed invoice)
    */
   private setDocumentTypeCode(doc: Document, typeCode: string): void {
     // Get root element
@@ -145,7 +146,7 @@ export class FacturXEncoder 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);
 
@@ -183,6 +184,9 @@ export class FacturXEncoder 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);
   }
@@ -284,12 +288,12 @@ export class FacturXEncoder 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);
@@ -321,10 +325,9 @@ export class FacturXEncoder extends CIIBaseEncoder {
     dateStringElement.setAttribute('format', '102'); // YYYYMMDD format
 
     // Calculate due date
-    const dueDate = new Date(invoice.date);
-    dueDate.setDate(dueDate.getDate() + invoice.dueInDays);
+    const dueDate = getWritableDueDate(invoice.date, invoice.dueInDays, 'cii');
 
-    dateStringElement.textContent = this.formatDateYYYYMMDD(dueDate.getTime());
+    dateStringElement.textContent = this.formatDateYYYYMMDD(dueDate.getTime(), 'BT-9 payment due date');
     dueDateElement.appendChild(dateStringElement);
     paymentTermsElement.appendChild(dueDateElement);
 
@@ -487,11 +490,12 @@ export class FacturXEncoder extends CIIBaseEncoder {
    * @param timestamp Timestamp to format
    * @returns Formatted date string
    */
-  private formatDateYYYYMMDD(timestamp: number): string {
-    const date = new Date(timestamp);
-    const year = date.getFullYear();
-    const month = (date.getMonth() + 1).toString().padStart(2, '0');
-    const day = date.getDate().toString().padStart(2, '0');
+  private formatDateYYYYMMDD(timestamp: number, field: string): string {
+    const date = getWritableDate(timestamp, field, 'cii');
+    // the UTC fields: a calendar day is its UTC midnight, whatever the server's zone
+    const year = date.getUTCFullYear();
+    const month = (date.getUTCMonth() + 1).toString().padStart(2, '0');
+    const day = date.getUTCDate().toString().padStart(2, '0');
     return `${year}${month}${day}`;
   }
 }

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
    */
@@ -43,9 +44,7 @@ export class ZUGFeRDDecoder extends CIIBaseDecoder {
     const invoiceId = this.getText('//rsm:ExchangedDocument/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');
@@ -57,9 +56,8 @@ export class ZUGFeRDDecoder 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: the days from the issue date to the moment of decoding
+    const dueInDays = this.dueInDaysOf(issueDate, this.extractDueDate(), Math.round((Date.now() - issueDate) / (1000 * 60 * 60 * 24)));
 
     // Extract currency
     const currencyCode = this.getText('//ram:InvoiceCurrencyCode') || 'EUR';
@@ -83,6 +81,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 +111,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,8 @@ 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, getWritableDueDate } from '../../utils/date.value.js';
+import { getPaymentTermsNote } from '../../utils/payment.terms.js';
 
 /**
  * Encoder for ZUGFeRD invoice format
@@ -35,7 +37,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 +45,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 +151,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 +189,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 +321,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 +337,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);
       }
@@ -378,7 +383,10 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
     if (invoice.paymentOptions) {
       // Add payment instructions as description - this is generic enough to work with any payment type
       const descriptionElement = doc.createElement('ram:Description');
-      descriptionElement.textContent = `Due in ${invoice.dueInDays} days. ${invoice.paymentOptions.description || ''}`;
+      descriptionElement.textContent = [
+        getPaymentTermsNote(invoice.date, invoice.dueInDays, invoice.language, 'cii'),
+        invoice.paymentOptions.description,
+      ].filter(Boolean).join('. ');
       paymentTermsElement.appendChild(descriptionElement);
     }
 
@@ -388,10 +396,9 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
     dateStringElement.setAttribute('format', '102'); // YYYYMMDD format
 
     // Calculate due date
-    const dueDate = new Date(invoice.date);
-    dueDate.setDate(dueDate.getDate() + invoice.dueInDays);
+    const dueDate = getWritableDueDate(invoice.date, invoice.dueInDays, 'cii');
 
-    dateStringElement.textContent = this.formatDateYYYYMMDD(dueDate.getTime());
+    dateStringElement.textContent = this.formatDateYYYYMMDD(dueDate.getTime(), 'BT-9 payment due date');
     dueDateElement.appendChild(dateStringElement);
     paymentTermsElement.appendChild(dueDateElement);
 
@@ -655,11 +662,12 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
    * @param timestamp Timestamp to format
    * @returns Formatted date string
    */
-  private formatDateYYYYMMDD(timestamp: number): string {
-    const date = new Date(timestamp);
-    const year = date.getFullYear();
-    const month = (date.getMonth() + 1).toString().padStart(2, '0');
-    const day = date.getDate().toString().padStart(2, '0');
+  private formatDateYYYYMMDD(timestamp: number, field: string): string {
+    const date = getWritableDate(timestamp, field, 'cii');
+    // the UTC fields: a calendar day is its UTC midnight, whatever the server's zone
+    const year = date.getUTCFullYear();
+    const month = (date.getUTCMonth() + 1).toString().padStart(2, '0');
+    const day = date.getUTCDate().toString().padStart(2, '0');
     return `${year}${month}${day}`;
   }
 }