@fin.cx/einvoice 8.3.0 → 9.0.0

package/ts/formats/semantic/semantic.validator.ts

@@ -3,7 +3,8 @@
  * Validates invoices against EN16931 Business Terms and Business Groups
  */
 
-import { findInvalidItemAmounts, getTotalsSkippedResult } from '../utils/document.totals.js';
+import { computeDocumentTotals, findInvalidItemAmounts, getTotalsSkippedResult } from '../utils/document.totals.js';
+import { findPaymentProblem } from '../utils/paid.amount.js';
 import type { ValidationResult } from '../validation/validation.types.js';
 import type { EN16931SemanticModel, BusinessTerms, BusinessGroups } from './bt-bg.model.js';
 import type { EInvoice } from '../../einvoice.js';
@@ -57,6 +58,21 @@ export class SemanticModelValidator {
       return results;
     }
     
+    // The amount due (BT-115) follows from the paid amount; a paid amount that cannot be written
+    // (more decimals than the currency has, or advance payments that do not add up to it) is
+    // reported and the model rules are skipped, as for a line amount that is no number
+    const paymentProblem = findPaymentProblem(invoice, computeDocumentTotals(invoice));
+    if (paymentProblem) {
+      results.push({
+        ruleId: paymentProblem.ruleId,
+        source: 'SEMANTIC',
+        severity: 'error',
+        message: paymentProblem.message,
+        field: paymentProblem.field,
+      });
+      return results;
+    }
+
     // Convert to semantic model
     const model = this.adapter.toSemanticModel(invoice);
     

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

@@ -7,7 +7,9 @@ import { getPrecedingInvoiceReferences } from '../../utils/preceding.invoice.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';
 
 /**
  * UBL Encoder implementation
@@ -253,17 +255,18 @@ export class UBLEncoder extends UBLBaseEncoder {
       this.appendElement(doc, postalAddressNode, 'cbc:PostalZone', party.address.postalCode);
     }
     
-    // Country
-    if (party.address.country || party.address.countryCode) {
-      const countryNode = doc.createElement('cac:Country');
-      postalAddressNode.appendChild(countryNode);
-      
-      const countryCode = party.address.countryCode || this.getCountryCode(party.address.country);
-      this.appendElement(doc, countryNode, 'cbc:IdentificationCode', countryCode);
-      
-      if (party.address.country) {
-        this.appendElement(doc, countryNode, 'cbc:Name', party.address.country);
-      }
+    // Country code (BT-40, BT-55), mandatory (BR-09, BR-11): an ISO 3166-1 alpha-2 code, never
+    // derived from a name (BR-CL-14)
+    const countryNode = doc.createElement('cac:Country');
+    postalAddressNode.appendChild(countryNode);
+    this.appendElement(
+      doc,
+      countryNode,
+      'cbc:IdentificationCode',
+      resolveCountryCode(party.address, elementName === 'cac:AccountingSupplierParty' ? 'seller' : 'buyer', 'ubl'),
+    );
+    if (party.address.country) {
+      this.appendElement(doc, countryNode, 'cbc:Name', party.address.country);
     }
     
     // Party tax scheme (VAT ID)
@@ -479,10 +482,19 @@ export class UBLEncoder extends UBLBaseEncoder {
     taxInclusiveAmountElement.textContent = amount(totals.grandTotal);
     legalMonetaryTotalNode.appendChild(taxInclusiveAmountElement);
     
-    // Payable amount
+    // Paid amount (BT-113), before the payable amount in the schema order
+    const payment = getPaymentTotals(invoice, totals);
+    if (payment.paidAmount) {
+      const prepaidAmountElement = doc.createElement('cbc:PrepaidAmount');
+      prepaidAmountElement.setAttribute('currencyID', invoice.currency);
+      prepaidAmountElement.textContent = amount(payment.paidAmount);
+      legalMonetaryTotalNode.appendChild(prepaidAmountElement);
+    }
+
+    // Payable amount (BT-115)
     const payableAmountElement = doc.createElement('cbc:PayableAmount');
     payableAmountElement.setAttribute('currencyID', invoice.currency);
-    payableAmountElement.textContent = amount(totals.duePayable);
+    payableAmountElement.textContent = amount(payment.duePayable);
     legalMonetaryTotalNode.appendChild(payableAmountElement);
   }
   
@@ -576,19 +588,6 @@ export class UBLEncoder extends UBLBaseEncoder {
     parentElement.appendChild(element);
   }
   
-  /**
-   * Helper method to get country code from country name
-   * Simple implementation that assumes the country name is already a code
-   * @param countryName Country name
-   * @returns Country code (2-letter ISO code)
-   */
-  private getCountryCode(countryName: string): string {
-    // In a real implementation, this would map country names to ISO codes
-    // For now, just return the first 2 characters or "XX" as fallback
-    if (!countryName) return 'XX';
-    return countryName.length >= 2 ? countryName.substring(0, 2).toUpperCase() : 'XX';
-  }
-
   /**
    * Preserves metadata from invoice to enhance UBL XML output
    * @param doc XML document

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 { computeDocumentTotals } from '../utils/document.totals.js';
+import { getPaymentTotals } from '../utils/paid.amount.js';
 
 /**
  * The children of the document root in the order the UBL 2.1 schema requires
@@ -51,6 +53,8 @@ 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 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);

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

@@ -12,6 +12,7 @@ import {
   getPrecedingInvoiceFields,
   type TPrecedingInvoiceReference,
 } from '../../utils/preceding.invoice.js';
+import { readPaidAmount } from '../../utils/paid.amount.js';
 
 /**
  * Decoder for XRechnung (UBL) format
@@ -240,6 +241,9 @@ export class XRechnungDecoder extends UBLBaseDecoder {
       const hasPaymentInformation = Object.values(paymentInformation).some(value => Boolean(value));
       const hasDateInformation = Object.values(dateInformation).some(value => Boolean(value));
 
+      // the paid amount (BT-113); the amount due (BT-115) follows from it and the totals
+      const paidAmount = readPaidAmount(this.getText('/*/cac:LegalMonetaryTotal/cbc:PrepaidAmount'), 'ubl');
+
       // Create the common invoice data with metadata only when the source XML actually contains it.
       const invoiceData: any = {
         type: 'accounting-doc' as const,
@@ -278,6 +282,7 @@ export class XRechnungDecoder extends UBLBaseDecoder {
             }
           : {}),
         ...getPrecedingInvoiceFields(accountingDocType, this.extractPrecedingInvoiceReferences()),
+        ...(paidAmount === undefined ? {} : { paidAmount }),
       };
 
       if (hasBusinessReferences || hasPaymentInformation || hasDateInformation) {

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

@@ -89,9 +89,6 @@ export class XRechnungEncoder extends UBLEncoder {
       }
     }
     
-    // Add country code handling for German addresses
-    this.fixGermanCountryCodes(doc);
-    
     // Preserve business references from metadata
     this.addBusinessReferences(doc, metadata?.businessReferences);
     
@@ -207,26 +204,6 @@ export class XRechnungEncoder extends UBLEncoder {
     }
   }
   
-  /**
-   * Fixes German country codes in the document
-   * @param doc XML document
-   */
-  private fixGermanCountryCodes(doc: Document): void {
-    const countryNodes = doc.getElementsByTagName('cbc:IdentificationCode');
-    for (let i = 0; i < countryNodes.length; i++) {
-      const node = countryNodes[i];
-      if (node.textContent) {
-        const text = node.textContent.toLowerCase();
-        if (text === 'germany' || text === 'deutschland' || text === 'de') {
-          node.textContent = 'DE';
-        } else if (text.length > 2) {
-          // Try to use first 2 characters as country code
-          node.textContent = text.substring(0, 2).toUpperCase();
-        }
-      }
-    }
-  }
-
   /**
    * Adds business references from metadata to the document
    * @param doc XML document

package/ts/formats/utils/country.code.ts

@@ -0,0 +1,53 @@
+import type { business } from '@tsclass/tsclass';
+import { EInvoiceFormatError } from '../../errors.js';
+import { CodeLists } from '../validation/validation.types.js';
+
+/** The party whose address a country code is written for */
+export type TCountryCodeParty = 'seller' | 'buyer';
+
+const partyFields: Record<TCountryCodeParty, { path: string; term: string; presenceRule: string }> = {
+  // BR-09: the seller postal address (BG-5) states the seller country code (BT-40)
+  seller: { path: 'from.address', term: 'BT-40', presenceRule: 'BR-09' },
+  // BR-11: the buyer postal address (BG-8) states the buyer country code (BT-55)
+  buyer: { path: 'to.address', term: 'BT-55', presenceRule: 'BR-11' },
+};
+
+/**
+ * The country code an encoder writes for a party's address: an ISO 3166-1
+ * alpha-2 code EN 16931 accepts (BR-CL-14, `CodeLists.ISO3166`), taken from
+ * `countryCode`, or from `country` when that is already such a code; letter
+ * case does not matter. A code is never derived from a country name, so a
+ * name, an unknown code or a missing country is refused with an
+ * `EInvoiceFormatError` naming the field and the business term.
+ * @param address The party's address
+ * @param party Whether it is the seller's or the buyer's
+ * @param targetFormat The format being written
+ */
+export const resolveCountryCode = (
+  address: Partial<business.IAddress> | undefined,
+  party: TCountryCodeParty,
+  targetFormat: string,
+): string => {
+  const { path, term, presenceRule } = partyFields[party];
+  const refuse = (rule: string, message: string): never => {
+    throw new EInvoiceFormatError(`${rule}: ${message}`, { targetFormat, unsupportedFeatures: [rule] });
+  };
+  const countryCode = (address?.countryCode ?? '').trim();
+  if (countryCode) {
+    if (!CodeLists.ISO3166.codes.has(countryCode.toUpperCase())) {
+      refuse('BR-CL-14', `the ${party} country code (${term}) is an ISO 3166-1 alpha-2 code, ${path}.countryCode is "${countryCode}"`);
+    }
+    return countryCode.toUpperCase();
+  }
+  const country = (address?.country ?? '').trim();
+  if (!country) {
+    refuse(presenceRule, `the ${party} postal address states a country code (${term}), ${path}.countryCode and ${path}.country are missing`);
+  }
+  if (!CodeLists.ISO3166.codes.has(country.toUpperCase())) {
+    refuse(
+      'BR-CL-14',
+      `the ${party} country code (${term}) is an ISO 3166-1 alpha-2 code, ${path}.countryCode is missing and ${path}.country is "${country}", which is not one; a code is not derived from a country name`,
+    );
+  }
+  return country.toUpperCase();
+};

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

@@ -96,10 +96,8 @@ export interface IDocumentTotals {
   vatGroups: IDocumentVatGroup[];
   /** Invoice total VAT amount (BT-110): the sum of the rounded VAT category tax amounts */
   taxTotal: Decimal;
-  /** Invoice total amount with VAT (BT-112): BT-109 + BT-110 */
+  /** Invoice total amount with VAT (BT-112): BT-109 + BT-110; the paid amount and the amount due are `getPaymentTotals` */
   grandTotal: Decimal;
-  /** Amount due for payment (BT-115): BT-112, as the envelope states no paid amount yet */
-  duePayable: Decimal;
 }
 
 /**
@@ -168,6 +166,5 @@ export const computeDocumentTotals = (
     vatGroups,
     taxTotal,
     grandTotal,
-    duePayable: grandTotal,
   };
 };

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

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

package/ts/formats/utils/preceding.invoice.ts

@@ -16,7 +16,13 @@ export type TPrecedingInvoiceReference = TCorrectedInvoiceReference;
  * taken only from what the document states:
  * - a corrected invoice: the invoice it corrects (`correctedInvoice`);
  * - a corrected invoice or a credit note: every related document with the
- *   relation `'corrects'`.
+ *   relation `'corrects'`;
+ * - a document that can be a final invoice (an invoice, a corrected invoice or
+ *   a self-billed invoice): the advance invoice of every advance payment that
+ *   states one (`advancePayments[].invoice`), after the references above. The
+ *   amounts are the paid amount (BT-113); the deduction per rate that § 14
+ *   Abs. 5 Satz 2 UStG asks of a final invoice has no element in EN 16931
+ *   (BMF letter of 15 October 2024, Rn. 48).
  * Other documents and other relations write none.
  */
 export const getPrecedingInvoiceReferences = (
@@ -40,6 +46,17 @@ export const getPrecedingInvoiceReferences = (
       }
     }
   }
+  if ('advancePayments' in accountingDoc) {
+    for (const advancePayment of accountingDoc.advancePayments ?? []) {
+      if (advancePayment.invoice) {
+        references.push(
+          advancePayment.invoice.issueDate === undefined
+            ? { documentId: advancePayment.invoice.documentId }
+            : { documentId: advancePayment.invoice.documentId, issueDate: advancePayment.invoice.issueDate },
+        );
+      }
+    }
+  }
   return references;
 };
 
@@ -48,7 +65,11 @@ export const getPrecedingInvoiceReferences = (
  * inverse of {@link getPrecedingInvoiceReferences}: on a corrected invoice the
  * first reference is the invoice it corrects and further ones are related
  * documents it corrects; on a credit note every reference is a related
- * document it corrects. Other documents keep no reference, as before.
+ * document it corrects. Other documents keep no reference, as before. The
+ * XML does not tell an advance invoice from a corrected one, so a corrected
+ * invoice's advance invoices read back as related documents it corrects, and
+ * an invoice's advance invoices are not read: `advancePayments` needs the net
+ * and the tax per rate of every payment, which the XML does not carry.
  */
 export const getPrecedingInvoiceFields = (
   accountingDocType: TAccountingDocType,

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

@@ -96,7 +96,7 @@ export class CodeListValidator {
     const buyerCountry = invoice.to?.address?.countryCode;
     if (buyerCountry && !CodeLists.ISO3166.codes.has(buyerCountry.toUpperCase())) {
       this.addError(
-        'BR-CL-15',
+        'BR-CL-14',
         `Invalid buyer country code: ${buyerCountry}. Must be ISO 3166-1 alpha-2`,
         'EN16931',
         'to.address.countryCode',
@@ -110,7 +110,7 @@ export class CodeListValidator {
     const deliveryCountry = invoice.metadata?.deliveryAddress?.countryCode;
     if (deliveryCountry && !CodeLists.ISO3166.codes.has(deliveryCountry.toUpperCase())) {
       this.addError(
-        'BR-CL-16',
+        'BR-CL-14',
         `Invalid delivery country code: ${deliveryCountry}. Must be ISO 3166-1 alpha-2`,
         'EN16931',
         'metadata.deliveryAddress.countryCode',

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

@@ -247,31 +247,33 @@ export class EN16931BusinessRulesValidator {
       );
     }
     
-    // BR-CO-16: Amount due for payment = Invoice total with VAT - Paid amount
-    const paidAmount = useDecimal
-      ? new Decimal(invoice.metadata?.paidAmount || 0)
-      : invoice.metadata?.paidAmount || 0;
-    const expectedDueAmount = useDecimal
-      ? (expectedGrossTotal as Decimal).subtract(paidAmount)
-      : (expectedGrossTotal as number) - (paidAmount as number);
-    const declaredDueAmount = useDecimal
-      ? new Decimal(invoice.metadata?.amountDue || (useDecimal ? (expectedGrossTotal as Decimal).toNumber() : expectedGrossTotal))
-      : invoice.metadata?.amountDue || expectedGrossTotal;
-    
-    const isDueEqual = useDecimal
-      ? this.decimalCalculator!.areEqual(expectedDueAmount, declaredDueAmount)
-      : this.currencyCalculator
-        ? this.currencyCalculator.areEqual(expectedDueAmount as number, declaredDueAmount as number)
-        : Math.abs((expectedDueAmount as number) - (declaredDueAmount as number)) < 0.01;
-    
-    if (!isDueEqual) {
-      this.addError(
-        'BR-CO-16',
-        `Amount due (${useDecimal ? (declaredDueAmount as Decimal).toFixed(2) : (declaredDueAmount as number).toFixed(2)}) does not match calculation (${useDecimal ? (expectedDueAmount as Decimal).toFixed(2) : (expectedDueAmount as number).toFixed(2)})`,
-        'amountDue',
-        useDecimal ? (declaredDueAmount as Decimal).toNumber() : declaredDueAmount as number,
-        useDecimal ? (expectedDueAmount as Decimal).toNumber() : expectedDueAmount as number
-      );
+    // BR-CO-16: Amount due for payment = Invoice total with VAT - Paid amount. The envelope's
+    // paid amount (BT-113) is the one the encoders write; the amount due (BT-115) is compared when
+    // a declared one is at hand (`metadata.amountDue`), since the envelope derives it otherwise
+    const paidAmountValue = invoice.paidAmount ?? 0;
+    const declaredDueValue = invoice.metadata?.amountDue;
+    if (declaredDueValue !== undefined) {
+      const paidAmount = useDecimal ? new Decimal(paidAmountValue) : paidAmountValue;
+      const expectedDueAmount = useDecimal
+        ? (expectedGrossTotal as Decimal).subtract(paidAmount)
+        : (expectedGrossTotal as number) - (paidAmount as number);
+      const declaredDueAmount = useDecimal ? new Decimal(declaredDueValue) : declaredDueValue;
+
+      const isDueEqual = useDecimal
+        ? this.decimalCalculator!.areEqual(expectedDueAmount, declaredDueAmount)
+        : this.currencyCalculator
+          ? this.currencyCalculator.areEqual(expectedDueAmount as number, declaredDueAmount as number)
+          : Math.abs((expectedDueAmount as number) - (declaredDueAmount as number)) < 0.01;
+
+      if (!isDueEqual) {
+        this.addError(
+          'BR-CO-16',
+          `Amount due (${useDecimal ? (declaredDueAmount as Decimal).toFixed(2) : (declaredDueAmount as number).toFixed(2)}) does not match calculation (${useDecimal ? (expectedDueAmount as Decimal).toFixed(2) : (expectedDueAmount as number).toFixed(2)})`,
+          'amountDue',
+          useDecimal ? (declaredDueAmount as Decimal).toNumber() : declaredDueAmount as number,
+          useDecimal ? (expectedDueAmount as Decimal).toNumber() : expectedDueAmount as number
+        );
+      }
     }
   }
   

package/ts/formats/validation/validation.types.ts

@@ -96,13 +96,30 @@ export const CodeLists = {
     ])
   },
   
-  // ISO 3166-1 alpha-2 Country codes
+  // ISO 3166-1 alpha-2 country codes, as EN 16931 accepts them (BR-CL-14, BR-CL-15): the code list
+  // of the CEN/TC 434 validation artefacts 1.3.16 for UBL, which adds 1A (Kosovo) and XI (Northern
+  // Ireland) to the codes ISO 3166-1 assigns
   ISO3166: {
-    version: '2020',
+    version: 'EN 16931 validation artefacts 1.3.16',
     codes: new Set([
-      'DE', 'FR', 'IT', 'ES', 'NL', 'BE', 'AT', 'CH', 'GB', 'IE', 'PT', 'GR',
-      'SE', 'NO', 'DK', 'FI', 'PL', 'CZ', 'HU', 'RO', 'BG', 'HR', 'SI', 'SK',
-      'LT', 'LV', 'EE', 'LU', 'MT', 'CY', 'US', 'CA', 'AU', 'NZ', 'JP', 'CN'
+      '1A', 'AD', 'AE', 'AF', 'AG', 'AI', 'AL', 'AM', 'AO', 'AQ', 'AR', 'AS', 'AT', 'AU',
+      'AW', 'AX', 'AZ', 'BA', 'BB', 'BD', 'BE', 'BF', 'BG', 'BH', 'BI', 'BJ', 'BL', 'BM',
+      'BN', 'BO', 'BQ', 'BR', 'BS', 'BT', 'BV', 'BW', 'BY', 'BZ', 'CA', 'CC', 'CD', 'CF',
+      'CG', 'CH', 'CI', 'CK', 'CL', 'CM', 'CN', 'CO', 'CR', 'CU', 'CV', 'CW', 'CX', 'CY',
+      'CZ', 'DE', 'DJ', 'DK', 'DM', 'DO', 'DZ', 'EC', 'EE', 'EG', 'EH', 'ER', 'ES', 'ET',
+      'FI', 'FJ', 'FK', 'FM', 'FO', 'FR', 'GA', 'GB', 'GD', 'GE', 'GF', 'GG', 'GH', 'GI',
+      'GL', 'GM', 'GN', 'GP', 'GQ', 'GR', 'GS', 'GT', 'GU', 'GW', 'GY', 'HK', 'HM', 'HN',
+      'HR', 'HT', 'HU', 'ID', 'IE', 'IL', 'IM', 'IN', 'IO', 'IQ', 'IR', 'IS', 'IT', 'JE',
+      'JM', 'JO', 'JP', 'KE', 'KG', 'KH', 'KI', 'KM', 'KN', 'KP', 'KR', 'KW', 'KY', 'KZ',
+      'LA', 'LB', 'LC', 'LI', 'LK', 'LR', 'LS', 'LT', 'LU', 'LV', 'LY', 'MA', 'MC', 'MD',
+      'ME', 'MF', 'MG', 'MH', 'MK', 'ML', 'MM', 'MN', 'MO', 'MP', 'MQ', 'MR', 'MS', 'MT',
+      'MU', 'MV', 'MW', 'MX', 'MY', 'MZ', 'NA', 'NC', 'NE', 'NF', 'NG', 'NI', 'NL', 'NO',
+      'NP', 'NR', 'NU', 'NZ', 'OM', 'PA', 'PE', 'PF', 'PG', 'PH', 'PK', 'PL', 'PM', 'PN',
+      'PR', 'PS', 'PT', 'PW', 'PY', 'QA', 'RE', 'RO', 'RS', 'RU', 'RW', 'SA', 'SB', 'SC',
+      'SD', 'SE', 'SG', 'SH', 'SI', 'SJ', 'SK', 'SL', 'SM', 'SN', 'SO', 'SR', 'SS', 'ST',
+      'SV', 'SX', 'SY', 'SZ', 'TC', 'TD', 'TF', 'TG', 'TH', 'TJ', 'TK', 'TL', 'TM', 'TN',
+      'TO', 'TR', 'TT', 'TV', 'TW', 'TZ', 'UA', 'UG', 'UM', 'US', 'UY', 'UZ', 'VA', 'VC',
+      'VE', 'VG', 'VI', 'VN', 'VU', 'WF', 'WS', 'XI', 'YE', 'YT', 'ZA', 'ZM', 'ZW',
     ])
   },
   

package/ts/interfaces/common.ts

@@ -93,6 +93,7 @@ export type { TCorrectedInvoice } from '@tsclass/tsclass/dist_ts/finance/index.j
 export type { TCorrectedInvoiceReference } from '@tsclass/tsclass/dist_ts/finance/index.js';
 export type { TInvoiceCorrection } from '@tsclass/tsclass/dist_ts/finance/index.js';
 export type { TRelatedDocument } from '@tsclass/tsclass/dist_ts/finance/index.js';
+export type { TAdvancePayment } from '@tsclass/tsclass/dist_ts/finance/index.js';
 export type { TCreditNote } from '@tsclass/tsclass/dist_ts/finance/index.js';
 export type { TDebitNote } from '@tsclass/tsclass/dist_ts/finance/index.js';
 export type { TSelfBilledInvoice } from '@tsclass/tsclass/dist_ts/finance/index.js';

package/ts/interfaces/en16931-metadata.ts

@@ -20,7 +20,6 @@ export interface IEInvoiceMetadata {
   vatAccountingCurrency?: string;                // BT-6
   documentTypeCode?: string;                     // BT-3
   paymentMeansCode?: string;                     // BT-81
-  paidAmount?: number;                          // BT-113
   amountDue?: number;                           // BT-115
   
   // Tax identifiers