@fin.cx/einvoice 8.3.1 → 10.0.0

package/ts/formats/ubl/xrechnung.validator.ts

@@ -1,31 +1,11 @@
 import { EN16931UBLValidator } from './en16931.ubl.validator.js';
+import { GERMAN_VAT_ID_FORMAT_CODE, germanVatIdFormatMessage, isMalformedGermanVatId } from '../utils/vat.id.js';
 
 /**
  * XRechnung-specific validator that extends EN16931 validation
  * Implements additional German CIUS (Core Invoice Usage Specification) rules
  */
 export class XRechnungValidator extends EN16931UBLValidator {
-  /**
-   * Validates XRechnung-specific structure requirements
-   */
-  protected validateStructure(): boolean {
-    // First validate EN16931 structure
-    let valid = super.validateStructure();
-
-    // XRechnung-specific: Check for proper customization ID
-    const customizationID = this.getText('//cbc:CustomizationID');
-    if (!customizationID || !customizationID.includes('xrechnung')) {
-      this.addError(
-        'XRECH-STRUCT-1',
-        'XRechnung customization ID is missing or invalid',
-        '//cbc:CustomizationID'
-      );
-      valid = false;
-    }
-
-    return valid;
-  }
-
   /**
    * Validates XRechnung-specific business rules
    */
@@ -33,26 +13,6 @@ export class XRechnungValidator extends EN16931UBLValidator {
     // First validate EN16931 business rules
     let valid = super.validateBusinessRules();
 
-    // BR-DE-1: Payment terms (BT-20) or Payment due date (BT-9) shall be provided.
-    if (!this.exists('//cbc:PaymentDueDate') && !this.exists('//cac:PaymentTerms/cbc:Note')) {
-      this.addError(
-        'BR-DE-1',
-        'Payment terms or Payment due date shall be provided',
-        '//cac:PaymentTerms'
-      );
-      valid = false;
-    }
-
-    // BR-DE-2: The element "Buyer reference" (BT-10) shall be provided.
-    if (!this.exists('//cbc:BuyerReference')) {
-      this.addError(
-        'BR-DE-2',
-        'Buyer reference is required in XRechnung',
-        '//cbc:BuyerReference'
-      );
-      valid = false;
-    }
-
     // BR-DE-16 (XRechnung): when a VAT category code S, Z, E, AE, K, G, L or M is used (BT-95,
     // BT-102, BT-151), the seller states a VAT identifier (BT-31) or a tax registration
     // identifier (BT-32), which is any party tax scheme of the seller, or a tax representative
@@ -79,111 +39,99 @@ export class XRechnungValidator extends EN16931UBLValidator {
       valid = false;
     }
 
-    // BR-DE-7: The element "Seller city" (BT-37) shall be provided.
-    if (!this.exists('//cac:AccountingSupplierParty//cac:PostalAddress/cbc:CityName')) {
-      this.addError(
-        'BR-DE-7',
-        'Seller city is required',
-        '//cac:AccountingSupplierParty//cac:PostalAddress'
-      );
-      valid = false;
-    }
+    // The rules below carry the IDs of the official rule sets and check what they check, in
+    // their context: KoSIT XRechnung Schematron 2.6.0 (BR-DE-*, and PEPPOL-EN16931-R010, which it
+    // includes) and the CEN EN 16931 validation artefacts 1.3.16 (BR-21, BR-49).
+    const supplierParty = '/*/cac:AccountingSupplierParty/cac:Party';
+    const customerParty = '/*/cac:AccountingCustomerParty/cac:Party';
+    const requireElement = (context: string, element: string, ruleId: string, message: string): void => {
+      for (const node of this.nodes(context)) {
+        if (!this.exists(`${element}[normalize-space(.)]`, node)) {
+          this.addError(ruleId, message, `${context}/${element}`);
+          valid = false;
+        }
+      }
+    };
 
-    // BR-DE-8: The element "Seller post code" (BT-38) shall be provided.
-    if (!this.exists('//cac:AccountingSupplierParty//cac:PostalAddress/cbc:PostalZone')) {
-      this.addError(
-        'BR-DE-8',
-        'Seller post code is required',
-        '//cac:AccountingSupplierParty//cac:PostalAddress'
-      );
+    // BR-DE-1: an invoice states PAYMENT INSTRUCTIONS (BG-16)
+    if (!this.exists('/*/cac:PaymentMeans')) {
+      this.addError('BR-DE-1', 'An invoice states the payment instructions (BG-16)', '/*/cac:PaymentMeans');
       valid = false;
     }
-
-    // BR-DE-9: The element "Buyer city" (BT-52) shall be provided.
-    if (!this.exists('//cac:AccountingCustomerParty//cac:PostalAddress/cbc:CityName')) {
-      this.addError(
-        'BR-DE-9',
-        'Buyer city is required',
-        '//cac:AccountingCustomerParty//cac:PostalAddress'
-      );
-      valid = false;
+    // BR-49 (EN 16931): a payment instruction (BG-16) states the payment means type code (BT-81)
+    for (const [index, paymentMeans] of this.nodes('/*/cac:PaymentMeans').entries()) {
+      if (!this.exists('cbc:PaymentMeansCode', paymentMeans)) {
+        this.addError('BR-49', 'A payment instruction (BG-16) states the payment means type code (BT-81)', `/*/cac:PaymentMeans[${index + 1}]/cbc:PaymentMeansCode`);
+        valid = false;
+      }
     }
 
-    // BR-DE-10: The element "Buyer post code" (BT-53) shall be provided.
-    if (!this.exists('//cac:AccountingCustomerParty//cac:PostalAddress/cbc:PostalZone')) {
-      this.addError(
-        'BR-DE-10',
-        'Buyer post code is required',
-        '//cac:AccountingCustomerParty//cac:PostalAddress'
-      );
-      valid = false;
-    }
+    // BR-DE-15: the buyer reference (BT-10) is stated
+    requireElement('/*', 'cbc:BuyerReference', 'BR-DE-15', 'The buyer reference (BT-10) is stated');
 
-    // BR-DE-11: The element "Seller contact telephone number" (BT-42) shall be provided.
-    if (!this.exists('//cac:AccountingSupplierParty//cac:Contact/cbc:Telephone')) {
-      this.addError(
-        'BR-DE-11',
-        'Seller contact telephone number is required',
-        '//cac:AccountingSupplierParty//cac:Contact'
-      );
+    // BR-DE-2: the seller contact (BG-6) is stated; BR-DE-6 and BR-DE-7: with a telephone number
+    // (BT-42) and an email address (BT-43)
+    if (this.exists(supplierParty) && !this.exists(`${supplierParty}/cac:Contact`)) {
+      this.addError('BR-DE-2', 'The seller contact (BG-6) is stated', `${supplierParty}/cac:Contact`);
       valid = false;
     }
-
-    // BR-DE-12: The element "Seller contact email address" (BT-43) shall be provided.
-    if (!this.exists('//cac:AccountingSupplierParty//cac:Contact/cbc:ElectronicMail')) {
-      this.addError(
-        'BR-DE-12',
-        'Seller contact email address is required',
-        '//cac:AccountingSupplierParty//cac:Contact'
-      );
-      valid = false;
+    requireElement(`${supplierParty}/cac:Contact`, 'cbc:Telephone', 'BR-DE-6', 'The seller contact telephone number (BT-42) is stated');
+    requireElement(`${supplierParty}/cac:Contact`, 'cbc:ElectronicMail', 'BR-DE-7', 'The seller contact email address (BT-43) is stated');
+
+    // BR-DE-3, BR-DE-4: the seller city (BT-37) and post code (BT-38)
+    requireElement(`${supplierParty}/cac:PostalAddress`, 'cbc:CityName', 'BR-DE-3', 'The seller city (BT-37) is stated');
+    requireElement(`${supplierParty}/cac:PostalAddress`, 'cbc:PostalZone', 'BR-DE-4', 'The seller post code (BT-38) is stated');
+    // BR-DE-8, BR-DE-9: the buyer city (BT-52) and post code (BT-53)
+    requireElement(`${customerParty}/cac:PostalAddress`, 'cbc:CityName', 'BR-DE-8', 'The buyer city (BT-52) is stated');
+    requireElement(`${customerParty}/cac:PostalAddress`, 'cbc:PostalZone', 'BR-DE-9', 'The buyer post code (BT-53) is stated');
+
+    // PEPPOL-EN16931-R010, part of the XRechnung rules: the buyer electronic address (BT-49)
+    for (const party of this.nodes(customerParty)) {
+      if (!this.exists('cbc:EndpointID', party)) {
+        this.addError('PEPPOL-EN16931-R010', 'The buyer electronic address (BT-49) is stated', `${customerParty}/cbc:EndpointID`);
+        valid = false;
+      }
     }
 
-    // BR-DE-13: The element "Buyer electronic address" (BT-49) shall be provided.
-    if (!this.exists('//cac:AccountingCustomerParty//cac:Party/cbc:EndpointID')) {
-      this.addError(
-        'BR-DE-13',
-        'Buyer electronic address (EndpointID) is required',
-        '//cac:AccountingCustomerParty//cac:Party'
-      );
-      valid = false;
+    // BR-21 (EN 16931): each invoice line (BG-25) has an invoice line identifier (BT-126)
+    for (const [index, line] of this.nodes('/*/cac:InvoiceLine | /*/cac:CreditNoteLine').entries()) {
+      if (!this.exists('cbc:ID[normalize-space(.)]', line)) {
+        this.addError('BR-21', `Invoice line ${index + 1} has an invoice line identifier (BT-126)`, `${this.locationOf(line as Element)}/cbc:ID`);
+        valid = false;
+      }
     }
 
-    // BR-DE-14: The element "Payment means type code" (BT-81) shall be provided.
-    if (!this.exists('//cac:PaymentMeans/cbc:PaymentMeansCode')) {
-      this.addError(
-        'BR-DE-14',
-        'Payment means type code is required',
-        '//cac:PaymentMeans'
-      );
+    // BR-CO-25 (EN 16931): while the amount due for payment (BT-115) is positive, the payment due
+    // date (BT-9) or the payment terms (BT-20) are stated. The CEN artefacts for UBL and CII do not
+    // check this rule; EN 16931 states it.
+    const amountDue = Number(this.getText('/*/cac:LegalMonetaryTotal/cbc:PayableAmount').trim());
+    if (
+      amountDue > 0 &&
+      !this.exists('/*/cbc:DueDate[normalize-space(.)] | /*/cac:PaymentMeans/cbc:PaymentDueDate[normalize-space(.)]') &&
+      !this.exists('/*/cac:PaymentTerms/cbc:Note[normalize-space(.)]')
+    ) {
+      this.addError('BR-CO-25', 'While an amount is due (BT-115), the payment due date (BT-9) or the payment terms (BT-20) are stated', '/*/cac:PaymentTerms');
       valid = false;
     }
 
-    // BR-DE-15: The element "Invoice line identifier" (BT-126) shall be provided.
-    const invoiceLines = this.select('//cac:InvoiceLine | //cac:CreditNoteLine', this.doc) as Node[];
-    for (let i = 0; i < invoiceLines.length; i++) {
-      const line = invoiceLines[i];
-      if (!this.exists('./cbc:ID', line)) {
-        this.addError(
-          'BR-DE-15',
-          `Invoice line ${i + 1} is missing identifier`,
-          `//cac:InvoiceLine[${i + 1}]`
-        );
+    // The package's own check of the German VAT identification number format (no official rule)
+    for (const vatId of this.nodes('/*/cac:AccountingSupplierParty/cac:Party/cac:PartyTaxScheme[cac:TaxScheme/cbc:ID="VAT"]/cbc:CompanyID')) {
+      const value = (vatId.textContent ?? '').trim();
+      if (isMalformedGermanVatId(value)) {
+        this.addError(GERMAN_VAT_ID_FORMAT_CODE, germanVatIdFormatMessage(value), '/*/cac:AccountingSupplierParty/cac:Party/cac:PartyTaxScheme/cbc:CompanyID');
         valid = false;
       }
     }
 
-    // German VAT ID format validation
-    const supplierVatId = this.getText('//cac:AccountingSupplierParty//cbc:CompanyID[../cac:TaxScheme/cbc:ID="VAT"]');
-    if (supplierVatId && supplierVatId.startsWith('DE') && !/^DE[0-9]{9}$/.test(supplierVatId)) {
-      this.addError(
-        'BR-DE-VAT',
-        'German VAT ID format is invalid (must be DE followed by 9 digits)',
-        '//cac:AccountingSupplierParty//cbc:CompanyID'
-      );
-      valid = false;
-    }
-
     return valid;
   }
+
+  /**
+   * The nodes an XPath expression selects
+   * @param xpathExpr XPath expression
+   */
+  private nodes(xpathExpr: string): Node[] {
+    const result = this.select(xpathExpr, this.doc);
+    return Array.isArray(result) ? (result as Node[]) : [];
+  }
 }

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

@@ -50,3 +50,36 @@ export const getWritableDueDate = (issueTimestamp: unknown, dueInDays: unknown,
   dueDate.setUTCDate(dueDate.getUTCDate() + dueInDays);
   return dueDate;
 };
+
+/**
+ * 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
+ * date. The value is `YYYY-MM-DD`, optionally followed by a time zone: `Z`, or
+ * `+hh:mm` / `-hh:mm` of at most 14:00. The zone says where the day is; it
+ * does not name another day, so `2026-08-01+02:00` and `2026-08-01-12:00` both
+ * name 1 August 2026. EN 16931 dates are calendar days without a zone, and CII
+ * format 102 has none, so the day is what every format reads and writes.
+ * @param value The date as the document states it
+ */
+export const parseXsdDateDay = (value: string): number | undefined => {
+  const match = /^(\d{4})-(\d{2})-(\d{2})(?:Z|[+-](\d{2}):(\d{2}))?$/.exec(value.trim());
+  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 (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();
+};

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

@@ -96,10 +96,8 @@ export interface IDocumentTotals {
   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 */
+  /** Invoice total amount with VAT (BT-112): BT-109 + BT-110; the paid amount and the amount due are `getPaymentTotals` */
   grandTotal: Decimal;
-  /** Amount due for payment (BT-115): BT-112, as the envelope states no paid amount yet */
-  duePayable: Decimal;
 }
 
 /**
@@ -168,6 +166,5 @@ export const computeDocumentTotals = (
     vatGroups,
     taxTotal,
     grandTotal,
-    duePayable: grandTotal,
   };
 };

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

@@ -97,12 +97,19 @@ export class FormatDetector {
       if (/xrechnung/i.test(guidelineId)) {
         return InvoiceFormat.XRECHNUNG;
       }
-      if (/factur-x/i.test(guidelineId) || /urn:cen\.eu:en16931:2017/i.test(guidelineId)) {
+      // an identifier that names Factur-X or ZUGFeRD decides; ZUGFeRD 2.0 BASIC and EXTENDED name ZUGFeRD
+      // after the EN 16931 identifier they extend (urn:cen.eu:en16931:2017#...#urn:zugferd.de:2p0:...)
+      if (/factur-x/i.test(guidelineId)) {
         return InvoiceFormat.FACTURX;
       }
-      if (/zugferd/i.test(guidelineId) || /urn:ferd:/i.test(guidelineId) || /urn:zugferd/i.test(guidelineId)) {
+      if (/zugferd/i.test(guidelineId) || /urn:ferd:/i.test(guidelineId)) {
         return InvoiceFormat.ZUGFERD;
       }
+      // the EN 16931 profile identifier is shared by Factur-X 1.0 and ZUGFeRD 2.x, one standard with one
+      // XML: an XML-only document of it reads as Factur-X
+      if (/urn:cen\.eu:en16931:2017/i.test(guidelineId)) {
+        return InvoiceFormat.FACTURX;
+      }
       return InvoiceFormat.CII;
     }
 
@@ -287,13 +294,11 @@ export class FormatDetector {
           for (const idNode of Array.from(idNodes)) {
             const profileText = idNode.textContent || '';
             
-            // Check for ZUGFeRD profiles (v1 and v2)
+            // Check for ZUGFeRD profiles: v1, the ZUGFeRD 2.0 identifiers (urn:zugferd.de:2p0:...) and the
+            // urn:zugferd:... identifiers earlier releases of this library wrote
             if (
               profileText.includes('zugferd') ||
               profileText.includes('urn:ferd:') ||
-              profileText === CII_PROFILE_IDS.ZUGFERD_BASIC ||
-              profileText === CII_PROFILE_IDS.ZUGFERD_COMFORT ||
-              profileText === CII_PROFILE_IDS.ZUGFERD_EXTENDED ||
               profileText === CII_PROFILE_IDS.ZUGFERD_V1_BASIC ||
               profileText === CII_PROFILE_IDS.ZUGFERD_V1_COMFORT ||
               profileText === CII_PROFILE_IDS.ZUGFERD_V1_EXTENDED
@@ -301,12 +306,13 @@ export class FormatDetector {
               return InvoiceFormat.ZUGFERD;
             }
 
-            // Check for Factur-X profiles
+            // Check for Factur-X profiles; the EN 16931 profile of ZUGFeRD 2.x has the same identifier, and
+            // an XML-only document of it is Factur-X: ZUGFeRD 2.x and Factur-X 1.0 are one standard
             if (
               profileText.includes('factur-x') ||
               profileText === CII_PROFILE_IDS.FACTURX_MINIMUM ||
-              profileText === CII_PROFILE_IDS.FACTURX_BASIC ||
-              profileText === CII_PROFILE_IDS.FACTURX_EN16931
+              profileText === CII_PROFILE_IDS.FACTURX_BASIC_WL ||
+              profileText === CII_PROFILE_IDS.EN16931
             ) {
               return InvoiceFormat.FACTURX;
             }

package/ts/formats/utils/paid.amount.ts

@@ -0,0 +1,160 @@
+import type { TAccountingDoc, TAdvancePayment } from '../../interfaces/common.js';
+import { EInvoiceFormatError, EInvoiceParsingError } from '../../errors.js';
+import { Decimal } from './decimal.js';
+import { toPlainDecimalString } from './number.text.js';
+import type { IDocumentTotals } from './document.totals.js';
+
+/** The paid amount (BT-113) and the amount due for payment (BT-115) an encoder writes */
+export interface IPaymentTotals {
+  /** Paid amount (BT-113) as the document states it; undefined when it states none or zero, and nothing is written */
+  paidAmount?: Decimal;
+  /** Amount due for payment (BT-115): BT-112 − BT-113 (BR-CO-16; the envelope has no rounding amount BT-114); zero or negative when paid in full or overpaid */
+  duePayable: Decimal;
+}
+
+/** Why a paid amount cannot be written: the rule it breaks, the field and what is wrong */
+export interface IPaymentProblem {
+  ruleId: string;
+  field: string;
+  message: string;
+}
+
+/** Carries a payment problem out of the computation */
+class PaymentProblemSignal extends Error {
+  constructor(public readonly problem: IPaymentProblem) {
+    super(problem.message);
+  }
+}
+
+const refuse = (field: string, message: string, ruleId = 'PAID-AMOUNT'): never => {
+  throw new PaymentProblemSignal({ ruleId, field, message });
+};
+
+/** An amount as the document states it, at its full precision; a value that is no finite number is refused */
+const statedDecimal = (value: unknown, field: string): Decimal => {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return refuse(field, `${field} is no finite number: ${String(value)}`);
+  }
+  return new Decimal(toPlainDecimalString(value));
+};
+
+/** The number of decimals of a stated amount */
+const decimalsOf = (value: number): number => (toPlainDecimalString(value).split('.')[1] ?? '').length;
+
+/** The document types that can be a final invoice (Endrechnung) and deduct advance payments */
+const finalInvoiceTypes: TAccountingDoc['accountingDocType'][] = ['invoice', 'corrected-invoice', 'self-billed-invoice'];
+
+/** What the paid amount and the amount due are computed from */
+export type TPaymentSource = Pick<TAccountingDoc, 'accountingDocType' | 'paidAmount'> & {
+  advancePayments?: TAdvancePayment[];
+};
+
+/**
+ * The paid amount and the amount due of a document, as an encoder writes them.
+ * - When the document lists `advancePayments`, its `paidAmount` equals their
+ *   gross sum, the `net` plus the `vat` of every group of every payment, to
+ *   the last decimal (the rule `@tsclass/tsclass` sets). A document that
+ *   breaks it, or lists advance payments without a paid amount, is refused;
+ *   neither value is recomputed from the other.
+ * - The paid amount (BT-113) has at most the currency's decimals, two at most
+ *   (BR-DEC-16); one with more is refused, not rounded.
+ * - A paid amount of zero is nothing paid, as an absent one: BT-113 is not
+ *   written and BT-115 is BT-112.
+ * @param accountingDoc The document
+ * @param totals Its totals (`computeDocumentTotals`)
+ */
+const computePaymentTotals = (accountingDoc: TPaymentSource, totals: IDocumentTotals): IPaymentTotals => {
+  const advancePayments = accountingDoc.advancePayments ?? [];
+  if (advancePayments.length > 0 && !finalInvoiceTypes.includes(accountingDoc.accountingDocType)) {
+    refuse(
+      'advancePayments',
+      `advancePayments: a ${accountingDoc.accountingDocType} deducts no advance payments; only an invoice, a corrected invoice or a self-billed invoice is a final invoice (§ 14 Abs. 5 Satz 2 UStG)`,
+    );
+  }
+  const statedPaid = accountingDoc.paidAmount;
+  if (advancePayments.length > 0) {
+    const grossSum = Decimal.sum(
+      advancePayments.flatMap((payment, paymentIndex) =>
+        payment.vatGroups.flatMap((group, groupIndex) => [
+          statedDecimal(group.net, `advancePayments[${paymentIndex}].vatGroups[${groupIndex}].net`),
+          statedDecimal(group.vat, `advancePayments[${paymentIndex}].vatGroups[${groupIndex}].vat`),
+        ]),
+      ),
+    );
+    if (statedPaid === undefined || !statedDecimal(statedPaid, 'paidAmount').equals(grossSum)) {
+      refuse(
+        'paidAmount',
+        `paidAmount (${statedPaid === undefined ? 'absent' : toPlainDecimalString(statedPaid)}) does not equal the gross sum of the advancePayments (${grossSum.toString()}), the net plus the vat of every group of every payment; neither value is recomputed from the other`,
+      );
+    }
+  }
+  if (statedPaid === undefined) {
+    return { duePayable: totals.grandTotal };
+  }
+  const paid = statedDecimal(statedPaid, 'paidAmount');
+  if (decimalsOf(statedPaid) > totals.minorUnits) {
+    refuse('paidAmount', `paidAmount: the paid amount (BT-113) has at most ${totals.minorUnits} decimals, it is ${toPlainDecimalString(statedPaid)}`, 'BR-DEC-16');
+  }
+  if (paid.isZero()) {
+    return { duePayable: totals.grandTotal };
+  }
+  return { paidAmount: paid, duePayable: totals.grandTotal.subtract(paid) };
+};
+
+/**
+ * The paid amount and the amount due as an encoder writes them (see
+ * `computePaymentTotals` above for the rules); a document that breaks one is
+ * refused with an `EInvoiceFormatError` naming the field.
+ * @param accountingDoc The document
+ * @param totals Its totals (`computeDocumentTotals`)
+ */
+export const getPaymentTotals = (accountingDoc: TPaymentSource, totals: IDocumentTotals): IPaymentTotals => {
+  try {
+    return computePaymentTotals(accountingDoc, totals);
+  } catch (error) {
+    if (error instanceof PaymentProblemSignal) {
+      throw new EInvoiceFormatError(`${error.problem.ruleId}: ${error.problem.message}`, {
+        unsupportedFeatures: [error.problem.field],
+      });
+    }
+    throw error;
+  }
+};
+
+/**
+ * What keeps a document's paid amount from being written, for a validator to
+ * report instead of throwing; undefined when there is nothing
+ * @param accountingDoc The document
+ * @param totals Its totals (`computeDocumentTotals`)
+ */
+export const findPaymentProblem = (accountingDoc: TPaymentSource, totals: IDocumentTotals): IPaymentProblem | undefined => {
+  try {
+    computePaymentTotals(accountingDoc, totals);
+    return undefined;
+  } catch (error) {
+    if (error instanceof PaymentProblemSignal) {
+      return error.problem;
+    }
+    throw error;
+  }
+};
+
+/**
+ * The paid amount (BT-113) a decoder reads: the number the document states,
+ * or undefined when it states none or zero (a stated zero is nothing paid, as
+ * an absent one). A paid amount that is no number is refused, since the amount
+ * due depends on it.
+ * @param text The text of the paid amount element, '' when absent
+ * @param format The format being read
+ */
+export const readPaidAmount = (text: string, format: string): number | undefined => {
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  const value = Number(trimmed);
+  if (!/^[+-]?(\d+\.?\d*|\.\d+)$/.test(trimmed) || !Number.isFinite(value)) {
+    throw new EInvoiceParsingError(`The paid amount (BT-113) is no decimal number: ${trimmed}`, { format });
+  }
+  return value === 0 ? undefined : value;
+};

package/ts/formats/utils/party.contact.ts

@@ -0,0 +1,30 @@
+import type { business } from '@tsclass/tsclass';
+
+/** The contact of a party: the seller contact (BG-6) or the buyer contact (BG-9) */
+export interface IPartyContact {
+  /** Contact point (BT-41, BT-56) */
+  name?: string;
+  /** Telephone number (BT-42, BT-57) */
+  phone?: string;
+  /** Email address (BT-43, BT-58) */
+  email?: string;
+}
+
+/** A party with the contact metadata the decoders read back (`metadata.contactInformation`) */
+type TPartyWithContactMetadata = business.TContact & { metadata?: { contactInformation?: IPartyContact } };
+
+/**
+ * The contact a party states, as the encoders write it: the contact metadata first, otherwise
+ * the party's own name, telephone number and email address; none when the party states neither.
+ * @param party The seller or the buyer
+ */
+export const getPartyContact = (party: business.TContact | undefined): IPartyContact | undefined => {
+  const explicit = (party as TPartyWithContactMetadata | undefined)?.metadata?.contactInformation;
+  if (explicit && (explicit.name || explicit.phone || explicit.email)) {
+    return explicit;
+  }
+  if (party?.email || party?.phone) {
+    return { name: party.name, phone: party.phone, email: party.email };
+  }
+  return undefined;
+};

package/ts/formats/utils/party.identifier.ts

@@ -0,0 +1,61 @@
+import type { TAccountingDoc } from '../../interfaces/common.js';
+import { EInvoiceFormatError } from '../../errors.js';
+
+/** A party identifier: the seller identifier (BT-29) or the buyer identifier (BT-46), with its scheme */
+export interface IPartyIdentifier {
+  value: string;
+  /** The identification scheme (BT-29-1, BT-46-1): an ISO/IEC 6523 ICD code, or SEPA for a creditor identifier */
+  scheme?: string;
+}
+
+/**
+ * The party identifiers (BT-29 seller, BT-46 buyer) a party carries in
+ * `additionalIdentifiers`, where the decoders keep the ones a document states;
+ * the envelope has no typed field for them. Entries without a value are
+ * skipped, a blank scheme is none.
+ * @param party The seller or the buyer
+ */
+export const getPartyIdentifiers = (party: unknown): IPartyIdentifier[] => {
+  const entries: unknown = (party as { additionalIdentifiers?: unknown } | undefined)?.additionalIdentifiers;
+  if (!Array.isArray(entries)) {
+    return [];
+  }
+  const identifiers: IPartyIdentifier[] = [];
+  for (const entry of entries) {
+    const { value, scheme } = (entry ?? {}) as { value?: unknown; scheme?: unknown };
+    if (typeof value !== 'string' || !value.trim()) {
+      continue;
+    }
+    const trimmedScheme = typeof scheme === 'string' ? scheme.trim() : '';
+    identifiers.push({ value: value.trim(), ...(trimmedScheme ? { scheme: trimmedScheme } : {}) });
+  }
+  return identifiers;
+};
+
+/**
+ * Refuses a document whose buyer carries an identifier (BT-46) with the scheme
+ * SEPA, naming the rule. The SEPA scheme is the creditor identifier (BT-90) of
+ * the seller or the payee. The CEN artefacts 1.3.16 report it on a buyer as
+ * BR-CL-10, "Any identifier identification scheme identifier MUST be coded
+ * using one of the ISO 6523 ICD list.": UBL admits it in a party identification
+ * of the seller and the payee only, and CII in no `ram:GlobalID` at all, which
+ * is where CII writes an identifier with a scheme. Nothing is left out
+ * silently.
+ * @param accountingDoc The document
+ * @param targetFormat The format being written
+ */
+export const assertPartyIdentifiersWritable = (accountingDoc: Pick<TAccountingDoc, 'to'>, targetFormat: string): void => {
+  const entries: unknown = (accountingDoc.to as { additionalIdentifiers?: unknown } | undefined)?.additionalIdentifiers;
+  if (!Array.isArray(entries)) {
+    return;
+  }
+  entries.forEach((entry: unknown, index: number) => {
+    const { scheme } = (entry ?? {}) as { scheme?: unknown };
+    if (typeof scheme === 'string' && scheme.trim().toUpperCase() === 'SEPA') {
+      throw new EInvoiceFormatError(
+        `BR-CL-10: Any identifier identification scheme identifier MUST be coded using one of the ISO 6523 ICD list. to.additionalIdentifiers[${index}] states the scheme SEPA, the creditor identifier (BT-90) of a seller or payee, which a buyer identifier (BT-46) cannot have`,
+        { targetFormat, unsupportedFeatures: ['BR-CL-10'] },
+      );
+    }
+  });
+};

package/ts/formats/utils/peppol.profile.ts

@@ -0,0 +1,13 @@
+import { UBL_CUSTOMIZATION_IDS } from '../ubl/ubl.types.js';
+
+/**
+ * Whether a specification identifier (BT-24) is that of PEPPOL BIS Billing 3.0,
+ * `urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0`,
+ * the one identifier the PEPPOL BIS Billing 3.0 rules apply to. PINT, the
+ * A-NZ, Singapore and other PEPPOL derivatives, and the PEPPOL business process
+ * type (BT-23, `urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`), which an
+ * EN 16931 document may state as well, do not make a document one.
+ * @param customizationId The specification identifier
+ */
+export const isPeppolBisBilling3 = (customizationId: string | undefined): boolean =>
+  (customizationId ?? '').trim() === UBL_CUSTOMIZATION_IDS.PEPPOL_BIS;