@fin.cx/einvoice 8.3.1 → 10.0.0

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

@@ -1,10 +1,22 @@
 import { BaseDecoder } from '../base/base.decoder.js';
 import type { TAccountingDoc, TCreditNote, TInvoiceDocument } from '../../interfaces/common.js';
-import { CII_NAMESPACES, CIIProfile } from './cii.types.js';
+import { CII_NAMESPACES } from './cii.types.js';
 import { DOMParser, xpath } from '../../plugins.js';
 import { EInvoiceParsingError } from '../../errors.js';
 import { getAccountingDocType } from '../utils/document.typecode.js';
 import type { TPrecedingInvoiceReference } from '../utils/preceding.invoice.js';
+import type { IEInvoiceMetadata } from '../../interfaces/en16931-metadata.js';
+import type { IEInvoiceStatedValues } from '../../interfaces/stated.values.js';
+import { readCiiStatedValues } from '../utils/stated.values.js';
+
+/**
+ * The invoicing period (BG-14) a CII document states: its start date (BT-73),
+ * its end date (BT-74), or both (BR-CO-19), as the UTC timestamps of the days
+ */
+export interface ICIIInvoicingPeriod {
+  start?: number;
+  end?: number;
+}
 
 const ciiParser = new DOMParser();
 const ciiNamespaces = {
@@ -22,7 +34,6 @@ export abstract class CIIBaseDecoder extends BaseDecoder {
   protected doc: Document;
   protected namespaces: Record<string, string>;
   protected select: xpath.XPathSelect;
-  protected profile: CIIProfile = CIIProfile.EN16931;
 
   constructor(xml: string, skipValidation: boolean = false) {
     super(xml, skipValidation);
@@ -35,20 +46,35 @@ export abstract class CIIBaseDecoder extends BaseDecoder {
 
     // Create XPath selector with namespaces
     this.select = ciiSelect;
-
-    // Detect profile
-    this.detectProfile();
   }
 
   public override getParsedDocument(): Document {
     return this.doc;
   }
 
+  /** The values the document states, read by `decode` */
+  private statedValues?: IEInvoiceStatedValues;
+
+  public override getStatedValues(): IEInvoiceStatedValues | undefined {
+    return this.statedValues;
+  }
+
+  /**
+   * Reads the values a CII (D16B) document states, by their EN 16931 business
+   * terms
+   */
+  protected readStatedValues(): IEInvoiceStatedValues | undefined {
+    return this.assertStatedValuesReadable(readCiiStatedValues(this.doc), 'cii');
+  }
+
   /**
    * Decodes CII 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.readStatedValues();
+
     // CII has one root for every document; the document type code (BT-3) alone tells them apart
     const accountingDocType = getAccountingDocType(
       this.getText('/rsm:CrossIndustryInvoice/rsm:ExchangedDocument/ram:TypeCode'),
@@ -59,33 +85,6 @@ export abstract class CIIBaseDecoder extends BaseDecoder {
     return this.decodeInvoice(accountingDocType);
   }
 
-  /**
-   * Detects the CII profile from the XML
-   */
-  protected detectProfile(): void {
-    // Look for profile identifier
-    const profileNode = this.select(
-      'string(//rsm:ExchangedDocumentContext/ram:GuidelineSpecifiedDocumentContextParameter/ram:ID)',
-      this.doc
-    );
-
-    if (profileNode) {
-      const profileText = profileNode.toString();
-
-      if (profileText.includes('BASIC')) {
-        this.profile = CIIProfile.BASIC;
-      } else if (profileText.includes('EN16931')) {
-        this.profile = CIIProfile.EN16931;
-      } else if (profileText.includes('EXTENDED')) {
-        this.profile = CIIProfile.EXTENDED;
-      } else if (profileText.includes('MINIMUM')) {
-        this.profile = CIIProfile.MINIMUM;
-      } else if (profileText.includes('COMFORT')) {
-        this.profile = CIIProfile.COMFORT;
-      }
-    }
-  }
-
   /**
    * Decodes a CII credit note
    * @returns Promise resolving to a TCreditNote object
@@ -186,6 +185,134 @@ export abstract class CIIBaseDecoder extends BaseDecoder {
     return this.parseRequiredCIIDate(deliveryDate, this.getText(`${deliveryDatePath}/@format`).trim());
   }
 
+  /**
+   * Reads the invoicing period (BG-14) of the header settlement: the start date
+   * (BT-73), the end date (BT-74), or both (BR-CO-19). A line's own period
+   * (BG-26) is not the document's.
+   */
+  protected extractInvoicingPeriod(): ICIIInvoicingPeriod {
+    return this.readInvoicingPeriod(
+      '/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeSettlement/ram:BillingSpecifiedPeriod',
+      (path) => this.getText(path).trim(),
+    );
+  }
+
+  /**
+   * Reads an invoicing period from its start and end date strings; each end is
+   * read when the document states it
+   * @param periodPath The path of the period element
+   * @param text The trimmed text a path selects, or ''
+   */
+  protected readInvoicingPeriod(periodPath: string, text: (path: string) => string): ICIIInvoicingPeriod {
+    const startPath = `${periodPath}/ram:StartDateTime/udt:DateTimeString`;
+    const endPath = `${periodPath}/ram:EndDateTime/udt:DateTimeString`;
+    const start = text(startPath);
+    const end = text(endPath);
+    return {
+      ...(start ? { start: this.parseRequiredCIIDate(start, text(`${startPath}/@format`)) } : {}),
+      ...(end ? { end: this.parseRequiredCIIDate(end, text(`${endPath}/@format`)) } : {}),
+    };
+  }
+
+  /**
+   * The accounting document fields of a stated invoicing period. With both
+   * dates it is `periodOfPerformance`. The envelope's period has both dates, so
+   * a period that states only its start or only its end keeps that date where
+   * the UBL decoder keeps it, in `metadata.extensions.dateInformation`
+   * (`periodStart` or `periodEnd`, the calendar day as YYYY-MM-DD); the CII and
+   * UBL encoders write it back from there.
+   * @param period The invoicing period the document states
+   */
+  protected invoicingPeriodFields(
+    period: ICIIInvoicingPeriod,
+  ): { periodOfPerformance: { from: number; to: number } } | { metadata: IEInvoiceMetadata } | Record<string, never> {
+    if (period.start !== undefined && period.end !== undefined) {
+      return { periodOfPerformance: { from: period.start, to: period.end } };
+    }
+    // the calendar day of the UTC timestamp the decoders return for a date
+    const dayOf = (timestamp: number) => new Date(timestamp).toISOString().slice(0, 10);
+    if (period.start !== undefined) {
+      return { metadata: { extensions: { dateInformation: { periodStart: dayOf(period.start) } } } };
+    }
+    if (period.end !== undefined) {
+      return { metadata: { extensions: { dateInformation: { periodEnd: dayOf(period.end) } } } };
+    }
+    return {};
+  }
+
+  /**
+   * Reads the seller electronic address (BT-34),
+   * `ram:URIUniversalCommunication/ram:URIID` of the seller, with its scheme;
+   * undefined when the document states none.
+   */
+  protected extractSellerElectronicAddress(): { scheme: string; value: string } | undefined {
+    const uriPath =
+      '/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeAgreement/ram:SellerTradeParty/ram:URIUniversalCommunication/ram:URIID';
+    const value = this.getText(uriPath).trim();
+    if (!value) {
+      return undefined;
+    }
+    return { scheme: this.getText(`${uriPath}/@schemeID`).trim(), value };
+  }
+
+  /**
+   * Reads the specification identifier (BT-24),
+   * `ram:GuidelineSpecifiedDocumentContextParameter/ram:ID` of the document
+   * context; undefined when the document states none.
+   */
+  protected extractSpecificationIdentifier(): string | undefined {
+    return (
+      this.getText('/rsm:CrossIndustryInvoice/rsm:ExchangedDocumentContext/ram:GuidelineSpecifiedDocumentContextParameter/ram:ID').trim() ||
+      undefined
+    );
+  }
+
+  /**
+   * The accounting document's `metadata`: the specification identifier (BT-24)
+   * as `customizationId`, which the validators read to tell an XRechnung, a
+   * PEPPOL or a Factur-X document, merged with the metadata of the invoicing
+   * period fields (`invoicingPeriodFields`), which it takes the place of in
+   * the decoded document.
+   * @param invoicingPeriod The invoicing period fields of the document
+   */
+  protected metadataFields(
+    invoicingPeriod: ReturnType<CIIBaseDecoder['invoicingPeriodFields']>,
+  ): { metadata: IEInvoiceMetadata } | Record<string, never> {
+    const customizationId = this.extractSpecificationIdentifier();
+    const periodMetadata = 'metadata' in invoicingPeriod ? invoicingPeriod.metadata : undefined;
+    if (customizationId === undefined && periodMetadata === undefined) {
+      return {};
+    }
+    return { metadata: { ...periodMetadata, ...(customizationId === undefined ? {} : { customizationId }) } };
+  }
+
+  /**
+   * Reads the party identifiers (BT-29 seller, BT-46 buyer) of a trade party:
+   * `ram:ID` without a scheme and `ram:GlobalID` with its scheme, kept where the
+   * UBL decoder keeps them, as the party's `additionalIdentifiers`
+   * @param partyXPath XPath to the trade party
+   */
+  protected extractPartyIdentifiers(partyXPath: string): Array<{ value: string; scheme: string }> {
+    const nodes = this.select(`${partyXPath}/ram:ID | ${partyXPath}/ram:GlobalID`, this.doc);
+    return (Array.isArray(nodes) ? nodes : [])
+      .map((node) => {
+        const element = node as Element;
+        return { value: (element.textContent ?? '').trim(), scheme: element.localName === 'GlobalID' ? (element.getAttribute('schemeID') ?? '').trim() : '' };
+      })
+      .filter((identifier) => identifier.value !== '');
+  }
+
+  /**
+   * Reads the buyer reference (BT-10), `ram:BuyerReference` of the header trade
+   * agreement; undefined when the document states none.
+   */
+  protected extractBuyerReference(): string | undefined {
+    return (
+      this.getText('/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeAgreement/ram:BuyerReference').trim() ||
+      undefined
+    );
+  }
+
   /**
    * Gets a text value from an XPath expression
    * @param xpath XPath expression

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

@@ -2,9 +2,43 @@ import { BaseEncoder } from '../base/base.encoder.js';
 import type { TAccountingDoc, TCreditNote, TInvoiceDocument } from '../../interfaces/common.js';
 import { EInvoiceFormatError } from '../../errors.js';
 import { getPrecedingInvoiceReferences } from '../utils/preceding.invoice.js';
-import { getWritableDate } from '../utils/date.value.js';
+import { getWritableDate, parseXsdDateDay } from '../utils/date.value.js';
 import { assertVatCategoryWritable } from '../utils/vat.category.js';
-import { CII_CHILD_SEQUENCES, CII_NAMESPACES, CIIProfile } from './cii.types.js';
+import { assertSellerIdentified } from '../utils/seller.identifier.js';
+import { assertPartyIdentifiersWritable, getPartyIdentifiers } from '../utils/party.identifier.js';
+import { computeDocumentTotals } from '../utils/document.totals.js';
+import { getPaymentTotals } from '../utils/paid.amount.js';
+import { CII_CHILD_SEQUENCES, CII_NAMESPACES, CII_PROFILE_IDS, CIIProfile } from './cii.types.js';
+import type { IEInvoiceMetadata } from '../../interfaces/en16931-metadata.js';
+
+/**
+ * Why a CII profile is not written. The CII encoders write the full EN 16931
+ * content, so the one profile they state is EN 16931 (`urn:cen.eu:en16931:2017`,
+ * named COMFORT in ZUGFeRD 2.x); stating another profile for that content would
+ * make a document that does not validate against the profile it names.
+ */
+const REFUSED_PROFILES: Partial<Record<CIIProfile, string>> = {
+  [CIIProfile.MINIMUM]:
+    'the content written is EN 16931, which the MINIMUM profile does not allow, and a MINIMUM document is not an e-invoice (BMF letter of 15 October 2024, Rn. 25 and 30)',
+  [CIIProfile.BASIC]:
+    'the content written is EN 16931, which neither the BASIC nor the BASIC WL profile allows, and a BASIC WL document is not an e-invoice (BMF letter of 15 October 2024, Rn. 25 and 30)',
+  [CIIProfile.EXTENDED]:
+    'the output has not been checked against the EXTENDED schema and rules',
+};
+
+/**
+ * Refuses a profile the CII encoders do not write, naming the profile and why
+ * @param profile CII profile
+ */
+const assertWritableProfile = (profile: CIIProfile): void => {
+  const reason = REFUSED_PROFILES[profile];
+  if (reason !== undefined) {
+    throw new EInvoiceFormatError(
+      `The CII encoders do not write the ${profile} profile: ${reason}; choose ${CIIProfile.EN16931}, the profile whose content they write`,
+      { targetFormat: 'cii', unsupportedFeatures: [`profile ${profile}`] },
+    );
+  }
+};
 
 /**
  * Base encoder for CII-based invoice formats
@@ -13,13 +47,26 @@ export abstract class CIIBaseEncoder extends BaseEncoder {
   protected profile: CIIProfile = CIIProfile.EN16931;
 
   /**
-   * Sets the CII profile to use for encoding
+   * Sets the CII profile to use for encoding. EN16931 and its ZUGFeRD name
+   * COMFORT are written; MINIMUM, BASIC (and with it BASIC WL) and EXTENDED are
+   * refused with an `EInvoiceFormatError`.
    * @param profile CII profile
    */
   public setProfile(profile: CIIProfile): void {
+    assertWritableProfile(profile);
     this.profile = profile;
   }
 
+  /**
+   * The specification identifier (BT-24) the document states: the EN 16931
+   * profile, the one profile whose content the encoders write. A refused
+   * profile a subclass assigned directly is refused here too.
+   */
+  protected getProfileId(): string {
+    assertWritableProfile(this.profile);
+    return CII_PROFILE_IDS.EN16931;
+  }
+
   /**
    * Encodes an accounting document into CII XML
    * @param invoice Accounting document to encode
@@ -28,18 +75,15 @@ export abstract class CIIBaseEncoder 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, 'cii');
-    // MINIMUM has no preceding invoice reference (BG-3): a reference the document states cannot be written there
-    if (this.profile === CIIProfile.MINIMUM && getPrecedingInvoiceReferences(invoice).length > 0) {
-      throw new EInvoiceFormatError(
-        'The MINIMUM profile has no preceding invoice reference (BG-3); a document that refers to a preceding invoice needs a profile that carries it',
-        { targetFormat: 'cii', unsupportedFeatures: ['BG-3 in profile MINIMUM'] },
-      );
-    }
+    // a buyer identifier with the SEPA scheme is refused (BR-CL-10)
+    assertPartyIdentifiersWritable(invoice, 'cii');
+    // 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));
     // CII has one root for every document; the two paths differ in the type code they write
-    if (invoice.accountingDocType === 'creditnote') {
-      return this.encodeCreditNote(invoice);
-    }
-    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, 'cii', 'cii');
+    return xml;
   }
 
   /**
@@ -161,4 +205,156 @@ export abstract class CIIBaseEncoder extends BaseEncoder {
   protected formatDate(timestamp: number, field: string): string {
     return getWritableDate(timestamp, field, 'cii').toISOString().split('T')[0];
   }
+
+  /**
+   * Formats a date as YYYYMMDD, the CII date format 102. A value that is no
+   * valid timestamp is refused with an `EInvoiceFormatError` naming the field.
+   * @param timestamp Timestamp to format
+   * @param field The business term the date is written as
+   * @returns Formatted date string
+   */
+  protected formatDateYYYYMMDD(timestamp: number, field: string): string {
+    const date = getWritableDate(timestamp, field, 'cii');
+    // the UTC fields: a calendar day is its UTC midnight, whatever the server's zone
+    const year = date.getUTCFullYear();
+    const month = (date.getUTCMonth() + 1).toString().padStart(2, '0');
+    const day = date.getUTCDate().toString().padStart(2, '0');
+    return `${year}${month}${day}`;
+  }
+
+  /**
+   * Adds the seller electronic address (BT-34), `electronicAddress`, as
+   * `ram:URIUniversalCommunication/ram:URIID` of the seller, with its scheme
+   * (BR-62). EN 16931 asks nothing of the seller for it, so a person states one
+   * as a company does.
+   * @param doc XML document
+   * @param sellerElement The seller trade party
+   * @param invoice Invoice data
+   */
+  protected addSellerElectronicAddress(doc: Document, sellerElement: Element, invoice: TAccountingDoc): void {
+    if (!invoice.electronicAddress) {
+      return;
+    }
+    const communicationElement = doc.createElement('ram:URIUniversalCommunication');
+    const uriElement = doc.createElement('ram:URIID');
+    uriElement.setAttribute('schemeID', invoice.electronicAddress.scheme);
+    uriElement.textContent = invoice.electronicAddress.value;
+    communicationElement.appendChild(uriElement);
+    sellerElement.appendChild(communicationElement);
+  }
+
+  /**
+   * Adds the party identifiers (BT-29 seller, BT-46 buyer) the party carries:
+   * one with a scheme as `ram:GlobalID` with its scheme (BT-29-1, an ISO/IEC
+   * 6523 ICD code), one without as `ram:ID`, first in the trade party as the
+   * CII schema orders it. A SEPA creditor identifier, which UBL states as a
+   * seller identification with the scheme SEPA, is the bank assigned creditor
+   * identifier (BT-90) and no party identifier in CII; it is not written here.
+   * @param doc XML document
+   * @param partyElement The seller or buyer trade party
+   * @param party The seller or the buyer
+   */
+  protected addPartyIdentifiers(doc: Document, partyElement: Element, party: unknown): void {
+    const identifiers = getPartyIdentifiers(party).filter((identifier) => identifier.scheme?.toUpperCase() !== 'SEPA');
+    for (const identifier of identifiers.reverse()) {
+      const idElement = doc.createElement(identifier.scheme ? 'ram:GlobalID' : 'ram:ID');
+      if (identifier.scheme) {
+        idElement.setAttribute('schemeID', identifier.scheme);
+      }
+      idElement.textContent = identifier.value;
+      partyElement.insertBefore(idElement, partyElement.firstChild);
+    }
+  }
+
+  /**
+   * Adds the buyer reference (BT-10) as `ram:BuyerReference` of the header
+   * trade agreement, its first child in the CII schema; nothing when the
+   * document has none.
+   * @param doc XML document
+   * @param agreementElement The header trade agreement
+   * @param invoice Invoice data
+   */
+  protected addBuyerReference(doc: Document, agreementElement: Element, invoice: TAccountingDoc): void {
+    const buyerReference = invoice.buyerReference?.trim();
+    if (!buyerReference) {
+      return;
+    }
+    const buyerReferenceElement = doc.createElement('ram:BuyerReference');
+    buyerReferenceElement.textContent = buyerReference;
+    agreementElement.appendChild(buyerReferenceElement);
+  }
+
+  /**
+   * 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
+   * the end date (BT-74) of `periodOfPerformance`. Without it, the date or
+   * dates a decoded document kept in `metadata.extensions.dateInformation`
+   * (`periodStart`, `periodEnd`) are written, as the UBL encoders write them:
+   * a period may state only one of its dates (BR-CO-19).
+   * @param doc XML document
+   * @param settlementElement The header trade settlement
+   * @param invoice Invoice data
+   */
+  protected addInvoicingPeriod(doc: Document, settlementElement: Element, invoice: TAccountingDoc): void {
+    const { start, end } = this.getInvoicingPeriodDays(invoice);
+    if (start === undefined && end === undefined) {
+      return;
+    }
+    const periodElement = doc.createElement('ram:BillingSpecifiedPeriod');
+    const appendDate = (name: string, day: string) => {
+      const dateElement = doc.createElement(name);
+      const dateStringElement = doc.createElement('udt:DateTimeString');
+      dateStringElement.setAttribute('format', '102');
+      dateStringElement.textContent = day;
+      dateElement.appendChild(dateStringElement);
+      periodElement.appendChild(dateElement);
+    };
+    if (start !== undefined) {
+      appendDate('ram:StartDateTime', start);
+    }
+    if (end !== undefined) {
+      appendDate('ram:EndDateTime', end);
+    }
+    settlementElement.appendChild(periodElement);
+  }
+
+  /**
+   * The start (BT-73) and end (BT-74) dates of the invoicing period, in CII
+   * format 102: from `periodOfPerformance`, or else from the dates kept in
+   * `metadata.extensions.dateInformation`. A kept date is an `xsd:date`, as
+   * the UBL decoder keeps it and the CII decoders write it (YYYY-MM-DD); a time
+   * zone does not move the day it names (`parseXsdDateDay`), so the stated day
+   * is written. '' is no date, as the UBL decoder writes it. Any other value is
+   * refused with an `EInvoiceFormatError` naming the date.
+   * @param invoice Invoice data
+   */
+  private getInvoicingPeriodDays(invoice: TAccountingDoc): { start?: string; end?: string } {
+    if (invoice.periodOfPerformance) {
+      return {
+        start: this.formatDateYYYYMMDD(invoice.periodOfPerformance.from, 'BT-73 invoicing period start date'),
+        end: this.formatDateYYYYMMDD(invoice.periodOfPerformance.to, 'BT-74 invoicing period end date'),
+      };
+    }
+    const dateInformation: unknown = (invoice as TAccountingDoc & { metadata?: IEInvoiceMetadata }).metadata?.extensions?.dateInformation;
+    if (typeof dateInformation !== 'object' || dateInformation === null) {
+      return {};
+    }
+    const keptDay = (key: 'periodStart' | 'periodEnd', field: string): string | undefined => {
+      const value: unknown = (dateInformation as Record<string, unknown>)[key];
+      if (value === undefined || value === '') {
+        return undefined;
+      }
+      const day = typeof value === 'string' ? parseXsdDateDay(value) : undefined;
+      if (day === undefined) {
+        throw new EInvoiceFormatError(`${field} is no valid date: ${String(value)}`, {
+          targetFormat: 'cii',
+          unsupportedFeatures: [field],
+        });
+      }
+      return this.formatDateYYYYMMDD(day, field);
+    };
+    const start = keptDay('periodStart', 'BT-73 invoicing period start date');
+    const end = keptDay('periodEnd', 'BT-74 invoicing period end date');
+    return { ...(start === undefined ? {} : { start }), ...(end === undefined ? {} : { end }) };
+  }
 }

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

@@ -26,17 +26,15 @@ export enum CIIProfile {
   MINIMUM = 'MINIMUM'
 }
 
-// CII profile IDs for different formats
+// CII profile IDs (BT-24, the specification identifier)
 export const CII_PROFILE_IDS = {
-  // Factur-X profiles
-  FACTURX_MINIMUM: 'urn:factur-x.eu:1p0:minimum',
-  FACTURX_BASIC: 'urn:factur-x.eu:1p0:basicwl',
-  FACTURX_EN16931: 'urn:cen.eu:en16931:2017',
+  // the EN 16931 profile of Factur-X 1.0 and ZUGFeRD 2.x (named COMFORT in ZUGFeRD): one standard, one
+  // identifier, and the only profile the CII encoders write
+  EN16931: 'urn:cen.eu:en16931:2017',
 
-  // ZUGFeRD v2 profiles
-  ZUGFERD_BASIC: 'urn:zugferd:basic',
-  ZUGFERD_COMFORT: 'urn:zugferd:comfort',
-  ZUGFERD_EXTENDED: 'urn:zugferd:extended',
+  // Factur-X and ZUGFeRD 2.1 subset profiles, recognised on decode
+  FACTURX_MINIMUM: 'urn:factur-x.eu:1p0:minimum',
+  FACTURX_BASIC_WL: 'urn:factur-x.eu:1p0:basicwl',
 
   // ZUGFeRD v1 profiles
   ZUGFERD_V1_BASIC: 'urn:ferd:CrossIndustryDocument:invoice:1p0:basic',

package/ts/formats/cii/cii.validator.ts

@@ -1,9 +1,11 @@
 import { BaseValidator } from '../base/base.validator.js';
 import { ValidationLevel } from '../../interfaces/common.js';
 import type { ValidationResult } from '../../interfaces/common.js';
-import { CII_NAMESPACES, CIIProfile } from './cii.types.js';
+import { CII_NAMESPACES } from './cii.types.js';
 import { DOMParser, xpath } from '../../plugins.js';
 import { meetsUnitCodeRule } from '../utils/unit.codes.js';
+import { BR_CO_26_TEXT, ciiSellerMeetsBrCo26 } from '../utils/seller.identifier.js';
+import { findStatedValueDisagreements, readCiiStatedValues } from '../utils/stated.values.js';
 
 const ciiValidatorParser = new DOMParser();
 const ciiValidatorNamespaces = {
@@ -20,7 +22,6 @@ export abstract class CIIBaseValidator extends BaseValidator {
   protected doc!: Document;
   protected namespaces!: Record<string, string>;
   protected select!: xpath.XPathSelect;
-  protected profile: CIIProfile = CIIProfile.EN16931;
 
   constructor(xml: string, doc?: Document) {
     super(xml);
@@ -34,9 +35,6 @@ export abstract class CIIBaseValidator extends BaseValidator {
 
       // Create XPath selector with namespaces
       this.select = ciiValidatorSelect;
-
-      // Detect profile
-      this.detectProfile();
     } catch (error) {
       this.addError('CII-PARSE', `Failed to parse XML: ${error}`, '/');
     }
@@ -114,6 +112,33 @@ export abstract class CIIBaseValidator 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(readCiiStatedValues(this.doc), 'cii');
+    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 (ciiSellerMeetsBrCo26(this.doc)) {
+      return true;
+    }
+    this.addError('BR-CO-26', BR_CO_26_TEXT, '//ram:SellerTradeParty');
+    return false;
+  }
+
   /**
    * BR-23: every invoice line has a unit code on its billed quantity.
    * @returns True if every line has one
@@ -160,33 +185,6 @@ export abstract class CIIBaseValidator extends BaseValidator {
     return valid;
   }
 
-  /**
-   * Detects the CII profile from the XML
-   */
-  protected detectProfile(): void {
-    // Look for profile identifier
-    const profileNode = this.select(
-      'string(//rsm:ExchangedDocumentContext/ram:GuidelineSpecifiedDocumentContextParameter/ram:ID)',
-      this.doc
-    );
-
-    if (profileNode) {
-      const profileText = profileNode.toString();
-
-      if (profileText.includes('BASIC')) {
-        this.profile = CIIProfile.BASIC;
-      } else if (profileText.includes('EN16931')) {
-        this.profile = CIIProfile.EN16931;
-      } else if (profileText.includes('EXTENDED')) {
-        this.profile = CIIProfile.EXTENDED;
-      } else if (profileText.includes('MINIMUM')) {
-        this.profile = CIIProfile.MINIMUM;
-      } else if (profileText.includes('COMFORT')) {
-        this.profile = CIIProfile.COMFORT;
-      }
-    }
-  }
-
   /**
    * Gets a text value from an XPath expression
    * @param xpath XPath expression

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

@@ -5,10 +5,10 @@ import type {
   TCreditNote,
   TInvoiceDocument,
 } from '../../../interfaces/common.js';
-import { FACTURX_PROFILE_IDS } from './facturx.types.js';
 import { business, finance, general } from '../../../plugins.js';
 import { EN16931Validator } from '../../validation/en16931.validator.js';
 import { getPrecedingInvoiceFields } from '../../utils/preceding.invoice.js';
+import { readPaidAmount } from '../../utils/paid.amount.js';
 
 /**
  * Decoder for Factur-X invoice format
@@ -97,6 +97,14 @@ export class FacturXDecoder extends CIIBaseDecoder {
     // Reverse charge: every line has the VAT category AE
     const reverseCharge = this.isReverseChargeDocument();
 
+    // the invoicing period (BG-14) and the seller electronic address (BT-34), when stated
+    const invoicingPeriod = this.invoicingPeriodFields(this.extractInvoicingPeriod());
+    // the buyer reference (BT-10), when stated
+    const buyerReference = this.extractBuyerReference();
+    const electronicAddress = this.extractSellerElectronicAddress();
+
+    const paidAmount = readPaidAmount(this.getText('//ram:ApplicableHeaderTradeSettlement/ram:SpecifiedTradeSettlementHeaderMonetarySummation/ram:TotalPrepaidAmount'), 'facturx');
+
     // Create the common invoice data
     const invoiceData = {
       type: 'accounting-doc' as const,
@@ -123,8 +131,15 @@ export class FacturXDecoder extends CIIBaseDecoder {
       notes: notes,
       // the day of supply as the document states it (BT-72)
       ...(deliveryDate === undefined ? {} : { deliveryDate }),
+      ...invoicingPeriod,
+      // the specification identifier (BT-24), with the metadata of a one-date period
+      ...this.metadataFields(invoicingPeriod),
+      ...(buyerReference === undefined ? {} : { buyerReference }),
+      ...(electronicAddress === undefined ? {} : { electronicAddress }),
       objectActions: [],
       ...getPrecedingInvoiceFields(accountingDocType, this.extractPrecedingInvoiceReferences()),
+      // the paid amount (BT-113); the amount due (BT-115) follows from it and the totals
+      ...(paidAmount === undefined ? {} : { paidAmount }),
     };
     
     // Validate mandatory EN16931 fields unless validation is skipped
@@ -163,6 +178,9 @@ export class FacturXDecoder extends CIIBaseDecoder {
     // the tax registration identifier (BT-32 for the seller), the Steuernummer: scheme FC
     const taxNumber = this.getText(`${partyXPath}/ram:SpecifiedTaxRegistration/ram:ID[@schemeID="FC"]`) || '';
 
+    // the party identifiers (BT-29 seller, BT-46 buyer)
+    const additionalIdentifiers = this.extractPartyIdentifiers(partyXPath);
+
     // Create contact object
     return {
       type: 'company',
@@ -176,7 +194,8 @@ export class FacturXDecoder extends CIIBaseDecoder {
         registrationId: registrationId,
         registrationName: '',
         ...(taxNumber ? { taxNumber } : {})
-      }
+      },
+      ...(additionalIdentifiers.length > 0 ? { additionalIdentifiers } : {})
     } as business.TContact;
   }