@fin.cx/einvoice 8.3.1 → 10.0.0

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/utils/seller.identifier.ts

@@ -0,0 +1,102 @@
+import type { TAccountingDoc } from '../../interfaces/common.js';
+import { EInvoiceFormatError } from '../../errors.js';
+import { DOMParser, xpath } from '../../plugins.js';
+import { CII_NAMESPACES } from '../cii/cii.types.js';
+import { UBL_NAMESPACES } from '../ubl/ubl.types.js';
+import { getPartyIdentifiers } from './party.identifier.js';
+
+/**
+ * The official text of EN 16931 BR-CO-26 (CEN/TC 434 EN 16931 validation
+ * artefacts 1.3.16, fatal in UBL and CII)
+ */
+export const BR_CO_26_TEXT =
+  'In order for the buyer to automatically identify a supplier, the Seller identifier (BT-29), the Seller legal registration identifier (BT-30) and/or the Seller VAT identifier (BT-31) shall be present.';
+
+const ublSelect = xpath.useNamespaces({ cac: UBL_NAMESPACES.CAC, cbc: UBL_NAMESPACES.CBC });
+const ciiSelect = xpath.useNamespaces({ rsm: CII_NAMESPACES.RSM, ram: CII_NAMESPACES.RAM });
+const nodesOf = (result: xpath.SelectReturnType): Node[] => (Array.isArray(result) ? result : []);
+
+/**
+ * Whether the seller of a UBL document meets BR-CO-26, as the CEN artefacts
+ * check it on `cac:AccountingSupplierParty`: a VAT identifier (BT-31, a
+ * `cac:PartyTaxScheme` with the scheme VAT), a seller identifier (BT-29, a
+ * `cac:PartyIdentification` whose scheme is not SEPA) or a legal registration
+ * identifier (BT-30, `cac:PartyLegalEntity/cbc:CompanyID`). A document without
+ * a seller party is not checked; BR-06 and BR-08 report that.
+ * @param doc The UBL document
+ */
+export const ublSellerMeetsBrCo26 = (doc: Document): boolean => {
+  const sellers = nodesOf(ublSelect('/*/cac:AccountingSupplierParty', doc));
+  return sellers.every((seller) => {
+    const vatSchemes = nodesOf(ublSelect('./cac:Party/cac:PartyTaxScheme/cac:TaxScheme/cbc:ID', seller)).filter(
+      (node) => (node.textContent ?? '').trim().toUpperCase() === 'VAT',
+    );
+    const hasVatIdentifier = vatSchemes.some(
+      (scheme) => nodesOf(ublSelect('../../cbc:CompanyID', scheme)).length > 0,
+    );
+    const hasSellerIdentifier = nodesOf(ublSelect("./cac:Party/cac:PartyIdentification/cbc:ID[not(@schemeID = 'SEPA')]", seller)).length > 0;
+    const hasLegalRegistration = nodesOf(ublSelect('./cac:Party/cac:PartyLegalEntity/cbc:CompanyID', seller)).length > 0;
+    return hasVatIdentifier || hasSellerIdentifier || hasLegalRegistration;
+  });
+};
+
+/**
+ * Whether the seller of a CII document meets BR-CO-26, as the CEN artefacts
+ * check it on `ram:SellerTradeParty`: a seller identifier (BT-29, `ram:ID` or
+ * `ram:GlobalID`), a legal registration identifier (BT-30,
+ * `ram:SpecifiedLegalOrganization/ram:ID`) or a VAT identifier (BT-31,
+ * `ram:SpecifiedTaxRegistration/ram:ID` with the scheme VA).
+ * @param doc The CII document
+ */
+export const ciiSellerMeetsBrCo26 = (doc: Document): boolean =>
+  nodesOf(ciiSelect('//ram:SellerTradeParty', doc)).every(
+    (seller) =>
+      nodesOf(
+        ciiSelect(
+          "./ram:ID | ./ram:GlobalID | ./ram:SpecifiedLegalOrganization/ram:ID | ./ram:SpecifiedTaxRegistration/ram:ID[@schemeID='VA']",
+          seller,
+        ),
+      ).length > 0,
+  );
+
+/**
+ * Whether the seller of an envelope states an identifier BR-CO-26 accepts:
+ * the VAT identifier (BT-31, `registrationDetails.vatId`), the legal
+ * registration identifier (BT-30, `registrationDetails.registrationId`) or a
+ * seller identifier (BT-29), which a decoded UBL document keeps in the
+ * party's `additionalIdentifiers`. A tax number (BT-32) is none of them.
+ * @param accountingDoc The document
+ */
+export const envelopeSellerMeetsBrCo26 = (accountingDoc: Pick<TAccountingDoc, 'from'>): boolean => {
+  const seller = accountingDoc.from;
+  if (!seller) {
+    return true;
+  }
+  const details = seller.registrationDetails;
+  const hasSellerIdentifier = getPartyIdentifiers(seller).some((identifier) => identifier.scheme?.toUpperCase() !== 'SEPA');
+  return Boolean(details?.vatId?.trim() || details?.registrationId?.trim() || hasSellerIdentifier);
+};
+
+const writtenParser = new DOMParser();
+
+/**
+ * Refuses a written document whose seller fails BR-CO-26, naming the rule; no
+ * identifier is put in place of a missing one. The seller states its VAT
+ * identifier (`registrationDetails.vatId`, BT-31) or its legal registration
+ * identifier (`registrationDetails.registrationId`, BT-30); a tax number
+ * (BT-32) alone does not identify it. A seller identifier (BT-29) is written
+ * from the party's `additionalIdentifiers` (no typed field in the envelope).
+ * @param xml The written document
+ * @param syntax The syntax it is written in
+ * @param targetFormat The format being written
+ */
+export const assertSellerIdentified = (xml: string, syntax: 'ubl' | 'cii', targetFormat: string): void => {
+  const doc = writtenParser.parseFromString(xml, 'application/xml');
+  const meets = syntax === 'ubl' ? ublSellerMeetsBrCo26(doc) : ciiSellerMeetsBrCo26(doc);
+  if (!meets) {
+    throw new EInvoiceFormatError(
+      `BR-CO-26: ${BR_CO_26_TEXT} The seller states none of them: set from.registrationDetails.vatId (BT-31) or .registrationId (BT-30), or give the seller a seller identifier (BT-29) in from.additionalIdentifiers, where a decoded document keeps it; a tax number (BT-32, .taxNumber) does not identify the seller`,
+      { targetFormat, unsupportedFeatures: ['BR-CO-26'] },
+    );
+  }
+};

package/ts/formats/utils/stated.values.ts

@@ -0,0 +1,499 @@
+import type {
+  IEInvoiceStatedValues,
+  IStatedAllowanceCharge,
+  IStatedDocumentTotals,
+  IStatedLine,
+  IStatedVatBreakdown,
+} from '../../interfaces/stated.values.js';
+import { xpath } from '../../plugins.js';
+import { CII_NAMESPACES } from '../cii/cii.types.js';
+import { UBL_NAMESPACES } from '../ubl/ubl.types.js';
+import { Decimal } from './decimal.js';
+import type { IDocumentTotals } from './document.totals.js';
+import { toPlainDecimalString } from './number.text.js';
+
+/** A stated value that is no decimal number, by business term and the text found */
+export interface IStatedValueProblem {
+  businessTerm: string;
+  text: string;
+}
+
+/** The EN 16931 names of the amounts read, for a message */
+const BUSINESS_TERM_NAMES: Record<string, string> = {
+  'BT-92': 'document level allowance amount',
+  'BT-93': 'document level allowance base amount',
+  'BT-94': 'document level allowance percentage',
+  'BT-96': 'document level allowance VAT rate',
+  'BT-99': 'document level charge amount',
+  'BT-100': 'document level charge base amount',
+  'BT-101': 'document level charge percentage',
+  'BT-103': 'document level charge VAT rate',
+  'BT-106': 'sum of invoice line net amount',
+  'BT-107': 'sum of allowances on document level',
+  'BT-108': 'sum of charges on document level',
+  'BT-109': 'invoice total amount without VAT',
+  'BT-110': 'invoice total VAT amount',
+  'BT-111': 'invoice total VAT amount in accounting currency',
+  'BT-112': 'invoice total amount with VAT',
+  'BT-113': 'paid amount',
+  'BT-114': 'rounding amount',
+  'BT-115': 'amount due for payment',
+  'BT-116': 'VAT category taxable amount',
+  'BT-117': 'VAT category tax amount',
+  'BT-119': 'VAT category rate',
+  'BT-131': 'invoice line net amount',
+  'BT-152': 'invoiced item VAT rate',
+};
+
+/**
+ * The message for a stated amount that is no decimal number, as the paid
+ * amount's has been: "The paid amount (BT-113) is no decimal number: …"
+ * @param problem The problem
+ */
+export const statedValueProblemMessage = (problem: IStatedValueProblem): string =>
+  `The ${BUSINESS_TERM_NAMES[problem.businessTerm] ?? 'amount'} (${problem.businessTerm}) is no decimal number: ${problem.text}`;
+
+/** The stated values of a document, and the stated amounts that are no number */
+export interface IStatedValuesRead {
+  values: IEInvoiceStatedValues;
+  problems: IStatedValueProblem[];
+  /** How many VAT totals (BT-110) in the document currency the document states; BR-CO-15 asks for exactly one */
+  documentCurrencyTaxTotals?: number;
+  /** Each `cac:TaxTotal` of a UBL document with its tax amount and the tax amounts of its own subtotals, which BR-CO-14 compares */
+  ublTaxTotals?: Array<{ taxAmount?: number; subtotalTaxAmounts: Array<number | undefined> }>;
+}
+
+/** A finding on stated values: the rule, its official text and where it applies */
+export interface IStatedValueFinding {
+  ruleId: string;
+  message: string;
+  location: string;
+}
+
+const nodesOf = (result: xpath.SelectReturnType): Node[] => (Array.isArray(result) ? result : []);
+
+/**
+ * Reads the stated values of one document, with an XPath selector for its
+ * syntax; an amount whose text is no decimal number is left undefined and
+ * listed as a problem
+ */
+class StatedValueReader {
+  public readonly problems: IStatedValueProblem[] = [];
+
+  constructor(private readonly select: xpath.XPathSelect, private readonly doc: Document) {}
+
+  public nodes(path: string, context: Node = this.doc): Node[] {
+    return nodesOf(this.select(path, context));
+  }
+
+  public text(path: string, context: Node = this.doc): string | undefined {
+    const [node] = this.nodes(path, context);
+    const text = node?.textContent?.trim();
+    return text ? text : undefined;
+  }
+
+  public amount(path: string, businessTerm: string, context: Node = this.doc): number | undefined {
+    const text = this.text(path, context);
+    if (text === undefined) {
+      return undefined;
+    }
+    const value = Number(text);
+    if (!/^[+-]?(\d+\.?\d*|\.\d+)$/.test(text) || !Number.isFinite(value)) {
+      this.problems.push({ businessTerm, text });
+      return undefined;
+    }
+    return value;
+  }
+}
+
+/** Whether an xs:boolean indicator states the value ('true' or '1', 'false' or '0') */
+const isIndicator = (text: string | undefined, value: boolean): boolean =>
+  value ? text === 'true' || text === '1' : text === 'false' || text === '0';
+
+/** Only the fields a document states, so that an absent one is undefined */
+const stated = <T extends object>(fields: T): T =>
+  Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined)) as T;
+
+const ublSelect = xpath.useNamespaces({ cac: UBL_NAMESPACES.CAC, cbc: UBL_NAMESPACES.CBC });
+
+/**
+ * Reads the stated values of a UBL invoice or credit note: the document totals
+ * (`cac:LegalMonetaryTotal`, BT-106 to BT-115, the VAT total `cac:TaxTotal/cbc:TaxAmount`
+ * in the document currency for BT-110 and in the VAT accounting currency for
+ * BT-111), the VAT breakdown (`cac:TaxSubtotal`, BT-116 to BT-121), the line
+ * amounts (BT-126, BT-131, BT-151, BT-152) and the document level allowances
+ * and charges (`cac:AllowanceCharge`, BT-92 to BT-105)
+ * @param doc The UBL document
+ */
+export const readUblStatedValues = (doc: Document): IStatedValuesRead => {
+  const read = new StatedValueReader(ublSelect, doc);
+  const total = '/*/cac:LegalMonetaryTotal';
+  const documentCurrency = read.text('/*/cbc:DocumentCurrencyCode');
+  const accountingCurrency = read.text('/*/cbc:TaxCurrencyCode');
+  const taxTotalIn = (currency: string | undefined, businessTerm: string): number | undefined =>
+    currency === undefined ? undefined : read.amount(`/*/cac:TaxTotal/cbc:TaxAmount[@currencyID = '${currency}']`, businessTerm);
+  const accountingTaxTotal = accountingCurrency && accountingCurrency !== documentCurrency ? taxTotalIn(accountingCurrency, 'BT-111') : undefined;
+  // BT-110 and the VAT breakdown (BG-23) are the VAT total in the document currency and its subtotals;
+  // a second total in the VAT accounting currency (BT-111) may state subtotals of its own
+  const documentTaxTotals = read
+    .nodes('/*/cac:TaxTotal')
+    .filter((taxTotal) => documentCurrency !== undefined && read.text(`./cbc:TaxAmount[@currencyID = '${documentCurrency}']`, taxTotal) !== undefined);
+  // a total without a currency, which the UBL schema does not allow, is read as the document's
+  const candidateTotals = documentTaxTotals.length > 0 ? documentTaxTotals : read.nodes('/*/cac:TaxTotal');
+  const [breakdownTotal] = candidateTotals.filter((taxTotal) => read.nodes('./cac:TaxSubtotal', taxTotal).length > 0);
+  const breakdownTaxTotal = breakdownTotal === undefined ? undefined : read.amount('./cbc:TaxAmount', 'BT-110', breakdownTotal);
+  const totals: IStatedDocumentTotals = stated({
+    lineTotal: read.amount(`${total}/cbc:LineExtensionAmount`, 'BT-106'),
+    allowanceTotal: read.amount(`${total}/cbc:AllowanceTotalAmount`, 'BT-107'),
+    chargeTotal: read.amount(`${total}/cbc:ChargeTotalAmount`, 'BT-108'),
+    taxExclusiveTotal: read.amount(`${total}/cbc:TaxExclusiveAmount`, 'BT-109'),
+    taxTotal: breakdownTaxTotal ?? taxTotalIn(documentCurrency, 'BT-110'),
+    taxTotalInAccountingCurrency:
+      accountingTaxTotal === undefined || accountingCurrency === undefined ? undefined : { amount: accountingTaxTotal, currency: accountingCurrency },
+    taxInclusiveTotal: read.amount(`${total}/cbc:TaxInclusiveAmount`, 'BT-112'),
+    paidAmount: read.amount(`${total}/cbc:PrepaidAmount`, 'BT-113'),
+    roundingAmount: read.amount(`${total}/cbc:PayableRoundingAmount`, 'BT-114'),
+    amountDue: read.amount(`${total}/cbc:PayableAmount`, 'BT-115'),
+  });
+  const vatBreakdown: IStatedVatBreakdown[] = (breakdownTotal === undefined ? [] : read.nodes('./cac:TaxSubtotal', breakdownTotal)).map((subtotal) =>
+    stated({
+      taxableAmount: read.amount('./cbc:TaxableAmount', 'BT-116', subtotal),
+      taxAmount: read.amount('./cbc:TaxAmount', 'BT-117', subtotal),
+      categoryCode: read.text('./cac:TaxCategory/cbc:ID', subtotal),
+      rate: read.amount('./cac:TaxCategory/cbc:Percent', 'BT-119', subtotal),
+      exemptionReason: read.text('./cac:TaxCategory/cbc:TaxExemptionReason', subtotal),
+      exemptionReasonCode: read.text('./cac:TaxCategory/cbc:TaxExemptionReasonCode', subtotal),
+    }),
+  );
+  const lines: IStatedLine[] = read.nodes('/*/cac:InvoiceLine | /*/cac:CreditNoteLine').map((line) =>
+    stated({
+      lineId: read.text('./cbc:ID', line),
+      netAmount: read.amount('./cbc:LineExtensionAmount', 'BT-131', line),
+      vatCategoryCode: read.text('./cac:Item/cac:ClassifiedTaxCategory/cbc:ID', line),
+      vatRate: read.amount('./cac:Item/cac:ClassifiedTaxCategory/cbc:Percent', 'BT-152', line),
+    }),
+  );
+  const allowanceCharges = (charge: boolean): IStatedAllowanceCharge[] =>
+    read
+      .nodes('/*/cac:AllowanceCharge')
+      .filter((node) => isIndicator(read.text('./cbc:ChargeIndicator', node), charge))
+      .map((node) =>
+        stated({
+          amount: read.amount('./cbc:Amount', charge ? 'BT-99' : 'BT-92', node),
+          baseAmount: read.amount('./cbc:BaseAmount', charge ? 'BT-100' : 'BT-93', node),
+          percentage: read.amount('./cbc:MultiplierFactorNumeric', charge ? 'BT-101' : 'BT-94', node),
+          vatCategoryCode: read.text('./cac:TaxCategory/cbc:ID', node),
+          vatRate: read.amount('./cac:TaxCategory/cbc:Percent', charge ? 'BT-103' : 'BT-96', node),
+          reason: read.text('./cbc:AllowanceChargeReason', node),
+          reasonCode: read.text('./cbc:AllowanceChargeReasonCode', node),
+        }),
+      );
+  return {
+    values: { totals, vatBreakdown, lines, allowances: allowanceCharges(false), charges: allowanceCharges(true) },
+    problems: read.problems,
+    documentCurrencyTaxTotals:
+      documentCurrency === undefined ? 0 : read.nodes(`/*/cac:TaxTotal/cbc:TaxAmount[@currencyID = '${documentCurrency}']`).length,
+    ublTaxTotals: read.nodes('/*/cac:TaxTotal').map((taxTotal) => ({
+      taxAmount: read.amount('./cbc:TaxAmount', 'BT-110', taxTotal),
+      subtotalTaxAmounts: read.nodes('./cac:TaxSubtotal', taxTotal).map((subtotal) => read.amount('./cbc:TaxAmount', 'BT-117', subtotal)),
+    })),
+  };
+};
+
+const ciiSelect = xpath.useNamespaces({ rsm: CII_NAMESPACES.RSM, ram: CII_NAMESPACES.RAM, udt: CII_NAMESPACES.UDT });
+
+/**
+ * Reads the stated values of a CII (D16B) document: the document totals of the
+ * header settlement (`ram:SpecifiedTradeSettlementHeaderMonetarySummation`,
+ * BT-106 to BT-115, `ram:TaxTotalAmount` in the invoice currency for BT-110 and
+ * in the VAT accounting currency for BT-111), the VAT breakdown (the header
+ * `ram:ApplicableTradeTax`, BT-116 to BT-121), the line amounts (BT-126,
+ * BT-131, BT-151, BT-152) and the document level allowances and charges (the
+ * header `ram:SpecifiedTradeAllowanceCharge`, BT-92 to BT-105)
+ * @param doc The CII document
+ */
+export const readCiiStatedValues = (doc: Document): IStatedValuesRead => {
+  const read = new StatedValueReader(ciiSelect, doc);
+  const settlement = '/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeSettlement';
+  const total = `${settlement}/ram:SpecifiedTradeSettlementHeaderMonetarySummation`;
+  const documentCurrency = read.text(`${settlement}/ram:InvoiceCurrencyCode`);
+  const accountingCurrency = read.text(`${settlement}/ram:TaxCurrencyCode`);
+  // CII tells BT-110 and BT-111 apart by their currency (BR-CO-15 reads BT-110 as the one in the invoice currency)
+  const taxTotalIn = (currency: string | undefined, businessTerm: string): number | undefined =>
+    currency === undefined ? undefined : read.amount(`${total}/ram:TaxTotalAmount[@currencyID = '${currency}']`, businessTerm);
+  const accountingTaxTotal = accountingCurrency && accountingCurrency !== documentCurrency ? taxTotalIn(accountingCurrency, 'BT-111') : undefined;
+  const totals: IStatedDocumentTotals = stated({
+    lineTotal: read.amount(`${total}/ram:LineTotalAmount`, 'BT-106'),
+    allowanceTotal: read.amount(`${total}/ram:AllowanceTotalAmount`, 'BT-107'),
+    chargeTotal: read.amount(`${total}/ram:ChargeTotalAmount`, 'BT-108'),
+    taxExclusiveTotal: read.amount(`${total}/ram:TaxBasisTotalAmount`, 'BT-109'),
+    taxTotal: taxTotalIn(documentCurrency, 'BT-110'),
+    taxTotalInAccountingCurrency:
+      accountingTaxTotal === undefined || accountingCurrency === undefined ? undefined : { amount: accountingTaxTotal, currency: accountingCurrency },
+    taxInclusiveTotal: read.amount(`${total}/ram:GrandTotalAmount`, 'BT-112'),
+    paidAmount: read.amount(`${total}/ram:TotalPrepaidAmount`, 'BT-113'),
+    roundingAmount: read.amount(`${total}/ram:RoundingAmount`, 'BT-114'),
+    amountDue: read.amount(`${total}/ram:DuePayableAmount`, 'BT-115'),
+  });
+  const vatBreakdown: IStatedVatBreakdown[] = read.nodes(`${settlement}/ram:ApplicableTradeTax`).map((tax) =>
+    stated({
+      taxableAmount: read.amount('./ram:BasisAmount', 'BT-116', tax),
+      taxAmount: read.amount('./ram:CalculatedAmount', 'BT-117', tax),
+      categoryCode: read.text('./ram:CategoryCode', tax),
+      rate: read.amount('./ram:RateApplicablePercent', 'BT-119', tax),
+      exemptionReason: read.text('./ram:ExemptionReason', tax),
+      exemptionReasonCode: read.text('./ram:ExemptionReasonCode', tax),
+    }),
+  );
+  const lines: IStatedLine[] = read.nodes('/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:IncludedSupplyChainTradeLineItem').map((line) =>
+    stated({
+      lineId: read.text('./ram:AssociatedDocumentLineDocument/ram:LineID', line),
+      netAmount: read.amount('./ram:SpecifiedLineTradeSettlement/ram:SpecifiedTradeSettlementLineMonetarySummation/ram:LineTotalAmount', 'BT-131', line),
+      vatCategoryCode: read.text('./ram:SpecifiedLineTradeSettlement/ram:ApplicableTradeTax/ram:CategoryCode', line),
+      vatRate: read.amount('./ram:SpecifiedLineTradeSettlement/ram:ApplicableTradeTax/ram:RateApplicablePercent', 'BT-152', line),
+    }),
+  );
+  const allowanceCharges = (charge: boolean): IStatedAllowanceCharge[] =>
+    read
+      .nodes(`${settlement}/ram:SpecifiedTradeAllowanceCharge`)
+      .filter((node) => isIndicator(read.text('./ram:ChargeIndicator/udt:Indicator', node), charge))
+      .map((node) =>
+        stated({
+          amount: read.amount('./ram:ActualAmount', charge ? 'BT-99' : 'BT-92', node),
+          baseAmount: read.amount('./ram:BasisAmount', charge ? 'BT-100' : 'BT-93', node),
+          percentage: read.amount('./ram:CalculationPercent', charge ? 'BT-101' : 'BT-94', node),
+          vatCategoryCode: read.text('./ram:CategoryTradeTax/ram:CategoryCode', node),
+          vatRate: read.amount('./ram:CategoryTradeTax/ram:RateApplicablePercent', charge ? 'BT-103' : 'BT-96', node),
+          reason: read.text('./ram:Reason', node),
+          reasonCode: read.text('./ram:ReasonCode', node),
+        }),
+      );
+  return {
+    values: { totals, vatBreakdown, lines, allowances: allowanceCharges(false), charges: allowanceCharges(true) },
+    problems: read.problems,
+    documentCurrencyTaxTotals:
+      documentCurrency === undefined ? 0 : read.nodes(`${total}/ram:TaxTotalAmount[@currencyID = '${documentCurrency}']`).length,
+  };
+};
+
+/** The official texts of the EN 16931 rules on the document totals (CEN artefacts 1.3.16) */
+const TOTALS_RULES = {
+  'BR-CO-10': 'Sum of Invoice line net amount (BT-106) = Σ Invoice line net amount (BT-131).',
+  'BR-CO-11': 'Sum of allowances on document level (BT-107) = Σ Document level allowance amount (BT-92).',
+  'BR-CO-12': 'Sum of charges on document level (BT-108) = Σ Document level charge amount (BT-99).',
+  'BR-CO-13':
+    'Invoice total amount without VAT (BT-109) = Σ Invoice line net amount (BT-131) - Sum of allowances on document level (BT-107) + Sum of charges on document level (BT-108).',
+  'BR-CO-14': 'Invoice total VAT amount (BT-110) = Σ VAT category tax amount (BT-117).',
+  'BR-CO-15': 'Invoice total amount with VAT (BT-112) = Invoice total amount without VAT (BT-109) + Invoice total VAT amount (BT-110).',
+  'BR-CO-16': 'Amount due for payment (BT-115) = Invoice total amount with VAT (BT-112) -Paid amount (BT-113) +Rounding amount (BT-114).',
+  'BR-CO-17': 'VAT category tax amount (BT-117) = VAT category taxable amount (BT-116) x (VAT category rate (BT-119) / 100), rounded to two decimals.',
+} as const;
+
+const decimal = (value: number): Decimal => new Decimal(toPlainDecimalString(value));
+const sum = (values: Array<number | undefined>): Decimal => Decimal.sum(values.map((value) => decimal(value ?? 0)));
+/** XPath's round(x × 100) div 100: two decimals, a half rounded towards positive infinity */
+const roundCents = (value: Decimal): Decimal => value.multiply(100).add('0.5').round(0, 'FLOOR').divide(100);
+/** XPath's round(x): an integer, a half rounded towards positive infinity */
+const roundInteger = (value: Decimal): Decimal => value.add('0.5').round(0, 'FLOOR');
+
+/**
+ * Checks the stated values of a document against each other as the EN 16931
+ * rules BR-CO-10 to BR-CO-17 do in the CEN artefacts 1.3.16: each sum rounded
+ * to two decimals, BR-CO-17 with the artefacts' tolerance of one unit (UBL
+ * strictly within it, CII up to it). A rule whose amounts the document does
+ * not state is not checked; the rules on the presence of the totals (BR-12 to
+ * BR-15) report that.
+ * @param read The stated values read from the document
+ * @param syntax The document's syntax
+ */
+export const findStatedValueDisagreements = (read: IStatedValuesRead, syntax: 'ubl' | 'cii'): IStatedValueFinding[] => {
+  const { values } = read;
+  const locations = syntax === 'ubl' ? UBL_TOTALS_LOCATIONS : CII_TOTALS_LOCATIONS;
+  const findings: IStatedValueFinding[] = [];
+  const report = (ruleId: keyof typeof TOTALS_RULES, detail: string) =>
+    findings.push({ ruleId, message: `${TOTALS_RULES[ruleId]} ${detail}`, location: locations[ruleId] });
+  const { totals } = values;
+  const text = (value: Decimal) => value.toString(2);
+
+  if (totals.lineTotal !== undefined) {
+    const expected = roundCents(sum(values.lines.map((line) => line.netAmount)));
+    if (!decimal(totals.lineTotal).equals(expected)) {
+      report('BR-CO-10', `The document states ${totals.lineTotal}, the sum of its line net amounts is ${text(expected)}.`);
+    }
+  }
+  const checkSum = (ruleId: 'BR-CO-11' | 'BR-CO-12', stated: number | undefined, entries: IStatedAllowanceCharge[]) => {
+    if (stated === undefined && entries.length === 0) {
+      return;
+    }
+    const expected = roundCents(sum(entries.map((entry) => entry.amount)));
+    if (stated === undefined || !decimal(stated).equals(expected)) {
+      report(ruleId, `The document states ${stated ?? 'none'}, the sum of its amounts is ${text(expected)}.`);
+    }
+  };
+  checkSum('BR-CO-11', totals.allowanceTotal, values.allowances);
+  checkSum('BR-CO-12', totals.chargeTotal, values.charges);
+  if (totals.taxExclusiveTotal !== undefined && totals.lineTotal !== undefined) {
+    const expected = roundCents(decimal(totals.lineTotal).subtract(totals.allowanceTotal ?? 0).add(totals.chargeTotal ?? 0));
+    if (!decimal(totals.taxExclusiveTotal).equals(expected)) {
+      report('BR-CO-13', `The document states ${totals.taxExclusiveTotal}, BT-106 - BT-107 + BT-108 is ${text(expected)}.`);
+    }
+  }
+  if (syntax === 'ubl') {
+    // each VAT total with subtotals, on its own, as the UBL artefacts check it
+    (read.ublTaxTotals ?? []).forEach((taxTotal) => {
+      if (taxTotal.subtotalTaxAmounts.length === 0) {
+        return;
+      }
+      const expected = roundCents(sum(taxTotal.subtotalTaxAmounts));
+      if (taxTotal.taxAmount === undefined || !decimal(taxTotal.taxAmount).equals(expected)) {
+        report('BR-CO-14', `A VAT total states ${taxTotal.taxAmount ?? 'none'}, the sum of its VAT category tax amounts is ${text(expected)}.`);
+      }
+    });
+  } else if (totals.taxTotal !== undefined) {
+    // the VAT total in the invoice currency against every header VAT breakdown
+    const expected = roundCents(sum(values.vatBreakdown.map((group) => group.taxAmount)));
+    if (!decimal(totals.taxTotal).equals(expected)) {
+      report('BR-CO-14', `The document states ${totals.taxTotal}, the sum of its VAT category tax amounts is ${text(expected)}.`);
+    }
+  }
+  if (totals.taxInclusiveTotal !== undefined && totals.taxExclusiveTotal !== undefined) {
+    const inclusive = decimal(totals.taxInclusiveTotal);
+    const exclusive = decimal(totals.taxExclusiveTotal);
+    const withTax = totals.taxTotal === undefined ? undefined : roundCents(exclusive.add(totals.taxTotal));
+    // both ask for exactly one VAT total in the document currency; CII also accepts a total with VAT equal to the one without
+    const agrees =
+      syntax === 'ubl'
+        ? read.documentCurrencyTaxTotals === 1 && withTax !== undefined && inclusive.equals(withTax)
+        : (read.documentCurrencyTaxTotals === 1 && withTax !== undefined && inclusive.equals(withTax)) || inclusive.equals(exclusive);
+    if (!agrees) {
+      report('BR-CO-15', `The document states ${totals.taxInclusiveTotal}, BT-109 + BT-110 is ${withTax === undefined ? 'not stated' : text(withTax)}.`);
+    }
+  }
+  if (totals.amountDue !== undefined && totals.taxInclusiveTotal !== undefined) {
+    const expected = decimal(totals.taxInclusiveTotal).subtract(totals.paidAmount ?? 0).add(totals.roundingAmount ?? 0);
+    // UBL compares both sides rounded to two decimals, CII the stated amounts as they are
+    const agrees =
+      syntax === 'ubl'
+        ? roundCents(decimal(totals.amountDue).subtract(totals.roundingAmount ?? 0)).equals(
+            roundCents(decimal(totals.taxInclusiveTotal).subtract(totals.paidAmount ?? 0)),
+          )
+        : decimal(totals.amountDue).equals(expected);
+    if (!agrees) {
+      report('BR-CO-16', `The document states ${totals.amountDue}, BT-112 - BT-113 + BT-114 is ${text(expected)}.`);
+    }
+  }
+  values.vatBreakdown.forEach((group, index) => {
+    if (group.taxAmount === undefined) {
+      return;
+    }
+    const taxAmount = decimal(group.taxAmount);
+    const rate = group.rate === undefined ? undefined : decimal(group.rate);
+    let agrees: boolean;
+    if (rate === undefined || roundInteger(rate).isZero()) {
+      agrees = roundInteger(taxAmount).isZero();
+    } else {
+      const expected = roundCents(decimal(group.taxableAmount ?? 0).abs().multiply(rate.divide(100)));
+      // the artefacts accept a tax amount within one unit of the computed one
+      agrees =
+        syntax === 'ubl'
+          ? taxAmount.abs().subtract(1).lessThan(expected) && taxAmount.abs().add(1).greaterThan(expected)
+          : taxAmount.abs().subtract(1).lessThanOrEqual(expected) && taxAmount.abs().add(1).greaterThanOrEqual(expected);
+    }
+    if (!agrees) {
+      findings.push({
+        ruleId: 'BR-CO-17',
+        message: `${TOTALS_RULES['BR-CO-17']} VAT breakdown ${index + 1} (${group.categoryCode ?? '?'} ${group.rate ?? ''}) states ${group.taxAmount} on ${group.taxableAmount ?? 'no taxable amount'}.`,
+        location: locations['BR-CO-17'],
+      });
+    }
+  });
+  return findings;
+};
+
+/** Where the rules on the totals apply in a UBL document */
+const UBL_TOTALS_LOCATIONS: Record<keyof typeof TOTALS_RULES, string> = {
+  'BR-CO-10': '/*/cac:LegalMonetaryTotal/cbc:LineExtensionAmount',
+  'BR-CO-11': '/*/cac:LegalMonetaryTotal/cbc:AllowanceTotalAmount',
+  'BR-CO-12': '/*/cac:LegalMonetaryTotal/cbc:ChargeTotalAmount',
+  'BR-CO-13': '/*/cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount',
+  'BR-CO-14': '/*/cac:TaxTotal/cbc:TaxAmount',
+  'BR-CO-15': '/*/cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount',
+  'BR-CO-16': '/*/cac:LegalMonetaryTotal/cbc:PayableAmount',
+  'BR-CO-17': '/*/cac:TaxTotal/cac:TaxSubtotal',
+};
+
+const CII_TOTALS = '/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeSettlement/ram:SpecifiedTradeSettlementHeaderMonetarySummation';
+/** Where the rules on the totals apply in a CII document */
+const CII_TOTALS_LOCATIONS: Record<keyof typeof TOTALS_RULES, string> = {
+  'BR-CO-10': `${CII_TOTALS}/ram:LineTotalAmount`,
+  'BR-CO-11': `${CII_TOTALS}/ram:AllowanceTotalAmount`,
+  'BR-CO-12': `${CII_TOTALS}/ram:ChargeTotalAmount`,
+  'BR-CO-13': `${CII_TOTALS}/ram:TaxBasisTotalAmount`,
+  'BR-CO-14': `${CII_TOTALS}/ram:TaxTotalAmount`,
+  'BR-CO-15': `${CII_TOTALS}/ram:GrandTotalAmount`,
+  'BR-CO-16': `${CII_TOTALS}/ram:DuePayableAmount`,
+  'BR-CO-17': '/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeSettlement/ram:ApplicableTradeTax',
+};
+
+/** The package's code for a stated value the envelope computes differently */
+export const STATED_VALUE_DIFFERS_CODE = 'EINVOICE-STATED-DIFFERS';
+
+/**
+ * The stated values of a loaded document that the envelope's computation
+ * (`computeDocumentTotals`, what `totalNet`, `totalVat`, `totalGross` and the
+ * encoders give) does not reproduce: the totals BT-106, BT-109, BT-110,
+ * BT-112 and BT-115, each line's net amount (BT-131) and VAT category
+ * (BT-151), and each VAT breakdown's category, rate and amounts (BG-23). No
+ * EN 16931 rule is broken by such a difference, so it is the package's own
+ * finding: the envelope has no document or line allowances and charges and no
+ * price base quantity, and every line is standard rated or reverse charge.
+ * Neither value is changed.
+ * @param values The stated values
+ * @param totals The envelope's computation
+ * @param paidAmount The envelope's paid amount (BT-113)
+ */
+export const findEnvelopeDifferences = (
+  values: IEInvoiceStatedValues,
+  totals: IDocumentTotals,
+  paidAmount: number | undefined,
+): IStatedValueFinding[] => {
+  const findings: IStatedValueFinding[] = [];
+  const differs = (businessTerm: string, field: string, stated: string | number, computed: string | number) =>
+    findings.push({
+      ruleId: STATED_VALUE_DIFFERS_CODE,
+      message: `The document states ${businessTerm} ${stated}; the envelope computes ${computed}. The stated value is statedValues.${field}; the envelope cannot express document or line allowances and charges (BG-20, BG-21, BG-27, BG-28), a price base quantity (BT-149) or a VAT category other than S and AE, and neither value is changed.`,
+      location: `statedValues.${field}`,
+    });
+  const compareAmount = (businessTerm: string, field: string, stated: number | undefined, computed: Decimal) => {
+    if (stated !== undefined && !decimal(stated).equals(computed)) {
+      differs(businessTerm, field, stated, computed.toString(totals.minorUnits));
+    }
+  };
+  compareAmount('BT-106', 'totals.lineTotal', values.totals.lineTotal, totals.lineTotal);
+  compareAmount('BT-109', 'totals.taxExclusiveTotal', values.totals.taxExclusiveTotal, totals.taxBasisTotal);
+  compareAmount('BT-110', 'totals.taxTotal', values.totals.taxTotal, totals.taxTotal);
+  compareAmount('BT-112', 'totals.taxInclusiveTotal', values.totals.taxInclusiveTotal, totals.grandTotal);
+  compareAmount('BT-115', 'totals.amountDue', values.totals.amountDue, totals.grandTotal.subtract(paidAmount ?? 0));
+  values.lines.forEach((line, index) => {
+    const computed = totals.lineNetAmounts[index];
+    if (computed !== undefined) {
+      compareAmount('BT-131', `lines[${index}].netAmount`, line.netAmount, computed);
+    }
+    const category = totals.lineVatCategories[index];
+    if (line.vatCategoryCode !== undefined && category !== undefined && line.vatCategoryCode !== category) {
+      differs('BT-151', `lines[${index}].vatCategoryCode`, line.vatCategoryCode, category);
+    }
+  });
+  values.vatBreakdown.forEach((group, index) => {
+    const computed = totals.vatGroups.find(
+      (candidate) => candidate.category === group.categoryCode && group.rate !== undefined && decimal(candidate.rate).equals(decimal(group.rate)),
+    );
+    if (!computed) {
+      differs('BG-23', `vatBreakdown[${index}]`, `${group.categoryCode ?? '?'} ${group.rate ?? ''}`.trim(), 'no breakdown of that category and rate');
+      return;
+    }
+    compareAmount('BT-116', `vatBreakdown[${index}].taxableAmount`, group.taxableAmount, computed.taxableAmount);
+    compareAmount('BT-117', `vatBreakdown[${index}].taxAmount`, group.taxAmount, computed.taxAmount);
+  });
+  return findings;
+};