@fin.cx/einvoice 8.3.1 → 10.0.0

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

@@ -1,12 +1,12 @@
 import { CIIBaseEncoder } from '../cii.encoder.js';
 import type { TAccountingDoc, TCreditNote, TInvoiceDocument } from '../../../interfaces/common.js';
-import { FACTURX_PROFILE_IDS } from './facturx.types.js';
 import { DOMParser, XMLSerializer } from '../../../plugins.js';
 import { getDocumentTypeCode } from '../../utils/document.typecode.js';
 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 { getWritableDate, getWritableDueDate } from '../../utils/date.value.js';
+import { getWritableDueDate } from '../../utils/date.value.js';
 
 /**
  * Encoder for Factur-X invoice format
@@ -93,15 +93,7 @@ export class FacturXEncoder extends CIIBaseEncoder {
     // Add ID element with profile
     const idElement = doc.createElement('ram:ID');
 
-    // Set profile based on the selected profile
-    let profileId = FACTURX_PROFILE_IDS.EN16931;
-    if (this.profile === 'BASIC') {
-      profileId = FACTURX_PROFILE_IDS.BASIC;
-    } else if (this.profile === 'MINIMUM') {
-      profileId = FACTURX_PROFILE_IDS.MINIMUM;
-    }
-
-    idElement.textContent = profileId;
+    idElement.textContent = this.getProfileId();
     guidelineElement.appendChild(idElement);
   }
 
@@ -208,9 +200,14 @@ export class FacturXEncoder extends CIIBaseEncoder {
     const agreementElement = doc.createElement('ram:ApplicableHeaderTradeAgreement');
     transactionElement.appendChild(agreementElement);
 
+    // Buyer reference (BT-10)
+    this.addBuyerReference(doc, agreementElement, invoice);
+
     // Add seller
     const sellerElement = doc.createElement('ram:SellerTradeParty');
     this.addPartyInfo(doc, sellerElement, invoice.from, 'seller');
+    // Seller electronic address (BT-34)
+    this.addSellerElectronicAddress(doc, sellerElement, invoice);
     agreementElement.appendChild(sellerElement);
 
     // Add buyer
@@ -227,6 +224,9 @@ export class FacturXEncoder extends CIIBaseEncoder {
    * @param partyRole Whether the party is the seller or the buyer
    */
   private addPartyInfo(doc: Document, partyElement: Element, party: any, partyRole: 'seller' | 'buyer'): void {
+    // Party identifiers (BT-29 seller, BT-46 buyer)
+    this.addPartyIdentifiers(doc, partyElement, party);
+
     // Add name
     const nameElement = doc.createElement('ram:Name');
     nameElement.textContent = party.name;
@@ -380,6 +380,9 @@ export class FacturXEncoder extends CIIBaseEncoder {
 
     settlementElement.appendChild(paymentTermsElement);
 
+    // Invoicing period (BG-14)
+    this.addInvoicingPeriod(doc, settlementElement, invoice);
+
     // Add totals, in the order of the CII schema
     const monetarySummationElement = doc.createElement('ram:SpecifiedTradeSettlementHeaderMonetarySummation');
     const appendAmount = (name: string, value: { toFixed(decimalPlaces: number): string }, withCurrency = false) => {
@@ -394,7 +397,11 @@ export class FacturXEncoder extends CIIBaseEncoder {
     appendAmount('ram:TaxBasisTotalAmount', totals.taxBasisTotal); // BT-109
     appendAmount('ram:TaxTotalAmount', totals.taxTotal, true); // BT-110
     appendAmount('ram:GrandTotalAmount', totals.grandTotal); // BT-112
-    appendAmount('ram:DuePayableAmount', totals.duePayable); // BT-115
+    const payment = getPaymentTotals(invoice, totals);
+    if (payment.paidAmount) {
+      appendAmount('ram:TotalPrepaidAmount', payment.paidAmount); // BT-113
+    }
+    appendAmount('ram:DuePayableAmount', payment.duePayable); // BT-115
 
     settlementElement.appendChild(monetarySummationElement);
   }
@@ -500,18 +507,4 @@ export class FacturXEncoder extends CIIBaseEncoder {
       }
     }
   }
-
-  /**
-   * Formats a date as YYYYMMDD
-   * @param timestamp Timestamp to format
-   * @returns Formatted date string
-   */
-  private 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}`;
-  }
 }

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

@@ -1,16 +1,7 @@
-import { CIIProfile, CII_PROFILE_IDS } from '../cii.types.js';
-
 /**
  * Factur-X specific constants and types
  */
 
-// Factur-X profile IDs
-export const FACTURX_PROFILE_IDS = {
-  MINIMUM: CII_PROFILE_IDS.FACTURX_MINIMUM,
-  BASIC: CII_PROFILE_IDS.FACTURX_BASIC,
-  EN16931: CII_PROFILE_IDS.FACTURX_EN16931
-};
-
 // Factur-X PDF attachment filename
 export const FACTURX_ATTACHMENT_FILENAME = 'factur-x.xml';
 

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

@@ -59,8 +59,8 @@ export class FacturXValidator extends CIIBaseValidator {
 
     let valid = true;
 
-    // BR-16: Amount due for payment (BT-115) = Invoice total amount with VAT (BT-112) - Paid amount (BT-113)
-    valid = this.validateAmounts() && valid;
+    // BR-CO-10 to BR-CO-17: the stated totals, VAT breakdown and line amounts agree with each other
+    valid = this.validateStatedTotals() && valid;
 
     // BR-CO-3: Value added tax point date (BT-7) and Value added tax point date code (BT-8) are mutually exclusive
     valid = this.validateMutuallyExclusiveFields() && valid;
@@ -70,6 +70,9 @@ export class FacturXValidator extends CIIBaseValidator {
     // and/or the Seller tax representative VAT identifier (BT-63).
     valid = this.validateSellerVatIdentifier() && valid;
 
+    // BR-CO-26: the seller states a seller, legal registration or VAT identifier
+    valid = this.validateSellerIdentifier() && valid;
+
     // BR-23: every line has a unit code
     valid = this.validateLineUnitCodePresence() && valid;
 
@@ -79,47 +82,6 @@ export class FacturXValidator extends CIIBaseValidator {
     return valid;
   }
 
-  /**
-   * Validates amount calculations in the invoice
-   * @returns True if amount validation passed
-   */
-  private validateAmounts(): boolean {
-    if (!this.doc) return false;
-
-    try {
-      // Extract amounts
-      const totalAmount = this.getNumber(
-        '//ram:ApplicableHeaderTradeSettlement/ram:SpecifiedTradeSettlementHeaderMonetarySummation/ram:GrandTotalAmount'
-      );
-
-      const paidAmount = this.getNumber(
-        '//ram:ApplicableHeaderTradeSettlement/ram:SpecifiedTradeSettlementHeaderMonetarySummation/ram:TotalPrepaidAmount'
-      ) || 0;
-
-      const dueAmount = this.getNumber(
-        '//ram:ApplicableHeaderTradeSettlement/ram:SpecifiedTradeSettlementHeaderMonetarySummation/ram:DuePayableAmount'
-      );
-
-      // Calculate expected due amount
-      const expectedDueAmount = totalAmount - paidAmount;
-
-      // Compare with a small tolerance for rounding errors
-      if (Math.abs(dueAmount - expectedDueAmount) > 0.01) {
-        this.addError(
-          'BR-16',
-          `Amount due for payment (${dueAmount}) must equal Invoice total amount with VAT (${totalAmount}) - Paid amount (${paidAmount})`,
-          '//ram:ApplicableHeaderTradeSettlement/ram:SpecifiedTradeSettlementHeaderMonetarySummation'
-        );
-        return false;
-      }
-
-      return true;
-    } catch (error) {
-      this.addError('FX-AMOUNT', `Error validating amounts: ${error}`, '/');
-      return false;
-    }
-  }
-
   /**
    * Validates mutually exclusive fields
    * @returns True if validation passed

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

@@ -8,6 +8,7 @@ import type {
 import { business, finance } 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 ZUGFeRD invoice format
@@ -87,6 +88,14 @@ export class ZUGFeRDDecoder 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'), 'zugferd');
+
     // Create the common invoice data
     const invoiceData = {
       type: 'accounting-doc' as const,
@@ -113,8 +122,15 @@ export class ZUGFeRDDecoder 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
@@ -166,6 +182,9 @@ export class ZUGFeRDDecoder 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',
@@ -179,7 +198,8 @@ export class ZUGFeRDDecoder extends CIIBaseDecoder {
         registrationId: registrationId,
         registrationName: '',
         ...(taxNumber ? { taxNumber } : {})
-      }
+      },
+      ...(additionalIdentifiers.length > 0 ? { additionalIdentifiers } : {})
     } as business.TContact;
   }
 

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

@@ -1,12 +1,11 @@
 import { CIIBaseEncoder } from '../cii.encoder.js';
 import type { TAccountingDoc, TCreditNote, TInvoiceDocument } from '../../../interfaces/common.js';
-import { ZUGFERD_PROFILE_IDS } from './zugferd.types.js';
-import { CIIProfile } from '../cii.types.js';
 import { DOMParser, XMLSerializer } from '../../../plugins.js';
 import { getDocumentTypeCode } from '../../utils/document.typecode.js';
-import { getWritableDate, getWritableDueDate } 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';
+import { getPaymentTotals } from '../../utils/paid.amount.js';
 import { toPlainDecimalString } from '../../utils/number.text.js';
 import { resolveCountryCode } from '../../utils/country.code.js';
 
@@ -14,12 +13,6 @@ import { resolveCountryCode } from '../../utils/country.code.js';
  * Encoder for ZUGFeRD invoice format
  */
 export class ZUGFeRDEncoder extends CIIBaseEncoder {
-  constructor() {
-    super();
-    // Set default profile to BASIC
-    this.profile = CIIProfile.BASIC;
-  }
-
   /**
    * Encodes a credit note into ZUGFeRD XML
    * @param creditNote Credit note to encode
@@ -101,15 +94,7 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
     // Add ID element with profile
     const idElement = doc.createElement('ram:ID');
 
-    // Set profile based on the selected profile
-    let profileId = ZUGFERD_PROFILE_IDS.BASIC;
-    if (this.profile === CIIProfile.COMFORT) {
-      profileId = ZUGFERD_PROFILE_IDS.COMFORT;
-    } else if (this.profile === CIIProfile.EXTENDED) {
-      profileId = ZUGFERD_PROFILE_IDS.EXTENDED;
-    }
-
-    idElement.textContent = profileId;
+    idElement.textContent = this.getProfileId();
     guidelineElement.appendChild(idElement);
   }
 
@@ -216,12 +201,8 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
     const agreementElement = doc.createElement('ram:ApplicableHeaderTradeAgreement');
     transactionElement.appendChild(agreementElement);
 
-    // Add buyer reference if available
-    if (invoice.buyerReference) {
-      const buyerRefElement = doc.createElement('ram:BuyerReference');
-      buyerRefElement.textContent = invoice.buyerReference;
-      agreementElement.appendChild(buyerRefElement);
-    }
+    // Buyer reference (BT-10)
+    this.addBuyerReference(doc, agreementElement, invoice);
 
     // Add seller
     const sellerElement = doc.createElement('ram:SellerTradeParty');
@@ -229,14 +210,7 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
     
     // Seller electronic address (BT-34): ram:URIUniversalCommunication/ram:URIID of the party; a
     // trade contact (ram:DefinedTradeContact) has no URIID
-    if (invoice.electronicAddress && invoice.from.type === 'company') {
-      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);
-    }
+    this.addSellerElectronicAddress(doc, sellerElement, invoice);
     
     agreementElement.appendChild(sellerElement);
 
@@ -254,6 +228,9 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
    * @param partyRole Whether the party is the seller or the buyer
    */
   private addPartyInfo(doc: Document, partyElement: Element, party: any, partyRole: 'seller' | 'buyer'): void {
+    // Party identifiers (BT-29 seller, BT-46 buyer)
+    this.addPartyIdentifiers(doc, partyElement, party);
+
     // Add name
     const nameElement = doc.createElement('ram:Name');
     nameElement.textContent = party.name;
@@ -442,31 +419,7 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
     this.addTaxDetails(doc, settlementElement, invoice);
 
     // Invoicing period (BG-14): in the header settlement, where the CII schema puts it
-    if (invoice.periodOfPerformance) {
-      const periodElement = doc.createElement('ram:BillingSpecifiedPeriod');
-      
-      // Start date
-      if (invoice.periodOfPerformance.from !== undefined) {
-        const startDateElement = doc.createElement('ram:StartDateTime');
-        const startDateStringElement = doc.createElement('udt:DateTimeString');
-        startDateStringElement.setAttribute('format', '102'); // YYYYMMDD format
-        startDateStringElement.textContent = this.formatDateYYYYMMDD(invoice.periodOfPerformance.from, 'BT-73 invoicing period start date');
-        startDateElement.appendChild(startDateStringElement);
-        periodElement.appendChild(startDateElement);
-      }
-      
-      // End date
-      if (invoice.periodOfPerformance.to !== undefined) {
-        const endDateElement = doc.createElement('ram:EndDateTime');
-        const endDateStringElement = doc.createElement('udt:DateTimeString');
-        endDateStringElement.setAttribute('format', '102'); // YYYYMMDD format
-        endDateStringElement.textContent = this.formatDateYYYYMMDD(invoice.periodOfPerformance.to, 'BT-74 invoicing period end date');
-        endDateElement.appendChild(endDateStringElement);
-        periodElement.appendChild(endDateElement);
-      }
-      
-      settlementElement.appendChild(periodElement);
-    }
+    this.addInvoicingPeriod(doc, settlementElement, invoice);
 
     // Add totals
     this.addMonetarySummation(doc, settlementElement, invoice);
@@ -554,7 +507,11 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
     appendAmount('ram:TaxBasisTotalAmount', totals.taxBasisTotal); // BT-109
     appendAmount('ram:TaxTotalAmount', totals.taxTotal, true); // BT-110
     appendAmount('ram:GrandTotalAmount', totals.grandTotal); // BT-112
-    appendAmount('ram:DuePayableAmount', totals.duePayable); // BT-115
+    const payment = getPaymentTotals(invoice, totals);
+    if (payment.paidAmount) {
+      appendAmount('ram:TotalPrepaidAmount', payment.paidAmount); // BT-113
+    }
+    appendAmount('ram:DuePayableAmount', payment.duePayable); // BT-115
 
     settlementElement.appendChild(monetarySummationElement);
   }
@@ -658,18 +615,4 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
       }
     }
   }
-
-  /**
-   * Formats a date as YYYYMMDD
-   * @param timestamp Timestamp to format
-   * @returns Formatted date string
-   */
-  private 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}`;
-  }
-}
+}

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

@@ -1,16 +1,7 @@
-import { CIIProfile, CII_PROFILE_IDS } from '../cii.types.js';
-
 /**
  * ZUGFeRD specific constants and types
  */
 
-// ZUGFeRD profile IDs
-export const ZUGFERD_PROFILE_IDS = {
-  BASIC: CII_PROFILE_IDS.ZUGFERD_BASIC,
-  COMFORT: CII_PROFILE_IDS.ZUGFERD_COMFORT,
-  EXTENDED: CII_PROFILE_IDS.ZUGFERD_EXTENDED
-};
-
 // ZUGFeRD PDF attachment filename
 export const ZUGFERD_ATTACHMENT_FILENAME = 'zugferd-invoice.xml';
 

package/ts/formats/cii/zugferd/zugferd.v1.decoder.ts

@@ -1,4 +1,5 @@
 import { CIIBaseDecoder } from '../cii.decoder.js';
+import type { ICIIInvoicingPeriod } from '../cii.decoder.js';
 import type {
   TAccountingDocEnvelope,
   TAccountingDocType,
@@ -8,6 +9,8 @@ import type {
 import { ZUGFERD_V1_NAMESPACES } from '../cii.types.js';
 import { business, finance, xpath } from '../../../plugins.js';
 import { EN16931Validator } from '../../validation/en16931.validator.js';
+import { readPaidAmount } from '../../utils/paid.amount.js';
+import type { IEInvoiceStatedValues } from '../../../interfaces/stated.values.js';
 
 /** XPath selection with the ZUGFeRD v1 namespaces */
 const zugferdV1Select = xpath.useNamespaces({
@@ -68,6 +71,38 @@ export class ZUGFeRDV1Decoder extends CIIBaseDecoder {
     return dueDate ? this.parseRequiredCIIDate(dueDate, this.v1Text(`${dueDatePath}/@format`)) : undefined;
   }
 
+  /**
+   * Reads the buyer reference of the v1 header trade agreement
+   * (`ram:ApplicableSupplyChainTradeAgreement/ram:BuyerReference`); undefined
+   * when the document states none.
+   */
+  protected override extractBuyerReference(): string | undefined {
+    return (
+      this.v1Text('/rsm:CrossIndustryDocument/rsm:SpecifiedSupplyChainTradeTransaction/ram:ApplicableSupplyChainTradeAgreement/ram:BuyerReference') ||
+      undefined
+    );
+  }
+
+  /**
+   * Reads the identifier of the v1 document context
+   * (`rsm:SpecifiedExchangedDocumentContext/ram:GuidelineSpecifiedDocumentContextParameter/ram:ID`);
+   * undefined when the document states none.
+   */
+  protected override extractSpecificationIdentifier(): string | undefined {
+    return (
+      this.v1Text('/rsm:CrossIndustryDocument/rsm:SpecifiedExchangedDocumentContext/ram:GuidelineSpecifiedDocumentContextParameter/ram:ID') ||
+      undefined
+    );
+  }
+
+  /**
+   * ZUGFeRD 1.0 predates EN 16931 and has no business terms to read the stated
+   * values by; a v1 document has none
+   */
+  protected override readStatedValues(): IEInvoiceStatedValues | undefined {
+    return undefined;
+  }
+
   /** The trimmed text of the first node a v1 path selects, or '' */
   private v1Text(path: string): string {
     return String(zugferdV1Select(`string(${path})`, this.doc)).trim();
@@ -89,6 +124,19 @@ export class ZUGFeRDV1Decoder extends CIIBaseDecoder {
     return this.parseRequiredCIIDate(deliveryDate, format);
   }
 
+  /**
+   * Reads the invoicing period of the v1 header settlement
+   * (`ram:ApplicableSupplyChainTradeSettlement/ram:BillingSpecifiedPeriod`).
+   * A ZUGFeRD 1.0 trade party has no electronic address, so a v1 document has
+   * no seller electronic address (BT-34).
+   */
+  protected override extractInvoicingPeriod(): ICIIInvoicingPeriod {
+    return this.readInvoicingPeriod(
+      '/rsm:CrossIndustryDocument/rsm:SpecifiedSupplyChainTradeTransaction/ram:ApplicableSupplyChainTradeSettlement/ram:BillingSpecifiedPeriod',
+      (path) => this.v1Text(path),
+    );
+  }
+
   /**
    * Decodes a ZUGFeRD v1 credit note
    * @returns Promise resolving to a TCreditNote object
@@ -163,6 +211,19 @@ export class ZUGFeRDV1Decoder extends CIIBaseDecoder {
     // Reverse charge: every line has the VAT category AE
     const reverseCharge = this.isReverseChargeDocument();
 
+    // the invoicing period (BG-14), when stated
+    const invoicingPeriod = this.invoicingPeriodFields(this.extractInvoicingPeriod());
+    // the buyer reference (BT-10), when stated
+    const buyerReference = this.extractBuyerReference();
+
+    // the paid amount (BT-113) of the v1 header settlement, read with the v1 namespaces
+    const paidAmount = readPaidAmount(
+      this.v1Text(
+        '/rsm:CrossIndustryDocument/rsm:SpecifiedSupplyChainTradeTransaction/ram:ApplicableSupplyChainTradeSettlement/ram:SpecifiedTradeSettlementMonetarySummation/ram:TotalPrepaidAmount',
+      ),
+      'zugferd',
+    );
+
     // Create the common invoice data
     const invoiceData = {
       type: 'accounting-doc' as const,
@@ -189,6 +250,11 @@ export class ZUGFeRDV1Decoder extends CIIBaseDecoder {
       notes: notes,
       // the day of supply as the document states it (BT-72), never the issue date in its place
       ...(deliveryDate === undefined ? {} : { deliveryDate }),
+      ...invoicingPeriod,
+      // the specification identifier (BT-24), with the metadata of a one-date period
+      ...this.metadataFields(invoicingPeriod),
+      ...(buyerReference === undefined ? {} : { buyerReference }),
+      ...(paidAmount === undefined ? {} : { paidAmount }),
       objectActions: []
     };
     

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

@@ -24,9 +24,13 @@ export class ZUGFeRDValidator extends CIIBaseValidator {
    * @returns True if business validation passed
    */
   protected validateBusinessRules(): boolean {
+    // BR-CO-10 to BR-CO-17: the stated totals, VAT breakdown and line amounts agree with each other
+    const totalsAgree = this.validateStatedTotals();
+    // BR-CO-26: the seller states a seller, legal registration or VAT identifier
+    const sellerIdentified = this.validateSellerIdentifier();
     // BR-23: every line has a unit code
     const linesHaveUnits = this.validateLineUnitCodePresence();
     // BR-CL-23: unit codes of UN/ECE Recommendation 20 with the Recommendation 21 extension
-    return this.validateUnitCodes() && linesHaveUnits;
+    return this.validateUnitCodes() && linesHaveUnits && sellerIdentified && totalsAgree;
   }
 }

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

@@ -5,6 +5,8 @@
 
 import { EInvoice } from '../../einvoice.js';
 import { getAccountingDocType, getDocumentTypeCode } from '../utils/document.typecode.js';
+import { computeDocumentTotals } from '../utils/document.totals.js';
+import { getPaymentTotals } from '../utils/paid.amount.js';
 import type { 
   EN16931SemanticModel,
   Seller,
@@ -43,14 +45,15 @@ export class SemanticModelAdapter {
       },
       
       // Process metadata
-      processControl: invoice.metadata?.profileId ? {
-        businessProcessType: invoice.metadata?.extensions?.businessProcessId,
-        specificationIdentifier: invoice.metadata.profileId
+      // the specification identifier (BT-24) is customizationId, the business process type (BT-23) profileId
+      processControl: invoice.metadata?.customizationId ? {
+        ...(invoice.metadata.profileId ? { businessProcessType: invoice.metadata.profileId } : {}),
+        specificationIdentifier: invoice.metadata.customizationId
       } : undefined,
       
       // References
       references: {
-        buyerReference: invoice.metadata?.buyerReference,
+        buyerReference: invoice.buyerReference,
         projectReference: invoice.metadata?.extensions?.projectReference,
         contractReference: invoice.metadata?.extensions?.contractReference,
         purchaseOrderReference: invoice.metadata?.extensions?.purchaseOrderReference,
@@ -132,24 +135,27 @@ export class SemanticModelAdapter {
     invoice.from = this.reverseMapSeller(model.seller);
     invoice.to = this.reverseMapBuyer(model.buyer);
     invoice.items = this.reverseMapInvoiceLines(model.invoiceLines);
+    // the paid amount (BT-113); a stated zero is nothing paid
+    if (model.documentTotals?.prepaidAmount) {
+      invoice.paidAmount = model.documentTotals.prepaidAmount;
+    }
     
     // Set metadata
     if (model.processControl) {
       invoice.metadata = {
         ...invoice.metadata,
-        profileId: model.processControl.specificationIdentifier,
-        extensions: {
-          ...invoice.metadata?.extensions,
-          businessProcessId: model.processControl.businessProcessType
-        }
+        customizationId: model.processControl.specificationIdentifier,
+        ...(model.processControl.businessProcessType ? { profileId: model.processControl.businessProcessType } : {}),
       };
     }
     
-    // Set references
+    // Set references; the buyer reference (BT-10) is the envelope's
     if (model.references) {
+      if (model.references.buyerReference) {
+        invoice.buyerReference = model.references.buyerReference;
+      }
       invoice.metadata = {
         ...invoice.metadata,
-        buyerReference: model.references.buyerReference,
         extensions: {
           ...invoice.metadata?.extensions,
           contractReference: model.references.contractReference,
@@ -251,8 +257,8 @@ export class SemanticModelAdapter {
         tradingName: contact.tradingName,
         identifier: contact.registrationDetails?.registrationId,
         legalRegistrationIdentifier: contact.registrationDetails?.registrationId,
-        vatIdentifier: contact.registrationDetails?.vatId || contact.vatNumber,
-        taxRegistrationIdentifier: contact.taxId,
+        vatIdentifier: contact.registrationDetails?.vatId || undefined,
+        taxRegistrationIdentifier: contact.registrationDetails?.taxNumber || undefined,
         additionalLegalInfo: contact.description,
         electronicAddress: contact.email || contact.contact?.email
       };
@@ -260,7 +266,8 @@ export class SemanticModelAdapter {
       return {
         name: contact.name || `${contact.firstName || ''} ${contact.lastName || ''}`.trim(),
         identifier: contact.registrationDetails?.registrationId,
-        vatIdentifier: contact.registrationDetails?.vatId || contact.vatNumber,
+        vatIdentifier: contact.registrationDetails?.vatId || undefined,
+        taxRegistrationIdentifier: contact.registrationDetails?.taxNumber || undefined,
         electronicAddress: contact.email
       };
     }
@@ -277,14 +284,14 @@ export class SemanticModelAdapter {
         tradingName: contact.tradingName,
         identifier: contact.registrationDetails?.registrationId,
         legalRegistrationIdentifier: contact.registrationDetails?.registrationId,
-        vatIdentifier: contact.registrationDetails?.vatId || contact.vatNumber,
+        vatIdentifier: contact.registrationDetails?.vatId || undefined,
         electronicAddress: contact.email || contact.contact?.email
       };
     } else {
       return {
         name: contact.name || `${contact.firstName || ''} ${contact.lastName || ''}`.trim(),
         identifier: contact.registrationDetails?.registrationId,
-        vatIdentifier: contact.registrationDetails?.vatId || contact.vatNumber,
+        vatIdentifier: contact.registrationDetails?.vatId || undefined,
         electronicAddress: contact.email
       };
     }
@@ -405,9 +412,10 @@ export class SemanticModelAdapter {
       chargeTotalAmount: invoice.metadata?.extensions?.documentCharges?.reduce(
         (sum: number, c: { amount: number }) => sum + c.amount, 0
       ),
-      prepaidAmount: invoice.metadata?.extensions?.prepaidAmount,
+      // the paid amount (BT-113) of the envelope; the amount due (BT-115) is the gross total less it
+      prepaidAmount: invoice.paidAmount,
       roundingAmount: invoice.metadata?.extensions?.roundingAmount,
-      payableAmount: invoice.totalGross
+      payableAmount: getPaymentTotals(invoice, computeDocumentTotals(invoice)).duePayable.toNumber()
     };
   }
   
@@ -502,7 +510,8 @@ export class SemanticModelAdapter {
       registrationDetails: {
         vatId: seller.vatIdentifier || '',
         registrationId: seller.identifier || seller.legalRegistrationIdentifier || '',
-        registrationName: seller.name
+        registrationName: seller.name,
+        ...(seller.taxRegistrationIdentifier ? { taxNumber: seller.taxRegistrationIdentifier } : {})
       },
       status: 'active',
       foundedDate: {