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
Validation: Validate invoices against format-specific rules
Conversion: Convert between different invoice formats
TypeScript: Fully typed API with TypeScript definitions
Modular architecture: Extensible design with specialized components

Install

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

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

# Using npm
npm install @fin.cx/xinvoice

# Using yarn
yarn add @fin.cx/xinvoice

Usage

The @fin.cx/xinvoice 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.

Basic Usage

import { XInvoice } from '@fin.cx/xinvoice';
import { promises as fs } from 'fs';

// Create a new invoice
const invoice = new XInvoice();
invoice.id = 'INV-2023-001';
invoice.from = {
  name: 'Supplier Company',
  // Add more details...
};
invoice.to = {
  name: 'Customer Company',
  // Add more details...
};
// Add more invoice details...

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

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

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

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

Working with Different Invoice Formats

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

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

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

PDF Handling

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

// Embed XML into PDF
const existingPdf = await fs.readFile('document.pdf');
const pdfWithInvoice = await invoice.exportPdf(existingPdf);
await fs.writeFile('invoice-with-xml.pdf', pdfWithInvoice);

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);
}

Architecture

XInvoice uses a modular architecture with specialized components:

Core Components

XInvoice: The main class that provides a high-level API for working with invoices
Decoders: Convert format-specific XML to a common invoice model
Encoders: Convert the common invoice model to format-specific XML
Validators: Validate invoices against format-specific rules

PDF Processing

PDF Extractors: Extract XML from PDF files using multiple strategies:
- Standard Extraction: Extracts XML from standard PDF/A-3 embedded files
- Associated Files Extraction: Extracts XML from associated files (AF entry)
- Text-based Extraction: Extracts XML by searching for patterns in the PDF text
PDF Embedders: Embed XML into PDF files

This modular approach ensures maximum compatibility with different PDF implementations and invoice formats.

Supported Invoice Formats

Format	Version	Read	Write	Validate
ZUGFeRD	1.0	✅	✅	✅
ZUGFeRD	2.0/2.1	✅	✅	✅
Factur-X	1.0	✅	✅	✅
XRechnung	1.2+	✅	✅	✅
UBL	2.1	✅	✅	✅
CII	16931	✅	✅	✅
FatturaPA	1.2	✅	✅	✅

Advanced Usage

Custom Encoders and Decoders

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

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

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

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

// 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();

Circular Encoding and Decoding

// Start with invoice data
const invoiceData = { /* your structured invoice data */ };

// Create XML
const encoder = new FacturXEncoder();
const xml = await encoder.createXml(invoiceData);

// Decode XML back to structured data
const decoder = new FacturXDecoder(xml);
const extractedData = await decoder.decode();

// Now extractedData contains the same information as your original invoiceData

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.xinvoice.ts

The library includes comprehensive test suites that verify:

XML creation capabilities
Format detection logic
XML encoding/decoding circularity
Special character handling
Different invoice types (invoices, credit notes)
PDF extraction and embedding

Key Features

PDF Integration
- Embed XML invoices in PDF documents
- Extract XML from existing PDF invoices using multiple strategies
- Handle different XML attachment methods
Encoding & Decoding
- Create standards-compliant XML from structured data
- Parse XML invoices back to structured data
- Support multiple format standards
- Circular encoding/decoding integrity
Format Detection
- Automatic detection of invoice XML format
- Support for different XML namespaces
- Graceful handling of malformed XML
Validation
- Validate invoices against format-specific rules
- Detailed error reporting
- Support for different validation levels

By embracing @fin.cx/xinvoice, 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.

readme.md

@fin.cx/xinvoice