SkillHub

zugferd-invoice

v1.0.0

合并ZUGFeRD 2.1合规发票PDF与工时报告，生成内嵌XML的单一可视多页PDF/A-3b文件，适用于德国B2B及政府用途。

Sourced from ClawHub, Authored by quantx-heiko

Installation

Please help me install the skill `zugferd-invoice` from SkillHub official store. npx skills add quantx-heiko/zugferd-invoice

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

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