@fin.cx/einvoice 8.3.1 → 10.0.0

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

@@ -44,8 +44,46 @@ export const getVatExemption = (category: TVatCategoryCode, language: string | u
     : 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.
+ * Whether a VAT rate is a number not greater than zero; a rate that is no
+ * number is refused as such (`findInvalidItemAmounts`), not as BR-S-05
+ * @param rate The rate
+ */
+export const isRateNotAboveZero = (rate: unknown): boolean => typeof rate === 'number' && Number.isFinite(rate) && !(rate > 0);
+
+/** A line written as standard rated (S) whose VAT rate is not greater than zero */
+export interface IStandardRatedLineWithoutRate {
+  index: number;
+  vatPercentage: number;
+}
+
+/**
+ * The first line of a document that is not reverse charge whose VAT rate is not
+ * greater than zero. The encoders write every such line as standard rated (S),
+ * and EN 16931 BR-S-05 asks a standard rated line for a rate greater than zero;
+ * the category the line has (zero rated Z, exempt E, intra-community supply K,
+ * export G, not subject to VAT O) cannot be stated until an item carries a VAT
+ * category of its own.
+ * @param items The document's items
+ */
+export const findStandardRatedLineWithoutRate = (
+  items: TAccountingDoc['items'] | undefined,
+): IStandardRatedLineWithoutRate | undefined => {
+  const index = (items ?? []).findIndex((item) => isRateNotAboveZero(item.vatPercentage));
+  return index < 0 ? undefined : { index, vatPercentage: items![index].vatPercentage };
+};
+
+/**
+ * The refusal or finding for such a line
+ * @param line The line
+ */
+export const standardRatedLineWithoutRateMessage = (line: IStandardRatedLineWithoutRate): string =>
+  `In an Invoice line (BG-25) where the Invoiced item VAT category code (BT-151) is "Standard rated" the Invoiced item VAT rate (BT-152) shall be greater than zero; items[${line.index}].vatPercentage is ${String(line.vatPercentage)}. A line outside reverse charge is written as standard rated (S); its category, zero rated, exempt, intra-community supply or export (Z, E, K, G or O), cannot be stated until an item carries a VAT category of its own`;
+
+/**
+ * Refuses a document whose lines cannot be written with a valid VAT category,
+ * naming the rule: a line outside reverse charge whose rate is not greater than
+ * zero (BR-S-05), and a reverse charge document that lacks what EN 16931
+ * requires of one; 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).
@@ -66,12 +104,16 @@ export const getVatExemption = (category: TVatCategoryCode, language: string | u
  * @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] });
   };
+  if (!accountingDoc.reverseCharge) {
+    const line = findStandardRatedLineWithoutRate(accountingDoc.items);
+    if (line) {
+      refuse('BR-S-05', standardRatedLineWithoutRateMessage(line));
+    }
+    return;
+  }
   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)}`);

package/ts/formats/utils/vat.id.ts

@@ -0,0 +1,24 @@
+/**
+ * The code of the package's own check of the German VAT identification number format. It is no
+ * rule of EN 16931 or XRechnung; the official rules do not check the format of BT-31.
+ */
+export const GERMAN_VAT_ID_FORMAT_CODE = 'EINVOICE-DE-VATID-FORMAT';
+
+/**
+ * The message of a German VAT identification number whose format is not the one the
+ * Bundeszentralamt für Steuern issues (§ 27a Abs. 1 UStG names it as the issuer, not the format)
+ * @param vatId The VAT identification number as stated
+ */
+export const germanVatIdFormatMessage = (vatId: string): string =>
+  `The German VAT identification number (BT-31) is DE followed by nine digits, the format the Bundeszentralamt für Steuern issues; it is "${vatId}"`;
+
+/**
+ * Whether a VAT identification number with the German prefix DE lacks the format the
+ * Bundeszentralamt für Steuern issues, DE followed by nine digits. A number with another prefix, or
+ * none, is not checked. The number is taken as it is written, without removing spaces.
+ * @param vatId The VAT identification number as stated
+ */
+export const isMalformedGermanVatId = (vatId: string | undefined): boolean => {
+  const value = (vatId ?? '').trim();
+  return value.startsWith('DE') && !/^DE[0-9]{9}$/.test(value);
+};

package/ts/formats/validation/conformance.harness.ts

@@ -488,9 +488,9 @@ export class ConformanceTestHarness {
       // VAT rules - Reverse charge
       'BR-AE-01', 'BR-AE-02', 'BR-AE-03', 'BR-AE-04', 'BR-AE-05', 'BR-AE-06', 'BR-AE-07', 'BR-AE-08',
       
-      // VAT rules - Intra-community
-      'BR-K-01', 'BR-K-02', 'BR-K-03', 'BR-K-04', 'BR-K-05', 'BR-K-06', 'BR-K-07', 'BR-K-08',
-      'BR-K-09', 'BR-K-10',
+      // VAT rules - Intra-community supply
+      'BR-IC-01', 'BR-IC-02', 'BR-IC-03', 'BR-IC-04', 'BR-IC-05', 'BR-IC-06', 'BR-IC-07', 'BR-IC-08',
+      'BR-IC-09', 'BR-IC-10', 'BR-IC-11', 'BR-IC-12',
       
       // VAT rules - Export
       'BR-G-01', 'BR-G-02', 'BR-G-03', 'BR-G-04', 'BR-G-05', 'BR-G-06', 'BR-G-07', 'BR-G-08',
@@ -511,7 +511,7 @@ export class ConformanceTestHarness {
    */
   private getRuleCategory(ruleId: string): keyof CoverageReport['byCategory'] | null {
     if (ruleId.startsWith('BR-CO-')) return 'calculation';
-    if (ruleId.match(/^BR-[SZAEKG0]-/)) return 'vat';
+    if (ruleId.match(/^BR-(S|Z|E|AE|IC|G|O)-/)) return 'vat';
     if (ruleId.startsWith('BR-CL-')) return 'codeLists';
     if (ruleId.match(/^BR-2[0-9]/) || ruleId.match(/^BR-3[0-9]/)) return 'lineLevel';
     if (ruleId.match(/^BR-[0-9]/) || ruleId.match(/^BR-1[0-9]/)) return 'document';
@@ -548,7 +548,7 @@ export class ConformanceTestHarness {
       'vat-category-S': ['BR-S-01', 'BR-S-02', 'BR-S-03', 'BR-S-04', 'BR-S-05'],
       'vat-category-Z': ['BR-Z-01', 'BR-Z-02', 'BR-Z-03', 'BR-Z-04', 'BR-Z-05'],
       'vat-category-AE': ['BR-AE-01', 'BR-AE-02', 'BR-AE-03', 'BR-AE-04', 'BR-AE-05', 'BR-AE-06'],
-      'vat-category-K': ['BR-K-01', 'BR-K-02', 'BR-K-03', 'BR-K-04', 'BR-K-05', 'BR-K-06'],
+      'vat-category-K': ['BR-IC-01', 'BR-IC-02', 'BR-IC-03', 'BR-IC-04', 'BR-IC-05', 'BR-IC-06'],
       'vat-category-G': ['BR-G-01', 'BR-G-02', 'BR-G-03', 'BR-G-04', 'BR-G-05', 'BR-G-06'],
       'vat-category-O': ['BR-O-01', 'BR-O-02', 'BR-O-03', 'BR-O-04', 'BR-O-05', 'BR-O-06']
     };

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

@@ -247,32 +247,9 @@ export class EN16931BusinessRulesValidator {
       );
     }
     
-    // BR-CO-16: Amount due for payment = Invoice total with VAT - Paid amount
-    const paidAmount = useDecimal
-      ? new Decimal(invoice.metadata?.paidAmount || 0)
-      : invoice.metadata?.paidAmount || 0;
-    const expectedDueAmount = useDecimal
-      ? (expectedGrossTotal as Decimal).subtract(paidAmount)
-      : (expectedGrossTotal as number) - (paidAmount as number);
-    const declaredDueAmount = useDecimal
-      ? new Decimal(invoice.metadata?.amountDue || (useDecimal ? (expectedGrossTotal as Decimal).toNumber() : expectedGrossTotal))
-      : invoice.metadata?.amountDue || expectedGrossTotal;
-    
-    const isDueEqual = useDecimal
-      ? this.decimalCalculator!.areEqual(expectedDueAmount, declaredDueAmount)
-      : this.currencyCalculator
-        ? this.currencyCalculator.areEqual(expectedDueAmount as number, declaredDueAmount as number)
-        : Math.abs((expectedDueAmount as number) - (declaredDueAmount as number)) < 0.01;
-    
-    if (!isDueEqual) {
-      this.addError(
-        'BR-CO-16',
-        `Amount due (${useDecimal ? (declaredDueAmount as Decimal).toFixed(2) : (declaredDueAmount as number).toFixed(2)}) does not match calculation (${useDecimal ? (expectedDueAmount as Decimal).toFixed(2) : (expectedDueAmount as number).toFixed(2)})`,
-        'amountDue',
-        useDecimal ? (declaredDueAmount as Decimal).toNumber() : declaredDueAmount as number,
-        useDecimal ? (expectedDueAmount as Decimal).toNumber() : expectedDueAmount as number
-      );
-    }
+    // BR-CO-16 (amount due for payment = invoice total with VAT - paid amount) is not checked
+    // here: the envelope has no amount due (BT-115); the encoders derive it from the gross total
+    // and the paid amount (BT-113), and the official rules check it on the written XML
   }
   
   /**

package/ts/formats/validation/facturx.validator.ts

@@ -79,7 +79,7 @@ export class FacturXValidator {
         'dueDate',             // BT-9: Payment due date
       ],
       optional: [
-        'metadata.buyerReference', // BT-10: Buyer reference
+        'buyerReference', // BT-10: Buyer reference
         'metadata.purchaseOrderReference', // BT-13: Purchase order reference
         'metadata.salesOrderReference', // BT-14: Sales order reference
         'metadata.contractReference', // BT-12: Contract reference
@@ -108,7 +108,7 @@ export class FacturXValidator {
         // No items required
       ],
       optional: [
-        'metadata.buyerReference',
+        'buyerReference',
         'metadata.purchaseOrderReference',
         'metadata.contractReference',
       ]
@@ -122,7 +122,7 @@ export class FacturXValidator {
         'issueDate',
         'accountingDocType',
         'currency',
-        'metadata.buyerReference',
+        'buyerReference',
         
         // Seller information
         'from.name',
@@ -411,12 +411,12 @@ export class FacturXValidator {
         
       case FacturXProfile.EN16931:
         // EN16931 requires full compliance - additional checks handled by EN16931 validator
-        if (!invoice.metadata?.buyerReference && !invoice.metadata?.extensions?.purchaseOrderReference) {
+        if (!invoice.buyerReference && !invoice.metadata?.extensions?.purchaseOrderReference) {
           results.push({
             ruleId: 'FX-EN-01',
             severity: 'error',
             message: 'EN16931 profile requires either buyer reference or purchase order reference',
-            field: 'metadata.buyerReference',
+            field: 'buyerReference',
             source: 'FACTURX'
           });
         }

package/ts/formats/validation/integrated.validator.ts

@@ -12,6 +12,7 @@ import { CodeListValidator } from './codelist.validator.js';
 import type { ValidationResult, ValidationOptions, ValidationReport } from './validation.types.js';
 import type { EInvoice } from '../../einvoice.js';
 import { UBL_CUSTOMIZATION_IDS } from '../ubl/ubl.types.js';
+import { isPeppolBisBilling3 } from '../utils/peppol.profile.js';
 
 /**
  * Main validator that combines all validation capabilities
@@ -172,8 +173,7 @@ export class MainValidator {
       return 'XRECHNUNG_3.0';
     }
     
-    if (profileId.includes('peppol') || customizationId.includes('peppol') ||
-        profileId.includes('urn:fdc:peppol.eu')) {
+    if (isPeppolBisBilling3(customizationId)) {
       return 'PEPPOL_BIS_3.0';
     }
     
@@ -215,20 +215,7 @@ export class MainValidator {
    * Check if invoice is PEPPOL
    */
   private isPeppolInvoice(invoice: EInvoice): boolean {
-    const profileId = invoice.metadata?.profileId || '';
-    const customizationId = invoice.metadata?.customizationId || '';
-    
-    const peppolProfiles = [
-      'urn:fdc:peppol.eu:2017:poacc:billing:3.0',
-      'urn:fdc:peppol.eu:2017:poacc:billing:01:1.0',
-      'peppol-bis-3',
-      'peppol'
-    ];
-    
-    return peppolProfiles.some(profile => 
-      profileId.toLowerCase().includes(profile.toLowerCase()) ||
-      customizationId.toLowerCase().includes(profile.toLowerCase())
-    );
+    return isPeppolBisBilling3(invoice.metadata?.customizationId);
   }
   
   /**

package/ts/formats/validation/peppol.validator.ts

@@ -5,6 +5,7 @@
 
 import type { ValidationResult } from './validation.types.js';
 import type { EInvoice } from '../../einvoice.js';
+import { isPeppolBisBilling3 } from '../utils/peppol.profile.js';
 
 /**
  * PEPPOL BIS 3.0 Validator
@@ -50,20 +51,8 @@ export class PeppolValidator {
    * Check if invoice is PEPPOL
    */
   private isPeppolInvoice(invoice: EInvoice): boolean {
-    const profileId = invoice.metadata?.profileId || '';
-    const customizationId = invoice.metadata?.customizationId || '';
-    
-    const peppolProfiles = [
-      'urn:fdc:peppol.eu:2017:poacc:billing:3.0',
-      'urn:fdc:peppol.eu:2017:poacc:billing:01:1.0',
-      'peppol-bis-3',
-      'peppol'
-    ];
-    
-    return peppolProfiles.some(profile => 
-      profileId.toLowerCase().includes(profile.toLowerCase()) ||
-      customizationId.toLowerCase().includes(profile.toLowerCase())
-    );
+    // the PEPPOL BIS Billing 3.0 specification identifier (BT-24), not a derivative that names PEPPOL
+    return isPeppolBisBilling3(invoice.metadata?.customizationId);
   }
   
   /**
@@ -393,12 +382,12 @@ export class PeppolValidator {
     
     // PEPPOL-B-01: Invoice must have a buyer reference or purchase order reference
     const purchaseOrderRef = invoice.metadata?.extensions?.purchaseOrderReference;
-    if (!invoice.metadata?.buyerReference && !purchaseOrderRef) {
+    if (!invoice.buyerReference && !purchaseOrderRef) {
       results.push({
         ruleId: 'PEPPOL-B-01',
         severity: 'error',
         message: 'Invoice must have either a buyer reference (BT-10) or purchase order reference (BT-13)',
-        field: 'metadata.buyerReference',
+        field: 'buyerReference',
         source: 'PEPPOL'
       });
     }

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

@@ -2,10 +2,16 @@
  * Enhanced validation types for EN16931 compliance
  */
 
+/**
+ * The source of a check of the package's own, one no official rule set states
+ * (such as `EINVOICE-DE-VATID-FORMAT`), so it is not attributed to a standard
+ */
+export const EINVOICE_RULE_SOURCE = 'EINVOICE';
+
 export interface ValidationResult {
   // Core identification
   ruleId: string;                    // e.g., "BR-CO-14"
-  source: string;                     // e.g., "EN16931", "PEPPOL", "XRECHNUNG"
+  source: string;                     // e.g., "EN16931", "PEPPOL", "XRECHNUNG"; EINVOICE_RULE_SOURCE for a check of the package's own
   severity: 'error' | 'warning' | 'info';
   message: string;