← Back to Skills Marketplace
ZUGFeRD Invoice Merger
by
quantx-heiko
· GitHub ↗
· v1.0.0
317
Downloads
0
Stars
0
Active Installs
1
Versions
Install in OpenClaw
/install zugferd-invoice
Description
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.
README (SKILL.md)
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: \x3Csummary 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
Usage Guidance
This skill appears coherent with its stated purpose, but take these precautions before installing/using it: 1) Download mustang.jar only from the official MustangProject GitHub releases page and verify the checksum/signature if available — running an untrusted JAR can execute arbitrary code. 2) Ensure Java and GhostScript are installed from trusted package sources (homebrew or distro packages). 3) Be aware the SKILL.md uses macOS/homebrew paths; if you run on Linux/Windows you may need to adjust PATH and install commands. 4) The included sample XML files contain real‑looking contact/IBAN data — treat them as sample data; don't accidentally publish them. 5) Run the skill on test files first and validate outputs before submitting to B2B/Gov portals. 6) If you need higher assurance, review the mustang.jar release's checksum or build MustangProject from source.
Capability Analysis
Type: OpenClaw Skill
Name: zugferd-invoice
Version: 1.0.0
The OpenClaw AgentSkills bundle for 'zugferd-invoice' is benign. It implements a workflow to create ZUGFeRD-compliant e-invoices using standard open-source tools like MustangProject (Java) and GhostScript. The `SKILL.md` and `README.md` files instruct the agent to download `mustang.jar` from its official GitHub repository via `curl`, which is a legitimate dependency installation. Python scripts (`zugferd_pages_workflow.py`, `zugferd_workflow.py`) execute `java` and `gs` using `subprocess.run` with arguments passed as lists, preventing shell injection. There is no evidence of data exfiltration, malicious execution, persistence mechanisms, or prompt injection attempts to subvert the agent's intended purpose.
Capability Assessment
Purpose & Capability
The name/description (ZUGFeRD invoice merger) match the code and required tools: Java (mustang.jar) and GhostScript are legitimately needed for extracting/re‑embedding ZUGFeRD XML and producing PDF/A‑3. No unrelated environment variables or credentials are requested. Minor note: the SKILL.md and scripts assume a macOS/homebrew layout (/opt/homebrew/opt/openjdk@21) and recommend brew; the skill has no OS restriction declared, so platform assumptions should be documented or adjusted.
Instruction Scope
SKILL.md and the two Python scripts only operate on user-supplied PDFs and local temporary/output paths. The runtime steps are explicit (extract XML, merge with gs, convert to PDF/A‑3, re‑embed XML with mustang). There are no instructions to read unrelated system files or to transmit data to remote endpoints. The scripts call external binaries (java, gs) with arguments; subprocess calls use argument lists (no shell interpolation).
Install Mechanism
No automated install spec is provided (instruction-only). The SKILL.md recommends manually downloading mustang.jar via curl from the official GitHub releases URL — a reasonable approach. Recommendation: verify the downloaded JAR (checksum/signature) because running arbitrary JARs carries risk. The manual curl direction writes into ~/.openclaw/tools/mustang which is a clear, confined location.
Credentials
The skill requests no credentials or secret environment variables. It does modify PATH locally for the subprocess environment to include the openjdk@21 bin path (expected for invoking java). No extraneous access to other configs or sensitive data is requested.
Persistence & Privilege
The skill is not force-included (always: false) and is user-invocable. It does create a workspace under the skill directory (temp and expected ~/.openclaw/tools paths) but does not modify other skills or system-wide agent settings. Autonomous invocation is enabled by default on the platform but is not combined with other concerning flags.
How to Use
- Make sure OpenClaw is installed (local or Docker)
- Run the install command in chat:
/install zugferd-invoice - After installation, invoke the skill by name or use
/zugferd-invoice - Provide required inputs per the skill's parameter spec and get structured output
Version History
v1.0.0
Initial release: GhostScript workflow for visible pages + ZUGFeRD 2.1 compliance
Metadata
Frequently Asked Questions
What is 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. It is an AI Agent Skill for Claude Code / OpenClaw, with 317 downloads so far.
How do I install ZUGFeRD Invoice Merger?
Run "/install zugferd-invoice" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.
Is ZUGFeRD Invoice Merger free?
Yes, ZUGFeRD Invoice Merger is completely free (open-source). You can download, install and use it at no cost.
Which platforms does ZUGFeRD Invoice Merger support?
ZUGFeRD Invoice Merger is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).
Who created ZUGFeRD Invoice Merger?
It is built and maintained by quantx-heiko (@quantx-heiko); the current version is v1.0.0.
More Skills