kivitendo-fixes/README.md

Kivitendo ZUGFeRD Fixes

Patches und Skripte für Kivitendo zur Behebung von ZUGFeRD-Kompatibilitätsproblemen.

Übersicht

Fix	Beschreibung	Betrifft
Einheiten-Migration	m3 → m³ in Datenbank	SQL
MTQ Mapping	m³ → MTQ Code hinzufügen	Perl

---

Einheiten-Migration (SQL)

Problem

Kivitendo erkennt beim ZUGFeRD-Export nur Unicode-Hochzahlen als valide Einheiten:

• ✅ m² (Unicode)
• ❌ m2 oder MTK (Text)

Lösung

change_m3_to_m_hoch_3.sql - Ändert m3 → m³ in der Datenbank

Betroffene Tabellen

• units (Stammdaten)
• parts (Artikel)
• invoice (Rechnungspositionen)
• orderitems (Auftragspositionen)
• delivery_order_items (Lieferscheinpositionen)
• units_language (Übersetzungen)

Anwendung

# 1. Backup erstellen!
sudo -u postgres pg_dumpall > /root/postgres_backup_$(date +%Y%m%d_%H%M%S).sql

# 2. Skript ausführen
sudo -u postgres psql -d <datenbankname> -f change_m3_to_m_hoch_3.sql

---

MTQ Mapping (Perl)

Problem

Kivitendo 3.5.6 hat kein Mapping für Kubikmeter (m³) im UN/ECE Recommendation 20 Helper:

• ✅ m² → MTK (funktioniert)
• ❌ m³ → ??? (fehlt!)

Fehlermeldung:

Die ZUGFeRD-Rechnungsdaten können nicht erzeugt werden, da die Validierung 
fehlschlug. Eine der verwendeten Einheiten (m³) kann keinem der bekannten 
Einheiten-Codes aus der Liste UN/ECE Recommendation 20 zugeordnet werden.

Lösung

Eintrag in SL/Helper/UNECERecommendation20.pm hinzufügen:

# cubic volumes
[ 'MTQ', qr{^(?:m³|cbm|kubik *meter|kubik *metre|cubic *meter|cubic *metre)$}i ],

Anwendung

Manuell:

# 1. Backup
cp /var/www/html/kivitendo-erp/SL/Helper/UNECERecommendation20.pm \
   /var/www/html/kivitendo-erp/SL/Helper/UNECERecommendation20.pm.bak

# 2. Datei bearbeiten
vi /var/www/html/kivitendo-erp/SL/Helper/UNECERecommendation20.pm

# 3. Nach der LTR-Zeile einfügen:
#   # cubic volumes
#   [ 'MTQ', qr{^(?:m³|cbm|kubik *meter|kubik *metre|cubic *meter|cubic *metre)$}i ],

Automatisch (Patch-Datei):

patch -p1 < add_mtq_mapping.patch

Unterstützte Schreibweisen nach dem Fix

Eingabe	UN/ECE Code
m³	MTQ
cbm	MTQ
kubik meter	MTQ
cubic meter	MTQ

Getestet auf

• Kivitendo 3.5.6
• Server: vrlnx-03-hemi (116.203.121.112)
• Datum: 2026-03-01

---

Server-Referenz

Server	IP	Datenbank	Kivitendo
vrlnx-03-hemi	116.203.121.112	hemi	3.5.6

---

Changelog

2026-03-01

• NEU: MTQ Mapping für m³ hinzugefügt (Perl-Fix)
• Root-Cause-Analyse: SL/Helper/UNECERecommendation20.pm fehlte MTQ

2026-01-31

• NEU: SQL-Skript für m3 → m³ Migration

---

Hinweise

⚠️ Backup vor jeder Änderung erstellen!

⚠️ Nach Kivitendo-Updates prüfen: Diese Fixes könnten überschrieben werden. Nach einem Kivitendo-Update sollte geprüft werden, ob:

1. Das MTQ-Mapping in der neuen Version enthalten ist
2. Falls nicht: Patch erneut anwenden

Lizenz

MIT