@fin.cx/einvoice 8.2.1 → 8.2.3

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

@@ -6,6 +6,7 @@ import { getDocumentTypeCode } from '../../utils/document.typecode.js';
 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';
 
 /**
  * UBL Encoder implementation
@@ -383,65 +384,45 @@ export class UBLEncoder extends UBLBaseEncoder {
   private addTaxTotal(doc: Document, parentElement: Element, invoice: TAccountingDoc): void {
     const taxTotalNode = doc.createElement('cac:TaxTotal');
     parentElement.appendChild(taxTotalNode);
-    
-    // Calculate total tax amount
-    let totalTaxAmount = 0;
-    const taxCategories = new Map<number, number>(); // Map of VAT rate to net amount
-    
-    // Calculate from items
-    if (invoice.items) {
-      for (const item of invoice.items) {
-        const itemNetAmount = item.unitNetPrice * item.unitQuantity;
-        const itemTaxAmount = itemNetAmount * (item.vatPercentage / 100);
-        const vatRate = item.vatPercentage;
-        
-        totalTaxAmount += itemTaxAmount;
-        
-        // Aggregate by VAT rate
-        const currentAmount = taxCategories.get(vatRate) || 0;
-        taxCategories.set(vatRate, currentAmount + itemNetAmount);
-      }
-    }
-    
-    // Add total tax amount
+
+    // the EN 16931 totals in decimal arithmetic, rounded as the business rules check them
+    const totals = computeDocumentTotals(invoice);
+
+    // Invoice total VAT amount (BT-110)
     const taxAmountElement = doc.createElement('cbc:TaxAmount');
     taxAmountElement.setAttribute('currencyID', invoice.currency);
-    taxAmountElement.textContent = totalTaxAmount.toFixed(2);
+    taxAmountElement.textContent = totals.taxTotal.toFixed(totals.minorUnits);
     taxTotalNode.appendChild(taxAmountElement);
-    
-    // Add tax subtotals
-    for (const [rate, baseAmount] of taxCategories.entries()) {
+
+    // VAT breakdown (BG-23), one subtotal per rate
+    for (const { category, rate, taxableAmount, taxAmount, exemption } of totals.vatGroups) {
       const taxSubtotalNode = doc.createElement('cac:TaxSubtotal');
       taxTotalNode.appendChild(taxSubtotalNode);
-      
-      // Taxable amount
+
+      // VAT category taxable amount (BT-116)
       const taxableAmountElement = doc.createElement('cbc:TaxableAmount');
       taxableAmountElement.setAttribute('currencyID', invoice.currency);
-      taxableAmountElement.textContent = baseAmount.toFixed(2);
+      taxableAmountElement.textContent = taxableAmount.toFixed(totals.minorUnits);
       taxSubtotalNode.appendChild(taxableAmountElement);
-      
-      // Tax amount
-      const taxAmount = baseAmount * (rate / 100);
+
+      // VAT category tax amount (BT-117)
       const subtotalTaxAmountElement = doc.createElement('cbc:TaxAmount');
       subtotalTaxAmountElement.setAttribute('currencyID', invoice.currency);
-      subtotalTaxAmountElement.textContent = taxAmount.toFixed(2);
+      subtotalTaxAmountElement.textContent = taxAmount.toFixed(totals.minorUnits);
       taxSubtotalNode.appendChild(subtotalTaxAmountElement);
       
       // Tax category
       const taxCategoryNode = doc.createElement('cac:TaxCategory');
       taxSubtotalNode.appendChild(taxCategoryNode);
       
-      // Determine tax category ID based on reverse charge
-      const categoryId = invoice.reverseCharge ? 'AE' : 'S';
-      this.appendElement(doc, taxCategoryNode, 'cbc:ID', categoryId);
-      
-      // Add percent with 2 decimal places
+      // VAT category code (BT-118) and rate (BT-119)
+      this.appendElement(doc, taxCategoryNode, 'cbc:ID', category);
       this.appendElement(doc, taxCategoryNode, 'cbc:Percent', rate.toFixed(2));
       
-      // Add tax exemption reason if reverse charge
-      if (invoice.reverseCharge) {
-        this.appendElement(doc, taxCategoryNode, 'cbc:TaxExemptionReasonCode', 'VATEX-EU-IC');
-        this.appendElement(doc, taxCategoryNode, 'cbc:TaxExemptionReason', 'Reverse charge');
+      // VAT exemption reason code (BT-121) and text (BT-120), for reverse charge (BR-AE-10)
+      if (exemption) {
+        this.appendElement(doc, taxCategoryNode, 'cbc:TaxExemptionReasonCode', exemption.code);
+        this.appendElement(doc, taxCategoryNode, 'cbc:TaxExemptionReason', exemption.reason);
       }
       
       // Add tax scheme
@@ -460,46 +441,33 @@ export class UBLEncoder extends UBLBaseEncoder {
   private addLegalMonetaryTotal(doc: Document, parentElement: Element, invoice: TAccountingDoc): void {
     const legalMonetaryTotalNode = doc.createElement('cac:LegalMonetaryTotal');
     parentElement.appendChild(legalMonetaryTotalNode);
-    
-    // Calculate totals
-    let totalNetAmount = 0;
-    let totalTaxAmount = 0;
-    
-    // Calculate from items
-    if (invoice.items) {
-      for (const item of invoice.items) {
-        const itemNetAmount = item.unitNetPrice * item.unitQuantity;
-        const itemTaxAmount = itemNetAmount * (item.vatPercentage / 100);
-        
-        totalNetAmount += itemNetAmount;
-        totalTaxAmount += itemTaxAmount;
-      }
-    }
-    
-    const totalGrossAmount = totalNetAmount + totalTaxAmount;
+
+    // the EN 16931 totals in decimal arithmetic, rounded as the business rules check them
+    const totals = computeDocumentTotals(invoice);
+    const amount = (value: { toFixed(decimalPlaces: number): string }) => value.toFixed(totals.minorUnits);
     
     // Line extension amount (sum of line net amounts)
     const lineExtensionAmountElement = doc.createElement('cbc:LineExtensionAmount');
     lineExtensionAmountElement.setAttribute('currencyID', invoice.currency);
-    lineExtensionAmountElement.textContent = totalNetAmount.toFixed(2);
+    lineExtensionAmountElement.textContent = amount(totals.lineTotal);
     legalMonetaryTotalNode.appendChild(lineExtensionAmountElement);
     
     // Tax exclusive amount
     const taxExclusiveAmountElement = doc.createElement('cbc:TaxExclusiveAmount');
     taxExclusiveAmountElement.setAttribute('currencyID', invoice.currency);
-    taxExclusiveAmountElement.textContent = totalNetAmount.toFixed(2);
+    taxExclusiveAmountElement.textContent = amount(totals.taxBasisTotal);
     legalMonetaryTotalNode.appendChild(taxExclusiveAmountElement);
     
     // Tax inclusive amount
     const taxInclusiveAmountElement = doc.createElement('cbc:TaxInclusiveAmount');
     taxInclusiveAmountElement.setAttribute('currencyID', invoice.currency);
-    taxInclusiveAmountElement.textContent = totalGrossAmount.toFixed(2);
+    taxInclusiveAmountElement.textContent = amount(totals.grandTotal);
     legalMonetaryTotalNode.appendChild(taxInclusiveAmountElement);
     
     // Payable amount
     const payableAmountElement = doc.createElement('cbc:PayableAmount');
     payableAmountElement.setAttribute('currencyID', invoice.currency);
-    payableAmountElement.textContent = totalGrossAmount.toFixed(2);
+    payableAmountElement.textContent = amount(totals.duePayable);
     legalMonetaryTotalNode.appendChild(payableAmountElement);
   }
   
@@ -512,8 +480,9 @@ export class UBLEncoder extends UBLBaseEncoder {
   private addInvoiceLines(doc: Document, parentElement: Element, invoice: TAccountingDoc, documentType: UBLDocumentType = UBLDocumentType.INVOICE): void {
     if (!invoice.items) return;
     const creditNote = documentType === UBLDocumentType.CREDIT_NOTE;
+    const totals = computeDocumentTotals(invoice);
     
-    for (const item of invoice.items) {
+    for (const [index, item] of invoice.items.entries()) {
       const invoiceLineNode = doc.createElement(creditNote ? 'cac:CreditNoteLine' : 'cac:InvoiceLine');
       parentElement.appendChild(invoiceLineNode);
       
@@ -529,11 +498,10 @@ export class UBLEncoder extends UBLBaseEncoder {
       quantityElement.textContent = item.unitQuantity.toString();
       invoiceLineNode.appendChild(quantityElement);
       
-      // Line extension amount (line net amount)
-      const itemNetAmount = item.unitNetPrice * item.unitQuantity;
+      // Invoice line net amount (BT-131): quantity × net price, rounded
       const lineExtensionAmountElement = doc.createElement('cbc:LineExtensionAmount');
       lineExtensionAmountElement.setAttribute('currencyID', invoice.currency);
-      lineExtensionAmountElement.textContent = itemNetAmount.toFixed(2);
+      lineExtensionAmountElement.textContent = totals.lineNetAmounts[index].toFixed(totals.minorUnits);
       invoiceLineNode.appendChild(lineExtensionAmountElement);
       
       // Item information
@@ -556,9 +524,8 @@ export class UBLEncoder extends UBLBaseEncoder {
       const classifiedTaxCategoryNode = doc.createElement('cac:ClassifiedTaxCategory');
       itemNode.appendChild(classifiedTaxCategoryNode);
       
-      // Determine tax category ID based on reverse charge
-      const categoryId = invoice.reverseCharge ? 'AE' : 'S';
-      this.appendElement(doc, classifiedTaxCategoryNode, 'cbc:ID', categoryId);
+      // Invoiced item VAT category code (BT-151)
+      this.appendElement(doc, classifiedTaxCategoryNode, 'cbc:ID', totals.lineVatCategories[index]);
       
       // Tax percent with 2 decimal places
       this.appendElement(doc, classifiedTaxCategoryNode, 'cbc:Percent', item.vatPercentage.toFixed(2));

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

@@ -2,6 +2,7 @@ import { BaseEncoder } from '../base/base.encoder.js';
 import type { TAccountingDoc, TCreditNote, TInvoiceDocument } from '../../interfaces/common.js';
 import { UBLDocumentType, UBL_NAMESPACES } from './ubl.types.js';
 import { getWritableDate } from '../utils/date.value.js';
+import { assertVatCategoryWritable } from '../utils/vat.category.js';
 
 /**
  * The children of the document root in the order the UBL 2.1 schema requires
@@ -48,6 +49,8 @@ export abstract class UBLBaseEncoder extends BaseEncoder {
    * @returns UBL XML string
    */
   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 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

@@ -261,7 +261,9 @@ export class XRechnungDecoder extends UBLBaseDecoder {
         subject: subject,
         items: items,
         dueInDays: dueInDays,
-        reverseCharge: false,
+        // reverse charge when every line is VAT category AE; the envelope states it for the
+        // whole document, so a document mixing AE lines with others cannot say it
+        reverseCharge: this.isReverseChargeDocument(),
         currency: currencyCode as finance.TCurrency,
         notes: notes,
         objectActions: [],
@@ -301,6 +303,18 @@ export class XRechnungDecoder extends UBLBaseDecoder {
     }
   }
 
+  /**
+   * Whether every line of the document has the VAT category reverse charge (AE, BT-151)
+   */
+  private isReverseChargeDocument(): boolean {
+    const categories = this.select(
+      '/*/cac:InvoiceLine/cac:Item/cac:ClassifiedTaxCategory/cbc:ID | /*/cac:CreditNoteLine/cac:Item/cac:ClassifiedTaxCategory/cbc:ID',
+      this.doc,
+    );
+    const codes = (Array.isArray(categories) ? categories : []).map((node) => (node.textContent ?? '').trim());
+    return codes.length > 0 && codes.every((code) => code === 'AE');
+  }
+
   /**
    * Reads the preceding invoice references (BG-3): the number (BT-25) and,
    * when stated, the issue date (BT-26) of each.

package/ts/formats/utils/currency.calculator.decimal.ts

@@ -15,12 +15,20 @@ export class DecimalCurrencyCalculator {
   private readonly minorUnits: number;
   private readonly roundingMode: RoundingMode;
   
+  /**
+   * @param currency The currency, whose minor unit sets the rounding scale
+   * @param roundingMode How values are rounded
+   * @param options.maxDecimals The most decimals an amount may have, when fewer than the
+   *   currency's minor unit (EN 16931 allows two, BR-DEC-*)
+   */
   constructor(
     currency: TCurrency,
-    roundingMode: RoundingMode = 'HALF_UP'
+    roundingMode: RoundingMode = 'HALF_UP',
+    options: { maxDecimals?: number } = {}
   ) {
     this.currency = currency;
-    this.minorUnits = getCurrencyMinorUnits(currency);
+    const minorUnits = getCurrencyMinorUnits(currency);
+    this.minorUnits = options.maxDecimals === undefined ? minorUnits : Math.min(minorUnits, options.maxDecimals);
     this.roundingMode = roundingMode;
   }
   

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

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

package/ts/formats/utils/vat.category.ts

@@ -0,0 +1,89 @@
+import type { TAccountingDoc } from '../../interfaces/common.js';
+import { EInvoiceFormatError } from '../../errors.js';
+
+/**
+ * The VAT category codes (UNTDID 5305, EN 16931 BT-118/BT-151) the encoders
+ * write: standard rated, or reverse charge. The envelope states reverse charge
+ * for the whole document (`reverseCharge`); an item carries no category of its
+ * own, so a document cannot mix reverse charge lines with standard rated ones.
+ */
+export type TVatCategoryCode = 'S' | 'AE';
+
+/** The VAT exemption reason (BT-121 code, BT-120 text) a VAT category states */
+export interface IVatExemption {
+  code: string;
+  reason: string;
+}
+
+/**
+ * The VAT category of every line of a document: reverse charge (`AE`) when the
+ * document states it, standard rated (`S`) otherwise.
+ * @param accountingDoc The document
+ */
+export const getVatCategory = (accountingDoc: { reverseCharge?: boolean }): TVatCategoryCode =>
+  accountingDoc.reverseCharge ? 'AE' : 'S';
+
+/**
+ * The exemption reason a reverse charge VAT breakdown states (BR-AE-10): the
+ * code `VATEX-EU-AE` and the wording the law prescribes, "Steuerschuldnerschaft
+ * des Leistungsempfängers" (§ 14a Abs. 1 and 5 UStG). A document in another
+ * language may use the wording of Article 226 Nr. 11a of the VAT Directive in
+ * that language, "Reverse charge" in English (Abschnitt 14a.1 Abs. 6 Satz 2
+ * UStAE). Other categories state none.
+ * @param category The VAT category
+ * @param language The document language
+ */
+export const getVatExemption = (category: TVatCategoryCode, language: string | undefined): IVatExemption | undefined =>
+  category === 'AE'
+    ? {
+        code: 'VATEX-EU-AE',
+        reason: (language ?? '').toLowerCase().startsWith('de')
+          ? 'Steuerschuldnerschaft des Leistungsempfängers'
+          : 'Reverse charge',
+      }
+    : undefined;
+
+/**
+ * Refuses a reverse charge document that lacks what EN 16931 requires of one,
+ * naming the rule; no value is put in place of a missing one.
+ * - BR-AE-05: every line of a reverse charge document has the VAT rate 0; the
+ *   recipient owes the tax, and the invoice states none (§ 14a Abs. 5 Satz 2
+ *   UStG; a stated amount would be owed under § 14c Abs. 1 UStG).
+ * - BR-AE-02: the seller states a VAT identifier (BT-31) and the buyer a VAT
+ *   identifier (BT-48) or a legal registration identifier (BT-47). The rule
+ *   also accepts the seller's tax registration identifier (BT-32, e.g. the
+ *   Steuernummer) or a tax representative's VAT identifier (BT-63) instead of
+ *   BT-31; the envelope can state neither, so a seller without a VAT
+ *   identifier is refused. A domestic § 13b issuer that states only a
+ *   Steuernummer, which § 14 Abs. 4 Satz 1 Nr. 2 UStG allows, is therefore
+ *   refused until the envelope carries a tax number.
+ * @param accountingDoc The document
+ * @param targetFormat The format being written
+ */
+export const assertVatCategoryWritable = (accountingDoc: TAccountingDoc, targetFormat: string): void => {
+  if (!accountingDoc.reverseCharge) {
+    return;
+  }
+  const refuse = (rule: string, message: string): never => {
+    throw new EInvoiceFormatError(`${rule}: ${message}`, { targetFormat, unsupportedFeatures: [rule] });
+  };
+  for (const [index, item] of (accountingDoc.items ?? []).entries()) {
+    if (item.vatPercentage !== 0) {
+      refuse('BR-AE-05', `a reverse charge line has the VAT rate 0, items[${index}].vatPercentage is ${String(item.vatPercentage)}`);
+    }
+  }
+  const seller = accountingDoc.from?.registrationDetails;
+  if (!seller?.vatId) {
+    refuse(
+      'BR-AE-02',
+      'a reverse charge document states the seller VAT identifier (BT-31), from.registrationDetails.vatId is missing; the rule would also accept a tax registration identifier (BT-32) or a tax representative (BT-63), which the envelope cannot state',
+    );
+  }
+  const buyer = accountingDoc.to?.registrationDetails;
+  if (!buyer?.vatId && !buyer?.registrationId) {
+    refuse(
+      'BR-AE-02',
+      'a reverse charge document states the buyer VAT identifier (BT-48) or legal registration identifier (BT-47), to.registrationDetails.vatId and .registrationId are missing',
+    );
+  }
+};

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

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