💰 Kontoauszugs-Importer

Automatische Konvertierung von PDF-Kontoauszügen zu CSV-Dateien für Excel, Numbers & Buchhaltungssoftware.

Unterstützte Banken: PayPal • HASPA (Hamburger Sparkasse)

---

🚀 Los geht's - 2 Schritte

Schritt 1: Installation (einmalig)

./install_dependencies.sh

Das war's! Das Skript installiert automatisch alles was du brauchst:

• Python 3.9+
• pdftotext (PDF-Text-Extraktion)
• ocrmypdf (automatisches OCR für Scans)
• Alle Python-Pakete

Wichtig für macOS: Falls Homebrew fehlt, erst installieren:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Schritt 2: PDF verarbeiten

So einfach:

./kontoauszug.sh haspa.pdf

oder

./kontoauszug.sh paypal.pdf

Das war's! Die CSV-Dateien liegen jetzt in export_<dateiname>/

---

📂 Was bekomme ich?

Das Tool erstellt zwei CSV-Dateien pro Bank:

Datei	Inhalt
*_import.csv	✅ Sichere Transaktionen (direkt in Excel importieren)
*_review.csv	⚠️ Unsichere Transaktionen (manuell prüfen)

CSV-Format:

Datum;Empfänger/Zahlungspflichtiger;Betrag in Euro;Verwendungszweck
13.02.2019;[email protected];-26,00;PayPal-Zahlung
14.02.2019;Supermarkt GmbH;476,00;Einkauf

• Trennzeichen: Semikolon (;)
• Encoding: UTF-8
• Direkt importierbar in Excel, Numbers, LibreOffice

---

🤖 Was macht das Tool automatisch?

Das Skript kontoauszug.sh macht alles automatisch:

1. ✅ Erkennt die Bank (anhand Dateiname: "haspa" oder "paypal")
2. ✅ Extrahiert das Jahr (z.B. aus "haspa_2020_01.pdf")
3. ✅ Führt OCR durch wenn das PDF ein Scan ist (dauert 10-30 Sek)
4. ✅ Korrigiert OCR-Fehler (@gmx.dee → @gmx.de, 43.02.2019 → 13.02.2019)
5. ✅ Erstellt Ausgabe-Ordner mit passendem Namen
6. ✅ Installiert fehlende Tools (ocrmypdf auf macOS)

Beispiel:

./kontoauszug.sh haspa_2020_01.pdf

# Ausgabe:
# [INFO] Verarbeite: haspa_2020_01.pdf
# [INFO] Erkannt: HASPA-Kontoauszug
# [INFO] Jahr erkannt: 2020
# [INFO] Ausgabe-Ordner: export_haspa_2020_01
# [OK] HASPA: 22 gut / 13 review
# [OK] Fertig! CSV-Dateien in: export_haspa_2020_01

---

❓ Häufige Fragen

Meine PDF ist ein Scan - was nun?

Kein Problem! Das Tool führt automatisch OCR durch:

./kontoauszug.sh haspa.pdf

# Wenn die PDF ein Scan ist:
# [WARN] Keine erkennbaren Buchungen im Text
# [INFO] Vermutlich ist 'haspa.pdf' ein Scan
# [INFO] Versuche automatisches OCR...
# [INFO] Führe OCR durch: haspa.pdf → haspa-ocr.pdf
# [INFO] Das kann 10-30 Sekunden dauern...
# [OK] OCR erfolgreich: haspa-ocr.pdf
# [INFO] Bitte erneut ausführen mit: ./kontoauszug.sh haspa-ocr.pdf

Dann einfach nochmal mit der OCR-PDF:

./kontoauszug.sh haspa-ocr.pdf

Die PDF ist passwortgeschützt

Lösung mit Preview (macOS):

1. Öffne die PDF in Preview
2. Menü → Ablage → Exportieren
3. Verschlüsselung: Keine
4. Speichern und erneut verarbeiten

Lösung mit qpdf:

brew install qpdf
qpdf --decrypt haspa.pdf haspa-ohne-pw.pdf
./kontoauszug.sh haspa-ohne-pw.pdf

Die PDF ist beschädigt

# Mit Ghostscript reparieren:
brew install ghostscript  # falls nicht installiert
gs -o haspa-repariert.pdf -sDEVICE=pdfwrite haspa.pdf
./kontoauszug.sh haspa-repariert.pdf

Viele Transaktionen in Review-CSV?

Das ist normal! OCR ist nicht perfekt. Das Tool markiert lieber zu viel als zu wenig.

So gehst du vor:

1. Öffne *_review.csv in Excel/Numbers
2. Spalte "Kommentar" zeigt das Problem (z.B. "Datum: unplausibel")
3. Korrigiere die betroffenen Zeilen
4. Kopiere sie in *_import.csv

Typische Kommentare:

Kommentar	Bedeutung	Was tun?
Datum: unplausibel	Datum ergibt keinen Sinn	Mit Original-PDF vergleichen
Betrag: verdächtig	Betrag scheint falsch	Mit Original-PDF vergleichen
Email: nicht korrigiert	Email-Domain unbekannt	Manuell korrigieren
Empfänger enthält OCR-Artefakte (Qualität: 45%)	Name mit vielen Sonderzeichen	Mit Original-PDF vergleichen

OCR-Qualität verbessern

Das Tool nutzt Tesseract OCR mit optimierten Parametern für beste Erkennung:

✅ Automatisch aktiviert:

• 300 DPI Upsampling - Hochskalierung für bessere Lesbarkeit
• Deskew - Korrigiert schiefe Seiten
• Rotate-pages - Dreht falsch ausgerichtete Seiten
• Clean-final - Entfernt Bildrauschen
• Remove-background - Verbessert Kontrast

💡 Tipps für bessere Ergebnisse:

Problem	Lösung
Scan zu dunkel/zu hell	PDF mit Scanner-Software neu scannen (300 DPI)
Schiefe Seiten	Wird automatisch korrigiert (deskew)
Viel Bildrauschen	PDF mit höherer Auflösung scannen (300+ DPI)
Tabellen falsch erkannt	Normal bei Tesseract - Review-CSV manuell prüfen
Schriftart ungewöhnlich	Tesseract bevorzugt Standard-Schriften (Arial, Times)

Erweiterte OCR-Parameter (falls nötig):

# Manuelles OCR mit maximaler Qualität:
ocrmypdf --language deu \
  --deskew \
  --rotate-pages \
  --clean-final \
  --remove-background \
  --oversample 300 \
  --optimize 1 \
  input.pdf output-ocr.pdf

Confidence-Scores in CSV:

Die Review-CSV enthält Qualitätsbewertungen (0-100%):

• confidence_datum - Wie sicher ist das Datum?
• confidence_betrag - Wie sicher ist der Betrag?
• confidence_empfaenger - Wie sicher ist der Empfänger?

Werte unter 60% werden automatisch zur Review markiert.

Ich will mehrere PDFs auf einmal verarbeiten

# Alle HASPA-PDFs im Ordner:
for pdf in haspa_*.pdf; do
  ./kontoauszug.sh "$pdf"
done

# Alle PayPal-PDFs:
for pdf in paypal_*.pdf; do
  ./kontoauszug.sh "$pdf"
done

---

🔧 Erweiterte Nutzung

Manueller Aufruf (ohne Wrapper-Skript)

Falls du mehr Kontrolle brauchst:

PayPal:

python3 statements.py --paypal-pdf paypal.pdf --autofix-domains

HASPA:

python3 statements.py --haspa-pdf haspa.pdf --year 2020

Beide gleichzeitig:

python3 statements.py \
  --paypal-pdf paypal.pdf \
  --haspa-pdf haspa.pdf \
  --year 2020 \
  --autofix-domains

Alle Optionen:

Option	Beschreibung
--paypal-pdf DATEI	PayPal-PDF verarbeiten
--haspa-pdf DATEI	HASPA-PDF verarbeiten
--year JAHR	Jahr für Datumsangaben (wichtig bei HASPA!)
--autofix-domains	Email-Domains korrigieren (empfohlen bei PayPal)
--out-dir ORDNER	Ausgabe-Ordner festlegen
--encoding CHARSET	Zeichensatz (z.B. latin-1 für Excel/Windows)

Ausgabe-Ordner anpassen

python3 statements.py --haspa-pdf haspa.pdf \
  --year 2020 \
  --out-dir meine_buchhaltung/2020

Encoding für Excel auf Windows

python3 statements.py --haspa-pdf haspa.pdf \
  --year 2020 \
  --encoding latin-1

Mit Text-Dateien arbeiten (vorab extrahiert)

# Text aus PDF extrahieren:
pdftotext -layout haspa.pdf haspa.txt

# Verarbeiten:
python3 statements.py --haspa-text haspa.txt --year 2020

---

🧠 Intelligente OCR-Korrektur

Das Tool korrigiert automatisch häufige OCR-Fehler:

Email-Adressen

OCR-Fehler	Korrektur
@gmx.dee	@gmx.de
@gmalle om	@gmail.com
@yahoco om	@yahoo.com
@web.dee	@web.de
@g mx.de	@gmx.de

Wie es funktioniert: Fuzzy-Matching mit Provider-Datenbank (70% Ähnlichkeit)

Datumsangaben

OCR-Fehler	Korrektur	Erklärung
43.02.2019	13.02.2019	4→1 Verwechslung
44.02.2019	14.02.2019	4→1 Verwechslung
50.12.2019	20.12.2019	5→2 Verwechslung

Wie es funktioniert: OCR-Fehler-Mapping + Kalender-Validierung (Schaltjahre, Monatslängen)

Beträge

OCR-Fehler	Korrektur
26, !G =	-26,00
ee 476,00+	476,00
125 ,57-x»	-125,57

Wie es funktioniert: Scoring-basierte Extraktion (Position, Format, Plausibilität)

---

💡 Tipps & Best Practices

✅ Beste PDF-Qualität

1. Digitale PDFs bevorzugen

• PDFs direkt aus Online-Banking (kein Scan) haben die beste Qualität
• Keine OCR nötig → schneller und genauer

2. Bei Scans: Gute Scan-Qualität

• Mindestens 300 DPI
• Gerade ausgerichtet (nicht schräg)
• Gute Beleuchtung (keine Schatten)

3. Jahr im Dateinamen

# Gut:
haspa_2020_01.pdf  → Jahr wird automatisch erkannt
haspa_2020.pdf

# Schlecht:
kontoauszug.pdf    → Jahr muss manuell angegeben werden

⚡ Workflow für monatliche Auszüge

#!/bin/bash
# Alle PDFs in einem Ordner verarbeiten

for pdf in *.pdf; do
  echo "Verarbeite: $pdf"
  ./kontoauszug.sh "$pdf"
done

echo "✓ Fertig! Alle CSVs in export_* Ordnern"

📊 CSVs zusammenführen

# Alle Import-CSVs zu einer Datei zusammenführen:

# Header von der ersten Datei:
head -n 1 export_haspa_2020_01/haspa_import.csv > alle_2020.csv

# Alle Daten (ohne Header):
tail -n +2 -q export_*/haspa_import.csv >> alle_2020.csv

echo "✓ Zusammengeführt: alle_2020.csv"

---

🛠️ Manuelle Installation

Falls install_dependencies.sh nicht funktioniert:

macOS

# 1. Homebrew (falls nicht vorhanden):
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. Dependencies:
brew install [email protected] poppler ghostscript ocrmypdf

# 3. Python-Pakete:
python3 -m pip install --user PyPDF2

# 4. Test:
python3 --version  # >= 3.9
pdftotext -v
ocrmypdf --version

Linux (Ubuntu/Debian)

# 1. Dependencies:
sudo apt update
sudo apt install -y python3 python3-pip poppler-utils ghostscript ocrmypdf tesseract-ocr-deu

# 2. Python-Pakete:
python3 -m pip install --user PyPDF2

# 3. Test:
python3 --version  # >= 3.9
pdftotext -v
ocrmypdf --version

---

🔒 Datenschutz

• ✅ Alles lokal - Keine Cloud, keine Übertragung
• ✅ Keine Speicherung - Tool speichert nur die CSV-Ausgabe
• ✅ Deine Daten bleiben auf deinem Computer

---

🤝 Hilfe & Support

Bei Problemen

1. Schau hier nach - Die meisten Probleme sind oben erklärt
2. Prüfe die Installation:

   python3 --version  # >= 3.9?
   pdftotext -v       # Installiert?
   ocrmypdf --version # Installiert?

3. Erstelle ein GitHub Issue mit:
   • Fehlermeldung (vollständig)
   • Kommando das du ausgeführt hast
   • Betriebssystem & Versionen

Bekannte Einschränkungen

• Windows wird nicht direkt unterstützt (nutze WSL)
• Nur PayPal & HASPA (andere Banken auf Anfrage)
• OCR ist nicht 100% perfekt (daher Review-CSV)

---

📊 Beispiel-Workflow

Szenario: Monatliche HASPA-Auszüge für 2020

# 1. PDFs herunterladen und benennen:
# haspa_2020_01.pdf
# haspa_2020_02.pdf
# ...
# haspa_2020_12.pdf

# 2. Alle auf einmal verarbeiten:
for pdf in haspa_2020_*.pdf; do
  ./kontoauszug.sh "$pdf"
done

# 3. CSVs zusammenführen:
head -n 1 export_haspa_2020_01/haspa_import.csv > haspa_2020_komplett.csv
tail -n +2 -q export_*/haspa_import.csv >> haspa_2020_komplett.csv

# 4. Review-CSVs prüfen:
cat export_*/haspa_review.csv > haspa_2020_review_alle.csv

# 5. In Excel öffnen und importieren:
open haspa_2020_komplett.csv

Fertig! 🎉

---

Viel Erfolg mit deiner Buchhaltung! 📊

Made with ❤️ for better financial organization