@fin.cx/einvoice 8.3.1 → 10.0.0

package/dist_ts/interfaces/stated.values.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The amounts, VAT breakdown, line amounts and document level allowances and
+ * charges a received document states, read as they are written, with their
+ * EN 16931 business terms. They are not computed and not updated when the
+ * envelope changes, and no encoder writes them: the envelope computes its
+ * totals from quantity × net price (`computeDocumentTotals`), and cannot yet
+ * express document or line allowances and charges or a price base quantity.
+ * Every field is undefined when the document does not state it.
+ */
+export interface IEInvoiceStatedValues {
+    /** Document totals (BG-22) */
+    totals: IStatedDocumentTotals;
+    /** VAT breakdown (BG-23), in document order */
+    vatBreakdown: IStatedVatBreakdown[];
+    /** Invoice lines (BG-25), in document order */
+    lines: IStatedLine[];
+    /** Document level allowances (BG-20), in document order */
+    allowances: IStatedAllowanceCharge[];
+    /** Document level charges (BG-21), in document order */
+    charges: IStatedAllowanceCharge[];
+}
+/** Document totals (BG-22) as a document states them */
+export interface IStatedDocumentTotals {
+    /** Sum of Invoice line net amount (BT-106) */
+    lineTotal?: number;
+    /** Sum of allowances on document level (BT-107) */
+    allowanceTotal?: number;
+    /** Sum of charges on document level (BT-108) */
+    chargeTotal?: number;
+    /** Invoice total amount without VAT (BT-109) */
+    taxExclusiveTotal?: number;
+    /** Invoice total VAT amount (BT-110), in the document currency */
+    taxTotal?: number;
+    /** Invoice total VAT amount in accounting currency (BT-111), with the VAT accounting currency code (BT-6) */
+    taxTotalInAccountingCurrency?: {
+        amount: number;
+        currency: string;
+    };
+    /** Invoice total amount with VAT (BT-112) */
+    taxInclusiveTotal?: number;
+    /** Paid amount (BT-113) */
+    paidAmount?: number;
+    /** Rounding amount (BT-114) */
+    roundingAmount?: number;
+    /** Amount due for payment (BT-115) */
+    amountDue?: number;
+}
+/** One VAT breakdown (BG-23) as a document states it */
+export interface IStatedVatBreakdown {
+    /** VAT category taxable amount (BT-116) */
+    taxableAmount?: number;
+    /** VAT category tax amount (BT-117) */
+    taxAmount?: number;
+    /** VAT category code (BT-118), UNTDID 5305 */
+    categoryCode?: string;
+    /** VAT category rate (BT-119); a category not subject to VAT states none */
+    rate?: number;
+    /** VAT exemption reason text (BT-120) */
+    exemptionReason?: string;
+    /** VAT exemption reason code (BT-121) */
+    exemptionReasonCode?: string;
+}
+/** The amounts and the VAT category of one invoice line (BG-25) as a document states them */
+export interface IStatedLine {
+    /** Invoice line identifier (BT-126) */
+    lineId?: string;
+    /** Invoice line net amount (BT-131) */
+    netAmount?: number;
+    /** Invoiced item VAT category code (BT-151) */
+    vatCategoryCode?: string;
+    /** Invoiced item VAT rate (BT-152) */
+    vatRate?: number;
+}
+/**
+ * One document level allowance (BG-20: BT-92 to BT-98) or charge (BG-21:
+ * BT-99 to BT-105) as a document states it
+ */
+export interface IStatedAllowanceCharge {
+    /** Amount (BT-92, BT-99) */
+    amount?: number;
+    /** Base amount (BT-93, BT-100) */
+    baseAmount?: number;
+    /** Percentage (BT-94, BT-101) */
+    percentage?: number;
+    /** VAT category code (BT-95, BT-102) */
+    vatCategoryCode?: string;
+    /** VAT rate (BT-96, BT-103) */
+    vatRate?: number;
+    /** Reason (BT-97, BT-104) */
+    reason?: string;
+    /** Reason code (BT-98, BT-105) */
+    reasonCode?: string;
+}

package/dist_ts/interfaces/stated.values.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3RhdGVkLnZhbHVlcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2ludGVyZmFjZXMvc3RhdGVkLnZhbHVlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIn0=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fin.cx/einvoice",
-  "version": "8.3.1",
+  "version": "10.0.0",
   "private": false,
   "description": "A TypeScript module for creating, manipulating, and embedding XML data within PDF files specifically tailored for electronic invoice (einvoice) packages.",
   "main": "dist_ts/index.js",
@@ -67,7 +67,7 @@
   ],
   "scripts": {
     "test": "pnpm run test:unit",
-    "test:unit": "tstest test/test.cii-xrechnung.node.ts --verbose --logfile --timeout 60 && tstest test/test.einvoice.ts --verbose --logfile --timeout 60 && tstest test/test.decimal.ts --verbose --logfile --timeout 60 && tstest test/test.decimal-currency-calculator.ts --verbose --logfile --timeout 60 && tstest test/test.currency-utils.ts --verbose --logfile --timeout 60 && tstest test/test.en16931-validators.ts --verbose --logfile --timeout 60 && tstest test/test.schematron-validator.ts --verbose --logfile --timeout 60 && tstest test/test.xrechnung-creditnote.node.ts --verbose --logfile --timeout 60 && tstest test/test.accountingdoc-types.node.ts --verbose --logfile --timeout 60 && tstest test/test.corrected-invoice.node.ts --verbose --logfile --timeout 60 && tstest test/test.xrechnung-3-due-date.node.ts --verbose --logfile --timeout 60 && tstest test/test.calendar-dates.node.ts --verbose --logfile --timeout 60 && tstest test/test.document-totals.node.ts --verbose --logfile --timeout 60 && tstest test/test.reverse-charge.node.ts --verbose --logfile --timeout 60 && tstest test/test.cii-schema-order.node.ts --verbose --logfile --timeout 60 && tstest test/test.tax-number.node.ts --verbose --logfile --timeout 60 && tstest test/test.country-codes.node.ts --verbose --logfile --timeout 60 && tstest test/test.en16931-unitcodes.node.ts --verbose --logfile --timeout 60 && tstest test/test.en16931-lineunit.node.ts --verbose --logfile --timeout 60",
+    "test:unit": "tstest test/test.cii-xrechnung.node.ts --verbose --logfile --timeout 60 && tstest test/test.einvoice.ts --verbose --logfile --timeout 60 && tstest test/test.decimal.ts --verbose --logfile --timeout 60 && tstest test/test.decimal-currency-calculator.ts --verbose --logfile --timeout 60 && tstest test/test.currency-utils.ts --verbose --logfile --timeout 60 && tstest test/test.en16931-validators.ts --verbose --logfile --timeout 60 && tstest test/test.schematron-validator.ts --verbose --logfile --timeout 60 && tstest test/test.xrechnung-creditnote.node.ts --verbose --logfile --timeout 60 && tstest test/test.accountingdoc-types.node.ts --verbose --logfile --timeout 60 && tstest test/test.corrected-invoice.node.ts --verbose --logfile --timeout 60 && tstest test/test.xrechnung-3-due-date.node.ts --verbose --logfile --timeout 60 && tstest test/test.calendar-dates.node.ts --verbose --logfile --timeout 60 && tstest test/test.document-totals.node.ts --verbose --logfile --timeout 60 && tstest test/test.reverse-charge.node.ts --verbose --logfile --timeout 60 && tstest test/test.cii-schema-order.node.ts --verbose --logfile --timeout 60 && tstest test/test.tax-number.node.ts --verbose --logfile --timeout 60 && tstest test/test.country-codes.node.ts --verbose --logfile --timeout 60 && tstest test/test.paid-amount.node.ts --verbose --logfile --timeout 60 && tstest test/test.en16931-unitcodes.node.ts --verbose --logfile --timeout 60 && tstest test/test.en16931-lineunit.node.ts --verbose --logfile --timeout 60 && tstest test/test.cii-profile.node.ts --verbose --logfile --timeout 60 && tstest test/test.validator-rule-ids.node.ts --verbose --logfile --timeout 60 && tstest test/test.cii-period-address.node.ts --verbose --logfile --timeout 60 && tstest test/test.amount-due.node.ts --verbose --logfile --timeout 60 && tstest test/test.ubl-zoned-dates.node.ts --verbose --logfile --timeout 60 && tstest test/test.vat-categories.node.ts --verbose --logfile --timeout 60 && tstest test/test.xrechnung-buyer-reference.node.ts --verbose --logfile --timeout 60 && tstest test/test.specification-identifier.node.ts --verbose --logfile --timeout 60 && tstest test/test.seller-identifier.node.ts --verbose --logfile --timeout 60 && tstest test/test.stated-values.node.ts --verbose --logfile --timeout 60 && tstest test/test.vat-category-limits.node.ts --verbose --logfile --timeout 60 && tstest test/test.received-conformance.node.ts --verbose --logfile --timeout 60",
     "test:format": "tstest test/test.format-detection.ts --verbose --logfile --timeout 60",
     "test:corpus": "tstest test/suite/einvoice_corpus-validation/ --verbose --logfile --timeout 60",
     "test:performance": "NODE_OPTIONS=--expose-gc tstest test/suite/einvoice_performance/ --verbose --logfile --timeout 60",

package/readme.md

@@ -222,8 +222,8 @@ The encoders write only what the document states:
   to enforce.
 - `corrections` has no element in EN 16931 and is not written. State what is
   corrected as a note (`notes`, BT-22); the encoders add no text of their own.
-- The Factur-X MINIMUM profile has no BG-3. A document with a preceding invoice
-  reference is refused there with an `EInvoiceFormatError`.
+- Factur-X and ZUGFeRD write BG-3 in the EN 16931 profile. The MINIMUM profile,
+  which has no BG-3, is not written at all (see [CII profiles](#cii-profiles)).
 
 With the reference stated, the XRechnung output of a corrected invoice passes
 the official EN 16931 1.3.16 and KoSIT XRechnung Schematron 2.6.0 rules without
@@ -267,6 +267,35 @@ console.log(business.errors);
 console.log(business.warnings ?? []);
 ```
 
+At the business level, an XRechnung document in UBL syntax that was loaded from
+XML is checked by the package's XRechnung validator. Its findings carry the IDs
+of the official rule sets, the KoSIT XRechnung Schematron 2.6.0 and the CEN
+EN 16931 validation artefacts 1.3.16, and check what those rules check, in their
+context:
+
+| Rule | What is missing |
+| --- | --- |
+| BR-DE-1 | Payment instructions (BG-16) |
+| BR-49 | The payment means type code (BT-81) of a payment instruction |
+| BR-DE-15 | The buyer reference (BT-10) |
+| BR-DE-2 | The seller contact (BG-6) |
+| BR-DE-6, BR-DE-7 | The telephone number (BT-42) or email address (BT-43) of the seller contact |
+| BR-DE-3, BR-DE-4 | The seller city (BT-37) or post code (BT-38) |
+| BR-DE-8, BR-DE-9 | The buyer city (BT-52) or post code (BT-53) |
+| BR-DE-16 | The seller VAT identifier (BT-31), tax registration identifier (BT-32) or tax representative (BG-11), when a VAT category S, Z, E, AE, K, G, L or M is used |
+| PEPPOL-EN16931-R010 | The buyer electronic address (BT-49), a rule the XRechnung Schematron includes |
+| BR-21 | The identifier (BT-126) of an invoice line |
+| BR-CO-25 | The payment due date (BT-9) or payment terms (BT-20), while an amount is due (BT-115). EN 16931 states this rule; the CEN artefacts for UBL and CII do not check it |
+
+One check of its own has a code no official rule has: `EINVOICE-DE-VATID-FORMAT`,
+a seller VAT identifier (BT-31) that begins with DE but is not DE followed by nine
+digits, the format the Bundeszentralamt für Steuern issues. The official rules
+do not check that format, and its finding has the source `EINVOICE`, not
+`XRECHNUNG`.
+
+These checks are a subset. The official Schematron remains the reference for
+whether a document passes.
+
 ### Unit codes (BR-CL-23)
 
 A line's `unitType` is written as the unit code of the invoiced quantity (BT-130), so it has to
@@ -375,6 +404,100 @@ The envelope states reverse charge for the whole document; an item has no VAT
 category of its own. A document mixing reverse charge lines with standard rated
 ones cannot be expressed until `@tsclass/tsclass` gives items a category.
 
+Outside reverse charge every line is written as standard rated (`S`), whose
+rate BR-S-05 asks to be greater than zero. Export refuses a document with a
+line at the rate 0 outside reverse charge with an `EInvoiceFormatError` naming
+BR-S-05 and the line (`unsupportedFeatures` `['BR-S-05']`), and `validate()`
+reports it at the business level for a document built in code. The envelope cannot state
+the other categories: zero rated (`Z`), exempt (`E`), intra-community supply
+(`K`), export (`G`) or not subject to VAT (`O`), until `@tsclass/tsclass`
+gives an item a VAT category, so a received document with such lines, which is
+read as 0 % lines, cannot be written back or converted. The VAT category rules the
+conformance harness checks on an envelope (BR-S-01, -05, -08 to -10, BR-AE-01,
+-02, -05, -08 to -10 and BR-CO-17) take the categories and the VAT breakdown
+from the same computation the encoders write, and report them under their
+EN 16931 IDs and texts. A decoded line keeps the category its document states
+(`statedValues.lines[].vatCategoryCode`); one that is not S is not reported as
+BR-S-05, since the envelope reads it as S.
+
+## Paid amount and advance payments
+
+`paidAmount` is the gross sum received before the document was issued, the
+paid amount (BT-113). Every format writes it (`cbc:PrepaidAmount`,
+`ram:TotalPrepaidAmount`) and the amount due for payment (BT-115) as the gross
+total less it (BR-CO-16), zero when paid in full and negative when more was
+paid; a paid amount of zero is nothing paid and is not written. The decoders
+read it back. A paid amount with more decimals than the currency has (two at
+most, BR-DEC-16) is refused, not rounded. The amount due is always derived, so
+the envelope has no field for it and the business rule check of the `EInvoice`
+has nothing to compare it with; the official rules check BR-CO-16 on the
+written XML.
+
+A final invoice (an invoice, a corrected invoice or a self-billed invoice) may
+list the `advancePayments` it deducts (`@tsclass/tsclass` 9.9.0 on).
+`paidAmount` then equals their gross sum, the `net` plus the `vat` of every
+group of every payment, to the last decimal; a document that breaks this, or
+lists advance payments without a paid amount, is refused, and neither value is
+recomputed from the other. The advance invoice of each payment that states one
+is written as a preceding invoice reference (BG-3), after the invoice a
+corrected invoice corrects. Another document type with advance payments is
+refused.
+
+The deduction a final invoice owes under § 14 Abs. 5 Satz 2 UStG, the
+considerations received before the supply and the tax on them per rate
+(Abschnitt 14.8 Abs. 7 UStAE), has no element in EN 16931: "Derzeit sind die
+Anforderungen an eine Endrechnung noch nicht im strukturierten Teil einer
+E-Rechnung darstellbar" (BMF letter of 15 October 2024, Rn. 48). The encoders
+write the paid amount and the references and add no text of their own. The
+issuer either adds the deduction as an annex (Abschnitt 14.8 Abs. 8 Nr. 2
+UStAE), which Rn. 48 accepts as an unstructured file in an e-invoice issued
+until 31 December 2027 and which `@design.estate/dees-document` 3.4 prints, or
+issues an invoice over the remaining consideration only (Restrechnung,
+Abschnitt 14.8 Abs. 11 UStAE), which Rn. 48 recommends. Reading an e-invoice
+back yields its paid amount but no `advancePayments`: the XML does not carry the
+net and the tax of every payment. A corrected invoice's advance invoices read
+back as related documents it corrects, since BG-3 does not tell them apart,
+and an invoice's are not read.
+
+## Received documents: what they state
+
+A document read from XML carries what it states in `statedValues`, with the
+EN 16931 business terms, as written: the document totals (BG-22: BT-106 to
+BT-115, and BT-111 with its currency BT-6), the VAT breakdown (BG-23: BT-116
+to BT-121), each line's net amount, VAT category and rate (BT-126, BT-131,
+BT-151, BT-152) and the document level allowances and charges (BG-20, BG-21:
+BT-92 to BT-105). A field is undefined when the document does not state it.
+UBL, XRechnung, Factur-X and ZUGFeRD 2.x documents are read; ZUGFeRD 1.0
+predates EN 16931 and has none, nor has a document built in code.
+
+```ts
+const invoice = await EInvoice.fromXml(receivedXml);
+const { totals, vatBreakdown } = invoice.statedValues!;
+console.log(totals.taxExclusiveTotal, totals.taxTotal, totals.amountDue);
+```
+
+Book what the document states. The envelope's totals (`totalNet`, `totalVat`,
+`totalGross`, `taxBreakdown`) are computed from quantity × net price, and the
+envelope cannot express document or line allowances and charges, a price base
+quantity (BT-149) or a VAT category other than standard rated and reverse
+charge, so for such a document they differ from what it states. Neither value
+is changed: `validate()` reports each difference at the business level as a
+warning `EINVOICE-STATED-DIFFERS`, the package's own code, naming the
+business term and both values. `statedValues` is not updated when the envelope
+changes, and no encoder writes it: an export writes the envelope's
+computation, so a received document with allowances, charges or base
+quantities is not written back with the amounts it states, and a document with
+lines of a category other than S and AE is refused on export (BR-S-05). The
+`EINVOICE-STATED-DIFFERS` warnings are the signal that an export would not
+state what was received; a faithful round trip needs `@tsclass/tsclass` to
+express allowances, charges, base quantities and line categories.
+
+The stated values are checked against each other at the business level as the
+CEN artefacts 1.3.16 check them, under the official rule IDs BR-CO-10 to
+BR-CO-17, in UBL and CII; these checks replace the approximate ones of earlier
+releases. A stated amount that is no decimal number is refused on read with an
+`EInvoiceParsingError` that names the business term.
+
 ## Calendar dates
 
 A calendar date of the invoice (issue date, due date, delivery date, invoicing
@@ -383,7 +506,10 @@ zone: UBL writes it as `xsd:date` (`2026-09-20`), CII in format 102
 (`20260920`). In the accounting document envelope such a day is a timestamp:
 the UTC midnight of that day, `Date.UTC(2026, 8, 20)`.
 
-- The decoders return that timestamp.
+- The decoders return that timestamp. A UBL date may carry a time zone
+  (`2026-09-20+02:00`, `2026-09-20Z`); the zone does not move the day, so the
+  decoders return the UTC midnight of the stated day, and every format writes
+  that day.
 - The encoders write the day of that timestamp in UTC and count the payment
   term in UTC days, so what they write does not depend on the time zone of the
   machine that writes it.
@@ -400,7 +526,7 @@ the UTC midnight of that day, `Date.UTC(2026, 8, 20)`.
 | `xrechnung` | Yes | Yes | Yes | Yes | UBL export; UBL and CII import |
 | `cii` | Yes | Yes | Yes | Partial | Generic CII export currently uses the Factur-X encoder path |
 | `facturx` | Yes | Yes | Yes | Yes | Main CII-based generation path |
-| `zugferd` | Yes | Yes | Yes | Partial | Input supports v1 and v2+, export focuses on the current encoder |
+| `zugferd` | Yes | Yes | Yes | Partial | Input supports v1 and v2+; export writes the EN 16931 profile, and v2 reads back as `facturx`, as XML and from a PDF (see [CII profiles](#cii-profiles)) |
 | `fatturapa` | Yes | No | No | Basic placeholder | Detection exists, decoder/encoder do not |
 
 ### Important format notes
@@ -408,13 +534,63 @@ the UTC midnight of that day, `Date.UTC(2026, 8, 20)`.
 - There is no dedicated root-level `peppol` export format. PEPPOL-specific checks exist, but the XML export targets are still `ubl` / `xrechnung`.
 - XRechnung import routes UBL and CII by the namespace-qualified XML root.
   Missing or invalid document-level invoice IDs and issue dates are rejected.
+- The buyer reference (BT-10): every format writes `buyerReference`
+  (`cbc:BuyerReference`, `ram:BuyerReference`) and reads it back, ZUGFeRD 1.0
+  input as well. XRechnung requires it (BR-DE-15), and it is the
+  buyer's: the identifier the buyer gives the seller for routing the invoice, a
+  Leitweg-ID for a public buyer, any identifier of the buyer's choice in B2B.
+  `exportXml('xrechnung')` writes `buyerReference` (or the reference a decoded
+  UBL document keeps) and refuses a document without one with an
+  `EInvoiceFormatError` whose `unsupportedFeatures` is `['BR-DE-15']`; nothing,
+  not the invoice number, is put in its place. A seller whose buyer gave no
+  reference exports `ubl` (EN 16931), where BT-10 is optional. The metadata has
+  no buyer reference of its own: `buyerReference` is the one field.
 - `FatturaPA` should be documented as detection-only right now.
-- The day of supply: UBL and XRechnung write `deliveryDate` as `cac:Delivery/cbc:ActualDeliveryDate` (BT-72) and `periodOfPerformance` as `cac:InvoicePeriod` (BG-14), and read both back. Factur-X and ZUGFeRD write `deliveryDate` as `ram:ActualDeliverySupplyChainEvent` and read it back only when the document states it.
-- Country codes: every format writes the seller and buyer country (BT-40, BT-55) as an ISO 3166-1 alpha-2 code EN 16931 accepts (BR-CL-14), taken from `address.countryCode`, or from `address.country` when that is already such a code (letter case does not matter). A code is never derived from a country name: a name without a `countryCode`, a code EN 16931 does not know, or a missing country is refused with an `EInvoiceFormatError` naming the field (BR-CL-14, BR-09, BR-11).
+- The day of supply: UBL and XRechnung write `deliveryDate` as `cac:Delivery/cbc:ActualDeliveryDate` (BT-72) and `periodOfPerformance` as `cac:InvoicePeriod` (BG-14), and read both back. Factur-X and ZUGFeRD write `deliveryDate` as `ram:ActualDeliverySupplyChainEvent` and `periodOfPerformance` as `ram:BillingSpecifiedPeriod` of the header settlement, and read each back only when the document states it; ZUGFeRD 1.0 input has its period read as well. `periodOfPerformance` has a start and an end date, so a document that states only one of them (EN 16931 allows that, BR-CO-19) reads back without `periodOfPerformance`, in every format; the date it states is kept in `metadata.extensions.dateInformation.periodStart` or `.periodEnd` (YYYY-MM-DD), and every encoder writes it back as the one date of the period, so it survives a round trip and a conversion between UBL and CII.
+- The seller electronic address (BT-34): Factur-X and ZUGFeRD write `electronicAddress` as `ram:URIUniversalCommunication/ram:URIID` of the seller, with its scheme (BR-62), for a company or a person, and read it back. A ZUGFeRD 1.0 trade party has no electronic address.
+- Country codes: every format writes the seller and buyer country (BT-40, BT-55) as an ISO 3166-1 alpha-2 code EN 16931 accepts (BR-CL-14), taken from `address.countryCode`, or from `address.country` when that is already such a code (letter case does not matter). A code is never derived from a country name: a name without a `countryCode`, a code EN 16931 does not know, or a missing country is refused with an `EInvoiceFormatError` naming the field (BR-CL-14, BR-09, BR-11). The list of codes is the UBL one of the CEN EN 16931 validation artefacts 1.3.16, for every format. Their CII list differs in two codes: it has AN (Netherlands Antilles, withdrawn from ISO 3166-1) and lacks SS (South Sudan). So a Factur-X or ZUGFeRD document with a party in South Sudan is written, and the official CII rules report BR-CL-14 for it; AN is refused in every format.
 - Party identifiers: `registrationDetails.vatId` is the VAT identifier (BT-31 seller, BT-48 buyer), `registrationId` the legal registration identifier such as the commercial register number (BT-30, BT-47), and `taxNumber` the seller's tax registration identifier, the Steuernummer (BT-32), which § 14 Abs. 4 Satz 1 Nr. 2 UStG allows in place of the VAT identifier. UBL and XRechnung write the tax number as a second `cac:PartyTaxScheme` with the tax scheme `FC`, after the VAT one; Factur-X and ZUGFeRD as `ram:SpecifiedTaxRegistration/ram:ID` with the scheme `FC`. The decoders read each by its scheme, whatever order the document lists them in. EN 16931 has no tax number for the buyer, so a buyer's `taxNumber` is not written.
+- The seller's identification (BR-CO-26): EN 16931 asks the seller to state a seller identifier (BT-29), a legal registration identifier (BT-30, `registrationDetails.registrationId`) or a VAT identifier (BT-31, `registrationDetails.vatId`); a tax number (BT-32) alone does not identify it. Every export whose seller states none of them is refused with an `EInvoiceFormatError` whose `unsupportedFeatures` is `['BR-CO-26']`, and `validate()` reports BR-CO-26 at the business level, for a loaded document and for one built in code. The party identifiers, the seller identifier (BT-29) and the buyer identifier (BT-46), have no typed field in the envelope: the decoders keep them in the party's `additionalIdentifiers` (`{ value, scheme }`), and every format writes them from there, UBL as `cac:PartyIdentification/cbc:ID` with the scheme as `schemeID`, CII as `ram:GlobalID` with its scheme or `ram:ID` without one. A UBL seller identification with the scheme SEPA is the bank assigned creditor identifier (BT-90) and is not written to CII. A buyer identifier with the scheme SEPA is refused (BR-CL-10): UBL admits the scheme for the seller and the payee only, CII for no party.
+- The specification identifier (BT-24): the decoders set `metadata.customizationId` to the identifier the document states (UBL `cbc:CustomizationID`, CII `ram:GuidelineSpecifiedDocumentContextParameter/ram:ID`), so `MainValidator` runs the XRechnung, PEPPOL or Factur-X checks on a decoded document of that kind. The PEPPOL checks run for the PEPPOL BIS Billing 3.0 identifier only, `urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0`, not for PINT, A-NZ or another derivative that names PEPPOL. `metadata.profileId` is the business process type (BT-23, UBL `cbc:ProfileID`). The encoders write the identifier of the format they write, not `customizationId`.
 - Credit notes, debit notes, corrected invoices and self-billed invoices share the `EInvoice` class; see the type code table above. Credit and debit amounts are written as given, the encoders do not change signs.
 - ZUGFeRD v1 input is detected and routed, but the v1 decoder does not read the v1 header, so such a document always arrives as an `invoice`. Known defect, to be fixed separately.
 
+### CII profiles
+
+The Factur-X and ZUGFeRD encoders, and `cii`, which uses the Factur-X one, write
+the full EN 16931 content, so they state the EN 16931 profile as the
+specification identifier (BT-24): `urn:cen.eu:en16931:2017`, the identifier the
+CEN validation artefacts use and the EN 16931 profile of Factur-X 1.0 and
+ZUGFeRD 2.x, which ZUGFeRD also calls COMFORT.
+
+`FacturXEncoder.setProfile` and `ZUGFeRDEncoder.setProfile` accept `EN16931` and
+`COMFORT`, both written as that identifier. The other choices are refused with an
+`EInvoiceFormatError` whose message names the profile and why, and whose
+`unsupportedFeatures` is `['profile MINIMUM']` and so on; nothing is downgraded
+to EN 16931 silently:
+
+| Choice | Why it is refused |
+| --- | --- |
+| `MINIMUM` | The content written is EN 16931, which MINIMUM does not allow (no lines, no VAT breakdown, no street, postcode or city). A MINIMUM document is not an e-invoice (BMF letter of 15 October 2024, Rn. 25 and 30). |
+| `BASIC` | The content written is EN 16931, which neither BASIC nor BASIC WL allows; BASIC WL has no lines and is not an e-invoice either (same letter, Rn. 25 and 30). |
+| `EXTENDED` | The output has not been checked against the EXTENDED schema and rules. |
+
+Factur-X 1.0 and ZUGFeRD 2.x are one standard with one XML, and their EN 16931
+profile has one identifier. A ZUGFeRD 2.x export therefore reads back as
+Factur-X, as XML and from a PDF alike, because a PDF's format is detected from
+its embedded XML: `FormatDetector.detectFormat` and `getFormat()` return
+`facturx`, and `FacturXDecoder` reads it. A ZUGFeRD PDF is still written with the
+`zugferd-invoice.xml` attachment.
+
+Decoding does not check the profile. A document that states another profile's
+identifier, such as Factur-X MINIMUM or BASIC WL, a ZUGFeRD 2.0 identifier, the
+`urn:zugferd:` identifiers earlier releases of this library wrote, or ZUGFeRD v1,
+is detected and read as before. An identifier that names Factur-X reads as
+`facturx`, one that names ZUGFeRD as `zugferd`: ZUGFeRD 2.0 has identifiers of
+its own (`urn:zugferd.de:2p0:minimum`, and for BASIC and EXTENDED the EN 16931
+identifier extended by `urn:zugferd.de:2p0:basic` or `urn:zugferd.de:2p0:extended`),
+where ZUGFeRD 2.1 and Factur-X 1.0 share theirs.
+
 ## Public API overview
 
 Top-level exports from `@fin.cx/einvoice` include:

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@fin.cx/einvoice',
-  version: '8.3.1',
+  version: '10.0.0',
   description: 'A TypeScript module for creating, manipulating, and embedding XML data within PDF files specifically tailored for electronic invoice (einvoice) packages.'
 }

package/ts/einvoice.ts

@@ -46,7 +46,11 @@ import {
 // Import enhanced validators
 import { EN16931Validator } from './formats/validation/en16931.validator.js';
 import { EN16931BusinessRulesValidator } from './formats/validation/en16931.business-rules.validator.js';
-import { computeDocumentTotals } from './formats/utils/document.totals.js';
+import { isRateNotAboveZero, standardRatedLineWithoutRateMessage } from './formats/utils/vat.category.js';
+import { BR_CO_26_TEXT, envelopeSellerMeetsBrCo26 } from './formats/utils/seller.identifier.js';
+import { findEnvelopeDifferences } from './formats/utils/stated.values.js';
+import type { IEInvoiceStatedValues } from './interfaces/stated.values.js';
+import { computeDocumentTotals, findInvalidItemAmounts } from './formats/utils/document.totals.js';
 import { CodeListValidator } from './formats/validation/codelist.validator.js';
 import type { ValidationOptions } from './formats/validation/validation.types.js';
 
@@ -168,6 +172,34 @@ export class EInvoice implements TAccountingDocEnvelope<TAccountingDocType, {}>
    * written to the XML; an issuer states them as a note in `notes`.
    */
   public corrections?: finance.TCorrectedInvoice['corrections'];
+
+  /**
+   * The gross sum received before the document was issued, the paid amount
+   * (BT-113); the amount due (BT-115) is the gross total less it. Absent or
+   * zero: nothing was paid.
+   */
+  public paidAmount?: number;
+
+  /**
+   * What a loaded document states: its totals (BG-22), VAT breakdown (BG-23),
+   * line net amounts and VAT categories (BT-131, BT-151) and document level
+   * allowances and charges (BG-20, BG-21), with their EN 16931 business terms,
+   * as written. Undefined for a document built in code and for ZUGFeRD 1.0.
+   * The envelope's totals (`totalNet`, `totalVat`, `totalGross`) are computed
+   * from quantity × net price and may differ; `validate()` reports each
+   * difference at the business level as `EINVOICE-STATED-DIFFERS`. No encoder
+   * writes these values, and they are not updated when the envelope changes.
+   */
+  public statedValues?: IEInvoiceStatedValues;
+
+  /**
+   * On a final invoice (an invoice, a corrected invoice or a self-billed
+   * invoice): the advance payments it deducts; `paidAmount` equals their gross
+   * sum. Their advance invoices are written as preceding invoice references
+   * (BG-3); the deduction per rate has no element in EN 16931, and a document
+   * read from XML has none.
+   */
+  public advancePayments?: finance.TInvoice['advancePayments'];
   public printResult?: {
     pdfBufferString: string;
     totalNet: number;
@@ -338,6 +370,8 @@ export class EInvoice implements TAccountingDocEnvelope<TAccountingDocType, {}>
       
       // Map the decoded invoice to our properties
       this.mapFromTInvoice(invoice);
+      // what the document states, as it states it; undefined for a ZUGFeRD 1.0 document
+      this.statedValues = decoder.getStatedValues();
 
       // Validate if requested
       if (this.options.validateOnLoad) {
@@ -465,6 +499,8 @@ export class EInvoice implements TAccountingDocEnvelope<TAccountingDocType, {}>
       relatedDocuments: this.relatedDocuments,
       correctedInvoice: this.correctedInvoice,
       corrections: this.corrections,
+      paidAmount: this.paidAmount,
+      advancePayments: this.advancePayments,
       printResult: this.printResult
     };
     
@@ -495,7 +531,14 @@ export class EInvoice implements TAccountingDocEnvelope<TAccountingDocType, {}>
       return await encoder.encode(invoice);
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
-      throw new EInvoiceFormatError(`Failed to encode to ${format}: ${errorMessage}`, { targetFormat: format });
+      // a refusal keeps the rules it names, so a caller can tell why without reading the message
+      throw new EInvoiceFormatError(
+        `Failed to encode to ${format}: ${errorMessage}`,
+        {
+          targetFormat: format,
+          ...(error instanceof EInvoiceFormatError && error.unsupportedFeatures ? { unsupportedFeatures: error.unsupportedFeatures } : {}),
+        },
+      );
     }
   }
 
@@ -536,6 +579,15 @@ export class EInvoice implements TAccountingDocEnvelope<TAccountingDocType, {}>
         result = this.validateDecodedInvoice(level);
       }
       
+      // What a loaded document states and the envelope computes differently, reported and not
+      // changed: the envelope cannot express allowances, charges or a price base quantity
+      if (level === ValidationLevel.BUSINESS && this.statedValues && findInvalidItemAmounts(this.items).length === 0) {
+        const differences = findEnvelopeDifferences(this.statedValues, computeDocumentTotals(this), this.paidAmount);
+        result.warnings = (result.warnings ?? []).concat(
+          differences.map((difference) => ({ code: difference.ruleId, message: difference.message, location: difference.location })),
+        );
+      }
+
       // At the business level the document check covers the unit rules (BR-23, BR-CL-23) on every
       // line. The feature flag validators below check the lines again on the decoded model, which
       // cannot tell an absent unit from an empty unitCode="" attribute, so there they would report
@@ -606,6 +658,22 @@ export class EInvoice implements TAccountingDocEnvelope<TAccountingDocType, {}>
     );
 
     if (level === ValidationLevel.BUSINESS) {
+      // BR-S-05: a line outside reverse charge is written as standard rated, whose rate is greater than zero
+      if (!invoice.reverseCharge) {
+        (invoice.items ?? []).forEach((item, index) => {
+          if (isRateNotAboveZero(item.vatPercentage)) {
+            errors.push({
+              code: 'BR-S-05',
+              message: standardRatedLineWithoutRateMessage({ index, vatPercentage: item.vatPercentage }),
+              location: `items[${index}].vatPercentage`,
+            });
+          }
+        });
+      }
+      // BR-CO-26: the seller states a seller, legal registration or VAT identifier; a tax number alone does not identify it
+      if (!envelopeSellerMeetsBrCo26(invoice)) {
+        errors.push({ code: 'BR-CO-26', message: BR_CO_26_TEXT, location: 'from.registrationDetails' });
+      }
       // BR-23 and BR-CL-23: every line has a unit code, and it is a code of UN/ECE Recommendation 20
       // with the Recommendation 21 extension, as the XML validators check it on an exported document
       (invoice.items ?? []).forEach((item, index) => {

package/ts/formats/base/base.decoder.ts

@@ -2,6 +2,9 @@ import type { TAccountingDoc } from '../../interfaces/common.js';
 import { ValidationLevel } from '../../interfaces/common.js';
 import type { ValidationResult } from '../../interfaces/common.js';
 import { EInvoiceParsingError } from '../../errors.js';
+import { parseXsdDateDay } from '../utils/date.value.js';
+import type { IEInvoiceStatedValues } from '../../interfaces/stated.values.js';
+import { statedValueProblemMessage, type IStatedValuesRead } from '../utils/stated.values.js';
 
 /**
  * Base decoder class that defines common decoding functionality
@@ -45,6 +48,29 @@ export abstract class BaseDecoder {
     return undefined;
   }
 
+  /**
+   * The amounts, VAT breakdown, line amounts and document level allowances
+   * and charges the decoded document states, as it states them; undefined for
+   * a format that has no EN 16931 business terms to read them by
+   */
+  public getStatedValues(): IEInvoiceStatedValues | undefined {
+    return undefined;
+  }
+
+  /**
+   * Refuses a document with a stated amount that is no decimal number, naming
+   * the business term; nothing is put in its place
+   * @param read The stated values read
+   * @param format The format read
+   */
+  protected assertStatedValuesReadable(read: IStatedValuesRead, format: string): IEInvoiceStatedValues {
+    const [problem] = read.problems;
+    if (problem) {
+      throw new EInvoiceParsingError(statedValueProblemMessage(problem), { format });
+    }
+    return read.values;
+  }
+
   /**
    * Parses a CII date string based on format code
    * @param dateStr Date string
@@ -122,40 +148,17 @@ export abstract class BaseDecoder {
   }
 
   /**
-   * Parses a required UBL xsd:date value strictly and deterministically.
+   * Parses a required UBL xsd:date value strictly: the calendar day it states,
+   * as the UTC midnight of that day. A time zone does not move the day
+   * (`parseXsdDateDay`).
    */
   protected parseRequiredUblDate(dateStr: string): number {
     const value = dateStr.trim();
-    const match =
-      /^(\d{4})-(\d{2})-(\d{2})(?:(Z)|([+-])(\d{2}):(\d{2}))?$/.exec(value);
-    if (!match) {
+    const day = parseXsdDateDay(value);
+    if (day === undefined) {
       throw this.createInvalidDateError(value, 'UBL xsd:date');
     }
-
-    const timestamp = this.createStrictUtcTimestamp(
-      Number(match[1]),
-      Number(match[2]),
-      Number(match[3]),
-      value,
-      'UBL xsd:date',
-    );
-
-    if (!match[5]) {
-      return timestamp;
-    }
-
-    const offsetHours = Number(match[6]);
-    const offsetMinutes = Number(match[7]);
-    if (
-      offsetHours > 14 ||
-      offsetMinutes > 59 ||
-      (offsetHours === 14 && offsetMinutes !== 0)
-    ) {
-      throw this.createInvalidDateError(value, 'UBL xsd:date');
-    }
-
-    const direction = match[5] === '+' ? 1 : -1;
-    return timestamp - direction * (offsetHours * 60 + offsetMinutes) * 60_000;
+    return day;
   }
 
   private createStrictUtcTimestamp(