import { BaseValidator } from './base.validator.js'; import { ValidationLevel } from '../interfaces.js'; import type { ValidationResult, ValidationError } from '../interfaces.js'; import * as xpath from 'xpath'; import { DOMParser } from 'xmldom'; /** * Validator for Factur-X/ZUGFeRD invoice format * Implements validation rules according to EN16931 and Factur-X specification */ export class FacturXValidator extends BaseValidator { // XML namespaces for Factur-X/ZUGFeRD private static NS_RSMT = 'urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100'; private static NS_RAM = 'urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100'; private static NS_UDT = 'urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100'; // XML document for processing private xmlDoc: Document | null = null; // Factur-X profile (BASIC, EN16931, EXTENDED, etc.) private profile: string = ''; constructor(xml: string) { super(xml); try { // Parse XML document this.xmlDoc = new DOMParser().parseFromString(xml, 'application/xml'); // Determine Factur-X profile this.detectProfile(); } catch (error) { this.addError('FX-PARSE', `Failed to parse XML: ${error}`, '/'); } } /** * Validates the Factur-X invoice against the specified level * @param level Validation level * @returns Validation result */ public validate(level: ValidationLevel = ValidationLevel.SYNTAX): ValidationResult { // Reset errors this.errors = []; // Check if document was parsed successfully if (!this.xmlDoc) { return { valid: false, errors: this.errors, level: level }; } // Perform validation based on level let valid = true; if (level === ValidationLevel.SYNTAX) { valid = this.validateSchema(); } else if (level === ValidationLevel.SEMANTIC) { valid = this.validateSchema() && this.validateStructure(); } else if (level === ValidationLevel.BUSINESS) { valid = this.validateSchema() && this.validateStructure() && this.validateBusinessRules(); } return { valid, errors: this.errors, level }; } /** * Validates XML against schema * @returns True if schema validation passed */ protected validateSchema(): boolean { // Basic schema validation (simplified for now) if (!this.xmlDoc) return false; // Check for root element const root = this.xmlDoc.documentElement; if (!root || root.nodeName !== 'rsm:CrossIndustryInvoice') { this.addError('FX-SCHEMA-1', 'Root element must be rsm:CrossIndustryInvoice', '/'); return false; } // Check for required namespaces if (!root.lookupNamespaceURI('rsm') || !root.lookupNamespaceURI('ram')) { this.addError('FX-SCHEMA-2', 'Required namespaces rsm and ram must be declared', '/'); return false; } return true; } /** * Validates structure of the XML document * @returns True if structure validation passed */ private validateStructure(): boolean { if (!this.xmlDoc) return false; let valid = true; // Check for required main sections const sections = [ 'rsm:ExchangedDocumentContext', 'rsm:ExchangedDocument', 'rsm:SupplyChainTradeTransaction' ]; for (const section of sections) { if (!this.exists(section)) { this.addError('FX-STRUCT-1', `Required section ${section} is missing`, '/rsm:CrossIndustryInvoice'); valid = false; } } // Check for SupplyChainTradeTransaction sections if (this.exists('rsm:SupplyChainTradeTransaction')) { const tradeSubsections = [ 'ram:ApplicableHeaderTradeAgreement', 'ram:ApplicableHeaderTradeDelivery', 'ram:ApplicableHeaderTradeSettlement' ]; for (const subsection of tradeSubsections) { if (!this.exists(`rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeTransaction/${subsection}`)) { this.addError('FX-STRUCT-2', `Required subsection ${subsection} is missing`, '/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeTransaction'); valid = false; } } } return valid; } /** * Validates business rules * @returns True if business rule validation passed */ protected validateBusinessRules(): boolean { if (!this.xmlDoc) return false; let valid = true; // BR-16: Amount due for payment (BT-115) = Invoice total amount with VAT (BT-112) - Paid amount (BT-113) valid = this.validateAmounts() && valid; // BR-CO-3: Value added tax point date (BT-7) and Value added tax point date code (BT-8) are mutually exclusive valid = this.validateMutuallyExclusiveFields() && valid; // BR-S-1: An Invoice that contains a line (BG-25) where the Invoiced item VAT category code (BT-151) is "Standard rated" // shall contain the Seller VAT Identifier (BT-31), the Seller tax registration identifier (BT-32) // and/or the Seller tax representative VAT identifier (BT-63). valid = this.validateSellerVatIdentifier() && valid; return valid; } /** * Detects Factur-X profile from the XML */ private detectProfile(): void { if (!this.xmlDoc) return; // Look for profile identifier const profileNode = xpath.select1( 'string(//rsm:ExchangedDocumentContext/ram:GuidelineSpecifiedDocumentContextParameter/ram:ID)', this.xmlDoc ); if (profileNode) { const profileText = profileNode.toString(); if (profileText.includes('BASIC')) { this.profile = 'BASIC'; } else if (profileText.includes('EN16931')) { this.profile = 'EN16931'; } else if (profileText.includes('EXTENDED')) { this.profile = 'EXTENDED'; } else if (profileText.includes('MINIMUM')) { this.profile = 'MINIMUM'; } } } /** * Validates amount calculations in the invoice * @returns True if amount validation passed */ private validateAmounts(): boolean { if (!this.xmlDoc) return false; try { // Extract amounts const totalAmount = this.getNumberValue( '//ram:ApplicableHeaderTradeSettlement/ram:SpecifiedTradeSettlementHeaderMonetarySummation/ram:GrandTotalAmount' ); const paidAmount = this.getNumberValue( '//ram:ApplicableHeaderTradeSettlement/ram:SpecifiedTradeSettlementHeaderMonetarySummation/ram:TotalPrepaidAmount' ) || 0; const dueAmount = this.getNumberValue( '//ram:ApplicableHeaderTradeSettlement/ram:SpecifiedTradeSettlementHeaderMonetarySummation/ram:DuePayableAmount' ); // Calculate expected due amount const expectedDueAmount = totalAmount - paidAmount; // Compare with a small tolerance for rounding errors if (Math.abs(dueAmount - expectedDueAmount) > 0.01) { this.addError( 'BR-16', `Amount due for payment (${dueAmount}) must equal Invoice total amount with VAT (${totalAmount}) - Paid amount (${paidAmount})`, '//ram:ApplicableHeaderTradeSettlement/ram:SpecifiedTradeSettlementHeaderMonetarySummation' ); return false; } return true; } catch (error) { this.addError('FX-AMOUNT', `Error validating amounts: ${error}`, '/'); return false; } } /** * Validates mutually exclusive fields * @returns True if validation passed */ private validateMutuallyExclusiveFields(): boolean { if (!this.xmlDoc) return false; try { // Check for VAT point date and code (BR-CO-3) const vatPointDate = this.exists('//ram:ApplicableHeaderTradeSettlement/ram:ApplicableTradeTax/ram:TaxPointDate'); const vatPointDateCode = this.exists('//ram:ApplicableHeaderTradeSettlement/ram:ApplicableTradeTax/ram:DueDateTypeCode'); if (vatPointDate && vatPointDateCode) { this.addError( 'BR-CO-3', 'Value added tax point date and Value added tax point date code are mutually exclusive', '//ram:ApplicableHeaderTradeSettlement/ram:ApplicableTradeTax' ); return false; } return true; } catch (error) { this.addError('FX-MUTUAL', `Error validating mutually exclusive fields: ${error}`, '/'); return false; } } /** * Validates seller VAT identifier requirements * @returns True if validation passed */ private validateSellerVatIdentifier(): boolean { if (!this.xmlDoc) return false; try { // Check if there are any standard rated line items const standardRatedItems = this.exists( '//ram:SpecifiedLineTradeSettlement/ram:ApplicableTradeTax/ram:CategoryCode[text()="S"]' ); if (standardRatedItems) { // Check for seller VAT identifier const sellerVatId = this.exists('//ram:ApplicableHeaderTradeAgreement/ram:SellerTradeParty/ram:SpecifiedTaxRegistration/ram:ID[@schemeID="VA"]'); const sellerTaxId = this.exists('//ram:ApplicableHeaderTradeAgreement/ram:SellerTradeParty/ram:SpecifiedTaxRegistration/ram:ID[@schemeID="FC"]'); const sellerTaxRepId = this.exists('//ram:ApplicableHeaderTradeAgreement/ram:SellerTaxRepresentativeTradeParty/ram:SpecifiedTaxRegistration/ram:ID[@schemeID="VA"]'); if (!sellerVatId && !sellerTaxId && !sellerTaxRepId) { this.addError( 'BR-S-1', 'An Invoice with standard rated items must contain the Seller VAT Identifier, Tax registration identifier or Tax representative VAT identifier', '//ram:ApplicableHeaderTradeAgreement/ram:SellerTradeParty' ); return false; } } return true; } catch (error) { this.addError('FX-VAT', `Error validating seller VAT identifier: ${error}`, '/'); return false; } } /** * Helper method to check if a node exists * @param xpathExpression XPath to check * @returns True if node exists */ private exists(xpathExpression: string): boolean { if (!this.xmlDoc) return false; const nodes = xpath.select(xpathExpression, this.xmlDoc); // Handle different return types from xpath.select() if (Array.isArray(nodes)) { return nodes.length > 0; } return nodes ? true : false; } /** * Helper method to get a number value from XPath * @param xpathExpression XPath to get number from * @returns Number value or NaN if not found */ private getNumberValue(xpathExpression: string): number { if (!this.xmlDoc) return NaN; const node = xpath.select1(`string(${xpathExpression})`, this.xmlDoc); return node ? parseFloat(node.toString()) : NaN; } }