@fin.cx/einvoice 9.0.0 → 10.0.1

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

@@ -10,6 +10,7 @@ import { computeDocumentTotals } from '../../utils/document.totals.js';
 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';
 
 /**
  * UBL Encoder implementation
@@ -114,6 +115,12 @@ export class UBLEncoder extends UBLBaseEncoder {
     // Document Currency Code
     this.appendElement(doc, root, 'cbc:DocumentCurrencyCode', invoice.currency);
 
+    // Buyer reference (BT-10), as the buyer gave it
+    const buyerReference = invoice.buyerReference?.trim();
+    if (buyerReference) {
+      this.appendElement(doc, root, 'cbc:BuyerReference', buyerReference);
+    }
+
     // Invoicing period (BG-14), in schema order before the document references
     this.addInvoicePeriod(doc, root, invoice);
 
@@ -229,6 +236,18 @@ export class UBLEncoder extends UBLBaseEncoder {
     
     const partyNode = doc.createElement('cac:Party');
     partyElement.appendChild(partyNode);
+
+    // Party identifiers (BT-29 seller, BT-46 buyer), before the name in the schema order
+    for (const identifier of getPartyIdentifiers(party)) {
+      const partyIdentificationNode = doc.createElement('cac:PartyIdentification');
+      partyNode.appendChild(partyIdentificationNode);
+      const idNode = doc.createElement('cbc:ID');
+      if (identifier.scheme) {
+        idNode.setAttribute('schemeID', identifier.scheme);
+      }
+      idNode.textContent = identifier.value;
+      partyIdentificationNode.appendChild(idNode);
+    }
     
     // Party name
     const partyNameNode = doc.createElement('cac:PartyName');
@@ -902,29 +921,6 @@ export class UBLEncoder extends UBLBaseEncoder {
       }
     }
     
-    // Add additional identifiers
-    if (partyData.additionalIdentifiers && Array.isArray(partyData.additionalIdentifiers)) {
-      for (const identifier of partyData.additionalIdentifiers) {
-        const partyId = doc.createElement('cac:PartyIdentification');
-        const id = doc.createElement('cbc:ID');
-        if (identifier.scheme) {
-          id.setAttribute('schemeID', identifier.scheme);
-        }
-        id.textContent = identifier.value;
-        partyId.appendChild(id);
-        
-        // Insert after EndpointID or at beginning
-        const endpoint = party.getElementsByTagName('cbc:EndpointID')[0];
-        if (endpoint && endpoint.nextSibling) {
-          party.insertBefore(partyId, endpoint.nextSibling);
-        } else if (party.firstChild) {
-          party.insertBefore(partyId, party.firstChild);
-        } else {
-          party.appendChild(partyId);
-        }
-      }
-    }
-    
     // Add contact information from metadata if not already present
     const contactInfo = partyData.metadata?.contactInformation;
     if (contactInfo) {

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

@@ -4,6 +4,8 @@ import { UBLDocumentType, UBL_NAMESPACES } from './ubl.types.js';
 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 type { IEInvoiceStatedValues } from '../../interfaces/stated.values.js';
 
 const ublParser = new DOMParser();
 const ublNamespaces = {
@@ -37,11 +39,21 @@ export abstract class UBLBaseDecoder extends BaseDecoder {
     return this.doc;
   }
 
+  /** The values the document states, read by `decode` */
+  private statedValues?: IEInvoiceStatedValues;
+
+  public override getStatedValues(): IEInvoiceStatedValues | undefined {
+    return this.statedValues;
+  }
+
   /**
    * Decodes UBL XML into an accounting document
    * @returns Promise resolving to the accounting document
    */
   public async decode(): Promise<TAccountingDoc> {
+    // 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
     if (this.getDocumentType() === UBLDocumentType.CREDIT_NOTE) {
       return this.decodeCreditNote();

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

@@ -3,6 +3,8 @@ import type { TAccountingDoc, TCreditNote, TInvoiceDocument } from '../../interf
 import { UBLDocumentType, UBL_NAMESPACES } from './ubl.types.js';
 import { getWritableDate } from '../utils/date.value.js';
 import { assertVatCategoryWritable } from '../utils/vat.category.js';
+import { assertSellerIdentified } from '../utils/seller.identifier.js';
+import { assertPartyIdentifiersWritable } from '../utils/party.identifier.js';
 import { computeDocumentTotals } from '../utils/document.totals.js';
 import { getPaymentTotals } from '../utils/paid.amount.js';
 
@@ -53,13 +55,15 @@ export abstract class UBLBaseEncoder extends BaseEncoder {
   public async encode(invoice: TAccountingDoc): Promise<string> {
     // a reverse charge document that lacks what EN 16931 requires of one is refused (BR-AE-02, BR-AE-05)
     assertVatCategoryWritable(invoice, 'ubl');
+    // a buyer identifier with the SEPA scheme is refused (BR-CL-10)
+    assertPartyIdentifiersWritable(invoice, 'ubl');
     // a paid amount the advance payments do not add up to, or with more decimals than the currency has, is refused
     getPaymentTotals(invoice, computeDocumentTotals(invoice));
     // a credit note is a CreditNote document; an invoice, a debit note and a self-billed invoice are Invoice documents that differ in their type code
-    if (invoice.accountingDocType === 'creditnote') {
-      return this.encodeCreditNote(invoice);
-    }
-    return this.encodeInvoice(invoice);
+    const xml = invoice.accountingDocType === 'creditnote' ? await this.encodeCreditNote(invoice) : await this.encodeInvoice(invoice);
+    // a seller the written document does not identify is refused (BR-CO-26), never written silently
+    assertSellerIdentified(xml, 'ubl', 'ubl');
+    return xml;
   }
 
   /**

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

@@ -4,6 +4,8 @@ import type { ValidationResult } from '../../interfaces/common.js';
 import { UBLDocumentType, UBL_NAMESPACES } from './ubl.types.js';
 import { DOMParser, xpath } from '../../plugins.js';
 import { meetsUnitCodeRule } from '../utils/unit.codes.js';
+import { BR_CO_26_TEXT, ublSellerMeetsBrCo26 } from '../utils/seller.identifier.js';
+import { findStatedValueDisagreements, readUblStatedValues } from '../utils/stated.values.js';
 
 const ublValidatorParser = new DOMParser();
 const ublValidatorNamespaces = {
@@ -105,6 +107,33 @@ export abstract class UBLBaseValidator extends BaseValidator {
    */
   protected abstract validateStructure(): boolean;
 
+  /**
+   * BR-CO-10 to BR-CO-17: the document totals, the VAT breakdown, the line
+   * amounts and the document level allowances and charges the document states
+   * agree with each other, as the CEN artefacts check them
+   * @returns True if they do
+   */
+  protected validateStatedTotals(): boolean {
+    const findings = findStatedValueDisagreements(readUblStatedValues(this.doc), 'ubl');
+    for (const finding of findings) {
+      this.addError(finding.ruleId, finding.message, finding.location);
+    }
+    return findings.length === 0;
+  }
+
+  /**
+   * BR-CO-26: the seller states a seller identifier (BT-29), a legal
+   * registration identifier (BT-30) or a VAT identifier (BT-31).
+   * @returns True if it does
+   */
+  protected validateSellerIdentifier(): boolean {
+    if (ublSellerMeetsBrCo26(this.doc)) {
+      return true;
+    }
+    this.addError('BR-CO-26', BR_CO_26_TEXT, '/*/cac:AccountingSupplierParty');
+    return false;
+  }
+
   /**
    * BR-23: every invoice or credit note line has a unit code on its invoiced or credited quantity.
    * @returns True if every line has one

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

@@ -271,6 +271,8 @@ export class XRechnungDecoder extends UBLBaseDecoder {
         currency: currencyCode as finance.TCurrency,
         notes: notes,
         objectActions: [],
+        // the buyer reference (BT-10), when stated
+        ...(buyerReference.trim() ? { buyerReference: buyerReference.trim() } : {}),
         // the day and the period of supply as the document states them (BT-72, BG-14)
         ...(deliveryDate ? { deliveryDate: this.parseRequiredUblDate(deliveryDate) } : {}),
         ...(periodStart && periodEnd
@@ -285,16 +287,22 @@ export class XRechnungDecoder extends UBLBaseDecoder {
         ...(paidAmount === undefined ? {} : { paidAmount }),
       };
 
+      // the specification identifier (BT-24), which the validators read to tell an XRechnung, a
+      // PEPPOL or a Factur-X document
+      const customizationId = this.getText('/*/cbc:CustomizationID', this.doc).trim();
       if (hasBusinessReferences || hasPaymentInformation || hasDateInformation) {
         invoiceData.metadata = {
           format: 'xrechnung' as any,
           version: '1.0.0',
+          ...(customizationId ? { customizationId } : {}),
           extensions: {
             ...(hasBusinessReferences ? { businessReferences } : {}),
             ...(hasPaymentInformation ? { paymentInformation } : {}),
             ...(hasDateInformation ? { dateInformation } : {}),
           }
         };
+      } else if (customizationId) {
+        invoiceData.metadata = { customizationId };
       }
       
       // Validate mandatory EN16931 fields unless validation is skipped

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

@@ -2,6 +2,32 @@ 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';
+import { getPartyContact } from '../../utils/party.contact.js';
+import { EInvoiceFormatError } from '../../../errors.js';
+
+/**
+ * The buyer reference (BT-10) an XRechnung document states: the envelope's
+ * `buyerReference`, or the one a decoded UBL document keeps in
+ * `metadata.extensions.businessReferences`. XRechnung requires it (BR-DE-15,
+ * "Das Element \"Buyer reference\" (BT-10) muss übermittelt werden."), and it is
+ * the buyer's: the buyer gives the seller an identifier of its choice, a
+ * Leitweg-ID for a public buyer. Without one the export is refused; a document
+ * for a buyer that gave none can be written as EN 16931 UBL (`ubl`), where
+ * BT-10 is optional.
+ * @param invoice The document
+ */
+const getXRechnungBuyerReference = (invoice: TAccountingDoc): string => {
+  const kept: unknown = (invoice as { metadata?: { extensions?: { businessReferences?: { buyerReference?: unknown } } } }).metadata
+    ?.extensions?.businessReferences?.buyerReference;
+  const buyerReference = invoice.buyerReference?.trim() || (typeof kept === 'string' ? kept.trim() : '');
+  if (!buyerReference) {
+    throw new EInvoiceFormatError(
+      "BR-DE-15: an XRechnung document states the buyer reference (BT-10), buyerReference is missing. It is the identifier the buyer gave for routing the invoice (a Leitweg-ID for a public buyer) and cannot be put in place by the seller; without one, export the document as EN 16931 UBL ('ubl'), where BT-10 is optional",
+      { targetFormat: 'xrechnung', unsupportedFeatures: ['BR-DE-15'] },
+    );
+  }
+  return buyerReference;
+};
 
 /**
  * Encoder for XRechnung (UBL) format
@@ -59,9 +85,11 @@ export class XRechnungEncoder extends UBLEncoder {
       customizationId.textContent = UBL_CUSTOMIZATION_IDS.XRECHNUNG;
     }
     
-    // Add or update Buyer Reference (required for XRechnung)
+    // The buyer reference (BT-10), which XRechnung requires (BR-DE-15): the identifier the buyer
+    // gave the seller for routing the invoice, a Leitweg-ID for a public buyer. It comes from the
+    // buyer, so there is none to put in place of a missing one.
+    const buyerReferenceValue = getXRechnungBuyerReference(invoice);
     let buyerRef = root.getElementsByTagName('cbc:BuyerReference')[0];
-    const buyerReferenceValue = (invoice as any).buyerReference || metadata?.businessReferences?.buyerReference || invoice.id;
     if (!buyerRef) {
       // Find where to insert it (after DocumentCurrencyCode)
       const currencyCode = root.getElementsByTagName('cbc:DocumentCurrencyCode')[0];
@@ -70,7 +98,7 @@ export class XRechnungEncoder extends UBLEncoder {
         buyerRef.textContent = buyerReferenceValue;
         currencyCode.parentNode!.insertBefore(buyerRef, currencyCode.nextSibling);
       }
-    } else if (!buyerRef.textContent || buyerRef.textContent.trim() === '') {
+    } else {
       buyerRef.textContent = buyerReferenceValue;
     }
     
@@ -151,29 +179,6 @@ export class XRechnungEncoder extends UBLEncoder {
       }
     }
     
-    // Add PartyIdentification for additional identifiers
-    if (party.additionalIdentifiers) {
-      for (const identifier of party.additionalIdentifiers) {
-        const partyId = doc.createElement('cac:PartyIdentification');
-        const id = doc.createElement('cbc:ID');
-        if (identifier.scheme) {
-          id.setAttribute('schemeID', identifier.scheme);
-        }
-        id.textContent = identifier.value;
-        partyId.appendChild(id);
-        
-        // Insert after EndpointID or at beginning
-        const endpoint = partyElement.getElementsByTagName('cbc:EndpointID')[0];
-        if (endpoint && endpoint.nextSibling) {
-          partyElement.insertBefore(partyId, endpoint.nextSibling);
-        } else if (partyElement.firstChild) {
-          partyElement.insertBefore(partyId, partyElement.firstChild);
-        } else {
-          partyElement.appendChild(partyId);
-        }
-      }
-    }
-    
     // Add company registration number to PartyLegalEntity
     if (party.registrationDetails?.registrationId) {
       let legalEntity = partyElement.getElementsByTagName('cac:PartyLegalEntity')[0];
@@ -444,27 +449,10 @@ export class XRechnungEncoder extends UBLEncoder {
    */
   private enhancePartyInformation(doc: Document, invoice: TAccountingDoc): void {
     // Enhance supplier party
-    this.addContactToParty(doc, 'cac:AccountingSupplierParty', this.contactInformationOf(invoice.from));
+    this.addContactToParty(doc, 'cac:AccountingSupplierParty', getPartyContact(invoice.from));
     
     // Enhance customer party
-    this.addContactToParty(doc, 'cac:AccountingCustomerParty', this.contactInformationOf(invoice.to));
-  }
-
-  /**
-   * The contact block of a party: explicit contact metadata first, otherwise
-   * the party's own email and phone (BR-DE-11 and BR-DE-12 require both for
-   * the seller).
-   * @param party Party data
-   */
-  private contactInformationOf(party: any): { name?: string; phone?: string; email?: string } | undefined {
-    const explicit = party?.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;
+    this.addContactToParty(doc, 'cac:AccountingCustomerParty', getPartyContact(invoice.to));
   }
 
   /**

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[]) : [];
+  }
 }