@fin.cx/einvoice 8.2.0 → 8.2.2

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

@@ -4,7 +4,9 @@ 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';
+import { getWritableDueDate } from '../../utils/date.value.js';
+import { getPaymentTermsNote } from '../../utils/payment.terms.js';
+import { computeDocumentTotals } from '../../utils/document.totals.js';
 
 /**
  * UBL Encoder implementation
@@ -81,8 +83,7 @@ export class UBLEncoder extends UBLBaseEncoder {
     
     // Due Date - the CreditNote schema has no DueDate element; its payment due date lives in cac:PaymentMeans
     if (documentType === UBLDocumentType.INVOICE) {
-      const dueDate = getWritableDate(invoice.date, 'BT-2 invoice issue date', 'ubl');
-      dueDate.setDate(dueDate.getDate() + (invoice.dueInDays || 30));
+      const dueDate = getWritableDueDate(invoice.date, invoice.dueInDays, 'ubl');
       this.appendElement(doc, root, 'cbc:DueDate', this.formatDate(dueDate.getTime(), 'BT-9 payment due date'));
     }
     // Document Type Code (380 invoice, 381 credit note, 383 debit note, 384 corrected invoice, 389 self-billed invoice; the element differs per schema)
@@ -319,7 +320,7 @@ export class UBLEncoder extends UBLBaseEncoder {
     parentElement.appendChild(paymentTermsNode);
     
     // Payment terms note
-    this.appendElement(doc, paymentTermsNode, 'cbc:Note', `Due in ${invoice.dueInDays} days`);
+    this.appendElement(doc, paymentTermsNode, 'cbc:Note', getPaymentTermsNote(invoice.date, invoice.dueInDays, invoice.language, 'ubl'));
     
     // Add payment means if available
     if (invoice.paymentOptions) {
@@ -346,8 +347,7 @@ export class UBLEncoder extends UBLBaseEncoder {
     this.appendElement(doc, paymentMeansNode, 'cbc:PaymentMeansCode', '30');
     
     // 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));
+    const dueDate = getWritableDueDate(invoice.date, invoice.dueInDays, 'ubl');
     this.appendElement(doc, paymentMeansNode, 'cbc:PaymentDueDate', this.formatDate(dueDate.getTime(), 'BT-9 payment due date'));
     
     // Add payment channel code if available
@@ -384,48 +384,31 @@ export class UBLEncoder extends UBLBaseEncoder {
   private addTaxTotal(doc: Document, parentElement: Element, invoice: TAccountingDoc): void {
     const taxTotalNode = doc.createElement('cac:TaxTotal');
     parentElement.appendChild(taxTotalNode);
-    
-    // Calculate total tax amount
-    let totalTaxAmount = 0;
-    const taxCategories = new Map<number, number>(); // Map of VAT rate to net amount
-    
-    // Calculate from items
-    if (invoice.items) {
-      for (const item of invoice.items) {
-        const itemNetAmount = item.unitNetPrice * item.unitQuantity;
-        const itemTaxAmount = itemNetAmount * (item.vatPercentage / 100);
-        const vatRate = item.vatPercentage;
-        
-        totalTaxAmount += itemTaxAmount;
-        
-        // Aggregate by VAT rate
-        const currentAmount = taxCategories.get(vatRate) || 0;
-        taxCategories.set(vatRate, currentAmount + itemNetAmount);
-      }
-    }
-    
-    // Add total tax amount
+
+    // the EN 16931 totals in decimal arithmetic, rounded as the business rules check them
+    const totals = computeDocumentTotals(invoice);
+
+    // Invoice total VAT amount (BT-110)
     const taxAmountElement = doc.createElement('cbc:TaxAmount');
     taxAmountElement.setAttribute('currencyID', invoice.currency);
-    taxAmountElement.textContent = totalTaxAmount.toFixed(2);
+    taxAmountElement.textContent = totals.taxTotal.toFixed(totals.minorUnits);
     taxTotalNode.appendChild(taxAmountElement);
-    
-    // Add tax subtotals
-    for (const [rate, baseAmount] of taxCategories.entries()) {
+
+    // VAT breakdown (BG-23), one subtotal per rate
+    for (const { rate, taxableAmount, taxAmount } of totals.vatGroups) {
       const taxSubtotalNode = doc.createElement('cac:TaxSubtotal');
       taxTotalNode.appendChild(taxSubtotalNode);
-      
-      // Taxable amount
+
+      // VAT category taxable amount (BT-116)
       const taxableAmountElement = doc.createElement('cbc:TaxableAmount');
       taxableAmountElement.setAttribute('currencyID', invoice.currency);
-      taxableAmountElement.textContent = baseAmount.toFixed(2);
+      taxableAmountElement.textContent = taxableAmount.toFixed(totals.minorUnits);
       taxSubtotalNode.appendChild(taxableAmountElement);
-      
-      // Tax amount
-      const taxAmount = baseAmount * (rate / 100);
+
+      // VAT category tax amount (BT-117)
       const subtotalTaxAmountElement = doc.createElement('cbc:TaxAmount');
       subtotalTaxAmountElement.setAttribute('currencyID', invoice.currency);
-      subtotalTaxAmountElement.textContent = taxAmount.toFixed(2);
+      subtotalTaxAmountElement.textContent = taxAmount.toFixed(totals.minorUnits);
       taxSubtotalNode.appendChild(subtotalTaxAmountElement);
       
       // Tax category
@@ -461,46 +444,33 @@ export class UBLEncoder extends UBLBaseEncoder {
   private addLegalMonetaryTotal(doc: Document, parentElement: Element, invoice: TAccountingDoc): void {
     const legalMonetaryTotalNode = doc.createElement('cac:LegalMonetaryTotal');
     parentElement.appendChild(legalMonetaryTotalNode);
-    
-    // Calculate totals
-    let totalNetAmount = 0;
-    let totalTaxAmount = 0;
-    
-    // Calculate from items
-    if (invoice.items) {
-      for (const item of invoice.items) {
-        const itemNetAmount = item.unitNetPrice * item.unitQuantity;
-        const itemTaxAmount = itemNetAmount * (item.vatPercentage / 100);
-        
-        totalNetAmount += itemNetAmount;
-        totalTaxAmount += itemTaxAmount;
-      }
-    }
-    
-    const totalGrossAmount = totalNetAmount + totalTaxAmount;
+
+    // the EN 16931 totals in decimal arithmetic, rounded as the business rules check them
+    const totals = computeDocumentTotals(invoice);
+    const amount = (value: { toFixed(decimalPlaces: number): string }) => value.toFixed(totals.minorUnits);
     
     // Line extension amount (sum of line net amounts)
     const lineExtensionAmountElement = doc.createElement('cbc:LineExtensionAmount');
     lineExtensionAmountElement.setAttribute('currencyID', invoice.currency);
-    lineExtensionAmountElement.textContent = totalNetAmount.toFixed(2);
+    lineExtensionAmountElement.textContent = amount(totals.lineTotal);
     legalMonetaryTotalNode.appendChild(lineExtensionAmountElement);
     
     // Tax exclusive amount
     const taxExclusiveAmountElement = doc.createElement('cbc:TaxExclusiveAmount');
     taxExclusiveAmountElement.setAttribute('currencyID', invoice.currency);
-    taxExclusiveAmountElement.textContent = totalNetAmount.toFixed(2);
+    taxExclusiveAmountElement.textContent = amount(totals.taxBasisTotal);
     legalMonetaryTotalNode.appendChild(taxExclusiveAmountElement);
     
     // Tax inclusive amount
     const taxInclusiveAmountElement = doc.createElement('cbc:TaxInclusiveAmount');
     taxInclusiveAmountElement.setAttribute('currencyID', invoice.currency);
-    taxInclusiveAmountElement.textContent = totalGrossAmount.toFixed(2);
+    taxInclusiveAmountElement.textContent = amount(totals.grandTotal);
     legalMonetaryTotalNode.appendChild(taxInclusiveAmountElement);
     
     // Payable amount
     const payableAmountElement = doc.createElement('cbc:PayableAmount');
     payableAmountElement.setAttribute('currencyID', invoice.currency);
-    payableAmountElement.textContent = totalGrossAmount.toFixed(2);
+    payableAmountElement.textContent = amount(totals.duePayable);
     legalMonetaryTotalNode.appendChild(payableAmountElement);
   }
   
@@ -513,8 +483,9 @@ export class UBLEncoder extends UBLBaseEncoder {
   private addInvoiceLines(doc: Document, parentElement: Element, invoice: TAccountingDoc, documentType: UBLDocumentType = UBLDocumentType.INVOICE): void {
     if (!invoice.items) return;
     const creditNote = documentType === UBLDocumentType.CREDIT_NOTE;
+    const totals = computeDocumentTotals(invoice);
     
-    for (const item of invoice.items) {
+    for (const [index, item] of invoice.items.entries()) {
       const invoiceLineNode = doc.createElement(creditNote ? 'cac:CreditNoteLine' : 'cac:InvoiceLine');
       parentElement.appendChild(invoiceLineNode);
       
@@ -530,11 +501,10 @@ export class UBLEncoder extends UBLBaseEncoder {
       quantityElement.textContent = item.unitQuantity.toString();
       invoiceLineNode.appendChild(quantityElement);
       
-      // Line extension amount (line net amount)
-      const itemNetAmount = item.unitNetPrice * item.unitQuantity;
+      // Invoice line net amount (BT-131): quantity × net price, rounded
       const lineExtensionAmountElement = doc.createElement('cbc:LineExtensionAmount');
       lineExtensionAmountElement.setAttribute('currencyID', invoice.currency);
-      lineExtensionAmountElement.textContent = itemNetAmount.toFixed(2);
+      lineExtensionAmountElement.textContent = totals.lineNetAmounts[index].toFixed(totals.minorUnits);
       invoiceLineNode.appendChild(lineExtensionAmountElement);
       
       // Item information

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

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

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

@@ -60,14 +60,18 @@ export class XRechnungDecoder extends UBLBaseDecoder {
       const issueDate = this.parseRequiredUblDate(issueDateText);
       const currencyCode = this.getText('//cbc:DocumentCurrencyCode', this.doc) || 'EUR';
 
-      // Extract payment terms
-      let dueInDays = 30; // Default
-      const dueDateText = this.getText('//cac:PaymentTerms/cbc:PaymentDueDate', this.doc);
+      // The payment due date (BT-9): cbc:DueDate on an Invoice, cac:PaymentMeans/cbc:PaymentDueDate
+      // on a CreditNote, cac:PaymentTerms/cbc:PaymentDueDate as a last resort; the payment term in
+      // days is the calendar days from the issue date to it.
+      // no due date stated: `dueInDays` cannot express it yet (required field in @tsclass/tsclass); value unchanged: 30 days
+      let dueInDays = 30;
+      const dueDateText = (
+        this.getText('/*/cbc:DueDate', this.doc) ||
+        this.getText('/*/cac:PaymentMeans/cbc:PaymentDueDate', this.doc) ||
+        this.getText('/*/cac:PaymentTerms/cbc:PaymentDueDate', this.doc)
+      ).trim();
       if (dueDateText) {
-        const dueDateObj = new Date(dueDateText);
-        const issueDateObj = new Date(issueDate);
-        const diffTime = Math.abs(dueDateObj.getTime() - issueDateObj.getTime());
-        dueInDays = Math.ceil(diffTime / (1000 * 60 * 60 * 24));
+        dueInDays = Math.round((this.parseRequiredUblDate(dueDateText) - issueDate) / (1000 * 60 * 60 * 24));
       }
 
       // Extract items

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

@@ -1,6 +1,7 @@
 import { UBLEncoder } from '../generic/ubl.encoder.js';
 import type { TAccountingDoc, TCreditNote, TInvoiceDocument } from '../../../interfaces/common.js';
 import { DOMParser, XMLSerializer } from '../../../plugins.js';
+import { UBL_CUSTOMIZATION_IDS } from '../ubl.types.js';
 
 /**
  * Encoder for XRechnung (UBL) format
@@ -52,10 +53,10 @@ export class XRechnungEncoder extends UBLEncoder {
     // Extract metadata if available
     const metadata = (invoice as any).metadata?.extensions;
     
-    // Update Customization ID to XRechnung 2.0
+    // Specification identifier (BT-24): XRechnung 3.0
     const customizationId = root.getElementsByTagName('cbc:CustomizationID')[0];
     if (customizationId) {
-      customizationId.textContent = 'urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_2.0';
+      customizationId.textContent = UBL_CUSTOMIZATION_IDS.XRECHNUNG;
     }
     
     // Add or update Buyer Reference (required for XRechnung)
@@ -73,15 +74,6 @@ export class XRechnungEncoder extends UBLEncoder {
       buyerRef.textContent = buyerReferenceValue;
     }
     
-    // Update payment terms to German
-    const paymentTermsNotes = root.getElementsByTagName('cac:PaymentTerms');
-    if (paymentTermsNotes.length > 0) {
-      const noteElement = paymentTermsNotes[0].getElementsByTagName('cbc:Note')[0];
-      if (noteElement && noteElement.textContent) {
-        noteElement.textContent = `Zahlung innerhalb von ${invoice.dueInDays || 30} Tagen`;
-      }
-    }
-    
     // Add electronic address for parties if available
     this.addElectronicAddressToParty(doc, 'cac:AccountingSupplierParty', invoice.from);
     this.addElectronicAddressToParty(doc, 'cac:AccountingCustomerParty', invoice.to);

package/ts/formats/utils/currency.calculator.decimal.ts

@@ -15,12 +15,20 @@ export class DecimalCurrencyCalculator {
   private readonly minorUnits: number;
   private readonly roundingMode: RoundingMode;
   
+  /**
+   * @param currency The currency, whose minor unit sets the rounding scale
+   * @param roundingMode How values are rounded
+   * @param options.maxDecimals The most decimals an amount may have, when fewer than the
+   *   currency's minor unit (EN 16931 allows two, BR-DEC-*)
+   */
   constructor(
     currency: TCurrency,
-    roundingMode: RoundingMode = 'HALF_UP'
+    roundingMode: RoundingMode = 'HALF_UP',
+    options: { maxDecimals?: number } = {}
   ) {
     this.currency = currency;
-    this.minorUnits = getCurrencyMinorUnits(currency);
+    const minorUnits = getCurrencyMinorUnits(currency);
+    this.minorUnits = options.maxDecimals === undefined ? minorUnits : Math.min(minorUnits, options.maxDecimals);
     this.roundingMode = roundingMode;
   }
   

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

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

package/ts/formats/utils/document.totals.ts

@@ -0,0 +1,144 @@
+import type { TAccountingDoc } from '../../interfaces/common.js';
+import { Decimal } from './decimal.js';
+import { DecimalCurrencyCalculator } from './currency.calculator.decimal.js';
+import { EInvoiceFormatError } from '../../errors.js';
+import type { ValidationResult } from '../validation/validation.types.js';
+
+/** An item amount that is no finite number, so no total can be computed from it */
+export interface IInvalidItemAmount {
+  index: number;
+  field: 'unitQuantity' | 'unitNetPrice' | 'vatPercentage';
+  value: unknown;
+}
+
+/**
+ * The item amounts of a document that are no finite number. The totals cannot
+ * be computed while there is one: the encoders and the total getters refuse
+ * the document, and a validator reports the lines and skips the rules that
+ * need the totals.
+ * @param items The document's items
+ */
+export const findInvalidItemAmounts = (items: TAccountingDoc['items'] | undefined): IInvalidItemAmount[] => {
+  const invalid: IInvalidItemAmount[] = [];
+  for (const [index, item] of (items ?? []).entries()) {
+    for (const field of ['unitQuantity', 'unitNetPrice', 'vatPercentage'] as const) {
+      const value: unknown = item[field];
+      if (typeof value !== 'number' || !Number.isFinite(value)) {
+        invalid.push({ index, field, value });
+      }
+    }
+  }
+  return invalid;
+};
+
+/**
+ * The result a validator adds when it skips the rules that need the totals,
+ * because a line amount is no number (the line rules report the lines)
+ * @param invalid The invalid item amounts
+ * @param source The validator's source
+ */
+export const getTotalsSkippedResult = (invalid: IInvalidItemAmount[], source: string): ValidationResult => ({
+  ruleId: 'TOTALS-NOT-CHECKED',
+  source,
+  severity: 'info',
+  message: `The rules on totals and the VAT breakdown were not checked: ${invalid
+    .map((entry) => `items[${entry.index}].${entry.field} is no number`)
+    .join(', ')}`,
+  field: invalid.map((entry) => `items[${entry.index}].${entry.field}`).join(', '),
+});
+
+/** The most decimals an amount may have in EN 16931 (BR-DEC-09 to BR-DEC-23) */
+export const EN16931_MAX_AMOUNT_DECIMALS = 2;
+
+/**
+ * The calculator every document amount is computed with: rounding half up to
+ * the currency's minor unit, at most two decimals as EN 16931 allows. A
+ * currency without minor unit (JPY) keeps 0 decimals; one with three (BHD,
+ * KWD, ...) is rounded to two.
+ * @param currency The document currency
+ */
+export const getDocumentCalculator = (currency: TAccountingDoc['currency']): DecimalCurrencyCalculator =>
+  new DecimalCurrencyCalculator(currency, 'HALF_UP', { maxDecimals: EN16931_MAX_AMOUNT_DECIMALS });
+
+/**
+ * The VAT breakdown of one rate (BG-23): the taxable amount (BT-116), the tax
+ * on it (BT-117) and the rate (BT-119).
+ */
+export interface IDocumentVatGroup {
+  rate: number;
+  taxableAmount: Decimal;
+  taxAmount: Decimal;
+}
+
+/**
+ * The totals of a document as EN 16931 computes them, in decimal arithmetic.
+ * Every amount is rounded to the minor unit of the currency; all encoders
+ * write these values, so the XML is consistent in every syntax.
+ */
+export interface IDocumentTotals {
+  /** decimals the amounts are rounded to and written with: the currency's minor unit, at most two */
+  minorUnits: number;
+  /** the Invoice line net amount (BT-131) of each item, in item order: quantity × net price, rounded */
+  lineNetAmounts: Decimal[];
+  /** Sum of Invoice line net amount (BT-106) */
+  lineTotal: Decimal;
+  /** Invoice total amount without VAT (BT-109): BT-106, as the envelope has no document level allowances or charges */
+  taxBasisTotal: Decimal;
+  /** VAT breakdown (BG-23), in the order the rates first appear */
+  vatGroups: IDocumentVatGroup[];
+  /** Invoice total VAT amount (BT-110): the sum of the rounded VAT category tax amounts */
+  taxTotal: Decimal;
+  /** Invoice total amount with VAT (BT-112): BT-109 + BT-110 */
+  grandTotal: Decimal;
+  /** Amount due for payment (BT-115): BT-112, as the envelope states no paid amount yet */
+  duePayable: Decimal;
+}
+
+/**
+ * Computes the totals of a document the way the EN 16931 business rules check
+ * them, every amount rounded half up to the currency's minor unit, at most two
+ * decimals (BR-DEC-*): each line net amount (BT-131) is quantity × net price
+ * rounded; the sum of line net amounts (BT-106) is their sum (BR-CO-10);
+ * each VAT category taxable amount (BT-116) is the sum of the line net amounts
+ * at that rate, and its tax amount (BT-117) is BT-116 × rate / 100 rounded
+ * (BR-CO-17); the total VAT (BT-110) is the sum of the category tax amounts
+ * (BR-CO-14); the total with VAT (BT-112) is BT-109 + BT-110 (BR-CO-15).
+ * @param accountingDoc The document
+ */
+export const computeDocumentTotals = (accountingDoc: Pick<TAccountingDoc, 'currency' | 'items'>): IDocumentTotals => {
+  const calculator = getDocumentCalculator(accountingDoc.currency);
+  const minorUnits = calculator.getCurrencyInfo().minorUnits;
+  const lineNetAmounts: Decimal[] = [];
+  const taxableByRate = new Map<number, Decimal>();
+  // an amount that is no number cannot be computed with; it is refused, not treated as 0
+  const [firstInvalid] = findInvalidItemAmounts(accountingDoc.items);
+  if (firstInvalid) {
+    throw new EInvoiceFormatError(
+      `items[${firstInvalid.index}].${firstInvalid.field} is no number: ${String(firstInvalid.value)}`,
+      { unsupportedFeatures: [`items[${firstInvalid.index}].${firstInvalid.field}`] },
+    );
+  }
+  for (const item of accountingDoc.items ?? []) {
+    const lineNet = calculator.calculateLineNet(item.unitQuantity, item.unitNetPrice);
+    lineNetAmounts.push(lineNet);
+    taxableByRate.set(item.vatPercentage, (taxableByRate.get(item.vatPercentage) ?? Decimal.ZERO).add(lineNet));
+  }
+  const vatGroups: IDocumentVatGroup[] = [...taxableByRate.entries()].map(([rate, taxableAmount]) => ({
+    rate,
+    taxableAmount: calculator.round(taxableAmount),
+    taxAmount: calculator.calculateVAT(taxableAmount, rate),
+  }));
+  const lineTotal = calculator.round(Decimal.sum(lineNetAmounts));
+  const taxTotal = calculator.round(Decimal.sum(vatGroups.map((group) => group.taxAmount)));
+  const grandTotal = calculator.round(lineTotal.add(taxTotal));
+  return {
+    minorUnits,
+    lineNetAmounts,
+    lineTotal,
+    taxBasisTotal: lineTotal,
+    vatGroups,
+    taxTotal,
+    grandTotal,
+    duePayable: grandTotal,
+  };
+};

package/ts/formats/utils/format.detector.ts

@@ -80,7 +80,9 @@ export class FormatDetector {
       );
       const customizationId = customizationIdMatch?.[1] ?? '';
 
-      if (/xrechnung/i.test(customizationId) || /urn:xoev-de:kosit:standard:xrechnung/i.test(customizationId)) {
+      // both identifier families: urn:xeinkauf.de:kosit:xrechnung_3.0 (XRechnung 3.0) and
+      // urn:xoev-de:kosit:standard:xrechnung_x.y (XRechnung 1.x and 2.x)
+      if (/xrechnung/i.test(customizationId)) {
         return InvoiceFormat.XRECHNUNG;
       }
       return InvoiceFormat.UBL;
@@ -133,10 +135,8 @@ export class FormatDetector {
     }
 
     // Check for obvious XRechnung indicators
-    if (
-      /xrechnung/i.test(sample) ||
-      /urn:xoev-de:kosit:standard:xrechnung/i.test(sample)
-    ) {
+    // covers both identifier families (urn:xeinkauf.de:kosit:xrechnung_, urn:xoev-de:kosit:standard:xrechnung_)
+    if (/xrechnung/i.test(sample)) {
       return InvoiceFormat.XRECHNUNG;
     }
 

package/ts/formats/utils/payment.terms.ts

@@ -0,0 +1,37 @@
+import { getWritableDueDate } from './date.value.js';
+
+/**
+ * The payment terms note (BT-20) the encoders write: the due date (BT-9) the
+ * document states, in the document language (German for `de`, English
+ * otherwise). It names the date rather than a count of days, so it reads
+ * correctly for every term:
+ * - a term of 0 days: "Zahlbar sofort" / "Payable immediately";
+ * - a later due date: "Zahlbar bis 04.10.2026" / "Payable by 2026-10-04";
+ * - an earlier due date, which is legitimate when the payment fell due before
+ *   the invoice was issued, as with an agreed advance payment or an invoice
+ *   issued after the contractual due date: "Fällig seit dem 03.09.2026" /
+ *   "Due since 2026-09-03".
+ * A term that is no whole number of days is refused by `getWritableDueDate`.
+ * @param issueTimestamp The issue date (BT-2)
+ * @param dueInDays The payment term in days, as the document states it
+ * @param language The document language
+ * @param targetFormat The format being written
+ */
+export const getPaymentTermsNote = (
+  issueTimestamp: unknown,
+  dueInDays: unknown,
+  language: string | undefined,
+  targetFormat: string,
+): string => {
+  const dueDate = getWritableDueDate(issueTimestamp, dueInDays, targetFormat);
+  const isoDate = dueDate.toISOString().slice(0, 10);
+  const german = (language ?? '').toLowerCase().startsWith('de');
+  const germanDate = `${isoDate.slice(8, 10)}.${isoDate.slice(5, 7)}.${isoDate.slice(0, 4)}`;
+  if (dueInDays === 0) {
+    return german ? 'Zahlbar sofort' : 'Payable immediately';
+  }
+  if ((dueInDays as number) > 0) {
+    return german ? `Zahlbar bis ${germanDate}` : `Payable by ${isoDate}`;
+  }
+  return german ? `Fällig seit dem ${germanDate}` : `Due since ${isoDate}`;
+};

package/ts/formats/validation/codelist.validator.ts

@@ -146,18 +146,9 @@ export class CodeListValidator {
    * Validate tax category codes (UNCL5305)
    */
   private validateTaxCategories(invoice: EInvoice): void {
-    // Document level tax breakdown
-    // Note: taxBreakdown is a computed property that doesn't have metadata
-    // We would need to access the raw tax breakdown data from metadata if it exists
-    invoice.taxBreakdown?.forEach((breakdown, index) => {
-      // Since the computed taxBreakdown doesn't have metadata, 
-      // we'll skip the tax category code validation for now
-      // This would need to be implemented differently to access the raw data
-      
-      // TODO: Access raw tax breakdown data with metadata from invoice.metadata.taxBreakdown
-      // when that structure is implemented
-    });
-    
+    // The document level VAT breakdown is computed from the lines (`taxBreakdown`) and
+    // carries no category code of its own, so only the lines' codes are checked here.
+
     // Line level tax categories
     invoice.items?.forEach((item, index) => {
       // Cast to extended type to access metadata