What ZUGFeRD / Factur-X is
Three things have to line up for a valid e-invoice:
- A PDF/A-3 document (the archivable, self-contained PDF profile).
- The invoice XML embedded as an associated file.
-
XMP metadata in the PDF that declares the embedded XML and which profile it follows.
Get one of those wrong and validators can reject the file. This makes e-invoices fiddly to produce by hand.
How Oicana builds one
Oicana compiles a Typst template to PDF, and its PDF export can embed files and write custom XMP metadata. That is exactly what the three points above need.
The invoice_zugferd example template shows the full setup.
1. Export to PDF/A-3 in the manifest. You declare the standards once, next to the template:
# typst.toml
[tool.oicana.export.pdf]
standards = ["ua-1", "a-3b"]
[[tool.oicana.inputs]]
type = "blob"
key = "zugferd"
default = { file = "factur-x.xml" }
Here the invoice XML comes in as a blob input, so you can pass a different one per invoice. The a-3b standard allows embedding files to be a valid e-invoice. Adding ua-1 makes the same document more accessible through PDF/UA-1.
2. Embed the XML in the template. A single line takes the XML bytes, embeds them, and writes the matching XMP metadata:
#import "@preview/oicana:0.2.0": setup
#import "@local/invoice-harness:0.1.1": *
#let read-project-file(path) = read(path, encoding: none)
#let (input, _, _) = setup(read-project-file)
// Embed the invoice XML and declare it in the PDF metadata
#factur-x(input.zugferd.bytes, profiles.en16931)
// ... the rest of the template renders the visible invoice
The factur-x call handles the embedding and the XMP. The rest of the template is an ordinary invoice layout, free to look however you want.
Note
The factur-x helper lives in the open source invoice-harness package. Embedding files and writing custom metadata currently only work through Oicana or a patched Typst, so invoice-harness is not published on the typst package registry yet. You can install it as a local package. See the e-invoice guide to learn more.
Getting started
The Oicana documentation includes a guide on creating e-invoices with one of our seven integrations. You can follow it see how to generate invoices from Node.js, the browser, Python, Rust, Java, PHP, or C#.
With Oicana it's easy to create e-invoices in your code.
Get started with Oicana