dolibarr.bankimport/CLAUDE.md

BankImport Modul - Entwicklernotizen

Modul-Übersicht

• Name: BankImport
• Version: 3.5
• Pfad: /srv/http/dolibarr/custom/bankimport/
• Funktion: FinTS/HBCI Kontoauszüge importieren und mit Dolibarr-Rechnungen abgleichen

Wichtige Dateien

Datei	Funktion
class/banktransaction.class.php	Hauptklasse für Transaktionen, findMatches(), confirmMultiplePayment()
confirm.php	Übersicht aller Matches zur Bestätigung
card.php	Einzelansicht einer Transaktion mit manueller Zuordnung
repair.php	Admin-Seite für verwaiste Transaktionen
cron/bankimport.cron.php	Cronjob für automatischen Import
admin/cronmonitor.php	Cron-Monitoring und Pause/Resume
pdfstatements.php	PDF-Kontoauszüge hochladen und per FinTS abrufen
vendor/.../Segment/EKP/*	HKEKP-Segmente für PDF-Abruf
vendor/.../Action/GetStatementPDF.php	Action-Klasse für PDF-Abruf

PDF-Kontoauszüge per FinTS (HKEKP)

Übersicht

Seit Version 3.5 können PDF-Kontoauszüge direkt von der Bank abgerufen werden (HKEKP = Elektronischer Kontoauszug PDF).

Neue Dateien in php-fints

vendor/nemiah/php-fints/lib/Fhp/
├── Action/GetStatementPDF.php     # Haupt-Action-Klasse
└── Segment/EKP/
    ├── HKEKPv2.php                # Request-Segment
    ├── HIEKPv2.php                # Response-Segment
    ├── HIEKP.php                  # Response-Interface
    ├── HIEKPSv2.php               # Parameter-Segment
    ├── HIEKPS.php                 # Parameter-Interface
    └── ParameterKontoauszugPdf.php # Parameter-Model

Verwendung

$fints = new BankImportFinTS();
if ($fints->supportsPdfStatements()) {
    $result = $fints->getStatementPDF(0);  // Account-Index, optional Nr+Jahr
    if ($result['success']) {
        $pdfData = $result['data']['pdf'];
        $info = $result['data']['info'];  // statementNumber, statementYear, etc.
    }
}

Cronjob

• Aktivieren: BANKIMPORT_PDF_AUTO_ENABLED = 1
• Klasse: BankImportCron::doAutoFetchPdf()
• Frequenz: Wie Transaktions-Import konfigurierbar

Multi-Invoice Matching (Sammelzahlungen)

Ablauf

1. findMatches() sucht Einzelmatches und Multi-Matches
2. findSupplierForMultiMatch() findet Lieferant über IBAN oder Name (Similarity > 70%)
3. findMultipleSupplierInvoiceMatches() kombiniert Rechnungen deren ref_supplier im Buchungstext steht
4. Toleranz: 3% des Betrags (für Skonto)

Sortierung

Matches werden sortiert nach:

1. Betragsnähe (innerhalb 10% Threshold bevorzugt)
2. Score (Multi-Match: 98-100, Einzelmatch: variabel)

Skonto-Verarbeitung

In confirmMultiplePayment():

1. Wenn gezahlter Betrag < Rechnungssumme (max 5% Abweichung)
2. Zahlungen werden proportional verteilt (discountFactor = actualAmount / totalPayment)
3. Rechnungen werden mit setPaid($user, 'discount_vat', 'Skonto (X EUR)') geschlossen

Datenbank-Struktur

llx_bankimport_transaction

Feld	Bedeutung
status	0=Neu, 1=Zugeordnet, 2=Abgestimmt, 9=Ignoriert
fk_facture_fourn	Verknüpfte Lieferantenrechnung (erste bei Multi)
fk_paiementfourn	Verknüpfte Zahlung
fk_bank	Verknüpfter Bank-Eintrag
note_private	Multi-invoice payment: SI..., SI..., SI... (Skonto: X EUR)

Rechnung (close_code)

Code	Bedeutung
NULL	Normal bezahlt
discount_vat	Mit Skonto bezahlt
badsupplier	Zahlungsausfall
abandon	Aufgegeben

Bekannte Edge Cases

Problem: Nur 1 statt 3 Rechnungen bestätigt

• Ursache: Multi-Match hatte niedrigeren Score als Einzelmatch
• Lösung: Score auf 98 erhöht + Sortierung nach Betragsnähe

Problem: Skonto nicht erkannt

• Ursache: Toleranz war 5€ fix, Skonto war 6,29€
• Lösung: Toleranz auf 3% des Betrags geändert

Problem: Bezahlte Rechnungen nicht in Liste

• Ursache: Filter prüfte payment.fk_bank statt BankImport-Verknüpfung
• Lösung: Nur llx_bankimport_transaction.status > 0 prüfen

Test-Datenbank

• Host: 192.168.155.1 (Produktiv) / 192.168.155.11 (Test)
• User: dolibarr
• Passwort: 8715

Typische Debug-Queries

-- Transaktion mit Verknüpfungen
SELECT rowid, ref, amount, status, fk_facture_fourn, fk_paiementfourn, fk_bank, note_private
FROM llx_bankimport_transaction WHERE rowid = X;

-- Zahlungsverteilung prüfen
SELECT pf.fk_paiementfourn, pf.fk_facturefourn, pf.amount, f.ref
FROM llx_paiementfourn_facturefourn pf
JOIN llx_facture_fourn f ON f.rowid = pf.fk_facturefourn
WHERE pf.fk_paiementfourn = X;

-- Rechnungen mit Skonto-Status
SELECT rowid, ref, total_ttc, fk_statut, paye, close_code, close_note
FROM llx_facture_fourn WHERE rowid IN (X, Y, Z);

Zurücksetzen einer Transaktion (für Tests)

-- 1. Zahlung-Rechnung Verknüpfung löschen
DELETE FROM llx_paiementfourn_facturefourn WHERE fk_paiementfourn = X;

-- 2. Bank-URL löschen
DELETE FROM llx_bank_url WHERE url_id = X AND type = 'payment_supplier';

-- 3. Zahlung löschen
DELETE FROM llx_paiementfourn WHERE rowid = X;

-- 4. Bank-Eintrag löschen
DELETE FROM llx_bank WHERE rowid = Y;

-- 5. Rechnung(en) auf offen setzen
UPDATE llx_facture_fourn SET fk_statut = 1, paye = 0, close_code = NULL, close_note = NULL WHERE rowid IN (...);

-- 6. BankImport-Transaktion zurücksetzen
UPDATE llx_bankimport_transaction
SET status = 0, fk_facture_fourn = NULL, fk_paiementfourn = NULL, fk_bank = NULL,
    fk_user_match = NULL, date_match = NULL
WHERE rowid = Z;