@fin.cx/einvoice 8.2.1 → 8.2.2

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

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

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

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

package/ts/formats/validation/en16931.business-rules.validator.ts

@@ -4,6 +4,12 @@ import type { EInvoice } from '../../einvoice.js';
 import { CurrencyCalculator, areMonetaryValuesEqual } from '../utils/currency.utils.js';
 import { DecimalCurrencyCalculator } from '../utils/currency.calculator.decimal.js';
 import { Decimal } from '../utils/decimal.js';
+import {
+  computeDocumentTotals,
+  findInvalidItemAmounts,
+  getDocumentCalculator,
+  getTotalsSkippedResult,
+} from '../utils/document.totals.js';
 import type { ValidationResult, ValidationOptions } from './validation.types.js';
 
 /**
@@ -24,24 +30,34 @@ export class EN16931BusinessRulesValidator {
     // Initialize currency calculators if currency is available
     if (invoice.currency) {
       this.currencyCalculator = new CurrencyCalculator(invoice.currency);
-      this.decimalCalculator = new DecimalCurrencyCalculator(invoice.currency);
+      // the rounding the encoders use: the currency's minor unit, at most two decimals
+      this.decimalCalculator = getDocumentCalculator(invoice.currency);
     }
     
     // Document level rules (BR-01 to BR-65)
     this.validateDocumentRules(invoice);
     
-    // Calculation rules (BR-CO-*)
-    if (options.checkCalculations !== false) {
-      this.validateCalculationRules(invoice);
-    }
-    
-    // VAT rules (BR-S-*, BR-Z-*, BR-E-*, BR-AE-*, BR-IC-*, BR-G-*, BR-O-*)
-    if (options.checkVAT !== false) {
-      this.validateVATRules(invoice);
-    }
-    
-    // Line level rules (BR-21 to BR-30)
+    // Line level rules (BR-21 to BR-30), first: they report a line amount that is no number
     this.validateLineRules(invoice);
+
+    // The totals are computed from the line amounts; while one is no number they cannot be,
+    // so the rules that need them are skipped and the result says so
+    const invalidAmounts = findInvalidItemAmounts(invoice.items);
+    if (invalidAmounts.length > 0) {
+      if (options.checkCalculations !== false || options.checkVAT !== false) {
+        this.results.push(getTotalsSkippedResult(invalidAmounts, 'EN16931'));
+      }
+    } else {
+      // Calculation rules (BR-CO-*)
+      if (options.checkCalculations !== false) {
+        this.validateCalculationRules(invoice);
+      }
+      
+      // VAT rules (BR-S-*, BR-Z-*, BR-E-*, BR-AE-*, BR-IC-*, BR-G-*, BR-O-*)
+      if (options.checkVAT !== false) {
+        this.validateVATRules(invoice);
+      }
+    }
     
     // Allowances and charges rules
     if (options.checkAllowances !== false) {
@@ -292,18 +308,19 @@ export class EN16931BusinessRulesValidator {
     // BR-S-03: VAT category tax amount for standard rated
     vatGroups.forEach((group, rate) => {
       if (rate > 0) { // Standard rated
+        // the category amounts as EN 16931 computes them: the sum of the rounded line net
+        // amounts at the rate, and the tax on it rounded once (BR-S-08, BR-CO-17)
+        const documentGroup = useDecimal
+          ? computeDocumentTotals(invoice).vatGroups.find((groupArg) => groupArg.rate === rate)
+          : undefined;
         const expectedTaxableAmount = useDecimal
-          ? group.reduce((sum, item) => {
-              const unitPrice = new Decimal(item.unitNetPrice);
-              const quantity = new Decimal(item.unitQuantity);
-              return sum.add(unitPrice.multiply(quantity));
-            }, Decimal.ZERO)
+          ? documentGroup?.taxableAmount ?? Decimal.ZERO
           : group.reduce((sum, item) => 
               sum + (item.unitNetPrice * item.unitQuantity), 0
             );
         
         const expectedTaxAmount = useDecimal
-          ? this.decimalCalculator!.calculateVAT(expectedTaxableAmount, new Decimal(rate))
+          ? documentGroup?.taxAmount ?? Decimal.ZERO
           : (expectedTaxableAmount as number) * (rate / 100);
         
         // Find corresponding breakdown
@@ -408,9 +425,10 @@ export class EN16931BusinessRulesValidator {
         );
       }
       
-      // BR-24: Each Invoice line shall have an Invoice line net amount
-      const lineNetAmount = item.unitNetPrice * item.unitQuantity;
-      if (isNaN(lineNetAmount)) {
+      // BR-24: Each Invoice line shall have an Invoice line net amount; it is quantity × net
+      // price, so a quantity or net price that is no number leaves the line without one
+      const isAmount = (value: unknown) => typeof value === 'number' && Number.isFinite(value);
+      if (!isAmount(item.unitNetPrice) || !isAmount(item.unitQuantity)) {
         this.addError(
           'BR-24',
           `Invoice line ${index + 1} must have a valid net amount`,
@@ -418,8 +436,9 @@ export class EN16931BusinessRulesValidator {
         );
       }
       
-      // BR-CO-04: Each Invoice line shall be categorized with an Invoiced item VAT category code
-      if (item.vatPercentage === undefined) {
+      // BR-CO-04: Each Invoice line shall be categorized with an Invoiced item VAT category code;
+      // the envelope derives the category from the rate, which has to be a number
+      if (!isAmount(item.vatPercentage)) {
         this.addError(
           'BR-CO-04',
           `Invoice line ${index + 1} must have a VAT category code`,
@@ -579,34 +598,8 @@ export class EN16931BusinessRulesValidator {
    * Calculate total VAT using decimal arithmetic
    */
   private calculateTotalVATDecimal(invoice: EInvoice): Decimal {
-    let totalVAT = Decimal.ZERO;
-    
-    // Group items by VAT rate
-    const vatGroups = new Map<string, Decimal>();
-    
-    for (const item of invoice.items || []) {
-      const vatRate = item.vatPercentage || 0;
-      const rateKey = vatRate.toString();
-      
-      const unitPrice = new Decimal(item.unitNetPrice || 0);
-      const quantity = new Decimal(item.unitQuantity || 0);
-      const lineNet = unitPrice.multiply(quantity);
-      
-      if (vatGroups.has(rateKey)) {
-        vatGroups.set(rateKey, vatGroups.get(rateKey)!.add(lineNet));
-      } else {
-        vatGroups.set(rateKey, lineNet);
-      }
-    }
-    
-    // Calculate VAT for each group
-    for (const [rateKey, baseAmount] of vatGroups) {
-      const rate = new Decimal(rateKey);
-      const vat = this.decimalCalculator!.calculateVAT(baseAmount, rate);
-      totalVAT = totalVAT.add(vat);
-    }
-    
-    return totalVAT;
+    // the sum of the VAT category tax amounts, each rounded once (BR-CO-14, BR-CO-17)
+    return computeDocumentTotals(invoice).taxTotal;
   }
   
   private calculateDocumentAllowances(invoice: EInvoice): number {

package/ts/formats/validation/facturx.validator.ts

@@ -3,6 +3,7 @@
  * Implements validation for MINIMUM, BASIC, EN16931, and EXTENDED profiles
  */
 
+import { findInvalidItemAmounts, getTotalsSkippedResult } from '../utils/document.totals.js';
 import type { ValidationResult } from './validation.types.js';
 import type { EInvoice } from '../../einvoice.js';
 
@@ -211,9 +212,19 @@ export class FacturXValidator {
       return results;
     }
     
+    // The totals are computed from the line amounts; while one is no number the checks on
+    // totals are skipped and the result says so
+    const invalidAmounts = findInvalidItemAmounts(invoice.items);
+    const totalsComputable = invalidAmounts.length === 0;
+    if (!totalsComputable) {
+      results.push(getTotalsSkippedResult(invalidAmounts, 'FACTURX'));
+    }
+
     // Validate according to profile
-    results.push(...this.validateProfileRequirements(invoice, detectedProfile));
-    results.push(...this.validateProfileSpecificRules(invoice, detectedProfile));
+    results.push(...this.validateProfileRequirements(invoice, detectedProfile, totalsComputable));
+    if (totalsComputable) {
+      results.push(...this.validateProfileSpecificRules(invoice, detectedProfile));
+    }
     
     // Add profile-specific business rules
     if (detectedProfile === FacturXProfile.MINIMUM) {
@@ -267,12 +278,16 @@ export class FacturXValidator {
   /**
    * Validate field requirements for a specific profile
    */
-  private validateProfileRequirements(invoice: EInvoice, profile: FacturXProfile): ValidationResult[] {
+  private validateProfileRequirements(invoice: EInvoice, profile: FacturXProfile, totalsComputable = true): ValidationResult[] {
     const results: ValidationResult[] = [];
     const requirements = this.profileRequirements[profile];
+    const totalFields = ['totalInvoiceAmount', 'totalNetAmount', 'totalVatAmount'];
     
-    // Check mandatory fields
+    // Check mandatory fields; the totals only when they can be computed
     for (const field of requirements.mandatory) {
+      if (!totalsComputable && totalFields.includes(field)) {
+        continue;
+      }
       const value = this.getFieldValue(invoice, field);
       if (value === undefined || value === null || value === '') {
         results.push({

package/ts/formats/validation/vat-categories.validator.ts

@@ -1,4 +1,5 @@
 import * as plugins from '../../plugins.js';
+import { findInvalidItemAmounts, getTotalsSkippedResult } from '../utils/document.totals.js';
 import type { TAccountingDocItem } from '@tsclass/tsclass/dist_ts/finance/index.js';
 import type { EInvoice } from '../../einvoice.js';
 import { CurrencyCalculator } from '../utils/currency.utils.js';
@@ -50,6 +51,14 @@ export class VATCategoriesValidator {
       this.currencyCalculator = new CurrencyCalculator(invoice.currency);
     }
     
+    // The VAT breakdown is computed from the line amounts; while one is no number it cannot
+    // be, so these rules are skipped and the result says so (the line rules report the lines)
+    const invalidAmounts = findInvalidItemAmounts(invoice.items);
+    if (invalidAmounts.length > 0) {
+      this.results.push(getTotalsSkippedResult(invalidAmounts, 'EN16931'));
+      return this.results;
+    }
+
     // Group items by VAT category
     const itemsByCategory = this.groupItemsByVATCategory(invoice.items || []);
     const breakdownsByCategory = this.groupBreakdownsByCategory(invoice.taxBreakdown || []);