https://github.com/jslno/node-zugferd
A Node.js library for creating ZUGFeRD/Factur-X compliant documents. Generating XML and embedding it into PDF/A files, enabling seamless e-invoicing and digital document compliance.
https://github.com/jslno/node-zugferd
business-invoice cross-industry-invoice e-invoice e-rechnung einvoicing electronic-invoice factur-x invoice-generation nodejs pdf-invoice xml-invoice zugferd
Last synced: 6 months ago
JSON representation
A Node.js library for creating ZUGFeRD/Factur-X compliant documents. Generating XML and embedding it into PDF/A files, enabling seamless e-invoicing and digital document compliance.
- Host: GitHub
- URL: https://github.com/jslno/node-zugferd
- Owner: jslno
- License: mit
- Created: 2025-01-25T20:55:18.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-12-22T12:03:12.000Z (7 months ago)
- Last Synced: 2025-12-23T23:12:27.838Z (6 months ago)
- Topics: business-invoice, cross-industry-invoice, e-invoice, e-rechnung, einvoicing, electronic-invoice, factur-x, invoice-generation, nodejs, pdf-invoice, xml-invoice, zugferd
- Language: TypeScript
- Homepage: https://node-zugferd.jsolano.de
- Size: 58.7 MB
- Stars: 50
- Watchers: 2
- Forks: 8
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
node-zugferd
> [!CAUTION]
> **[WIP]** This package is still under development.
A Node.js library for creating ZUGFeRD/Factur-X compliant documents. Generating XML and embedding it into PDF/A files, enabling seamless e-invoicing and digital document compliance.
Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Default Supported Profiles](#default-supported-profiles)
- [Basic Usage](#basic-usage)
- [Roadmap](#roadmap)
- [Dependencies](#dependencies)
- [License](#license)
Features
* Create Factur-X compliant xml
* Attach xml to pdf/a-3b
* Validate xml
Installation
Install node-zugferd with npm:
```bash
npm install node-zugferd@latest
```
Default Supported Profiles
> [!WARNING]
> 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](https://www.bundesfinanzministerium.de/Content/DE/Downloads/BMF_Schreiben/Weitere_Steuerthemen/Abgabenordnung/2019-11-28-GoBD.html)); 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.**
* MINIMUM
* BASIC WL
* BASIC
* EN 16931 (COMFORT)
* EXTENDED
> [!NOTE]
> By default this package only provides support for the CII-Syntax
> [!TIP]
> You can also define your own Profiles.
If you encounter invalid or missing fields, feel free to open a new [Issue](https://github.com/jslno/node-zugferd/issues) or [Pull Request](https://github.com/jslno/node-zugferd/pulls).
Basic Usage
1. Create a new instance:
```ts
import { zugferd } from "node-zugferd";
import { BASIC } from "node-zugferd/profile/basic";
export const invoicer = zugferd({
profile: BASIC,
});
```
2. Define the documents data
```ts
import { invoicer } from "./your/path/invoicer";
const data: typeof invoicer.$Infer.Schema = {
//... your data
};
const invoice = invoicer.create(data);
```
3. Save the document
as XML
```ts
const xml = await invoice.toXML();
```
as PDF/A-3b
```ts
// 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",
},
});
```
Dependencies
* [fast-xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser)
* [pdf-lib](https://github.com/Hopding/pdf-lib)
* [xsd-schema-validator](https://github.com/nikku/node-xsd-schema-validator)
* [zod](https://github.com/colinhacks/zod)
* [defu](https://github.com/unjs/defu)
License
Distributed under the MIT License. See LICENSE.md for more information.