# Attach ZUGFeRD and Factur-X XML, and extract it again

Source: https://pdfluent.com/how-to/einvoice/

A developer guide for creating compliant e-invoice PDFs and extracting their embedded XML data using the PDFluent SDK.

## On this page

- Create a ZUGFeRD or Factur-X e-invoice PDF in Rust
- Extract ZUGFeRD or Factur-X XML from a PDF in Rust

## Add PDFluent to Cargo.toml

XML extraction works with the base crate. The einvoice feature adds profile detection and validation helpers.

toml

```
# Cargo.toml
[dependencies]
pdfluent = { version = "0.9", features = ["einvoice"] }
```

## Create a ZUGFeRD or Factur-X e-invoice PDF in Rust

ZUGFeRD and Factur-X are hybrid e-invoice formats. The PDF is human-readable and machine-readable at the same time. The XML payload is embedded as an attachment.

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(())
}
```

1. Step 1 Open the rendered invoiceStart from the PDF a human reads. The XML is attached to it; it does not replace it. rust `*let mut doc = PdfDocument::open("invoice-template.pdf")?;*`
2. Step 2 Read the invoice XMLattach_zugferd_xml takes the XML as bytes. PDFluent attaches it; it does not generate or validate the invoice content. rust `*let xml = std::fs::read("factur-x.xml")?;*`
3. Step 3 Attach it with the matching profileThe profile writes the ZUGFeRD identifier into the document XMP. Pick the one the XML was built to: Minimum, BasicWL, Basic, EN16931, Extended or XRechnung. rust `*use pdfluent::ZugferdProfile;**doc.attach_zugferd_xml(&xml, ZugferdProfile::EN16931)?;*`
4. Step 4 Convert to PDF/A-3Attaching 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. rust `*use pdfluent::PdfAProfile;**let archival = doc.convert_to_pdfa(PdfAProfile::A3b)?;*`
5. Step 5 Save the e-invoiceWrite the converted document. The XML travels inside it as an associated file named factur-x.xml. rust `*archival.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

Read the structured invoice XML embedded inside a ZUGFeRD or Factur-X PDF. Parse it for automated accounting import.

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(())
}
```

1. Step 1 Open the PDFReading the attachment does not modify the document, so an immutable handle is enough. rust `*let doc = PdfDocument::open("invoice.pdf")?;*`
2. Step 2 Ask for the invoice XMLzugferd_xml returns Ok(None) for a PDF that carries no invoice attachment. That is the normal answer, not an error. rust `*let xml = doc.zugferd_xml()?;*`
3. Step 3 Handle both outcomesMatch on the Option so a plain PDF is reported rather than treated as a failure. rust `*match doc.zugferd_xml()? {**Some(xml) => println!("found {} bytes of invoice XML", xml.len()),**None => println!("No e-invoice XML found in this PDF."),**}*`
4. Step 4 Write the XML outThe return value is the raw bytes of the attachment, ready to hand to an XML parser or write to disk. rust `*if 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.
