EBICS — Bankanbindung¶

Überblick¶

Der EBICS-Service ermöglicht die automatische Anbindung an jede deutsche Bank über den EBICS-Standard (Electronic Banking Internet Communication Standard). Kontoauszüge werden automatisch abgerufen und eingehende Zahlungen den offenen Rechnungen im CRM zugeordnet.

Funktionen¶

Automatischer Kontoauszug-Abruf — Täglich (MT940/camt.053) und stündlich (MT942/camt.052)
Auto-Reconciliation — Bankumsätze werden offenen Rechnungen automatisch zugeordnet
Mahnwesen-Integration — Zahlungseingänge stoppen Mahnläufe sofort
Echtzeit-Cashflow — Stündliche Umsatzdaten im CRM-Dashboard
Multi-Bankkonto — Beliebig viele Konten bei verschiedenen Banken
GoBD-Archivierung — Rohe Kontoauszüge 10 Jahre aufbewahrt

Voraussetzungen¶

Was die Bank bereitstellt¶

Nach Beantragung eines EBICS-Zugangs stellt die Bank folgende Daten bereit:

Information	Beschreibung
Host-ID	Technische Kennung des Bank-Servers
Partner-ID	Kundennummer im EBICS-System
User-ID	Benutzer-ID für den Zugang
Server-URL	URL des EBICS-Servers der Bank

Zusätzlich müssen die gewünschten Order Types (STA, VMK, C53, C52) bei der Bank freigeschaltet werden.

Was der Kunde bereitstellt¶

Information	Beschreibung
IBAN	Kontonummer des Bankkontos
BIC	Bankleitzahl (SWIFT-Code)
EBICS-Zugangsdaten	Host-ID, Partner-ID, User-ID (von der Bank erhalten)
Unterschrift	Physische Unterschrift auf dem INI-Brief

Kein technisches Setup nötig

Der Kunde benötigt keine Software-Installation und kein Zertifikat-Management. Alles läuft über den xynap Setup-Wizard.

Einrichtung (Setup-Wizard)¶

Schritt 1: Bankdaten eingeben¶

Im CRM unter Finanzen → EBICS Bankkonten → Neues Konto die Bankdaten und EBICS-Zugangsdaten eingeben.

Schritt 2: Schlüssel generieren¶

RSA-Schlüssel werden automatisch generiert. Ein Klick auf „Schlüssel generieren" startet den Prozess.

Schritt 3: INI + HIA senden¶

Die Initialisierungsbriefe werden an die Bank gesendet. Anschließend muss der INI-Brief ausgedruckt, unterschrieben und per Post an die Bank geschickt werden.

Schritt 4: Aktivierung¶

Nach Erhalt des INI-Briefs aktiviert die Bank den Zugang (1-3 Werktage). Im Wizard auf „Aktivierung prüfen" klicken — bei Erfolg startet der automatische Abruf.

Unterstützte Formate¶

Format	Order Type	Beschreibung	Frequenz
camt.053	C53	Kontoauszug (ISO 20022)	Täglich
camt.052	C52	Untertägige Umsatzdaten (ISO 20022)	Stündlich
MT940	STA	Kontoauszug (SWIFT, wird abgelöst)	Täglich
MT942	VMK	Untertägige Umsatzdaten (SWIFT, wird abgelöst)	Stündlich

Format-Umstellung

Ab November 2026 stellen viele Banken MT940/MT942 ab. camt.053/052 wird automatisch bevorzugt.

Auto-Reconciliation¶

Eingehende Zahlungen werden automatisch offenen Rechnungen zugeordnet:

Strategie	Konfidenz	Beschreibung
Exakte Referenz	100%	Rechnungsnummer im Verwendungszweck oder SEPA End-to-End-ID
Betrag + Datum	70%	Offener Betrag passt exakt, Datum im Fälligkeitsfenster
Gegenkonto IBAN	60%	IBAN des Kunden bekannt, Betrag passt
Fuzzy Matching	40%	Mustersuche im Verwendungszweck

Ab 85% Konfidenz: Automatische Zuordnung (CRM-Zahlung wird erstellt)
Unter 85%: Vorschlag zur manuellen Bestätigung im Reconciliation-View

API-Endpoints¶

Alle Endpoints unter /api/v1/crm/ebics/. Authentifizierung via JWT, Tenant-Scoping automatisch.

Kontoverwaltung¶

GET    /crm/ebics/accounts              → Bankkonten auflisten
POST   /crm/ebics/accounts              → Bankkonto anlegen
GET    /crm/ebics/accounts/{uuid}       → Konto-Detail
PUT    /crm/ebics/accounts/{uuid}       → Konto bearbeiten
DELETE /crm/ebics/accounts/{uuid}       → Konto deaktivieren

Schlüsselmanagement¶

POST   /crm/ebics/accounts/{uuid}/keys/init      → Keys generieren
POST   /crm/ebics/accounts/{uuid}/keys/ini       → INI an Bank senden
POST   /crm/ebics/accounts/{uuid}/keys/hia       → HIA an Bank senden
POST   /crm/ebics/accounts/{uuid}/keys/activate  → Aktivierung prüfen
GET    /crm/ebics/accounts/{uuid}/keys/ini-letter → INI-Brief PDF
GET    /crm/ebics/accounts/{uuid}/keys/status     → Key-Status

Kontoauszüge¶

POST   /crm/ebics/accounts/{uuid}/fetch    → Manueller Abruf
GET    /crm/ebics/statements               → Auszüge filtern
GET    /crm/ebics/statements/{uuid}        → Auszug-Detail
GET    /crm/ebics/statements/{uuid}/raw    → Original-Datei (GoBD)

Transaktionen + Reconciliation¶

GET    /crm/ebics/transactions                      → Transaktionen filtern
GET    /crm/ebics/transactions/{uuid}               → Detail
GET    /crm/ebics/transactions/{uuid}/suggestions   → Match-Vorschläge
POST   /crm/ebics/transactions/{uuid}/reconcile     → Manuell zuordnen
POST   /crm/ebics/transactions/{uuid}/ignore        → Ignorieren
POST   /crm/ebics/transactions/{uuid}/undo          → Rückgängig
POST   /crm/ebics/reconcile/batch                   → Auto-Reconciliation

Dashboard¶

GET    /crm/ebics/dashboard    → Salden, unmatched Count, Tagesstatistik

Berechtigungen¶

Permission	Beschreibung
`ebics.view`	Bankkonten, Auszüge und Transaktionen ansehen
`ebics.manage`	Bankkonten anlegen/bearbeiten, Keys verwalten
`ebics.fetch`	Kontoauszüge manuell abrufen
`ebics.reconcile`	Zahlungen zuordnen, ignorieren, rückgängig machen

Technische Details¶

Architektur¶

┌─────────────────┐     REST      ┌──────────────┐     EBICS      ┌──────────┐
│  Platform API   │ ──────────── │  ebics-api   │ ────────────── │   Bank   │
│  (FastAPI)      │              │  (Container) │               │  Server  │
│                 │              │              │               │          │
│  Parser         │              │  Keys        │               │  MT940   │
│  Reconciliation │              │  Connections │               │  camt053 │
│  Scheduler      │              │  Protocol    │               │  MT942   │
└─────────────────┘              └──────────────┘               │  camt052 │
                                                                └──────────┘

Scheduler¶

Täglicher Abruf (~08:00 UTC, via CRM Daily Scheduler): Kontoauszüge (camt.053/MT940) + Auto-Reconciliation
Stündlicher Intraday (eigener Background-Task, 07:00-20:00 UTC): Untertägige Umsätze (camt.052/MT942)
Zeitfenster konfigurierbar via EBICS_INTRADAY_START_HOUR / EBICS_INTRADAY_END_HOUR
Duplikat-Erkennung via SHA-256 Hash der Rohdaten
Intraday-Auszüge werden kumulativ ersetzt (Bank liefert Tages-Kumulativ)

Key-Status Lifecycle¶

pending → keys_generated → ini_sent → hia_sent → active
                                                → suspended

Nach dem HIA-Versand muss der INI-Brief ausgedruckt, unterschrieben und per Post an die Bank geschickt werden. Die Aktivierung durch die Bank dauert üblicherweise 1-3 Werktage. Danach kann der HPB-Download erfolgen (Button "Aktivierung prüfen").

Reconciliation-Status¶

Status	Beschreibung
`unmatched`	Keine Zuordnung gefunden
`suggested`	Vorschlag vorhanden, manuelle Bestätigung nötig
`auto_matched`	Automatisch zugeordnet (Konfidenz ≥ 85%)
`manual_matched`	Manuell zugeordnet durch Benutzer
`ignored`	Als irrelevant markiert
`partial`	Teilzahlung — Rechnung nur anteilig beglichen

Datenbank-Tabellen¶

ebics_bank_accounts — Bankkonten mit EBICS-Zugangsdaten und Key-Status
ebics_bank_statements — Kontoauszüge inkl. raw_data + raw_hash (GoBD-Archivierung, 10 Jahre)
ebics_bank_transactions — Einzelumsätze mit Reconciliation-Status und SEPA-Referenzen

Parser-Details¶

MT940-Parser (ebics_parsers.py):

Bibliothek: mt940 (WoLpH/mt940) — API: mt940.MT940(io.StringIO(raw)).statements
Unterstützt Standard-SEPA-Tags (SVWZ+, EREF+, MREF+, ...) und DK-Format-Subfelder (?30=BIC, ?31=IBAN, ?32=Name)
Liefert Statement-Namedtuples mit start_balance, end_balance, transactions

camt.053/052-Parser (ebics_parsers.py):

Direktes XML-Parsing via Python ElementTree (kein externes Framework)
Namespace-aware (urn:iso:std:iso:20022:tech:xsd:camt.053.001.02)
Extrahiert NtryRef, EndToEndId, RmtInf/Ustrd, IBAN aus RltdPties, BIC aus RltdAgts

Teststatus¶

103 Backend-Tests grün (Stand 2026-03-17):

Test-Datei	Tests	Abdeckung
`test_ebics_parsers.py`	60	MT940 (Standard + ABN AMRO + SEPA), camt.053 (Minimal + Real-Dateien)
`test_ebics_key_manager.py`	20	Key-Lifecycle, Status-Transitions, Error-Handling
`test_ebics_reconciliation.py`	23	Alle Matching-Strategien, Apply/Undo, Batch
`ebics-demobank/test_api.py`	67	Demobank-API End-to-End