Docs

Basic Usage

Getting started with node-zugferd

Install the Package

Let's start by adding node-zugferd to your project:

npm install node-zugferd

GitHubjslno/node-zugferd

12

Create a new Instance

Create a file named invoicer.ts in preferably one of those locations:

  • Project root
  • lib/ folder
  • utils/ folder

In this file, import node-zugferd and create your instance. Make sure to export the instance.

invoicer.ts
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:

Documents containing only information of the first two profiles (MINIMUM and BASIC WL) are not considered to be invoices according to German fiscal law (→ GoBD); they may therefore not be used as electronic invoices in Germany. They will not be considered as invoices in France anymore once the einvoicing B2B mandate CTC reform has been fully deployed (2028). It is then highly recommended to target the BASIC profile at minimum.

By default this package only provides support for the CII-Syntax

You can also define your own Profiles.
invoicer.ts
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 type { ProfileBasic } from "node-zugferd/profile/basic";
import { invoicer } from "./your/path";
 
const data: ProfileBasic = {
  //...
};
 
const invoice = await 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.

The data in your pdf must exactly match the provided data!

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.

🎉 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.

Edit on GitHub

Introduction

Minimum

On this page