EPCQR - QR-Code Generator für Dolibarr Rechnungen

Version: 1.5 Autor: Eduard Wisch Dolibarr: 13.x - 20.x Lizenz: GPL-3.0+

---

Übersicht

Das EPCQR Modul generiert automatisch EPC-QR-Codes (European Payments Council) für Dolibarr-Rechnungen und bietet eine wiederverwendbare Lösung zum Einfügen von Bildern in ODT-Dokumentvorlagen.

Neu in Version 1.5

✅ Lokale QR-Code-Generierung mit Caching ✅ Generisches Bildintegration-System für ODT-Dokumente ✅ {qrcode} Keyword in ODT-Templates ✅ Substitutionssystem für beliebige Bilder ✅ Hook-basierte ODT-Verarbeitung

Was sind EPC-QR-Codes?

EPC-QR-Codes enthalten alle relevanten Zahlungsinformationen im GiroCode-Format:

• Empfänger (Kontoinhaber)
• IBAN
• BIC
• Betrag
• Verwendungszweck (Rechnungsnummer)

---

Features

QR-Code Generierung

✅ Automatische Generierung bei Rechnungsfreigabe ✅ Lokales Caching (keine externe Service-Abhängigkeit mehr) ✅ EPC/GiroCode-Standard konform ✅ Finale Rechnungsnummer im QR-Code (keine PROV-Nummern)

Bildintegration in ODT

✅ {qrcode} Keyword für einfache Verwendung in Templates ✅ Generisches System für beliebige Bilder ✅ Automatische Bildgrößen-Anpassung ✅ Wiederverwendbar für andere Module

Technisch

✅ Hook-System für ODT-Verarbeitung ✅ Substitutionsfunktionen für Dokumente ✅ Extra-Felder mit _imagepath Suffix automatisch erkannt ✅ Vollständige ODT-ZIP-Verarbeitung

---

Installation

1. Modul aktivieren

1. Gehe zu: Home → Setup → Modules/Applications
2. Suche nach "EPCQR"
3. Klicke auf Activate

2. Extra-Felder werden automatisch erstellt

Das Modul erstellt automatisch 3 Extra-Felder für Rechnungen:

Feldname	Typ	Beschreibung
qrcode	HTML	QR-Code als <img> Tag (Kompatibilität)
qrcodepfad	Varchar(255)	QR-Code URL via viewimage.php
qrcodepath	Varchar(255)	NEU: Lokaler Dateipfad für ODT-Integration

---

Konfiguration

Bankdaten anpassen

WICHTIG: Du musst deine Bankdaten im Code hinterlegen!

Datei: /custom/epcqr/class/actions_epcqr.class.php

Suche nach dieser Stelle im Trigger BILL_VALIDATE:

// Bankdaten - HIER ANPASSEN!
$accountHolder = 'Peter Casimir';
$iban = 'DE70217625500013438147';
$bic = 'GENODEF1HUM';

Ändere diese Werte auf deine Daten:

$accountHolder = 'Dein Name / Firmenname';
$iban = 'DE12345678901234567890';
$bic = 'ABCDEFGH123';

Speichern und fertig!

---

Verwendung

Automatische QR-Code Generierung

Der QR-Code wird automatisch generiert wenn du eine Rechnung freigibst:

1. Rechnung erstellen (Status: Draft)
2. Freigeben (Validate)
3. QR-Code wird automatisch generiert
4. Extra-Felder werden befüllt

QR-Code in ODT-Templates einfügen

NEU in Version 1.5: Verwenden Sie das einfache {qrcode} Keyword!

Schritt 1: ODT-Template öffnen (z.B. in LibreOffice)

Schritt 2: An gewünschter Stelle einfügen:

{qrcode}

Schritt 3: Template speichern und hochladen

Schritt 4: Rechnung freigeben → QR-Code wird automatisch generiert

Schritt 5: Dokument als ODT generieren → QR-Code wird eingefügt

Ergebnis: Der QR-Code erscheint automatisch als Bild im ODT-Dokument!

Hinweis: Das alte Format {invoice_options_qrcode} funktioniert weiterhin für Kompatibilität.

Beispiel Template-Position

┌─────────────────────────────────┐
│ RECHNUNG IN2601-0001              │
│                                 │
│ Gesamtbetrag: 1.234,56 €       │
│                                 │
│ {invoice_options_qrcode}        │ ← QR-Code hier
│                                 │
│ Bitte überweisen Sie...        │
└─────────────────────────────────┘

---

Technische Details

Wie funktioniert das Modul?

1. Trigger-System

Das Modul nutzt den Dolibarr-Trigger BILL_VALIDATE, der bei Rechnungsfreigabe ausgeführt wird.

Problem: Zu diesem Zeitpunkt hat das $object noch die provisorische Nummer (z.B. PROV23)!

Lösung: Das Modul lädt das Rechnungsobjekt neu aus der Datenbank:

$invoice = new Facture($this->db);
$invoice->fetch($object->id);
// Jetzt hat $invoice->ref die finale Nummer (z.B. IN26-0001)

2. QR-Code Service

Das Modul nutzt einen externen Service:

URL: https://qr.data-it-solution.de/epc

Parameter:

• name = Kontoinhaber
• iban = IBAN
• bic = BIC/SWIFT
• amount = Betrag (formatiert mit price2num())
• remittance = Verwendungszweck (Rechnungsnummer)

Beispiel-URL:

https://qr.data-it-solution.de/epc?name=Eduard+Wisch&iban=DE70217625500013438147&bic=GENODEF1HUM&amount=1234.56&remittance=IN26-0001

3. Speicherung

Der QR-Code wird in 2 Extra-Feldern gespeichert:

// Als HTML-Tag für ODT
$invoice-&gt;array_options['options_qrcode'] = "<img src="$qrurl" width="100px">";

// Als URL für Backup/Referenz
$invoice-&gt;array_options['options_qrcodepfad'] = $qrurl;

---

Workflow-Diagramm

┌─────────────────────┐
│ Rechnung erstellen  │
│ (Status: DRAFT)     │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ Freigeben (Validate)│
└──────────┬──────────┘
           │
           ▼
┌─────────────────────────────┐
│ 1. Datenbank Update         │
│    → Finale Nummer vergeben │
└──────────┬──────────────────┘
           │
           ▼
┌─────────────────────────────┐
│ 2. Trigger BILL_VALIDATE    │
│    → Modul wird aufgerufen  │
└──────────┬──────────────────┘
           │
           ▼
┌─────────────────────────────┐
│ 3. Object neu laden         │
│    → Finale Nummer holen    │
└──────────┬──────────────────┘
           │
           ▼
┌─────────────────────────────┐
│ 4. QR-URL generieren        │
│    → Mit finaler Nummer     │
└──────────┬──────────────────┘
           │
           ▼
┌─────────────────────────────┐
│ 5. Extra-Felder speichern   │
│    → options_qrcode         │
│    → options_qrcodepfad     │
└─────────────────────────────┘

---

Troubleshooting

Problem: QR-Code zeigt PROV-Nummer

Symptom: QR-Code enthält "PROV23" statt "IN26-0001"

Ursache: Object wurde nicht neu geladen im Trigger

Lösung: Prüfe in actions_epcqr.class.php:

// FALSCH:
$ref = $object->ref;

// RICHTIG:
$invoice = new Facture($this->db);
$invoice->fetch($object->id);
$ref = $invoice->ref;

Problem: Extra-Felder sind leer

Symptom: Nach Freigabe sind die Felder qrcode und qrcodepfad leer

Lösung:

1. Modul deaktivieren
2. Modul wieder aktivieren
3. Prüfe: Setup → Dictionaries → Extra Attributes → Invoices
4. Sollten 2 Felder da sein: qrcode und qrcodepfad

Problem: QR-Code wird in ODT nicht angezeigt

Symptom: Template zeigt nur {invoice_options_qrcode} als Text

Lösungen:

1. Feldname prüfen: Muss exakt {invoice_options_qrcode} heißen
2. Extra-Feld aktiviert? Setup → Extra Attributes → "Printable" = Ja
3. Template neu generieren: Rechnung → "Generate document"

Problem: Falscher Betrag im QR-Code

Symptom: Banking-App zeigt falschen Betrag

Ursache: Formatierung falsch

Lösung: Modul nutzt korrekt price2num($invoice->total_ttc, 'MT')

Problem: QR-Code kann nicht gescannt werden

Mögliche Ursachen:

• QR-Code zu klein im PDF → Größe in ODT anpassen
• Externe URL nicht erreichbar → Internetverbindung prüfen
• Falsches Format → Service-URL prüfen

---

Extra-Felder Details

Feld: qrcode

• Typ: HTML
• Inhalt: <img src="https://..." width="100px">
• Verwendung: Für ODT-Templates
• Printable: Ja
• Position: 100

Feld: qrcodepfad

• Typ: varchar(255)
• Inhalt: Vollständige QR-Code URL
• Verwendung: Backup, Debugging, externe Verarbeitung
• Printable: Nein (nur intern)
• Position: 101

---

Code-Referenz

Kompletter Trigger-Code

public function runTrigger($action, $object, User $user, Translate $langs, Conf $conf)
{
    if ($action == 'BILL_VALIDATE') {
        
        dol_syslog("EPCQR: Generiere QR-Code für Rechnung ID " . $object->id);
        
        // ⚠️ WICHTIG: Objekt neu laden für finale Rechnungsnummer!
        require_once DOL_DOCUMENT_ROOT.'/compta/facture/class/facture.class.php';
        $invoice = new Facture($this->db);
        $result = $invoice->fetch($object->id);
        
        if ($result > 0) {
            // Bankdaten - HIER ANPASSEN!
            $accountHolder = 'Eduard Wisch';
            $iban = 'DE70217625500013438147';
            $bic = 'GENODEF1HUM';
            $amount = price2num($invoice->total_ttc, 'MT');
            $ref = $invoice->ref; // Finale Nummer
            
            // QR-Code URL generieren
            $qrurl = "https://qr.data-it-solution.de/epc?"
                . "name=" . urlencode($accountHolder)
                . "&iban=" . urlencode($iban)
                . "&bic=" . urlencode($bic)
                . "&amount=" . urlencode($amount)
                . "&remittance=" . urlencode($ref);
            
            // In Extra-Felder speichern
            $invoice-&gt;array_options['options_qrcode'] = "<img src="&quot;.$qrurl.&quot;" width="100px">";
            $invoice-&gt;insertExtraFields();
            $invoice-&gt;array_options['options_qrcodepfad'] = $qrurl;
            $invoice-&gt;insertExtraFields();
            
            dol_syslog("EPCQR: QR-Code generiert für " . $invoice-&gt;ref);
        } else {
            dol_syslog("EPCQR: Fehler beim Laden der Rechnung", LOG_ERR);
            return -1;
        }
        
        return 1;
    }
    
    return 0;
}

---

FAQ

Kann ich andere QR-Services nutzen?

Ja! Ändere einfach die URL in actions_epcqr.class.php:

$qrurl = "https://dein-service.de/qr?"
    . "deine_parameter=" . urlencode($value);

Funktioniert das Modul mit allen Rechnungstypen?

Ja, der Trigger BILL_VALIDATE wird für alle Rechnungstypen aufgerufen:

• Standard-Rechnungen
• Gutschriften
• Ersatzrechnungen
• Anzahlungsrechnungen

Kann ich die QR-Code-Größe ändern?

Ja, in 2 Varianten:

1. Im Code:

$invoice-&gt;array_options['options_qrcode'] = "<img src="&quot;.$qrurl.&quot;" width="150px">";

2. Im ODT-Template: Bild markieren → Rechtsklick → Eigenschaften → Größe ändern

Werden alte Rechnungen auch mit QR-Codes versehen?

Nein, nur neue Rechnungen die nach Modulaktivierung freigegeben werden.

Für alte Rechnungen:

1. Rechnung auf "Draft" setzen
2. Erneut freigeben
3. QR-Code wird generiert

---

Dokumentation

📖 Ausführliche Dokumentation: doc/BILDER_IN_ODT.md

Die erweiterte Dokumentation enthält:

• Technische Details zur Bildverarbeitung
• Anleitung für eigene Bilder
• Fehlerbehebung und Debugging
• Code-Referenz und Architektur
• Erweiterte Verwendungsmöglichkeiten

---

Support & Kontakt

Entwickler: Eduard Wisch E-Mail: data@data-it-solution.de

Bei Problemen

1. Log-Dateien prüfen: documents/dolibarr.log
2. Debug aktivieren: Setup → Other → Enable debug mode
3. Dokumentation lesen: doc/BILDER_IN_ODT.md

---

Changelog

Version 1.5 (2026-01-27)

• ✅ Lokale QR-Code-Generierung mit Caching-System
• ✅ {qrcode} Keyword für ODT-Templates
• ✅ Generisches Bildintegration-System für beliebige Bilder
• ✅ Substitutionssystem aktiviert und implementiert
• ✅ Hook-basierte ODT-Verarbeitung (afterODTCreation)
• ✅ Automatische Bildgrößen-Anpassung in ODT
• ✅ Wiederverwendbare Lösung für andere Module
• ✅ Neue Klassen: QRCodeGenerator, ActionsEpcqr
• ✅ Neue Funktionen: epcqr_processODTImages, epcqr_insertImagesIntoODT
• ✅ Dokumentation: doc/BILDER_IN_ODT.md

Version 1.4 (2026-01-11)

• ✅ Erste stabile Version
• ✅ Automatische QR-Code Generierung
• ✅ Extra-Felder für ODT-Integration
• ✅ Externe QR-Service Integration
• ✅ Object-Reload Fix für finale Rechnungsnummer

---

Lizenz

GPL-3.0+

Dieses Modul ist freie Software; Sie können es unter den Bedingungen der GNU General Public License Version 3 oder später weitergeben und/oder modifizieren.

---

Viel Erfolg mit EPCQR! 🎉