ZUGFeRD Generator

ZUGFeRD (short for "Zentraler User Guide des Forums elektronische Rechnung Deutschland") is a standard for electronic invoicing in Germany. It combines structured invoice data (in XML format) with a visual representation (typically a PDF), allowing businesses to automate invoice processing while maintaining a human-readable version.

A lightweight Node.js module for creating ZUGFeRD-compliant invoices.

Installation

Install the module via npm:

npm install zugferd-generator

Usage

Import the Module

import ZUGFeRDGenerator from 'zugferd-generator'

Example: Using the Functions

const invoiceData = {
    id: 'INV-001',
    issueDate: '2024-01-01',
    currency: 'EUR',
    supplier: { name: 'Supplier Ltd.', country: 'DE' },
    customer: { name: 'Customer Ltd.', country: 'DE' },
    taxTotal: { taxAmount: 19, taxPercentage: 19 },
    lineItems: [
        {
            id: 'ITEM-001',
            description: 'Product A',
            quantity: 1,
            unitPrice: 100,
            lineTotal: 100,
        },
    ],
};

// Create a new invoice
const zugferd = new ZUGFeRDGenerator(invoiceData);
const invoicePdf = await fs.readFile('invoice.pdf');
const pdfWithEmbeddedEInvoice = await zugferd.embedInPDF(invoicePdf);

API

ZUGFeRDGenerator

const zugferd = new ZUGFeRDGenerator(invoiceData);

• invoiceData (InvoiceData): The invoice to convert (see example above).

interface InvoiceData {
  id: string;
  issueDate: string;
  dueDate?: string; // optional
  currency: string;
  totalAmount: number;
  supplier: {
    name: string;
    country: string;
    street?: string; // optional
    postalCode?: string; // optional
    city?: string; // optional
    taxNumber?: string; // optional
    legalEntityID?: string; // optional
  };
  customer: {
    name: string;
    country: string;
    street?: string; // optional
    postalCode?: string; // optional
    city?: string; // optional
    taxNumber?: string; // optional
  };
  taxTotal: {
    taxAmount: number;
    taxPercentage: number;
  };
  paymentDetails?: { // optional
    paymentMeansCode?: string; // optional
    paymentID?: string; // optional
    bankDetails?: {
      accountName?: string; // optional
      iban?: string; // optional
      bic?: string; // optional
      bankName?: string; // optional
    }
  };
  notes?: string[]; // optional
  lineItems: {
    id: string;
    description: string;
    quantity: number;
    unitPrice: number;
    lineTotal: number;
  }[];
}

Methods

1. toXMLString()

   • Returns the XML representation of the invoice as a string.

   const xmlString = zugferd.toXMLString();

2. toBuffer()

   • Returns the XML representation as a Buffer object.

   const buffer = zugferd.toBuffer();

3. toBlob()

   • Returns the XML representation as a Blob object (useful for browser environments).

   const blob = zugferd.toBlob();
   console.log(blob.content);

4. embedInPDF(pdfBuffer)

   • Embeds the ZUGFeRD XML invoice into a given PDF file.
   • Parameters:
     • pdfBuffer (Buffer): The pdf file that the e-invoice should be attached to
   • Returns a Promise<Buffer>.

   const invoicePdf = await fs.readFile('invoice.pdf');
   const pdfWithEmbeddedEInvoice = await zugferd.embedInPDF(invoicePdf);

Contribution

Contributions in the form of bug reports, feature requests, or pull requests are welcome! Please ensure you run the tests and cover new functionality when contributing.

License

This project is licensed under the MIT License.

Hire Me

Looking for a developer with expertise in Node.js? Feel free to reach out to me for freelance projects, collaborations, or full-time opportunities!

Contact me [email protected]