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:

``bash
npm install zugferd-generator
`

Usage

$3

`javascript
import ZUGFeRDGenerator from 'zugferd-generator'
`

$3

`javascript
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

$3

`javascript
const zugferd = new ZUGFeRDGenerator(invoiceData);
`

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

`typescript
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.

`javascript
const xmlString = zugferd.toXMLString();
`

2. toBuffer()
- Returns the XML representation as a Buffer object.

`javascript
const buffer = zugferd.toBuffer();
`

3. toBlob()
- Returns the XML representation as a Blob object (useful for browser environments).

`javascript
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.

`javascript
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 hello@pixelpal.io