epcqr/README.md.back

# EPCQR - QR-Code Generator für Dolibarr Rechnungen

**Version:** 1.4  
**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. Diese QR-Codes ermöglichen es Kunden, Rechnungen direkt mit ihrer Banking-App zu scannen und zu bezahlen - ohne manuelle Eingabe von IBAN, Betrag oder Verwendungszweck.

### Was sind EPC-QR-Codes?

EPC-QR-Codes enthalten alle relevanten Zahlungsinformationen im GiroCode-Format:
- Empfänger (Kontoinhaber)
- IBAN
- BIC
- Betrag
- Verwendungszweck (Rechnungsnummer)

---

## Features

✅ **Automatische Generierung** bei Rechnungsfreigabe  
✅ **EPC/GiroCode-Standard** konform  
✅ **Externe QR-Service Integration** (kein lokaler PHP-Code nötig)  
✅ **Extra-Felder** für ODT-Template Integration  
✅ **Finale Rechnungsnummer** im QR-Code (keine PROV-Nummern)  
✅ **Einfache Konfiguration** über Code  

---

## 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 2 Extra-Felder für Rechnungen:

| Feldname | Typ | Beschreibung |
|----------|-----|--------------|
| `qrcode` | HTML | QR-Code als `<img>` Tag für ODT-Templates |
| `qrcodepfad` | Varchar(255) | Vollständige QR-Code URL (Backup) |

---

## 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`:

```php
// Bankdaten - HIER ANPASSEN!
$accountHolder = 'Eduard Wisch';
$iban = 'DE70217625500013438147';
$bic = 'GENODEF1HUM';
```

**Ändere diese Werte auf deine Daten:**

```php
$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

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

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

```
{invoice_options_qrcode}
```

**Schritt 3:** Template speichern und hochladen

**Ergebnis:** Der QR-Code erscheint automatisch auf jeder generierten Rechnung!

### Beispiel Template-Position

```
┌─────────────────────────────────┐
│ RECHNUNG IN26-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:

```php
$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:

```php
// 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`:

```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

```php
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`:

```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:**
```php
$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

---

## Support &amp; Kontakt

**Entwickler:** Eduard Wisch  
**GitHub:** [Dein GitHub Link]  
**E-Mail:** [Deine E-Mail]

### Bei Problemen

1. **Log-Dateien prüfen:** `documents/dolibarr.log`
2. **Debug aktivieren:** Setup → Other → Enable debug mode
3. **GitHub Issues:** [Link zu Issues]

---

## Changelog

### Version 1.0 (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!** 🎉