data/epcqr
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
epcqr/README.md
data 3078cc6f67 Stabile Version 2.0 QR Code lokal generiert und ins odt eingefügt. 
Veränderungen wie Design, Größe, Rahmen usw
2026-01-29 20:37:59 +01:00

14 KiB
Executable file
Raw Blame History

EPC QR-Code Modul für Dolibarr

Version: 2.0 Autor: DATA IT-Solutions (Eduard Wisch) Kompatibilität: Dolibarr 19.0+ Lizenz: GPL-3.0+

Übersicht

Das EPC QR-Code Modul generiert automatisch EPC/GiroCode QR-Codes für SEPA-Überweisungen auf Dolibarr-Rechnungen. Kunden können den QR-Code mit ihrer Banking-App scannen und die Zahlung sofort ausführen - ohne manuelle Eingabe von IBAN, Betrag oder Verwendungszweck.

Neu in Version 2.0

  • Admin-Center mit allen Einstellungen an einem Ort
  • 4 Modul-Stile: Quadrat, Abgerundet, Punkte, Diamant
  • 5 Rahmen-Stile: Kein Rahmen, Einfach, Abgerundet, Doppelt, Gestrichelt
  • Transparenter Hintergrund möglich
  • Logo-Einbettung mit konfigurierbarer Größe (5-30%)
  • Individuelle Farben für Vordergrund und Hintergrund
  • Cache-Verwaltung direkt im Admin-Center
  • Extrafeld-Sichtbarkeit konfigurierbar
  • Verbesserte ODT-Integration

Was sind EPC-QR-Codes?

EPC-QR-Codes (auch GiroCode genannt) enthalten alle relevanten Zahlungsinformationen:

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

Diese QR-Codes sind mit allen europäischen Banking-Apps kompatibel.

Installation

Voraussetzungen

  • Dolibarr 19.0 oder höher
  • PHP 7.1 oder höher
  • PHP GD-Extension (für Bildgenerierung)
  • TCPDF-Bibliothek (in Dolibarr enthalten)

Installationsschritte

  1. Modul-Ordner kopieren:

    cp -r epcqr /path/to/dolibarr/htdocs/custom/

  2. Modul aktivieren:

    • Einstellungen → Module/Anwendungen
    • Kategorie "Finanzen" auswählen
    • "EPC QR-Code" aktivieren

  3. Bankdaten konfigurieren:

    • Einstellungen → Module → EPC QR-Code → Einstellungen
    • Bankverbindung eingeben oder Systembankkonto auswählen

Konfiguration

Admin-Center

Das Admin-Center erreichen Sie unter: Einstellungen → Module → EPC QR-Code → Einstellungen

Es gibt drei Tabs:

  • Einstellungen - Alle Konfigurationsoptionen
  • Debug - QR-Code Testseite
  • Über - Modul-Informationen

Bankverbindung

Einstellung Beschreibung
Datenquelle "Systembankkonto verwenden" oder "Manuelle Eingabe"
Kontoinhaber Name des Kontoinhabers (bei manueller Eingabe)
IBAN Internationale Bankkontonummer
BIC Bank Identifier Code (optional)

Tipp: Bei "Systembankkonto verwenden" werden die Bankdaten automatisch aus dem in Dolibarr konfigurierten Bankkonto geladen.

QR-Code Größe

Einstellung Beschreibung
QR-Code Größe (Verhältnis) Größe in ODT-Dokumenten (0.01 - 2.0)

Empfohlene Werte:

Wert Größe
0.03 - 0.05 sehr klein
0.1 klein
0.3 mittel (Standard)
0.5 groß

Styling-Optionen

Farben

Einstellung Beschreibung
Vordergrundfarbe Farbe der QR-Code-Module (Standard: #000000 schwarz)
Hintergrundfarbe Hintergrundfarbe oder "Transparent" aktivieren

Hinweis: Bei transparentem Hintergrund sollte die Vordergrundfarbe ausreichend Kontrast zum Dokumenthintergrund haben.

Einstellung Beschreibung
Logo (optional) Absoluter Pfad zum Logo-Bild (PNG, JPG, GIF)
Logo-Größe 5% - 30% der QR-Code-Größe (Standard: 20%)

Beispiel-Pfade:

/var/www/dolibarr/documents/mycompany/logos/logo.png
/srv/http/dolibarr/htdocs/custom/epcqr/img/mylogo.png

Wichtig: Bei Verwendung eines Logos wird automatisch die höchste Fehlerkorrektur (H = 30%) verwendet, um die Scanbarkeit zu gewährleisten.

Modul-Stil

Stil Beschreibung
Quadrat Standard QR-Code-Module (klassisch)
Abgerundet Module mit abgerundeten Ecken
Punkte Kreisförmige Module
Diamant Rautenförmige Module

Rahmen-Stil

Stil Beschreibung
Kein Rahmen Standard - ohne Rahmen
Einfach Schlichte Linie um den QR-Code
Abgerundet Rahmen mit runden Ecken
Doppelt Zwei parallele Linien
Gestrichelt Unterbrochene Linie

Cache-Verwaltung

QR-Codes werden lokal gecached für optimale Performance. Nach Änderung der Styling-Einstellungen:

Cache leeren - Klicken Sie auf den Button, um alle gecachten QR-Codes zu löschen. Neue QR-Codes werden mit den aktuellen Einstellungen generiert.

Extrafeld-Sichtbarkeit

Kontrollieren Sie, welche QR-Code-Felder im Rechnungsformular angezeigt werden:

Einstellung Beschreibung
QR-Code (HTML) ausblenden Versteckt das Bild-Feld
QR-Code URL ausblenden Versteckt den URL-Link
QR-Code Pfad ausblenden Versteckt den lokalen Dateipfad

Verwendung

Automatische Generierung

Der QR-Code wird automatisch generiert, wenn:

  1. Eine neue Rechnung erstellt wird
  2. Eine bestehende Rechnung validiert wird

Der Trigger läuft beim Event BILL_VALIDATE.

Extrafelder

Das Modul erstellt drei Extrafelder auf Rechnungen:

Feld Typ Inhalt
qrcode HTML <img>-Tag zur Anzeige im Formular
qrcodepfad HTML URL zum QR-Code-Bild (klickbar)
qrcodepath varchar Lokaler Dateipfad (für ODT-Integration)

ODT-Integration

Um den QR-Code in ODT-Dokumentvorlagen einzufügen:

  1. Platzhalter einfügen:

    {qrcode}

  2. Der QR-Code wird automatisch beim Generieren des Dokuments eingefügt.

  3. Größe anpassen: Die Größe wird über die "QR-Code Größe (Verhältnis)" Einstellung im Admin-Center gesteuert.

Hinweis: Der Platzhalter muss exakt {qrcode} lauten.

Beispiel Template-Position

┌─────────────────────────────────┐
│ RECHNUNG RE2501-0001            │
│                                 │
│ Gesamtbetrag: 1.234,56 EUR      │
│                                 │
│         ┌──────────┐            │
│         │ {qrcode} │            │
│         └──────────┘            │
│                                 │
│ Bitte überweisen Sie den       │
│ Betrag unter Angabe der        │
│ Rechnungsnummer.                │
└─────────────────────────────────┘

Technische Details

EPC/GiroCode Format

Der generierte QR-Code enthält folgende Daten im EPC-Standard:

BCD                     # Service Tag
002                     # Version
1                       # Character set (UTF-8)
SCT                     # SEPA Credit Transfer
[BIC]                   # Bank Identifier Code
[Kontoinhaber]          # Empfänger Name
[IBAN]                  # Empfänger IBAN
EUR[Betrag]             # Währung und Betrag
                        # Purpose (leer)
[Rechnungsnummer]       # Verwendungszweck
                        # Info (leer)

Dateispeicherung

QR-Codes werden gespeichert unter:

/documents/epcqr/qrcodes/epc_[hash].png

Der Hash basiert auf:

  • Bankdaten (Kontoinhaber, IBAN, BIC)
  • Rechnungsdaten (Betrag, Referenz)
  • Styling-Einstellungen (Farben, Logo, Modul-Stil, Rahmen-Stil)

Hooks

Das Modul verwendet folgende Dolibarr-Hooks:

Hook Funktion
invoicecard QR-Code bei Rechnungsvalidierung generieren
odtgeneration QR-Code-Bild in ODT einfügen (beforeODTSave)
pdfgeneration Substitutionsvariablen für PDF

Substitutionsvariablen

Für ODT/PDF-Dokumente stehen folgende Substitutionen zur Verfügung:

Variable Inhalt
{qrcode} QR-Code als Bild
{options_qrcodepath} Lokaler Dateipfad

Modul-Struktur

epcqr/
├── admin/
│   ├── setup.php          # Einstellungen
│   └── about.php          # Über-Seite
├── class/
│   └── actions_epcqr.class.php  # Hook-Aktionen
├── core/
│   ├── modules/
│   │   └── modEpcqr.class.php   # Modul-Deskriptor
│   ├── substitutions/
│   │   └── functions_epcqr.lib.php  # Substitutionen
│   └── triggers/
│       └── interface_99_modEpcqr_EpcqrTriggers.class.php
├── langs/
│   ├── de_DE/
│   │   └── epcqr.lang     # Deutsche Übersetzung
│   └── en_US/
│       └── epcqr.lang     # Englische Übersetzung
├── lib/
│   ├── epcqr.lib.php      # Bibliotheksfunktionen
│   └── qrcode.class.php   # QR-Code Generator
├── sql/
│   ├── llx_epcqr_extrafields.sql  # Extrafelder
│   └── dolibarr_allversions.sql   # Upgrade-Script
├── test_qrcode.php        # Debug-Seite
└── README.md              # Diese Dokumentation

Fehlerbehebung

QR-Code wird nicht generiert

  1. Bankdaten prüfen: Sind Kontoinhaber und IBAN konfiguriert?
  2. Modul aktiv? Ist das EPC QR-Code Modul aktiviert?
  3. Rechnung validiert? QR-Codes werden erst bei Validierung generiert.
  4. Logs prüfen: Einstellungen → Logs auf Fehlermeldungen prüfen.
    • Suche nach "EPCQR" in den Logs

QR-Code nicht scannbar

  1. Größe erhöhen: Mindestens 2x2 cm für zuverlässiges Scannen.
  2. Kontrast prüfen: Dunkle Vordergrundfarbe auf hellem Hintergrund.
  3. Logo verkleinern: Maximale Logo-Größe 30% (besser 20% oder weniger).
  4. Modul-Stil: Bei Problemen "Quadrat" (Standard) verwenden.

ODT: QR-Code erscheint nicht

  1. Platzhalter korrekt? Muss exakt {qrcode} sein.
  2. Pfad existiert? Prüfen ob die Datei unter qrcodepath existiert.
  3. Cache leeren: Nach Änderungen den Cache leeren.
  4. Extrafeld vorhanden? qrcodepath muss als Extrafeld existieren.

Styling-Änderungen haben keine Wirkung

Nach Änderung der Styling-Einstellungen:

  1. Cache leeren im Admin-Center klicken
  2. Rechnung erneut generieren (auf Draft setzen → Validieren)
  3. Oder neuen QR-Code durch neue Rechnung testen

Extra-Felder fehlen

Falls die Extrafelder nicht automatisch erstellt wurden:

  1. Modul deaktivieren
  2. Modul wieder aktivieren
  3. Prüfen unter: Einstellungen → Wörterbücher → Zusatzattribute → Rechnungen

Changelog

Version 2.0 (Januar 2025)

Neue Funktionen:

  • Vollständiges Admin-Center mit allen Einstellungen
  • Modul-Stile: Quadrat, Abgerundet, Punkte, Diamant
  • Rahmen-Stile: Kein Rahmen, Einfach, Abgerundet, Doppelt, Gestrichelt
  • Transparenter Hintergrund
  • Logo-Einbettung mit konfigurierbarer Größe (5-30%)
  • Cache-Verwaltung im Admin-Center
  • Extrafeld-Sichtbarkeit konfigurierbar
  • Verbesserte ODT-Integration mit beforeODTSave Hook
  • Kleinere QR-Code-Größen möglich (ab 0.01)
  • Systembankkonto-Unterstützung

Verbesserungen:

  • Neues Icon (fa-qrcode)
  • Deutsche und englische Übersetzungen vollständig
  • Bessere Fehlerbehandlung und Logging
  • Performance-Optimierungen durch intelligentes Caching
  • SQL-Scripts für automatische Extrafeld-Erstellung

Technische Änderungen:

  • Komplette Überarbeitung der QRCodeGenerator-Klasse
  • Neue Methoden für Modul-Stile und Rahmen
  • Hash-basiertes Caching mit Styling-Berücksichtigung
  • Verbesserte Transparenz-Unterstützung

Version 1.5 (Januar 2025)

  • Lokales QR-Code-Caching
  • Extrafeld qrcodepath für ODT-Integration
  • Grundlegende Farbkonfiguration
  • {qrcode} Keyword für ODT-Templates
  • Hook-basierte ODT-Verarbeitung

Version 1.0 (2025)

  • Initiale Version
  • Automatische EPC QR-Code-Generierung
  • Extra-Felder für Rechnungen
  • Externe QR-Service Integration

API / Entwickler

QR-Code manuell generieren

require_once DOL_DOCUMENT_ROOT.'/custom/epcqr/lib/qrcode.class.php';

$qrGen = new QRCodeGenerator($db);
$filepath = $qrGen->generateEPCQRCode(
    'Max Mustermann',    // Kontoinhaber
    'DE89370400440532013000',  // IBAN
    'COBADEFFXXX',       // BIC
    1234.56,             // Betrag
    'RE2501-0001'        // Verwendungszweck
);

Cache leeren

require_once DOL_DOCUMENT_ROOT.'/custom/epcqr/lib/qrcode.class.php';

$qrGen = new QRCodeGenerator($db);
$deleted = $qrGen->clearCache();
echo "Gelöscht: $deleted QR-Codes";

Styling programmatisch setzen

Die Styling-Optionen werden aus der Dolibarr-Konfiguration geladen:

// In llx_const Tabelle:
// EPCQR_FG_COLOR = '#000000'
// EPCQR_BG_COLOR = '#FFFFFF' oder 'transparent'
// EPCQR_LOGO_PATH = '/path/to/logo.png'
// EPCQR_LOGO_SIZE = 20
// EPCQR_MODULE_STYLE = 'square' | 'rounded' | 'dots' | 'diamond'
// EPCQR_BORDER_STYLE = 'none' | 'simple' | 'rounded' | 'double' | 'dashed'

Support

Bei Fragen oder Problemen:

Bei Problemen

  1. Log-Dateien prüfen: documents/dolibarr.log
  2. Debug-Seite nutzen: Admin-Center → Debug Tab
  3. EPCQR in Logs suchen: Alle Meldungen beginnen mit "EPCQR:"

Lizenz

GNU General Public License v3.0 oder höher

Copyright (C) 2025 Eduard Wisch / DATA IT-Solutions

Dieses Programm ist freie Software; Sie können es unter den Bedingungen der GNU General Public License, wie von der Free Software Foundation veröffentlicht, weitergeben und/oder modifizieren; entweder Version 3 der Lizenz oder (nach Ihrer Wahl) jede spätere Version.

Dieses Programm wird in der Hoffnung verteilt, dass es nützlich sein wird, aber OHNE JEDE GEWÄHRLEISTUNG; sogar ohne die implizite Gewährleistung der MARKTGÄNGIGKEIT oder EIGNUNG FÜR EINEN BESTIMMTEN ZWECK.

Die vollständige Lizenz finden Sie unter: https://www.gnu.org/licenses/gpl-3.0.html