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 (direkt)
vendor/.../Segment/KAA/*	HKKAA-Segmente für PDF-Abruf (Archiv)
vendor/.../Action/GetStatementPDF.php	Action-Klasse für HKEKP
vendor/.../Action/GetStatementFromArchive.php	Action-Klasse für HKKAA

PDF-Kontoauszüge per FinTS

Übersicht

Seit Version 3.5 können PDF-Kontoauszüge von der Bank abgerufen werden. Es gibt zwei Methoden:

Methode	Segment	Beschreibung	Bank-Beispiele
HKEKP	Elektronischer Kontoauszug PDF	Direkt-Abruf	Sparkassen, einige Volksbanken
HKKAA	Kontoauszug aus Archiv	Abruf aus Bank-Postfach	VR Banken (z.B. VR Bank Schleswig-Holstein)

Das System wählt automatisch die beste verfügbare Methode.

Neue Dateien in php-fints

vendor/nemiah/php-fints/lib/Fhp/
├── Action/
│   ├── GetStatementPDF.php        # HKEKP Action
│   └── GetStatementFromArchive.php # HKKAA Action
└── Segment/
    ├── EKP/                        # HKEKP Segmente
    │   ├── HKEKPv2.php
    │   ├── HIEKPv2.php
    │   └── ...
    └── KAA/                        # HKKAA Segmente
        ├── HKKAAv2.php
        ├── HIKAAv2.php
        ├── HIKAASv1.php
        └── ParameterKontoauszugArchiv.php

Verwendung (empfohlen: Auto-Modus)

$fints = new BankImportFinTS($db);
$fints->login();

// Automatische Methodenwahl
$method = $fints->getPdfStatementMethod();  // 'HKEKP', 'HKKAA' oder false
if ($method) {
    $result = $fints->getStatementPDFAuto(0);
    if (is_array($result) && !empty($result['pdfData'])) {
        $pdfData = $result['pdfData'];
        $info = $result['info'];
        $usedMethod = $result['method'];  // 'HKEKP' oder 'HKKAA'
    }
}

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;