@fin.cx/einvoice

Documentation for @fin.cx/einvoice

readme.md for @fin.cx/einvoice

The Ultimate TypeScript E-Invoicing Library for Europe - Now with 100% EN16931 Compliance โœ…

TypeScript EN16931 Standards License

Transform the chaos of European e-invoicing into pure TypeScript elegance. @fin.cx/einvoice is your battle-tested solution for creating, validating, and converting electronic invoices across all major European standards - with blazing fast performance and enterprise-grade reliability.

๐ŸŽฏ Why @fin.cx/einvoice?

๐Ÿš€ Quick Start

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

# Using npm
npm install @fin.cx/einvoice

# Using yarn
yarn add @fin.cx/einvoice

One-Minute Example

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

// Load from any source
const invoice = await EInvoice.fromFile('invoice.xml');      // From file
const invoice2 = await EInvoice.fromXml(xmlString);          // From XML string
const invoice3 = await EInvoice.fromPdf(pdfBuffer);          // From PDF with embedded XML

// Validate with comprehensive EN16931 rules
const validation = await invoice.validate();
console.log(`Valid: ${validation.valid}`);

// Convert between any formats - losslessly!
const xrechnung = await invoice.exportXml('xrechnung');      // For German B2G
const peppol = await invoice.exportXml('ubl');               // For PEPPOL network
const facturx = await invoice.exportXml('facturx');          // For France/Germany
const zugferd = await invoice.exportXml('zugferd');          // For German standard

// Embed into PDF for hybrid invoices
const pdfWithXml = await invoice.exportPdf('facturx');

๐Ÿ—๏ธ Complete Invoice Creation

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

// Create a fully compliant invoice from scratch
const invoice = new EInvoice();

// Essential metadata
invoice.accountingDocId = 'INV-2025-001';
invoice.issueDate = new Date('2025-01-15');
invoice.accountingDocType = 'invoice';
invoice.currency = 'EUR';
invoice.dueInDays = 30;

// Seller information
invoice.from = {
  type: 'company',
  name: 'Tech Solutions GmbH',
  address: {
    streetName: 'Innovation Street',
    houseNumber: '42',
    city: 'Berlin',
    postalCode: '10115',
    country: 'DE'
  },
  registrationDetails: {
    vatId: 'DE123456789',
    registrationId: 'HRB 123456',
    registrationName: 'Tech Solutions GmbH'
  },
  status: 'active'
};

// Buyer information
invoice.to = {
  type: 'company',
  name: 'Customer Corp SAS',
  address: {
    streetName: 'Rue de la Paix',
    houseNumber: '10',
    city: 'Paris',
    postalCode: '75001',
    country: 'FR'
  },
  registrationDetails: {
    vatId: 'FR987654321',
    registrationId: 'RCS Paris 987654321'
  }
};

// Payment details - SEPA ready
invoice.paymentAccount = {
  iban: 'DE89370400440532013000',
  bic: 'COBADEFFXXX',
  accountName: 'Tech Solutions GmbH',
  institutionName: 'Commerzbank'
};

// Line items with automatic calculations
invoice.items = [
  {
    position: 1,
    name: 'Cloud Infrastructure Services',
    description: 'Monthly cloud hosting and support',
    articleNumber: 'CLOUD-PRO-001',
    unitQuantity: 1,
    unitNetPrice: 2500.00,
    vatPercentage: 19,
    unitType: 'MON'  // Month
  },
  {
    position: 2,
    name: 'Professional Consulting',
    description: 'Architecture review and optimization',
    articleNumber: 'CONSULT-001',
    unitQuantity: 16,
    unitNetPrice: 150.00,
    vatPercentage: 19,
    unitType: 'HUR'  // Hour
  }
];

// Export to any format you need
const zugferdXml = await invoice.exportXml('zugferd');
const pdfWithXml = await invoice.exportPdf('facturx');

๐ŸŽจ Supported Standards & Formats

Standard Version Status Use Case
EN16931 2017 โœ… 100% Complete Core European standard
ZUGFeRD 1.0, 2.0, 2.1 โœ… Full Support German B2B/B2C
Factur-X 1.0 (all profiles) โœ… Full Support France/Germany
XRechnung 2.0, 3.0 โœ… Full Support German public sector
PEPPOL BIS 3.0 3.0 โœ… Full Support Cross-border B2G
UBL 2.1 โœ… Full Support International
CII D16B โœ… Full Support Cross Industry

๐Ÿ“‹ Factur-X Profile Support

// Automatic profile detection and validation
const profiles = {
  MINIMUM: 'Essential fields only (BT-1, BT-2, BT-3)',
  BASIC: 'Core invoice with line items',
  BASIC_WL: 'Basic without lines (summary invoices)',
  EN16931: 'Full EN16931 compliance',
  EXTENDED: 'Additional structured data'
};

๐Ÿ”ฅ Power Features

๐Ÿงฎ Decimal Precision for Financial Accuracy

No more floating-point errors! Built-in arbitrary precision arithmetic:

// Perfect financial calculations every time
const calculator = new DecimalCurrencyCalculator('EUR');
const result = calculator.calculateLineNet(
  '3.14159', // Quantity
  '999.99',  // Unit price
  '0'        // Discount (optional)
);
// Result: 3141.56 (correctly rounded for EUR)

๐Ÿ” Multi-Level Validation

// Three-layer validation with detailed diagnostics
const syntaxResult = await invoice.validate(ValidationLevel.SYNTAX);
const semanticResult = await invoice.validate(ValidationLevel.SEMANTIC);
const businessResult = await invoice.validate(ValidationLevel.BUSINESS);

// Get specific rule violations
businessResult.errors.forEach(error => {
  console.log(`Rule ${error.ruleId}: ${error.message}`);
  console.log(`Business Term: ${error.btReference}`);
  console.log(`Field: ${error.field}`);
});

๐Ÿ”„ Format Detection & Conversion

// Automatic format detection
const format = FormatDetector.detectFormat(xmlString);
console.log(`Detected: ${format}`); // 'zugferd', 'facturx', 'xrechnung', etc.

// Intelligent conversion preserves all data
const zugferd = await EInvoice.fromFile('zugferd.xml');
const xrechnung = await zugferd.exportXml('xrechnung');
const backToZugferd = await EInvoice.fromXml(xrechnung);
// All data preserved through round-trip!

๐Ÿ“„ PDF Operations

// Extract XML from PDF invoices
const extractor = new PDFExtractor();
const result = await extractor.extractXml(pdfBuffer);
if (result.success) {
  console.log(`Found ${result.format} invoice`);
  const invoice = await EInvoice.fromXml(result.xml);
}

// Embed XML into PDF for hybrid invoices
const embedder = new PDFEmbedder();
const pdfWithXml = await embedder.createPdfWithXml(
  existingPdf,
  xmlContent,
  'factur-x.xml',
  'Factur-X Invoice'
);

๐ŸŒ Country-Specific Requirements

๐Ÿ‡ฉ๐Ÿ‡ช German XRechnung

invoice.metadata = {
  customizationId: 'urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0',
  extensions: {
    leitwegId: '991-12345-67',        // Required routing ID
    buyerReference: 'DE-BUYER-REF',    // Mandatory
    sellerContact: {
      name: 'Max Mustermann',
      phone: '+49 30 12345678',
      email: 'invoice@company.de'
    }
  }
};

๐Ÿ‡ช๐Ÿ‡บ PEPPOL BIS 3.0

invoice.metadata = {
  profileId: 'urn:fdc:peppol.eu:2017:poacc:billing:01:1.0',
  extensions: {
    endpointId: '0088:1234567890128',  // GLN with checksum
    documentTypeId: 'urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017',
    processId: 'urn:fdc:peppol.eu:2017:poacc:billing:01:1.0'
  }
};

๐Ÿ‡ซ๐Ÿ‡ท French Chorus Pro

invoice.metadata = {
  extensions: {
    siret: '12345678901234',
    serviceCode: 'SERVICE-2025',
    engagementNumber: 'ENG-123456',
    marketReference: 'MARKET-REF-001'
  }
};

โšก Performance Metrics

Lightning-fast operations with minimal memory footprint:

Operation Speed Memory
Format Detection ~0.1ms Minimal
XML Parsing ~0.5ms ~100KB
Full Validation ~2.2ms ~136KB
Format Conversion ~0.6ms ~150KB
PDF Extraction ~5ms ~1MB
PDF Embedding ~10ms ~2MB

๐Ÿ—๏ธ Architecture

Plugin-Based Design

// Factory pattern for extensibility
DecoderFactory.getDecoder(format) โ†’ BaseDecoder
EncoderFactory.getEncoder(format) โ†’ BaseEncoder
ValidatorFactory.getValidator(format) โ†’ BaseValidator

Data Flow

Input (XML/PDF) โ†’ Format Detection โ†’ Decoder โ†’ EInvoice Model
                                                    โ†“
                                               Validation
                                                    โ†“
                                    Encoder โ†’ Output (XML/PDF)

๐Ÿ”’ Security Features

๐Ÿงช Testing

# Run all tests
pnpm test

# Run specific test suites
pnpm test test/test.peppol-validator.ts
pnpm test test/test.facturx-validator.ts
pnpm test test/test.semantic-model.ts

# Run with verbose output
pnpm test -- --verbose

๐Ÿ“š Advanced Examples

Batch Processing with Concurrency Control

import pLimit from 'p-limit';

const limit = pLimit(5); // Max 5 concurrent operations
const files = ['invoice1.xml', 'invoice2.xml', /* ... */];

const results = await Promise.all(
  files.map(file => 
    limit(async () => {
      const invoice = await EInvoice.fromFile(file);
      const validation = await invoice.validate();
      return { file, valid: validation.valid };
    })
  )
);

REST API Integration

app.post('/api/invoice/convert', async (req, res) => {
  try {
    const { xml, targetFormat } = req.body;
    const invoice = await EInvoice.fromXml(xml);
    
    // Validate before conversion
    const validation = await invoice.validate();
    if (!validation.valid) {
      return res.status(400).json({ 
        error: 'Invalid invoice',
        violations: validation.errors 
      });
    }
    
    const converted = await invoice.exportXml(targetFormat);
    res.json({ success: true, xml: converted });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

๐ŸŽฏ What Makes Us Different

๐Ÿ† 100% EN16931 Compliance

๐Ÿ’Ž Production Excellence

๐Ÿš€ Developer Experience

๐Ÿ“ฆ Installation Requirements

๐Ÿค Standards Compliance

This library implements:

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

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.

changelog.md for @fin.cx/einvoice

2025-08-11 - 5.1.1 - fix(build/publishing)

Remove migration guide and update publishing and schematron download configurations

2025-01-11 - 5.1.0 - feat(compliance)

Achieve 100% EN16931 compliance with comprehensive validation support

2025-05-24 - 5.0.0 - BREAKING CHANGE(core)

Rebrand XInvoice to EInvoice: update package name, class names, imports, and documentation

[5.0.0] - Unreleased

BREAKING CHANGES

Migration Guide

To migrate from v4.x to v5.x:

  1. Update package dependency: @fin.cx/xinvoice โ†’ @fin.cx/einvoice
  2. Update imports: import { XInvoice } from '@fin.cx/xinvoice' โ†’ import { EInvoice } from '@fin.cx/einvoice'
  3. Update class usage: new XInvoice() โ†’ new EInvoice()
  4. Update type references: XInvoiceOptions โ†’ EInvoiceOptions

2025-05-24 - 4.3.0 - feat(readme.plan)

Add detailed EInvoice Improvement Plan outlining project rebranding, performance optimizations, enhanced error handling, comprehensive test suite, format conversion, and future enterprise features.

2025-04-04 - 4.2.2 - fix(documentation)

Improve readme documentation for better clarity on PDF handling, XML validation and error reporting

2025-04-04 - 4.2.1 - fix(release)

No changes detected in project files; project remains in sync.

2025-04-04 - 4.2.0 - feat(UBL Encoder & Test Suite)

Implement UBLEncoder and update corpus summary generation; adjust PDF timestamps in test outputs

2025-04-04 - 4.1.7 - fix(ZUGFeRD encoder & dependency)

Update @tsclass/tsclass dependency to ^8.2.0 and fix paymentOptions field in ZUGFeRD encoder for proper description output

2025-04-04 - 4.1.6 - fix(core)

Improve PDF XML extraction, embedding, and format detection; update loadPdf/exportPdf error handling; add new validator implementations and enhance IPdf metadata.

2025-04-03 - 4.1.5 - fix(core)

No uncommitted changes detected in the repository. The project files and functionality remain unchanged.

2025-04-03 - 4.1.4 - fix(corpus-tests, format-detection)

Adjust corpus test thresholds and improve XML format detection for invoice documents

2025-04-03 - 4.1.3 - fix(core)

Refactor module imports to use the centralized plugins module and update relative paths across the codebase. Also remove the obsolete test file (test/test.other-formats-corpus.ts) and update file metadata in test outputs.

2025-04-03 - 4.1.2 - fix(readme)

Update readme documentation: enhance feature summary, update installation instructions and usage examples, remove obsolete config details, and better clarify supported invoice formats.

2025-04-03 - 4.1.1 - fix(zugferd)

Refactor Zugferd decoders to properly extract house numbers from street names and remove unused imports; update readme hints with additional TInvoice reference and refresh PDF metadata timestamps.

2025-04-03 - 4.1.0 - feat(ZUGFERD)

Add dedicated ZUGFERD v1/v2 support and refine invoice format detection logic

2025-03-20 - 3.0.1 - fix(test/pdf-export)

Improve PDF export tests with detailed logging and enhanced embedded file structure verification.

2025-03-20 - 3.0.0 - BREAKING CHANGE(XInvoice)

Refactor XInvoice API for XML handling and PDF export by replacing deprecated methods (addXmlString and getParsedXmlData) with fromXml and loadXml, and by introducing a new ExportFormat type for type-safe export. Update tests accordingly.

2025-03-20 - 2.0.0 - BREAKING CHANGE(core)

Refactor contact and PDF handling across the library by replacing IContact with TContact and updating PDF processing to use a structured IPdf object. These changes ensure that empty contact objects include registration details, founded/closed dates, and status, and that PDF loading/exporting uniformly wraps buffers in a proper object.

2025-03-17 - 1.3.3 - fix(commitinfo)

Synchronize commit info version with package.json version

2025-03-17 - 1.3.1 - fix(documentation)

Update readme to enhance installation instructions and expand feature documentation for Factur-X/ZUGFeRD, UBL, and FatturaPA support, including details on circular encoding/decoding.

2025-03-17 - 1.3.0 - feat(encoder)

Rename encoder class from ZugferdXmlEncoder to FacturXEncoder to better reflect Factur-X compliance. All related imports, exports, and tests have been updated while maintaining backward compatibility.

2025-03-17 - 1.2.0 - feat(core)

Improve XML processing and error handling for PDF invoice attachments

2025-01-01 - 1.1.2 - fix(core)

Fix file import paths and remove markdown syntax from README

2024-12-31 - 1.1.1 - fix(documentation)

Updated documentation to reflect accurate module description and usage guidance

2024-12-30 - 1.1.0 - feat(core)

Add EInvoiceCreator class for generating ZUGFeRD/Factur-X XML

2024-07-02 - 1.0.6 - fix(core)

Project files committed with initial structure and class implementation

2024-04-22 - 1.0.3 to 1.0.5 - core

Minor updates and bug fixes.