data/epcqr
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
epcqr/README.md

13 KiB
Executable file
Raw Blame History

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-&gt;db);
$invoice-&gt;fetch($object-&gt;id);
// Jetzt hat $invoice-&gt;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&amp;iban=DE70217625500013438147&amp;bic=GENODEF1HUM&amp;amount=1234.56&amp;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-&gt;ref;

// RICHTIG:
$invoice = new Facture($this-&gt;db);
$invoice-&gt;fetch($object-&gt;id);
$ref = $invoice-&gt;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-&gt;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-&gt;id);
        
        // ⚠️ WICHTIG: Objekt neu laden für finale Rechnungsnummer!
        require_once DOL_DOCUMENT_ROOT.'/compta/facture/class/facture.class.php';
        $invoice = new Facture($this-&gt;db);
        $result = $invoice-&gt;fetch($object-&gt;id);
        
        if ($result &gt; 0) {
            // Bankdaten - HIER ANPASSEN!
            $accountHolder = 'Eduard Wisch';
            $iban = 'DE70217625500013438147';
            $bic = 'GENODEF1HUM';
            $amount = price2num($invoice-&gt;total_ttc, 'MT');
            $ref = $invoice-&gt;ref; // Finale Nummer
            
            // QR-Code URL generieren
            $qrurl = "https://qr.data-it-solution.de/epc?"
                . "name=" . urlencode($accountHolder)
                . "&amp;iban=" . urlencode($iban)
                . "&amp;bic=" . urlencode($bic)
                . "&amp;amount=" . urlencode($amount)
                . "&amp;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! 🎉