@fin.cx/einvoice 10.0.0 → 10.1.0

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

@@ -8,6 +8,8 @@ import type { TPrecedingInvoiceReference } from '../utils/preceding.invoice.js';
 import type { IEInvoiceMetadata } from '../../interfaces/en16931-metadata.js';
 import type { IEInvoiceStatedValues } from '../../interfaces/stated.values.js';
 import { readCiiStatedValues } from '../utils/stated.values.js';
+import { applyStatedVatCategories } from '../utils/vat.category.js';
+import { deliveryAddressOf, withDeliveryAddress, type TDeliveryAddress } from '../utils/delivery.address.js';
 
 /**
  * The invoicing period (BG-14) a CII document states: its start date (BT-73),
@@ -79,10 +81,29 @@ export abstract class CIIBaseDecoder extends BaseDecoder {
     const accountingDocType = getAccountingDocType(
       this.getText('/rsm:CrossIndustryInvoice/rsm:ExchangedDocument/ram:TypeCode'),
     );
-    if (accountingDocType === 'creditnote') {
-      return this.decodeCreditNote();
-    }
-    return this.decodeInvoice(accountingDocType);
+    const document = accountingDocType === 'creditnote' ? await this.decodeCreditNote() : await this.decodeInvoice(accountingDocType);
+    // every item with the VAT category its line states and its breakdown's exemption reason
+    applyStatedVatCategories(document.items, this.statedValues);
+    return withDeliveryAddress(document, this.readDeliveryAddress());
+  }
+
+  /**
+   * Reads the deliver to address (BG-15) of the header delivery: line one and
+   * two as the street (BT-75) and the house number, the city (BT-77), the post
+   * code (BT-78), the country subdivision (BT-79) and the country (BT-80);
+   * undefined when the document states no address with a country
+   */
+  protected readDeliveryAddress(): TDeliveryAddress | undefined {
+    const address =
+      '/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeDelivery/ram:ShipToTradeParty/ram:PostalTradeAddress';
+    return deliveryAddressOf({
+      streetName: this.getText(`${address}/ram:LineOne`),
+      houseNumber: this.getText(`${address}/ram:LineTwo`),
+      city: this.getText(`${address}/ram:CityName`),
+      postalCode: this.getText(`${address}/ram:PostcodeCode`),
+      countrySubdivision: this.getText(`${address}/ram:CountrySubDivisionName`),
+      countryCode: this.getText(`${address}/ram:CountryID`),
+    });
   }
 
   /**
@@ -158,9 +179,9 @@ export abstract class CIIBaseDecoder extends BaseDecoder {
   }
 
   /**
-   * Whether every line of the document has the VAT category reverse charge (AE, BT-151); the
-   * envelope states it for the whole document, so a document mixing AE lines with others
-   * cannot say it
+   * Whether every line of the document has the VAT category reverse charge (AE, BT-151); a
+   * document mixing AE lines with others is not, and its items carry their categories
+   * (`applyStatedVatCategories`)
    */
   protected isReverseChargeDocument(): boolean {
     const categories = this.select(

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

@@ -284,6 +284,42 @@ export abstract class CIIBaseEncoder extends BaseEncoder {
     agreementElement.appendChild(buyerReferenceElement);
   }
 
+  /**
+   * Adds the deliver to address (BG-15) of `metadata.deliveryAddress` as
+   * `ram:ShipToTradeParty/ram:PostalTradeAddress` of the header delivery, when
+   * it states a country (BT-80, which BR-57 requires of the address): the
+   * street and house number as line one and two (BT-75, BT-76), the city
+   * (BT-77), the post code (BT-78), the country subdivision (BT-79) and the
+   * country. An intra-community supply states it (BR-IC-12).
+   * @param doc XML document
+   * @param deliveryElement The header trade delivery
+   * @param invoice Invoice data
+   */
+  protected addDeliverToAddress(doc: Document, deliveryElement: Element, invoice: TAccountingDoc): void {
+    const address = (invoice as TAccountingDoc & { metadata?: IEInvoiceMetadata }).metadata?.deliveryAddress;
+    const countryCode = address?.countryCode?.trim();
+    if (!address || !countryCode) {
+      return;
+    }
+    const shipTo = doc.createElement('ram:ShipToTradeParty');
+    const postal = doc.createElement('ram:PostalTradeAddress');
+    const append = (name: string, text: string | undefined) => {
+      if (text?.trim()) {
+        const element = doc.createElement(name);
+        element.textContent = text.trim();
+        postal.appendChild(element);
+      }
+    };
+    append('ram:PostcodeCode', address.postalCode);
+    append('ram:LineOne', address.streetName);
+    append('ram:LineTwo', address.houseNumber);
+    append('ram:CityName', address.city);
+    append('ram:CountryID', countryCode);
+    append('ram:CountrySubDivisionName', address.countrySubdivision);
+    shipTo.appendChild(postal);
+    deliveryElement.insertBefore(shipTo, deliveryElement.firstChild);
+  }
+
   /**
    * Adds the invoicing period (BG-14) as `ram:BillingSpecifiedPeriod` of the
    * header settlement, where the CII schema puts it: the start date (BT-73) and

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

@@ -59,6 +59,7 @@ export const CII_CHILD_SEQUENCES: Readonly<Record<string, readonly string[]>> =
   ApplicableHeaderTradeAgreement: ['Reference', 'BuyerReference', 'SellerTradeParty', 'BuyerTradeParty', 'SalesAgentTradeParty', 'BuyerRequisitionerTradeParty', 'BuyerAssignedAccountantTradeParty', 'SellerAssignedAccountantTradeParty', 'BuyerTaxRepresentativeTradeParty', 'SellerTaxRepresentativeTradeParty', 'ProductEndUserTradeParty', 'ApplicableTradeDeliveryTerms', 'SellerOrderReferencedDocument', 'BuyerOrderReferencedDocument', 'QuotationReferencedDocument', 'OrderResponseReferencedDocument', 'ContractReferencedDocument', 'DemandForecastReferencedDocument', 'SupplyInstructionReferencedDocument', 'PromotionalDealReferencedDocument', 'PriceListReferencedDocument', 'AdditionalReferencedDocument', 'RequisitionerReferencedDocument', 'BuyerAgentTradeParty', 'PurchaseConditionsReferencedDocument', 'SpecifiedProcuringProject', 'UltimateCustomerOrderReferencedDocument'],
   SellerTradeParty: ['ID', 'GlobalID', 'Name', 'RoleCode', 'Description', 'SpecifiedLegalOrganization', 'DefinedTradeContact', 'PostalTradeAddress', 'URIUniversalCommunication', 'SpecifiedTaxRegistration', 'EndPointURIUniversalCommunication', 'LogoAssociatedSpecifiedBinaryFile'],
   BuyerTradeParty: ['ID', 'GlobalID', 'Name', 'RoleCode', 'Description', 'SpecifiedLegalOrganization', 'DefinedTradeContact', 'PostalTradeAddress', 'URIUniversalCommunication', 'SpecifiedTaxRegistration', 'EndPointURIUniversalCommunication', 'LogoAssociatedSpecifiedBinaryFile'],
+  ShipToTradeParty: ['ID', 'GlobalID', 'Name', 'RoleCode', 'Description', 'SpecifiedLegalOrganization', 'DefinedTradeContact', 'PostalTradeAddress', 'URIUniversalCommunication', 'SpecifiedTaxRegistration', 'EndPointURIUniversalCommunication', 'LogoAssociatedSpecifiedBinaryFile'],
   PostalTradeAddress: ['ID', 'PostcodeCode', 'PostOfficeBox', 'BuildingName', 'LineOne', 'LineTwo', 'LineThree', 'LineFour', 'LineFive', 'StreetName', 'CityName', 'CitySubDivisionName', 'CountryID', 'CountryName', 'CountrySubDivisionID', 'CountrySubDivisionName', 'AttentionOf', 'CareOf', 'BuildingNumber', 'DepartmentName', 'AdditionalStreetName'],
   DefinedTradeContact: ['ID', 'PersonName', 'DepartmentName', 'TypeCode', 'JobTitle', 'Responsibility', 'PersonID', 'TelephoneUniversalCommunication', 'DirectTelephoneUniversalCommunication', 'MobileTelephoneUniversalCommunication', 'FaxUniversalCommunication', 'EmailURIUniversalCommunication', 'TelexUniversalCommunication', 'VOIPUniversalCommunication', 'InstantMessagingUniversalCommunication', 'SpecifiedNote', 'SpecifiedContactPerson'],
   SpecifiedLegalOrganization: ['LegalClassificationCode', 'Name', 'ID', 'TradingBusinessName', 'PostalTradeAddress', 'AuthorizedLegalRegistration'],

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

@@ -308,6 +308,9 @@ export class FacturXEncoder extends CIIBaseEncoder {
     const deliveryElement = doc.createElement('ram:ApplicableHeaderTradeDelivery');
     transactionElement.appendChild(deliveryElement);
 
+    // Deliver to address (BG-15), when the document states its country (BT-80)
+    this.addDeliverToAddress(doc, deliveryElement, invoice);
+
     // Add delivery date if available
     if (invoice.deliveryDate !== undefined) {
       const deliveryDateElement = doc.createElement('ram:ActualDeliverySupplyChainEvent');
@@ -351,12 +354,12 @@ export class FacturXEncoder extends CIIBaseEncoder {
       };
       appendText('ram:CalculatedAmount', taxAmount.toFixed(totals.minorUnits)); // BT-117
       appendText('ram:TypeCode', 'VAT');
-      if (exemption) {
-        appendText('ram:ExemptionReason', exemption.reason); // BT-120 (BR-AE-10)
+      if (exemption?.reason) {
+        appendText('ram:ExemptionReason', exemption.reason); // BT-120 (BR-x-10)
       }
       appendText('ram:BasisAmount', taxableAmount.toFixed(totals.minorUnits)); // BT-116
       appendText('ram:CategoryCode', category); // BT-118
-      if (exemption) {
+      if (exemption?.code) {
         appendText('ram:ExemptionReasonCode', exemption.code); // BT-121
       }
       appendText('ram:RateApplicablePercent', rate.toString()); // BT-119
@@ -483,10 +486,12 @@ export class FacturXEncoder extends CIIBaseEncoder {
         taxCategoryCodeElement.textContent = totals.lineVatCategories[index]; // BT-151
         taxElement.appendChild(taxCategoryCodeElement);
 
-        // Add tax rate
-        const taxRateElement = doc.createElement('ram:RateApplicablePercent');
-        taxRateElement.textContent = item.vatPercentage.toString();
-        taxElement.appendChild(taxRateElement);
+        // Invoiced item VAT rate (BT-152); an item not subject to VAT has none (BR-O-05)
+        if (totals.lineVatCategories[index] !== 'O') {
+          const taxRateElement = doc.createElement('ram:RateApplicablePercent');
+          taxRateElement.textContent = item.vatPercentage.toString();
+          taxElement.appendChild(taxRateElement);
+        }
 
         settlementElement.appendChild(taxElement);
 

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

@@ -320,6 +320,9 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
     const deliveryElement = doc.createElement('ram:ApplicableHeaderTradeDelivery');
     transactionElement.appendChild(deliveryElement);
 
+    // Deliver to address (BG-15), when the document states its country (BT-80)
+    this.addDeliverToAddress(doc, deliveryElement, invoice);
+
     // Add delivery date if available
     if (invoice.deliveryDate !== undefined) {
       const deliveryDateElement = doc.createElement('ram:ActualDeliverySupplyChainEvent');
@@ -449,8 +452,8 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
       typeCodeElement.textContent = 'VAT';
       taxElement.appendChild(typeCodeElement);
 
-      // VAT exemption reason text (BT-120), for reverse charge (BR-AE-10)
-      if (exemption) {
+      // VAT exemption reason text (BT-120), for the categories that state one (BR-x-10)
+      if (exemption?.reason) {
         const exemptionReasonElement = doc.createElement('ram:ExemptionReason');
         exemptionReasonElement.textContent = exemption.reason;
         taxElement.appendChild(exemptionReasonElement);
@@ -467,7 +470,7 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
       taxElement.appendChild(categoryCodeElement);
 
       // VAT exemption reason code (BT-121)
-      if (exemption) {
+      if (exemption?.code) {
         const exemptionReasonCodeElement = doc.createElement('ram:ExemptionReasonCode');
         exemptionReasonCodeElement.textContent = exemption.code;
         taxElement.appendChild(exemptionReasonCodeElement);
@@ -591,10 +594,12 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
         taxCategoryCodeElement.textContent = totals.lineVatCategories[index]; // BT-151
         taxElement.appendChild(taxCategoryCodeElement);
 
-        // Add tax rate
-        const taxRateElement = doc.createElement('ram:RateApplicablePercent');
-        taxRateElement.textContent = item.vatPercentage.toString();
-        taxElement.appendChild(taxRateElement);
+        // Invoiced item VAT rate (BT-152); an item not subject to VAT has none (BR-O-05)
+        if (totals.lineVatCategories[index] !== 'O') {
+          const taxRateElement = doc.createElement('ram:RateApplicablePercent');
+          taxRateElement.textContent = item.vatPercentage.toString();
+          taxElement.appendChild(taxRateElement);
+        }
 
         settlementElement.appendChild(taxElement);
 

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

@@ -7,6 +7,7 @@ import { EInvoice } from '../../einvoice.js';
 import { getAccountingDocType, getDocumentTypeCode } from '../utils/document.typecode.js';
 import { computeDocumentTotals } from '../utils/document.totals.js';
 import { getPaymentTotals } from '../utils/paid.amount.js';
+import { getItemVatCategory } from '../utils/vat.category.js';
 import type { 
   EN16931SemanticModel,
   Seller,
@@ -119,7 +120,7 @@ export class SemanticModelAdapter {
       additionalDocuments: invoice.metadata?.extensions?.supportingDocuments,
       
       // Invoice lines
-      invoiceLines: this.mapInvoiceLines(invoice.items || [])
+      invoiceLines: this.mapInvoiceLines(invoice)
     };
   }
   
@@ -443,9 +444,8 @@ export class SemanticModelAdapter {
   /**
    * Map invoice lines
    */
-  private mapInvoiceLines(items: EInvoice['items']): InvoiceLine[] {
-    if (!items) return [];
-    
+  private mapInvoiceLines(invoice: EInvoice): InvoiceLine[] {
+    const items = invoice.items ?? [];
     return items.map((item, index) => ({
       identifier: (index + 1).toString(),
       note: (item as any).description || (item as any).text || '',
@@ -464,7 +464,8 @@ export class SemanticModelAdapter {
         itemPriceBaseQuantity: (item as any).priceBaseQuantity || 1
       },
       vatInformation: {
-        categoryCode: this.mapVATCategory(item.vatPercentage),
+        // the category the encoders write: the item's own, else AE or S (BT-151)
+        categoryCode: getItemVatCategory(invoice, item),
         rate: item.vatPercentage
       },
       itemInformation: {
@@ -480,16 +481,6 @@ export class SemanticModelAdapter {
     }));
   }
   
-  /**
-   * Map VAT category from percentage
-   */
-  private mapVATCategory(percentage?: number): string {
-    if (percentage === undefined || percentage === null) return 'S';
-    if (percentage === 0) return 'Z';
-    if (percentage > 0) return 'S';
-    return 'E'; // Exempt
-  }
-  
   /**
    * Reverse map seller
    */

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

@@ -11,6 +11,7 @@ import { getPaymentTotals } from '../../utils/paid.amount.js';
 import { toPlainDecimalString } from '../../utils/number.text.js';
 import { resolveCountryCode } from '../../utils/country.code.js';
 import { getPartyIdentifiers } from '../../utils/party.identifier.js';
+import type { IEInvoiceMetadata } from '../../../interfaces/en16931-metadata.js';
 
 /**
  * UBL Encoder implementation
@@ -189,17 +190,45 @@ export class UBLEncoder extends UBLBaseEncoder {
   }
 
   /**
-   * Writes the actual delivery date (BT-72) the document states.
+   * Writes the actual delivery date (BT-72) and the deliver to address (BG-15)
+   * the document states. The address is `metadata.deliveryAddress` when it
+   * states a country (BT-80, which BR-57 requires of the address): the street
+   * (BT-75), the house number, the city (BT-77), the post code (BT-78), the
+   * country subdivision (BT-79) and the country. An intra-community supply
+   * states it (BR-IC-12).
    * @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) {
+    const address = (invoice as TAccountingDoc & { metadata?: IEInvoiceMetadata }).metadata?.deliveryAddress;
+    const countryCode = address?.countryCode?.trim();
+    if (invoice.deliveryDate === undefined && !countryCode) {
       return;
     }
     const delivery = doc.createElement('cac:Delivery');
-    this.appendElement(doc, delivery, 'cbc:ActualDeliveryDate', this.formatDate(invoice.deliveryDate, 'BT-72 actual delivery date'));
+    if (invoice.deliveryDate !== undefined) {
+      this.appendElement(doc, delivery, 'cbc:ActualDeliveryDate', this.formatDate(invoice.deliveryDate, 'BT-72 actual delivery date'));
+    }
+    if (address && countryCode) {
+      const location = doc.createElement('cac:DeliveryLocation');
+      const addressNode = doc.createElement('cac:Address');
+      const append = (name: string, text: string | undefined) => {
+        if (text?.trim()) {
+          this.appendElement(doc, addressNode, name, text.trim());
+        }
+      };
+      append('cbc:StreetName', address.streetName);
+      append('cbc:BuildingNumber', address.houseNumber);
+      append('cbc:CityName', address.city);
+      append('cbc:PostalZone', address.postalCode);
+      append('cbc:CountrySubentity', address.countrySubdivision);
+      const country = doc.createElement('cac:Country');
+      this.appendElement(doc, country, 'cbc:IdentificationCode', countryCode);
+      addressNode.appendChild(country);
+      location.appendChild(addressNode);
+      delivery.appendChild(location);
+    }
     root.appendChild(delivery);
   }
 
@@ -456,9 +485,11 @@ export class UBLEncoder extends UBLBaseEncoder {
       this.appendElement(doc, taxCategoryNode, 'cbc:ID', category);
       this.appendElement(doc, taxCategoryNode, 'cbc:Percent', rate.toFixed(2));
       
-      // VAT exemption reason code (BT-121) and text (BT-120), for reverse charge (BR-AE-10)
-      if (exemption) {
+      // VAT exemption reason code (BT-121) and text (BT-120), for the categories that state one (BR-x-10)
+      if (exemption?.code) {
         this.appendElement(doc, taxCategoryNode, 'cbc:TaxExemptionReasonCode', exemption.code);
+      }
+      if (exemption?.reason) {
         this.appendElement(doc, taxCategoryNode, 'cbc:TaxExemptionReason', exemption.reason);
       }
       
@@ -573,8 +604,10 @@ export class UBLEncoder extends UBLBaseEncoder {
       // Invoiced item VAT category code (BT-151)
       this.appendElement(doc, classifiedTaxCategoryNode, 'cbc:ID', totals.lineVatCategories[index]);
       
-      // Tax percent with 2 decimal places
-      this.appendElement(doc, classifiedTaxCategoryNode, 'cbc:Percent', item.vatPercentage.toFixed(2));
+      // Invoiced item VAT rate (BT-152) with 2 decimal places; an item not subject to VAT has none (BR-O-05)
+      if (totals.lineVatCategories[index] !== 'O') {
+        this.appendElement(doc, classifiedTaxCategoryNode, 'cbc:Percent', item.vatPercentage.toFixed(2));
+      }
       
       // Tax scheme
       const taxSchemeNode = doc.createElement('cac:TaxScheme');

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

@@ -5,6 +5,8 @@ import { DOMParser, xpath } from '../../plugins.js';
 import { EInvoiceParsingError } from '../../errors.js';
 import { getAccountingDocType } from '../utils/document.typecode.js';
 import { readUblStatedValues } from '../utils/stated.values.js';
+import { applyStatedVatCategories } from '../utils/vat.category.js';
+import { deliveryAddressOf, withDeliveryAddress, type TDeliveryAddress } from '../utils/delivery.address.js';
 import type { IEInvoiceStatedValues } from '../../interfaces/stated.values.js';
 
 const ublParser = new DOMParser();
@@ -54,6 +56,35 @@ export abstract class UBLBaseDecoder extends BaseDecoder {
     // the values the document states, read first: an amount that is no number is refused
     this.statedValues = this.assertStatedValuesReadable(readUblStatedValues(this.doc), 'ubl');
 
+    // a CreditNote root is a credit note whatever its type code says
+    const document = await this.decodeByType();
+    // every item with the VAT category its line states and its breakdown's exemption reason
+    applyStatedVatCategories(document.items, this.statedValues);
+    return withDeliveryAddress(document, this.readDeliveryAddress());
+  }
+
+  /**
+   * Reads the deliver to address (BG-15) of the first delivery: the street
+   * (BT-75), the house number, the city (BT-77), the post code (BT-78), the
+   * country subdivision (BT-79) and the country (BT-80); undefined when the
+   * document states no address with a country
+   */
+  private readDeliveryAddress(): TDeliveryAddress | undefined {
+    const address = '/*/cac:Delivery[1]/cac:DeliveryLocation/cac:Address';
+    return deliveryAddressOf({
+      streetName: this.getText(`${address}/cbc:StreetName`, this.doc),
+      houseNumber: this.getText(`${address}/cbc:BuildingNumber`, this.doc),
+      city: this.getText(`${address}/cbc:CityName`, this.doc),
+      postalCode: this.getText(`${address}/cbc:PostalZone`, this.doc),
+      countrySubdivision: this.getText(`${address}/cbc:CountrySubentity`, this.doc),
+      countryCode: this.getText(`${address}/cac:Country/cbc:IdentificationCode`, this.doc),
+    });
+  }
+
+  /**
+   * Decodes the document by its root and document type code (BT-3)
+   */
+  private async decodeByType(): Promise<TAccountingDoc> {
     // a CreditNote root is a credit note whatever its type code says
     if (this.getDocumentType() === UBLDocumentType.CREDIT_NOTE) {
       return this.decodeCreditNote();

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

@@ -265,8 +265,8 @@ export class XRechnungDecoder extends UBLBaseDecoder {
         subject: subject,
         items: items,
         dueInDays: dueInDays,
-        // reverse charge when every line is VAT category AE; the envelope states it for the
-        // whole document, so a document mixing AE lines with others cannot say it
+        // reverse charge when every line is VAT category AE; in a document mixing AE lines with
+        // others each item carries its category (applyStatedVatCategories)
         reverseCharge: this.isReverseChargeDocument(),
         currency: currencyCode as finance.TCurrency,
         notes: notes,

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

@@ -51,6 +51,42 @@ export const getWritableDueDate = (issueTimestamp: unknown, dueInDays: unknown,
   return dueDate;
 };
 
+/**
+ * The UTC midnight of a calendar day, or undefined when there is no such day
+ * @param year The year, 1 or later
+ * @param month The month, 1 to 12
+ * @param day The day of the month
+ */
+const utcMidnightOf = (year: number, month: number, day: number): number | undefined => {
+  if (year < 1) {
+    return undefined;
+  }
+  const date = new Date(0);
+  date.setUTCFullYear(year, month - 1, day);
+  if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) {
+    return undefined;
+  }
+  return date.getTime();
+};
+
+/**
+ * Whether a time of day is one: hours 0 to 23, minutes and seconds 0 to 59
+ * @param hours The hours
+ * @param minutes The minutes
+ * @param seconds The seconds, 0 when not stated
+ */
+const isTimeOfDay = (hours: number, minutes: number, seconds: number): boolean =>
+  hours <= 23 && minutes <= 59 && seconds <= 59;
+
+/**
+ * Whether a time zone offset is one an `xsd:date` or `xsd:dateTime` may carry:
+ * at most 14:00
+ * @param hours The hours of the offset
+ * @param minutes The minutes of the offset
+ */
+const isZoneOffset = (hours: number, minutes: number): boolean =>
+  hours < 14 ? minutes <= 59 : hours === 14 && minutes === 0;
+
 /**
  * The calendar day a UBL `xsd:date` names (BT-2, BT-9, BT-26, BT-72, BT-73,
  * BT-74), as the UTC midnight of that day; undefined when the value is no such
@@ -66,20 +102,57 @@ export const parseXsdDateDay = (value: string): number | undefined => {
   if (!match) {
     return undefined;
   }
-  const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
-  if (match[4] !== undefined) {
-    const [zoneHours, zoneMinutes] = [Number(match[4]), Number(match[5])];
-    if (zoneHours > 14 || zoneMinutes > 59 || (zoneHours === 14 && zoneMinutes !== 0)) {
-      return undefined;
-    }
+  if (match[4] !== undefined && !isZoneOffset(Number(match[4]), Number(match[5]))) {
+    return undefined;
   }
-  if (year < 1) {
+  return utcMidnightOf(Number(match[1]), Number(match[2]), Number(match[3]));
+};
+
+/**
+ * The calendar day an ISO 8601 date, or date and time, names, as the UTC
+ * midnight of that day; undefined when the value is no such date. A CII date
+ * without a format code may be stated so. The value is `YYYY-MM-DD`,
+ * optionally followed by a time of day `Thh:mm`, `Thh:mm:ss` or
+ * `Thh:mm:ss.fff`, and then optionally by a time zone: `Z`, or `+hh:mm` /
+ * `-hh:mm` of at most 14:00. Neither the time of day nor the zone moves the
+ * day the document states: `2026-09-11T00:30:00+02:00` is 22:30 UTC on
+ * 10 September, but the document states 11 September, and that is the day an
+ * invoice is dated with (§ 14 Abs. 4 Satz 1 Nr. 3 UStG asks for the issue date,
+ * a calendar day).
+ * @param value The date as the document states it
+ */
+export const parseIsoDateTimeDay = (value: string): number | undefined => {
+  const match =
+    /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?)?(?:Z|[+-](\d{2}):(\d{2}))?$/.exec(value.trim());
+  if (!match) {
     return undefined;
   }
-  const date = new Date(0);
-  date.setUTCFullYear(year, month - 1, day);
-  if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) {
+  if (match[4] !== undefined && !isTimeOfDay(Number(match[4]), Number(match[5]), Number(match[6] ?? 0))) {
     return undefined;
   }
-  return date.getTime();
+  if (match[7] !== undefined && !isZoneOffset(Number(match[7]), Number(match[8]))) {
+    return undefined;
+  }
+  return utcMidnightOf(Number(match[1]), Number(match[2]), Number(match[3]));
+};
+
+/**
+ * The calendar day a CII date in format 102 (`YYYYMMDD`), 203
+ * (`YYYYMMDDhhmm`) or 204 (`YYYYMMDDhhmmss`) names, as the UTC midnight of that
+ * day; undefined when the value is no such date in that format. A time of day
+ * in formats 203 and 204 does not move the day stated; the formats carry no
+ * time zone.
+ * @param value The date as the document states it
+ * @param format The format code: '102', '203' or '204'
+ */
+export const parseCiiDateDay = (value: string, format: '102' | '203' | '204'): number | undefined => {
+  const timeDigits = { '102': '', '203': '(\\d{2})(\\d{2})', '204': '(\\d{2})(\\d{2})(\\d{2})' }[format];
+  const match = new RegExp(`^(\\d{4})(\\d{2})(\\d{2})${timeDigits}$`).exec(value.trim());
+  if (!match) {
+    return undefined;
+  }
+  if (format !== '102' && !isTimeOfDay(Number(match[4]), Number(match[5]), Number(match[6] ?? 0))) {
+    return undefined;
+  }
+  return utcMidnightOf(Number(match[1]), Number(match[2]), Number(match[3]));
 };

package/ts/formats/utils/delivery.address.ts

@@ -0,0 +1,36 @@
+import type { TAccountingDoc } from '../../interfaces/common.js';
+import type { IEInvoiceMetadata } from '../../interfaces/en16931-metadata.js';
+
+/** The deliver to address (BG-15) of a document, as `metadata.deliveryAddress` carries it */
+export type TDeliveryAddress = NonNullable<IEInvoiceMetadata['deliveryAddress']>;
+
+/**
+ * The deliver to address from the texts a document states, each trimmed and
+ * left out when empty; undefined when it states no country (BT-80), which
+ * every deliver to address has (BR-57)
+ * @param texts The texts read, '' where the document states none
+ */
+export const deliveryAddressOf = (texts: Record<keyof TDeliveryAddress, string>): TDeliveryAddress | undefined => {
+  const address: TDeliveryAddress = {};
+  for (const [field, text] of Object.entries(texts) as Array<[keyof TDeliveryAddress, string]>) {
+    if (text.trim()) {
+      address[field] = text.trim();
+    }
+  }
+  return address.countryCode ? address : undefined;
+};
+
+/**
+ * The decoded document with the deliver to address in its metadata, or
+ * unchanged when it states none
+ * @param document The decoded document
+ * @param address The deliver to address read
+ */
+export const withDeliveryAddress = <TDocument extends TAccountingDoc>(document: TDocument, address: TDeliveryAddress | undefined): TDocument => {
+  if (!address) {
+    return document;
+  }
+  const withMetadata = document as TDocument & { metadata?: IEInvoiceMetadata };
+  withMetadata.metadata = { ...withMetadata.metadata, deliveryAddress: address };
+  return withMetadata;
+};