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
- Extract XML from original e-invoice
- Merge PDFs with GhostScript (visible pages)
- Convert to PDF/A-3 with GhostScript
- Embed XML with MustangProject combine
- Validate final PDF
Why This Works
Standard PDF merging breaks PDF/A-3 compliance. The trick:
- Merge first (any PDFs allowed)
- Then convert the merged result to PDF/A-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+