@fin.cx/einvoice 8.2.2 → 8.2.3

package/ts/formats/cii/zugferd/zugferd.encoder.ts

@@ -249,6 +249,17 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
     nameElement.textContent = party.name;
     partyElement.appendChild(nameElement);
 
+    // Legal registration identifier (BT-30 seller, BT-47 buyer), e.g. the commercial register
+    // number; in the schema order it follows the name. It is no tax registration: the scheme
+    // FC of ram:SpecifiedTaxRegistration is the seller's tax number (BT-32)
+    if (party.registrationDetails && party.registrationDetails.registrationId) {
+      const legalOrganizationElement = doc.createElement('ram:SpecifiedLegalOrganization');
+      const legalIdElement = doc.createElement('ram:ID');
+      legalIdElement.textContent = party.registrationDetails.registrationId;
+      legalOrganizationElement.appendChild(legalIdElement);
+      partyElement.appendChild(legalOrganizationElement);
+    }
+
     // Add postal address
     const addressElement = doc.createElement('ram:PostalTradeAddress');
 
@@ -299,15 +310,6 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
       partyElement.appendChild(taxRegistrationElement);
     }
 
-    // Add registration ID if available
-    if (party.registrationDetails && party.registrationDetails.registrationId) {
-      const regRegistrationElement = doc.createElement('ram:SpecifiedTaxRegistration');
-      const regIdElement = doc.createElement('ram:ID');
-      regIdElement.setAttribute('schemeID', 'FC');
-      regIdElement.textContent = party.registrationDetails.registrationId;
-      regRegistrationElement.appendChild(regIdElement);
-      partyElement.appendChild(regRegistrationElement);
-    }
   }
 
   /**
@@ -460,8 +462,8 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
     // the EN 16931 totals in decimal arithmetic, rounded as the business rules check them
     const totals = computeDocumentTotals(invoice);
 
-    // VAT breakdown (BG-23), one per rate
-    for (const { rate, taxableAmount, taxAmount } of totals.vatGroups) {
+    // VAT breakdown (BG-23), one per VAT category and rate
+    for (const { category, rate, taxableAmount, taxAmount, exemption } of totals.vatGroups) {
       const taxElement = doc.createElement('ram:ApplicableTradeTax');
 
       // VAT category tax amount (BT-117)
@@ -473,6 +475,13 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
       const typeCodeElement = doc.createElement('ram:TypeCode');
       typeCodeElement.textContent = 'VAT';
       taxElement.appendChild(typeCodeElement);
+
+      // VAT exemption reason text (BT-120), for reverse charge (BR-AE-10)
+      if (exemption) {
+        const exemptionReasonElement = doc.createElement('ram:ExemptionReason');
+        exemptionReasonElement.textContent = exemption.reason;
+        taxElement.appendChild(exemptionReasonElement);
+      }
       
       // VAT category taxable amount (BT-116)
       const basisAmountElement = doc.createElement('ram:BasisAmount');
@@ -481,8 +490,15 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
       
       // Add category code
       const categoryCodeElement = doc.createElement('ram:CategoryCode');
-      categoryCodeElement.textContent = invoice.reverseCharge ? 'AE' : 'S';
+      categoryCodeElement.textContent = category;
       taxElement.appendChild(categoryCodeElement);
+
+      // VAT exemption reason code (BT-121)
+      if (exemption) {
+        const exemptionReasonCodeElement = doc.createElement('ram:ExemptionReasonCode');
+        exemptionReasonCodeElement.textContent = exemption.code;
+        taxElement.appendChild(exemptionReasonCodeElement);
+      }
       
       // Add rate
       const rateElement = doc.createElement('ram:RateApplicablePercent');
@@ -594,7 +610,7 @@ export class ZUGFeRDEncoder extends CIIBaseEncoder {
 
         // Add tax category code
         const taxCategoryCodeElement = doc.createElement('ram:CategoryCode');
-        taxCategoryCodeElement.textContent = invoice.reverseCharge ? 'AE' : 'S';
+        taxCategoryCodeElement.textContent = totals.lineVatCategories[index]; // BT-151
         taxElement.appendChild(taxCategoryCodeElement);
 
         // Add tax rate

package/ts/formats/cii/zugferd/zugferd.v1.decoder.ts

@@ -35,6 +35,19 @@ export class ZUGFeRDV1Decoder extends CIIBaseDecoder {
     };
   }
 
+  /**
+   * Whether every line of the v1 document has the VAT category reverse charge (AE), read with
+   * the v1 namespaces from the line settlement (`ram:SpecifiedSupplyChainTradeSettlement`)
+   */
+  protected override isReverseChargeDocument(): boolean {
+    const categories = zugferdV1Select(
+      '/rsm:CrossIndustryDocument/rsm:SpecifiedSupplyChainTradeTransaction/ram:IncludedSupplyChainTradeLineItem/ram:SpecifiedSupplyChainTradeSettlement/ram:ApplicableTradeTax/ram:CategoryCode',
+      this.doc,
+    );
+    const codes = (Array.isArray(categories) ? categories : []).map((node) => ((node as Node).textContent ?? '').trim());
+    return codes.length > 0 && codes.every((code) => code === 'AE');
+  }
+
   /**
    * Reads the issue date of the v1 header (`rsm:HeaderExchangedDocument`); a
    * missing or invalid one is refused with an `EInvoiceParsingError`.
@@ -147,8 +160,8 @@ export class ZUGFeRDV1Decoder extends CIIBaseDecoder {
     // Extract the actual delivery date, if stated
     const deliveryDate = this.extractDeliveryDate();
 
-    // Check for reverse charge
-    const reverseCharge = this.exists('//ram:SpecifiedTradeAllowanceCharge/ram:ReasonCode[text()="62"]');
+    // Reverse charge: every line has the VAT category AE
+    const reverseCharge = this.isReverseChargeDocument();
 
     // Create the common invoice data
     const invoiceData = {
@@ -217,8 +230,13 @@ export class ZUGFeRDV1Decoder extends CIIBaseDecoder {
     // Extract VAT ID
     const vatId = this.getText(`${partyXPath}/ram:SpecifiedTaxRegistration/ram:ID[@schemeID="VA"]`) || '';
 
-    // Extract registration ID
-    const registrationId = this.getText(`${partyXPath}/ram:SpecifiedTaxRegistration/ram:ID[@schemeID="FC"]`) || '';
+    // the legal registration identifier, and a tax number (scheme FC) as before when that is all
+    // the document states; the party is still read with the ZUGFeRD 2 namespaces (the known v1
+    // header defect), so for a v1 document this finds nothing yet
+    const registrationId =
+      this.getText(`${partyXPath}/ram:SpecifiedLegalOrganization/ram:ID`) ||
+      this.getText(`${partyXPath}/ram:SpecifiedTaxRegistration/ram:ID[@schemeID="FC"]`) ||
+      '';
 
     // Create contact object
     return {

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

@@ -395,7 +395,7 @@ export class UBLEncoder extends UBLBaseEncoder {
     taxTotalNode.appendChild(taxAmountElement);
 
     // VAT breakdown (BG-23), one subtotal per rate
-    for (const { rate, taxableAmount, taxAmount } of totals.vatGroups) {
+    for (const { category, rate, taxableAmount, taxAmount, exemption } of totals.vatGroups) {
       const taxSubtotalNode = doc.createElement('cac:TaxSubtotal');
       taxTotalNode.appendChild(taxSubtotalNode);
 
@@ -415,17 +415,14 @@ export class UBLEncoder extends UBLBaseEncoder {
       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
@@ -527,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/document.totals.ts

@@ -3,6 +3,7 @@ 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 {
@@ -61,13 +62,17 @@ export const getDocumentCalculator = (currency: TAccountingDoc['currency']): Dec
   new DecimalCurrencyCalculator(currency, 'HALF_UP', { maxDecimals: EN16931_MAX_AMOUNT_DECIMALS });
 
 /**
- * The VAT breakdown of one rate (BG-23): the taxable amount (BT-116), the tax
- * on it (BT-117) and the rate (BT-119).
+ * 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;
 }
 
 /**
@@ -80,11 +85,13 @@ export interface IDocumentTotals {
   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), in the order the rates first appear */
+  /** 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;
@@ -100,16 +107,20 @@ export interface IDocumentTotals {
  * decimals (BR-DEC-*): each line net amount (BT-131) is quantity × net price
  * rounded; the sum of line net amounts (BT-106) is their sum (BR-CO-10);
  * each VAT category taxable amount (BT-116) is the sum of the line net amounts
- * at that rate, and its tax amount (BT-117) is BT-116 × rate / 100 rounded
- * (BR-CO-17); the total VAT (BT-110) is the sum of the category tax amounts
+ * 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'>): IDocumentTotals => {
+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 taxableByRate = new Map<number, 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) {
@@ -121,19 +132,31 @@ export const computeDocumentTotals = (accountingDoc: Pick<TAccountingDoc, 'curre
   for (const item of accountingDoc.items ?? []) {
     const lineNet = calculator.calculateLineNet(item.unitQuantity, item.unitNetPrice);
     lineNetAmounts.push(lineNet);
-    taxableByRate.set(item.vatPercentage, (taxableByRate.get(item.vatPercentage) ?? Decimal.ZERO).add(lineNet));
+    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[] = [...taxableByRate.entries()].map(([rate, taxableAmount]) => ({
-    rate,
-    taxableAmount: calculator.round(taxableAmount),
-    taxAmount: calculator.calculateVAT(taxableAmount, rate),
-  }));
+  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,

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',
+    );
+  }
+};