HV-Buchhaltung API

Offene REST-API für Hausverwaltungs-Buchhaltung. Vollständig integrierbar mit Donexus, CASITA-Portal, easimo und anderen HV-Systemen. Das ERP ist das führende System — externe Systeme synchronisieren bidirektional.

Rechnungen https://buchhaltung.verwaltercoach.de/api/invoice

Banking https://buchhaltung.verwaltercoach.de/api/banking

Buchhaltung https://buchhaltung.verwaltercoach.de/api/accounting

ERP als führendes System: Alle Buchungen, Sollstellungen und Zahlungen entstehen hier. Externe Systeme (Donexus, CASITA-Portal) synchronisieren über Webhooks oder Polling.

Prinzipien

API-First

Jede Funktion ist über REST-API erreichbar. Kein Feature existiert nur in der UI.

Event-basiert

Änderungen im ERP feuern Webhooks. Externe Systeme reagieren darauf statt zu pollen.

Idempotent

Alle POST-Endpunkte sind idempotent wo möglich. Duplikate werden erkannt und abgewiesen.

Portabel

Vollständig Docker-basiert. Umzug auf neuen VPS: docker compose up -d.

Authentifizierung

API-Key (Header)

X-API-Key: hv_live_xxxxxxxxxxxxxxxxxxxx

API-Keys werden pro Integration vergeben. Donexus, CASITA-Portal und externe Tools erhalten jeweils eigene Keys mit eingeschränkten Scopes.

Auth noch nicht produktiv — wird in v0.2 aktiviert. Aktuell alle Endpunkte offen (internes Netz + Traefik BasicAuth).

Scopes (geplant)

Scope	Zugriff
`invoices:read`	Rechnungen lesen
`invoices:write`	Rechnungen anlegen, freigeben
`banking:read`	Kontoumsätze, VKN lesen
`banking:write`	Zahlungen auslösen, VKN anlegen
`accounting:read`	Journal, Saldenliste
`accounting:write`	Buchungssätze erstellen
`ebics:admin`	EBICS-Verbindungen verwalten

Rechnungseingang

POST Rechnung hochladen & extrahieren /invoices/upload

PDF-Datei hochladen. Automatische Extraktion von Lieferant, IBAN, Beträgen, Datum per Regex (+ optional Claude AI als Fallback).

Request — multipart/form-data

Feld	Typ	Beschreibung
`file`	File (PDF)	Pflicht — Rechnungs-PDF
`email_subject`	string	Optional — E-Mail-Betreff für Objekt-Matching

Response 200

"id": 42,
"supplier_name": "Musterbau GmbH",
"supplier_iban": "DE89370400440532013000",
"invoice_number": "2026-1847",
"invoice_date": "2026-06-15",
"due_date": "2026-06-30",
"gross_amount": "193.38",
"property_hint": "Scheunhornweg 14, 13583 Berlin",
"extraction_confidence": 1.0,
"status": "extracted"

PATCH Rechnung korrigieren / freigeben /invoices/{id}

Manuelle Korrekturen, Objekt-/Kontenzuordnung, Status-Wechsel.

Request JSON

{
  "property_id": "SHW14",
  "cost_account": "5250",
  "status": "approved"
}

Status-Flow: extracted → approved → booked → paid

EBICS-Bankverbindung

Voraussetzung: EBICS-Teilnahmevertrag mit der Bank existiert bereits.

Initialisierungsablauf

POST /ebics — Verbindung anlegen

RSA-Schlüsselpaare werden automatisch erzeugt und verschlüsselt gespeichert.

POST /ebics/{id}/init — INI + HIA senden

Öffentliche Schlüssel werden an die Bank übermittelt.

POST /ebics/{id}/ini-letter — INI-Brief herunterladen

PDF-Brief mit Schlüssel-Hashes ausdrucken, unterschreiben, an Bank senden.

POST /ebics/{id}/activate — Nach Bank-Bestätigung

Bank-Schlüssel (HPB) laden. Ab jetzt: automatischer C53-Pull 3x täglich.

POST EBICS-Verbindung anlegen /ebics

Request JSON

{
  "label": "Berliner Sparkasse – CASITA Betriebskonto",
  "bank_name": "Berliner Sparkasse",
  "host_url": "https://ebics.berliner-sparkasse.de/ebics",
  "host_id": "BELADEBE",
  "partner_id": "CASITA001",
  "user_id": "TIM01",
  "ebics_version": "H004"
}

POST Kontoauszug abrufen (C53) /ebics/{id}/pull

Ruft CAMT.053 per EBICS ab, importiert Transaktionen und führt automatisches VKN-Matching durch.

Query-Parameter

Parameter	Default	Beschreibung
`date_from`	heute	YYYY-MM-DD
`date_to`	heute	YYYY-MM-DD
`auto_match`	true	VKN-Matching automatisch ausführen

Response

{
  "imported": 12,
  "duplicates_skipped": 0,
  "auto_match": { "total": 12, "matched": 10, "unmatched": 2 }
}

Webhooks (bidirektionale Sync)

Das ERP ist das führende System. Externe Systeme registrieren Webhook-URLs und werden bei Ereignissen benachrichtigt.

Ereignisse

Event	Wann	Payload
`invoice.created`	Neue Rechnung erkannt	Invoice-Objekt
`invoice.approved`	Rechnung freigegeben	Invoice + Kostenstelle
`invoice.booked`	Rechnung gebucht	Invoice + Buchungssatz
`transaction.imported`	Bankumsatz per EBICS/CAMT	BankTransaction
`transaction.matched`	VKN-Zuordnung	Transaction + VKN
`journal.posted`	Buchung festgeschrieben	JournalEntry
`recurring.run`	Monatliche Sollstellungen	Liste gebuchter Einträge

Webhook-Format

{
  "event": "invoice.approved",
  "timestamp": "2026-06-20T14:32:11Z",
  "source": "hv-erp",
  "data": { ... }
}

Integrationen

Donexus → ERP

→

Objekte & Einheiten

Donexus liefert property_id und unit_id. ERP übernimmt als Kostenstellen-Codes.

←

Offene Forderungen

ERP schickt offene Mieten/Hausgelder per Webhook. Donexus zeigt Status im Portal.

↔

Schadensmeldungen → Rechnungen

Donexus-Incident-ID wird in Rechnung gespeichert. Bezahlung fließt zurück als Webhook.

CASITA-Portal → ERP

GET /api/accounting/balance-sheet?cost_center_id={id}
→ Saldenliste für Eigentümer-Anzeige im Portal

GET /api/banking/transactions?match_status=unmatched
→ Liste offener Zahlungen für manuelle Zuordnung im Portal

POST /api/invoices/{id} { "status": "approved" }
→ Freigabe direkt aus dem Portal heraus