Basic Usage
Getting started with node-zugferd
Install the Package
Let's start by adding node-zugferd to your project:
npm install node-zugferd
jslno/node-zugferd
33
Create a new Instance
Create a file named invoicer.ts
in preferably one of those locations:
- Project root
lib/
folderutils/
folder
In this file, import node-zugferd and create your instance. Make sure to export the instance.
import { zugferd } from "node-zugferd";
export const invoicer = zugferd({
//...
});
Select a Profile
node-zugferd requires a profile to generate the invoice. You can easily configure node-zugferd to use these built-in profiles:
import { zugferd } from "node-zugferd";
import { BASIC } from "node-zugferd/profile/basic";
export const invoicer = zugferd({
profile: BASIC,
});
Your first invoice
Once the necessary setup is complete, it's time to create your first invoice. This involves defining the invoice data and embedding it into a PDF to ensure it meets electronic invoicing standards.
Define the data
Invoices contain essential details like transaction information, participant details, and line items. This data will be structured in a way that allows it to be processed electronically and integrated seamlessly into business workflows.
import { invoicer } from "./your/path/invoicer";
const data: typeof invoicer.$Infer.Schema = {
//...
};
const invoice = invoicer.create(data);
Save the document
After creating the invoice, it needs to be saved in a format that meets the necessary standards for distribution and compliance. This ensures the document is both human-readable and machine-readable, allowing for automated processing within business workflows.
The most common practice for saving invoices is embedding them in a PDF/A document. This format retains the visual appearance of the invoice while also embedding the structured data. PDF/A ensures that the invoice can be archived and retrieved in a standardized, legally-compliant manner.
const pdf = fs.readFileSync("./your/invoice.pdf");
const pdfA = await invoice.embedInPdf(pdf, {
metadata: {
title: "New Invoice",
},
});
PDF/A is the preferred format for ZUGFeRD invoices, as it complies with the necessary legal standards for document archiving and submission.
Alternatively, you can generate the invoice as an XML file. However, it's important to note that just the XML does not meet the full ZUGFeRD standard. Without embedding the data into a PDF/A file, the invoice is incomplete for compliance and automated processing in most cases.
const xml = await invoice.toXML();
🎉 That's it
That's it! You've successfully set up node-zugferd, generated your first invoice, and learned how to save it as a PDF/A-3b file or XML. You can now automate the generation of invoices with structured data in the format that fits your needs.