ZUGFeRD Invoice Merger

Merge ZUGFeRD 2.1 compliant invoice PDF and time report into a single visible multi-page PDF/A-3b file with embedded XML for German B2B/Gov use.

zugferd-invoice

Create ZUGFeRD 2.1 / Factur-X compliant e-invoices with visible merged pages. German B2B / Gov-ready.

🇩🇪 Germany/EU only - This skill implements the German ZUGFeRD standard for electronic invoicing.

Features

• ✅ Visible pages: Merge invoice + time report into a single multi-page PDF
• ✅ ZUGFeRD 2.1 compliant: PDF/A-3b with embedded XML
• ✅ EN16931 valid: Ready for B2B portals and government submission
• ✅ No paid APIs: Uses MustangProject (open source) + GhostScript
• ✅ Two workflows: Visible pages (recommended) or attachment-only fallback

Requirements

Dependency	Install	Notes
Java 11+	brew install openjdk@21	Required by MustangProject
GhostScript	brew install ghostscript	PDF/A-3 conversion
mustang.jar	Manual download	ZUGFeRD processor

Install mustang.jar

mkdir -p ~/.openclaw/tools/mustang
curl -L https://github.com/ZUGFeRD/mustangproject/releases/download/core-2.22.0/mustang.jar \
     -o ~/.openclaw/tools/mustang/mustang.jar

Usage

Recommended: GhostScript Workflow (Visible Pages)

export PATH="/opt/homebrew/opt/openjdk@21/bin:$PATH"
cd ~/.openclaw/workspace/skills/zugferd-invoice

python3 scripts/zugferd_pages_workflow.py \
  --invoice Rechnung.pdf \
  --attachment Zeitnachweis.pdf \
  --output Rechnung_komplett.pdf

Output:

• Multi-page PDF (both documents visible)
• PDF/A-3b compliant
• ZUGFeRD 2.1 XML embedded
• Valid for B2B/Gov portals

Fallback: Attachment-Only Workflow

python3 scripts/zugferd_workflow.py \
  --invoice Rechnung.pdf \
  --attachment Zeitnachweis.pdf \
  --output Rechnung_komplett.pdf

Output:

• Invoice visible, time report as file attachment
• Use when GhostScript is unavailable

Arguments

Flag	Description	Required
--invoice	Original ZUGFeRD e-invoice PDF	✅ Yes
--attachment	Time report / additional document	✅ Yes
--output	Output path for merged PDF	✅ Yes
--keep-temp	Keep temporary files (debug)	❌ No

Workflows Compared

Feature	GhostScript (Recommended)	Attachment-Only (Fallback)
Visible pages	✅ Both documents	⚠️ Only invoice
Time report visibility	✅ Page 2+	❌ File attachment only
PDF/A-3 compliance	✅ Full	✅ Full
Requires GhostScript	✅ Yes	❌ No
Complexity	Medium	Low

Technical Details

GhostScript Workflow Steps

1. Extract XML from original e-invoice
2. Merge PDFs with GhostScript (visible pages)
3. Convert to PDF/A-3 with GhostScript
4. Embed XML with MustangProject combine
5. Validate final PDF

Why This Works

Standard PDF merging breaks PDF/A-3 compliance. The trick:

1. Merge first (any PDFs allowed)
2. Then convert the merged result to PDF/A-3
3. Finally embed the ZUGFeRD XML

This preserves visible pages while achieving full compliance.

Why Attachment-Only?

If your time report cannot be converted to PDF/A (e.g., Lexware exports with broken ICC profiles), use --attachments flag which embeds files without visible merging.

Troubleshooting

"gs not found"

brew install ghostscript

"java not found"

brew install openjdk@21
export PATH="/opt/homebrew/opt/openjdk@21/bin:$PATH"

"mustang.jar not found"

Download from MustangProject releases

Validation fails

• Ensure input invoice is valid ZUGFeRD PDF/A-3
• Check GhostScript version: gs --version (should be 10+)

Output Verification

# Check PDF/A compliance
java -jar ~/.openclaw/tools/mustang/mustang.jar --action validate \
  --source Rechnung_komplett.pdf

# Should output: <summary status="valid"/>

Notes

• ZUGFeRD = Germany only: Electronic invoicing standard for German B2B
• Factur-X: French equivalent (also supported)
• EN16931: European standard for e-invoices
• Source PDFs: Invoice must be ZUGFeRD PDF/A-3; attachment can be any PDF

Dependencies

• Python 3.8+
• Java 11+ (MustangProject)
• GhostScript 10+
• MustangProject CLI 2.22.0+

See Also

• ZUGFeRD Standard
• MustangProject
• EN16931