Attach ZUGFeRD and Factur-X XML, and extract it again
Add PDFluent to Cargo.toml
# Cargo.toml
[dependencies]
pdfluent = { version = "0.9", features = ["einvoice"] }Create a ZUGFeRD or Factur-X e-invoice PDF in Rust
use pdfluent::{PdfAProfile, PdfDocument, ZugferdProfile};
fn main() -> pdfluent::Result<()> {
let mut doc = PdfDocument::open("invoice-template.pdf")?;
let xml = std::fs::read("factur-x.xml")?;
doc.attach_zugferd_xml(&xml, ZugferdProfile::EN16931)?;
// PDF/A-3 is the conformance level that permits embedded files.
let archival = doc.convert_to_pdfa(PdfAProfile::A3b)?;
archival.save("invoice-einvoice.pdf")?;
Ok(())
}- Step 1
Open the rendered invoice
Start from the PDF a human reads. The XML is attached to it; it does not replace it.
rustlet mut doc = PdfDocument::open("invoice-template.pdf")?; - Step 2
Read the invoice XML
attach_zugferd_xml takes the XML as bytes. PDFluent attaches it; it does not generate or validate the invoice content.
rustlet xml = std::fs::read("factur-x.xml")?; - Step 3
Attach it with the matching profile
The profile writes the ZUGFeRD identifier into the document XMP. Pick the one the XML was built to: Minimum, BasicWL, Basic, EN16931, Extended or XRechnung.
rustuse pdfluent::ZugferdProfile; doc.attach_zugferd_xml(&xml, ZugferdProfile::EN16931)?; - Step 4
Convert to PDF/A-3
Attaching does not change the conformance level. PDF/A-3 is the level that allows embedded files, and convert_to_pdfa returns a new document rather than changing this one in place.
rustuse pdfluent::PdfAProfile; let archival = doc.convert_to_pdfa(PdfAProfile::A3b)?; - Step 5
Save the e-invoice
Write the converted document. The XML travels inside it as an associated file named factur-x.xml.
rustarchival.save("invoice-einvoice.pdf")?;
- PDFluent attaches and extracts invoice XML. It does not build the XML, and it does not check the invoice against EN 16931 business rules -- produce and validate the XML with a dedicated e-invoicing library first.
- The attachment is written as an associated file named factur-x.xml with an /AFRelationship of Alternative, which is what ZUGFeRD and Factur-X readers look for.
- The profile argument records which ZUGFeRD identifier goes in the XMP. It does not change or validate the XML you supply, so a mismatch between the two is not detected here.
- Attaching does not imply PDF/A. Call convert_to_pdfa(PdfAProfile::A3b) yourself; A1b and A2b do not permit embedded files.
- convert_to_pdfa returns a new document. Save the returned value, not the original.
- What is the difference between ZUGFeRD and Factur-X?
- They are the same technical format. ZUGFeRD is the German name (Zentraler User Guide des Forums elektronische Rechnung Deutschland). Factur-X is the French name. Both use the same CII XML schema and PDF/A-3 container.
- Does PDFluent validate the XML against the CII schema?
- PDFluent validates the XML is well-formed and that the profile ID in the XML matches the profile you specified. Full Schematron validation of business rules requires a separate validation step.
- Can I extract the XML from an existing e-invoice PDF?
- Yes. See the Extract Invoice XML guide. doc.zugferd_xml() returns Option<Vec<u8>> -- the raw bytes of the attachment, or None when the PDF carries no invoice.
- Does this work for XRechnung (German public sector)?
- XRechnung is a CIUS of EN 16931 and is usually exchanged as a standalone XML file rather than inside a PDF. PDFluent does not generate that XML. If you already have it, attach_zugferd_xml with ZugferdProfile::XRechnung embeds it and records the KoSIT identifier in the XMP -- it does not enforce XRechnung business rules.
Extract ZUGFeRD or Factur-X XML from a PDF in Rust
use pdfluent::PdfDocument;
fn main() -> pdfluent::Result<()> {
let doc = PdfDocument::open("invoice.pdf")?;
match doc.zugferd_xml()? {
Some(xml) => {
println!("found {} bytes of invoice XML", xml.len());
std::fs::write("extracted-invoice.xml", &xml)?;
}
None => println!("No e-invoice XML found in this PDF."),
}
Ok(())
}- Step 1
Open the PDF
Reading the attachment does not modify the document, so an immutable handle is enough.
rustlet doc = PdfDocument::open("invoice.pdf")?; - Step 2
Ask for the invoice XML
zugferd_xml returns Ok(None) for a PDF that carries no invoice attachment. That is the normal answer, not an error.
rustlet xml = doc.zugferd_xml()?; - Step 3
Handle both outcomes
Match on the Option so a plain PDF is reported rather than treated as a failure.
rustmatch doc.zugferd_xml()? { Some(xml) => println!("found {} bytes of invoice XML", xml.len()), None => println!("No e-invoice XML found in this PDF."), } - Step 4
Write the XML out
The return value is the raw bytes of the attachment, ready to hand to an XML parser or write to disk.
rustif let Some(xml) = doc.zugferd_xml()? { std::fs::write("extracted-invoice.xml", &xml)?; }
- zugferd_xml returns the raw bytes of the embedded file. Parse them with an XML library to read invoice values; PDFluent does not model the invoice contents.
- Ok(None) means the PDF carries no invoice attachment. Only an unreadable or damaged document produces an error.
- The profile is recorded in the document XMP rather than returned alongside the bytes, so read it from the XML or the metadata if you need it.
- Extraction looks for the associated file the ZUGFeRD and Factur-X specifications define. A PDF that merely has an XML file stapled to it by other means is not guaranteed to be found.
- What Rust XML parser should I use to process the extracted XML?
- roxmltree is a good choice for read-only parsing. quick-xml is faster for streaming large documents. Both are written in Rust.
- Can I extract XML from a ZUGFeRD 1.0 PDF?
- No. zugferd_xml() looks for the associated file named factur-x.xml, which is what ZUGFeRD 2.x and Factur-X use. ZUGFeRD 1.0 named its attachment ZUGFeRD-invoice.xml and is not detected. Read that one through the general attachment API instead.
- Does PDFluent validate the extracted XML?
- zugferd_xml() does not run Schematron validation -- it returns the raw bytes of the attachment. Use a dedicated e-invoicing validator if you need the business rules checked.
- How do I create an e-invoice PDF?
- See the Create an E-Invoice PDF guide. PDFluent can embed XML into a PDF and set the required PDF/A-3 metadata in one call.