einvoice/readme.md

@fin.cx/einvoice

A comprehensive TypeScript library for creating, manipulating, and embedding XML invoice data within PDF files, supporting multiple European electronic invoice standards including ZUGFeRD (v1 & v2), Factur-X, XRechnung, UBL, and FatturaPA.

Features

• Multi-format support: Process invoices in ZUGFeRD (v1 & v2), Factur-X, XRechnung, UBL, and FatturaPA
• PDF handling: Extract XML from PDF/A-3 invoices and embed XML into PDFs with robust error handling
• Validation: Validate invoices against format-specific rules with detailed error reporting
• Conversion: Convert between different invoice formats while preserving data integrity
• TypeScript: Fully typed API with TypeScript definitions following @tsclass/tsclass standards
• Modular architecture: Extensible design with specialized components
• Robust error handling: Detailed error information and graceful fallbacks
• High performance: Fast validation (~2.2ms) and efficient memory usage (~136KB per validation)

Install

To install @fin.cx/einvoice, you'll need a package manager. We recommend using pnpm:

# Using pnpm (recommended)
pnpm add @fin.cx/einvoice

# Using npm
npm install @fin.cx/einvoice

# Using yarn
yarn add @fin.cx/einvoice

Usage

The @fin.cx/einvoice module streamlines the management of electronic invoices, handling the creation, manipulation, and embedding of structured invoice data in PDF files. Below are examples of common use cases.

Quick Start

import { EInvoice } from '@fin.cx/einvoice';

// Load from XML file
const invoice = await EInvoice.fromFile('invoice.xml');

// Load from XML string
const invoice2 = await EInvoice.fromXml(xmlString);

// Load from PDF with embedded XML
const invoice3 = await EInvoice.fromPdf(pdfBuffer);

// Convert between formats
const xrechnungXml = await invoice.exportXml('xrechnung');
const facturxXml = await invoice.exportXml('facturx');
const ublXml = await invoice.exportXml('ubl');

Basic Usage

import { EInvoice } from '@fin.cx/einvoice';
import { promises as fs } from 'fs';

// Create a new invoice
const invoice = new EInvoice();
invoice.id = 'INV-2023-001';
invoice.from = {
  name: 'Supplier Company',
  type: 'company',
  address: {
    streetName: 'Main Street',
    houseNumber: '123',
    city: 'Berlin',
    postalCode: '10115',
    country: 'Germany',
    countryCode: 'DE'
  },
  registrationDetails: {
    vatId: 'DE123456789',
    registrationId: 'HRB 123456'
  }
};
invoice.to = {
  name: 'Customer Company',
  type: 'company',
  address: {
    streetName: 'Customer Street',
    houseNumber: '456',
    city: 'Paris',
    postalCode: '75001',
    country: 'France',
    countryCode: 'FR'
  },
  registrationDetails: {
    vatId: 'FR87654321',
    registrationId: 'RCS 654321'
  }
};

// Add payment options
invoice.paymentOptions = {
  info: 'Please transfer to our bank account',
  sepaConnection: {
    iban: 'DE89370400440532013000',
    bic: 'COBADEFFXXX'
  }
};

// Add invoice items
invoice.items = [
  {
    position: 1,
    name: 'Product A',
    articleNumber: 'PROD-001',
    unitQuantity: 2,
    unitNetPrice: 100,
    vatPercentage: 19,
    unitType: 'EA'
  },
  {
    position: 2,
    name: 'Service B',
    articleNumber: 'SERV-001',
    unitQuantity: 1,
    unitNetPrice: 200,
    vatPercentage: 19,
    unitType: 'EA'
  }
];

// Export to XML
const xml = await invoice.exportXml('zugferd');

// Load from XML
const loadedInvoice = await EInvoice.fromXml(xml);

// Load from PDF
const pdfBuffer = await fs.readFile('invoice.pdf');
const invoiceFromPdf = await EInvoice.fromPdf(pdfBuffer);

// Export to PDF with embedded XML
const pdfWithXml = await invoice.exportPdf('facturx');
await fs.writeFile('invoice-with-xml.pdf', pdfWithXml.buffer);

Working with Different Invoice Formats

// Load a ZUGFeRD invoice
const zugferdXml = await fs.readFile('zugferd-invoice.xml', 'utf8');
const zugferdInvoice = await EInvoice.fromXml(zugferdXml);

// Load a Factur-X invoice
const facturxXml = await fs.readFile('facturx-invoice.xml', 'utf8');
const facturxInvoice = await EInvoice.fromXml(facturxXml);

// Load an XRechnung invoice
const xrechnungXml = await fs.readFile('xrechnung-invoice.xml', 'utf8');
const xrechnungInvoice = await EInvoice.fromXml(xrechnungXml);

// Export as different formats
const facturxXml = await zugferdInvoice.exportXml('facturx');
const ublXml = await facturxInvoice.exportXml('ubl');
const xrechnungXml = await zugferdInvoice.exportXml('xrechnung');

PDF Handling

// Extract XML from PDF
const pdfBuffer = await fs.readFile('invoice.pdf');
const invoice = await EInvoice.fromPdf(pdfBuffer);

// Check the detected format
console.log(`Detected format: ${invoice.getFormat()}`);

// Embed XML into PDF
invoice.pdf = {
  name: 'invoice.pdf',
  id: 'invoice-1234',
  metadata: { textExtraction: '' },
  buffer: await fs.readFile('document.pdf')
};

const pdfWithInvoice = await invoice.exportPdf('facturx');
await fs.writeFile('invoice-with-xml.pdf', pdfWithInvoice.buffer);

Validating Invoices

// Validate an invoice
const validationResult = await invoice.validate();
if (validationResult.valid) {
  console.log('Invoice is valid');
} else {
  console.log('Validation errors:', validationResult.errors);
}

// Validate at different levels
const syntaxValidation = await invoice.validate(ValidationLevel.SYNTAX);
const semanticValidation = await invoice.validate(ValidationLevel.SEMANTIC);
const businessValidation = await invoice.validate(ValidationLevel.BUSINESS);

Error Handling

try {
  const invoice = await EInvoice.fromFile('invoice.xml');
  const result = await invoice.validate();
  
  if (!result.valid) {
    for (const error of result.errors) {
      console.log(`Error at ${error.path}: ${error.message}`);
    }
  }
} catch (error) {
  if (error instanceof ParseError) {
    console.error('Failed to parse XML:', error.message);
  } else if (error instanceof ValidationError) {
    console.error('Validation failed:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

Converting Between Formats

// Load a ZUGFeRD invoice and convert to various formats
const zugferdInvoice = await EInvoice.fromFile('zugferd.xml');

// Convert to XRechnung (German standard)
const xrechnungXml = await zugferdInvoice.exportXml('xrechnung');

// Convert to UBL format
const ublXml = await zugferdInvoice.exportXml('ubl');

// Convert to Factur-X
const facturxXml = await zugferdInvoice.exportXml('facturx');

// Convert to generic CII format
const ciiXml = await zugferdInvoice.exportXml('cii');

// All conversions preserve:
// - Invoice ID and dates
// - Party information
// - Line items with descriptions
// - Tax calculations
// - Payment terms
// - Notes and references

Architecture

EInvoice implements a sophisticated plugin-based, factory-driven architecture that excels at handling multiple European e-invoicing standards while maintaining clean separation of concerns.

Design Philosophy

The library follows these architectural principles:

• Single Responsibility: Each component has one clear purpose
• Open/Closed: Easy to extend with new formats without modifying existing code
• Dependency Inversion: Core logic depends on abstractions, not implementations
• Interface Segregation: Small, focused interfaces for maximum flexibility

Core Components

Central Classes

• EInvoice: High-level API facade implementing the TInvoice interface from @tsclass/tsclass
• FormatDetector: Multi-strategy format detection using namespace analysis and content patterns
• Error Classes: Specialized errors (ParseError, ValidationError, ConversionError) with context

Factory Pattern Implementation

// Three main factories orchestrate format-specific operations
DecoderFactory.getDecoder(format: InvoiceFormat, xml: string)
EncoderFactory.getEncoder(format: ExportFormat) 
ValidatorFactory.getValidator(format: InvoiceFormat)

Decoder Hierarchy

BaseDecoder (abstract)
├── CIIDecoder (abstract)
│   ├── FacturXDecoder
│   ├── ZUGFeRDDecoder  
│   └── ZUGFeRDV1Decoder
└── UBLDecoder
    └── XRechnungDecoder

Encoder Hierarchy

BaseEncoder (abstract)
├── CIIEncoder (abstract)
│   ├── FacturXEncoder
│   └── ZUGFeRDEncoder
└── UBLEncoder
    └── XRechnungEncoder

PDF Processing Architecture

• PDFExtractor: Implements chain of responsibility pattern with three extraction strategies:
  • StandardExtractor: PDF/A-3 embedded files via /EmbeddedFiles
  • AssociatedExtractor: Associated files via /AF entry
  • TextExtractor: Pattern matching in PDF text stream
• PDFEmbedder: Creates PDF/A-3 compliant documents with embedded XML

Data Flow

XML/PDF Input → Format Detection → Decoder → TInvoice Model → Encoder → XML/PDF Output
                                              ↓
                                          Validation

Key Design Patterns

1. Factory Pattern: Dynamic creation of format-specific handlers
2. Strategy Pattern: Different algorithms for each invoice format
3. Template Method: Base classes define processing skeleton
4. Chain of Responsibility: PDF extractors with fallback strategies
5. Facade Pattern: EInvoice class simplifies complex subsystems

This modular architecture ensures maximum extensibility, maintainability, and compatibility across all supported invoice formats.

Supported Invoice Formats

Format	Version	Read	Write	Validate	Notes
ZUGFeRD	1.0	✅	✅	✅	Legacy format, full support
ZUGFeRD	2.0/2.1	✅	✅	✅	Current German standard
Factur-X	1.0	✅	✅	✅	French/German standard
XRechnung	2.0+	✅	✅	✅	German public sector
UBL	2.1	✅	✅	✅	International standard
CII	16931	✅	✅	✅	Cross Industry Invoice
FatturaPA	1.2	✅	✅	✅	Italian standard

Performance Metrics

The library is optimized for both speed and memory efficiency:

Operation	Average Time	Memory Usage
Format detection	~0.1ms	Minimal
XML parsing	~0.5ms	~100KB
Validation	~2.2ms	~136KB
Format conversion	~0.6ms	~150KB
PDF extraction	~5ms	~1MB
PDF embedding	~10ms	~2MB

Benchmarks

// Performance monitoring
import { PerformanceTracker } from '@fin.cx/einvoice';

const tracker = new PerformanceTracker('invoice-processing');
const { result, metric } = await tracker.track('validation', async () => {
  return await invoice.validate();
});

console.log(`Validation took ${metric.duration}ms`);

Implementation Details

Advanced Date Handling

The library implements sophisticated date parsing for different formats:

// CII formats use special date format codes
// Format 102: YYYYMMDD (e.g., "20240315")
// Format 610: YYYYMM (e.g., "202403")
// Automatic detection and parsing based on format attribute

Character Encoding and Special Characters

Full Unicode support with automatic XML escaping:

// Supports all Unicode including emojis and special characters
invoice.notes = ['Invoice for services 🚀', '中文发票', 'Facture française'];

// Automatic XML entity escaping
invoice.description = 'Products & Services <special> "quoted"';
// Becomes: Products &amp; Services &lt;special&gt; &quot;quoted&quot;

Round-Trip Data Preservation

The library guarantees 100% data preservation through metadata:

// Format-specific fields are preserved in metadata.extensions
const zugferdInvoice = await EInvoice.fromFile('zugferd.xml');
console.log(zugferdInvoice.metadata.extensions); // Original ZUGFeRD fields

// Convert to UBL and back - no data loss
const ublXml = await zugferdInvoice.exportXml('ubl');
const backToZugferd = await EInvoice.fromXml(ublXml);
const zugferdXml2 = await backToZugferd.exportXml('zugferd');
// zugferdXml2 contains all original data

Tax Calculation Engine

Efficient tax grouping and calculation:

// Automatic tax breakdown by rate
const taxBreakdown = invoice.calculateTaxBreakdown();
// Returns: Map<number, { base: number, tax: number }>
// Example: { 19 => { base: 1000, tax: 190 }, 7 => { base: 500, tax: 35 } }

Advanced Validation

Three-layer validation with detailed business rules:

// Validation levels cascade
const syntaxResult = await invoice.validate(ValidationLevel.SYNTAX);    // XML structure
const semanticResult = await invoice.validate(ValidationLevel.SEMANTIC); // Field content
const businessResult = await invoice.validate(ValidationLevel.BUSINESS); // EN16931 rules

// Business rules include:
// - BR-CO-10: Sum of line amounts = invoice total
// - BR-CO-13: Sum of allowances calculation
// - BR-CO-15: Invoice total with VAT calculation
// All with 0.01 tolerance for floating-point

Error Recovery Mechanisms

Sophisticated error handling with recovery:

try {
  const invoice = await EInvoice.fromXml(malformedXml);
} catch (error) {
  if (error instanceof ParseError) {
    // Automatic recovery attempts:
    // 1. BOM removal
    // 2. Entity fixing
    // 3. Namespace correction
    // 4. Encoding detection
  }
}

Performance Optimizations

• Quick format detection: String checks before DOM parsing
• Lazy loading: Format handlers loaded on demand
• Efficient calculations: Single-pass tax grouping
• Memory efficiency: ~136KB per validation

Advanced Usage

Custom Encoders and Decoders

// Using specific encoders
import { ZUGFeRDEncoder, FacturXEncoder, UBLEncoder } from '@fin.cx/einvoice';

// Create ZUGFeRD XML
const zugferdEncoder = new ZUGFeRDEncoder();
const zugferdXml = await zugferdEncoder.encode(invoiceData);

// Create Factur-X XML
const facturxEncoder = new FacturXEncoder();
const facturxXml = await facturxEncoder.encode(invoiceData);

// Create UBL XML
const ublEncoder = new UBLEncoder();
const ublXml = await ublEncoder.encode(invoiceData);

// Using specific decoders
import { ZUGFeRDDecoder, FacturXDecoder } from '@fin.cx/einvoice';

// Decode ZUGFeRD XML
const zugferdDecoder = new ZUGFeRDDecoder(zugferdXml);
const zugferdData = await zugferdDecoder.decode();

// Decode Factur-X XML
const facturxDecoder = new FacturXDecoder(facturxXml);
const facturxData = await facturxDecoder.decode();

Working with PDF Extraction and Embedding

import { PDFExtractor, PDFEmbedder } from '@fin.cx/einvoice';

// Extract XML from PDF
const extractor = new PDFExtractor();
const extractResult = await extractor.extractXml(pdfBuffer);

if (extractResult.success) {
  console.log('Extracted XML:', extractResult.xml);
  console.log('Detected format:', extractResult.format);
  console.log('Extraction method used:', extractResult.extractorUsed);
} else {
  console.error('Extraction failed:', extractResult.error?.message);
}

// Embed XML into PDF
const embedder = new PDFEmbedder();
const embedResult = await embedder.createPdfWithXml(
  pdfBuffer,
  xmlContent,
  'factur-x.xml',
  'Factur-X XML Invoice',
  'invoice.pdf',
  'invoice-123456'
);

if (embedResult.success && embedResult.pdf) {
  await fs.writeFile('output.pdf', embedResult.pdf.buffer);
} else {
  console.error('Embedding failed:', embedResult.error?.message);
}

Format Detection

import { FormatDetector, InvoiceFormat } from '@fin.cx/einvoice';

// Detect format from XML
const format = FormatDetector.detectFormat(xmlString);

// Check format
if (format === InvoiceFormat.ZUGFERD) {
  console.log('This is a ZUGFeRD invoice');
} else if (format === InvoiceFormat.FACTURX) {
  console.log('This is a Factur-X invoice');
} else if (format === InvoiceFormat.XRECHNUNG) {
  console.log('This is an XRechnung invoice');
} else if (format === InvoiceFormat.UBL) {
  console.log('This is a UBL invoice');
}

Country-Specific Extensions

The library supports country-specific requirements and extensions:

German XRechnung

const invoice = new EInvoice();
invoice.metadata = {
  format: InvoiceFormat.XRECHNUNG,
  extensions: {
    'BT-DE-2': 'Leitweg-ID-123456', // German routing ID (required)
    'BT-DE-1': 'Payment conditions text',
    'BT-DE-3': 'Project reference'
  }
};

// XRechnung requires specific payment terms
invoice.paymentTerms = {
  method: 'SEPA',
  iban: 'DE89370400440532013000',
  bic: 'DEUTDEFF',
  reference: 'RF18539007547034'
};

Italian FatturaPA

const invoice = new EInvoice();
invoice.metadata = {
  format: InvoiceFormat.FATTURAPA,
  extensions: {
    FormatoTrasmissione: 'FPR12',
    CodiceDestinatario: '0000000',
    IdFiscaleIVA: 'IT12345678901',
    CodiceFiscale: 'RSSMRA80A01H501U'
  }
};

French Factur-X with Chorus Pro

const invoice = new EInvoice();
invoice.metadata = {
  format: InvoiceFormat.FACTURX,
  extensions: {
    siret: '12345678901234',
    tvaIntracommunautaire: 'FR12345678901',
    chorus: {
      serviceCode: 'SERVICE123',
      engagementNumber: 'ENG123456'
    }
  }
};

Why Choose @fin.cx/einvoice

🏗️ Production-Ready Architecture

• Plugin-based design with factory pattern for easy extensibility
• SOLID principles throughout the codebase
• Comprehensive test coverage with 500+ test cases
• Battle-tested with real-world invoice corpus

🔒 Enterprise Security

• XXE prevention with disabled external entities
• Resource limits to prevent DoS attacks
• Path traversal protection for PDF operations
• SSRF mitigation in XML processing

⚡ High Performance

• Sub-millisecond conversions (~0.6ms average)
• Efficient memory usage (~136KB per validation)
• Concurrent processing support
• Streaming capabilities for large files

🌍 Standards Compliance

• EN16931 business rules implementation
• Country-specific extensions (XRechnung, FatturaPA, Factur-X)
• 100% data preservation in round-trip conversions
• Multi-format validation with detailed error reporting

🛠️ Developer Experience

• Fully typed with TypeScript
• Intuitive API with static factory methods
• Detailed error messages with recovery suggestions
• Extensive documentation and examples

Recent Improvements

Version 2.0.0 (2025)

• TypeScript Type System: Full alignment with @tsclass/tsclass interfaces
• Date Parsing: Enhanced CII date parsing for various formats (YYYYMMDD, YYYYMM)
• API Enhancements: Added static factory methods (fromXml, fromFile, fromPdf)
• Format Support: Added generic CII export format
• Performance: Optimized validation to ~2.2ms average
• Memory Efficiency: Reduced memory usage to ~136KB per validation
• XRechnung Encoder: Complete implementation with German-specific requirements
• Error Recovery: Improved error handling with detailed messages
• Security Hardening: XXE prevention, resource limits, path traversal protection
• Production Features: Concurrent processing, memory management, integration patterns

Development

Building the Project

# Install dependencies
pnpm install

# Build the project
pnpm run build

Running Tests

# Run all tests
pnpm test

# Run specific test
pnpm test test/test.einvoice.ts

# Run with verbose output
tstest test/suite/einvoice_validation/test.val-12.validation-performance.ts --verbose

# Run specific test suites
pnpm test test/suite/einvoice_conversion/  # Conversion tests
pnpm test test/suite/einvoice_validation/  # Validation tests
pnpm test test/suite/einvoice_performance/ # Performance tests

The library includes comprehensive test suites that verify:

• Format Detection: Automatic detection of all supported formats
• Conversion: Round-trip conversion between all format pairs
• Validation: Multi-level validation (syntax, semantic, business rules)
• Performance: Validation in ~2.2ms, memory usage ~136KB
• PDF Operations: Extraction and embedding with multiple strategies
• Error Handling: Recovery from malformed data
• Special Characters: Unicode and escape sequence handling
• Country Extensions: XRechnung, FatturaPA, Factur-X specifics

Production Deployment

Security Considerations

The library implements comprehensive security measures:

// XXE (XML External Entity) Prevention
// ✓ External entity processing disabled by default
// ✓ DTD processing disabled
// ✓ SSRF protection via entity blocking

// Resource Limits
// ✓ Maximum XML size: 100MB (configurable)
// ✓ Maximum nesting depth: 100 levels
// ✓ Memory protection via streaming for large files

// Path Traversal Prevention
// ✓ Filename sanitization for PDF attachments
// ✓ No file system access from XML content

Concurrent Processing

The library is designed for concurrent operations:

// Process multiple invoices concurrently
const invoices = ['invoice1.xml', 'invoice2.xml', 'invoice3.xml'];
const results = await Promise.all(
  invoices.map(file => EInvoice.fromFile(file))
);

// Concurrent validation with controlled concurrency
const pLimit = (await import('p-limit')).default;
const limit = pLimit(5); // Max 5 concurrent operations

const validationResults = await Promise.all(
  invoices.map(invoice => 
    limit(() => invoice.validate())
  )
);

Memory Management

Best practices for handling large volumes:

// Process large batches with memory control
async function processBatch(files: string[]) {
  const batchSize = 100;
  const results = [];
  
  for (let i = 0; i < files.length; i += batchSize) {
    const batch = files.slice(i, i + batchSize);
    const batchResults = await Promise.all(
      batch.map(f => processInvoice(f))
    );
    results.push(...batchResults);
    
    // Allow garbage collection between batches
    if (global.gc) global.gc();
  }
  
  return results;
}

Edge Case Handling

The library handles numerous edge cases:

// Empty files
try {
  await EInvoice.fromXml(''); // Throws ParseError
} catch (e) {
  // Handle empty input
}

// Huge files (500+ line items)
const largeInvoice = new EInvoice();
largeInvoice.items = Array(1000).fill(null).map((_, i) => ({
  position: i + 1,
  name: `Item ${i + 1}`,
  unitQuantity: 1,
  unitNetPrice: 10,
  vatPercentage: 19
}));
// Handles efficiently with ~136KB memory per validation

// Mixed character encodings
invoice.notes = ['UTF-8: €', 'Emoji: 🚀', 'Chinese: 中文'];
// All properly encoded in output XML

// Timezone handling
invoice.issueDate = new Date('2024-01-01T00:00:00+02:00');
// Preserves timezone information

Production Configuration

Recommended settings for production:

// Error handling strategy
const productionConfig = {
  // Validation
  validationLevel: ValidationLevel.BUSINESS,
  strictMode: true,
  
  // Performance
  maxConcurrency: os.cpus().length,
  cacheEnabled: true,
  
  // Security
  maxXmlSize: 100 * 1024 * 1024, // 100MB
  maxNestingDepth: 100,
  externalEntities: false,
  
  // Logging
  logLevel: 'error', // 'debug' | 'info' | 'warn' | 'error'
  logFormat: 'json'
};

Integration Patterns

Common integration scenarios:

// REST API Integration
app.post('/invoice/convert', async (req, res) => {
  try {
    const { xml, targetFormat } = req.body;
    const invoice = await EInvoice.fromXml(xml);
    const converted = await invoice.exportXml(targetFormat);
    res.json({ success: true, xml: converted });
  } catch (error) {
    res.status(400).json({ 
      success: false, 
      error: error.message,
      type: error.constructor.name
    });
  }
});

// Message Queue Processing
async function processInvoiceMessage(message: any) {
  const { invoiceId, pdfBuffer } = message;
  
  try {
    const invoice = await EInvoice.fromPdf(Buffer.from(pdfBuffer, 'base64'));
    const validation = await invoice.validate();
    
    await saveToDatabase(invoiceId, invoice, validation);
    await acknowledgeMessage(message);
  } catch (error) {
    await handleError(message, error);
  }
}

// Batch Processing Pipeline
const pipeline = [
  extractFromPdf,
  validateInvoice,
  convertToXRechnung,
  sendToERP
];

for (const step of pipeline) {
  await step(invoice);
}

Troubleshooting

Common Issues

XML Parsing Errors

// Handle malformed XML
try {
  const invoice = await EInvoice.fromXml(xmlString);
} catch (error) {
  console.error('Failed to parse:', error.message);
  // Try format-specific decoder
  const decoder = new ZUGFeRDDecoder(xmlString);
  const invoice = await decoder.decode();
}

PDF Extraction Failures

// PDF might not contain XML
const result = await PDFExtractor.extractXml(pdfBuffer);
if (!result.success) {
  console.log('No XML found in PDF');
  // Create invoice from scratch or OCR
}

Validation Errors

// Check validation level
const result = await invoice.validate();
if (!result.valid) {
  // Check if it's a warning vs error
  const errors = result.errors.filter(e => e.severity === 'error');
  const warnings = result.errors.filter(e => e.severity === 'warning');
}

API Reference

EInvoice Class

class EInvoice {
  // Static factory methods
  static fromXml(xmlString: string): Promise<EInvoice>
  static fromFile(filePath: string): Promise<EInvoice>
  static fromPdf(pdfBuffer: Buffer): Promise<EInvoice>
  
  // Instance methods
  validate(level?: ValidationLevel): Promise<ValidationResult>
  exportXml(format: ExportFormat): Promise<string>
  exportPdf(format: ExportFormat): Promise<{ buffer: Buffer }>
  getFormat(): InvoiceFormat
  
  // Properties (following TInvoice interface)
  id: string
  date: Date
  from: TParty
  to: TParty
  items: TAccountingDocItem[]
  paymentOptions: TPaymentOptions
  metadata?: any
}

Supported Export Formats

type ExportFormat = 'facturx' | 'zugferd' | 'xrechnung' | 'ubl' | 'cii'

Validation Levels

enum ValidationLevel {
  SYNTAX = 'syntax',      // XML structure validation
  SEMANTIC = 'semantic',  // Field content validation
  BUSINESS = 'business'   // Business rule validation
}

Key Features

1. PDF Integration

   • Embed XML invoices in PDF documents with detailed error reporting
   • Extract XML from existing PDF invoices using multiple fallback strategies
   • Handle different XML attachment methods and encodings

2. Encoding & Decoding

   • Create standards-compliant XML from structured data
   • Parse XML invoices back to structured data
   • Support multiple format standards
   • Circular encoding/decoding integrity

3. Format Detection

   • Automatic detection of invoice XML format
   • Support for different XML namespaces
   • Graceful handling of malformed XML

4. Validation

   • Validate invoices against format-specific rules
   • Detailed error reporting
   • Support for different validation levels

5. Error Handling

   • Robust error recovery mechanisms
   • Detailed error information
   • Type-safe error reporting

By embracing @fin.cx/einvoice, you simplify the handling of electronic invoice documents, fostering seamless integration across different financial processes, thus empowering practitioners with robust, flexible tools for VAT invoices in ZUGFeRD/Factur-X compliance or equivalent digital formats.

License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the license file within this repository.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

Company Information

Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.