4.7 KiB
name, description
| name | description |
|---|---|
| finanz-api | Referenz aller REST-Endpunkte des Finanzberatungs-Tools (Konten, Buchungen, Kategorien, Regeln, Importe, wiederkehrende/geplante Posten, Kredite, Szenarien) mit curl-Beispielen. Use when Claude Code Daten aus dem Finanzberatungs-Tool lesen oder schreiben soll — Konten/Salden abfragen, Buchungen filtern/anlegen/korrigieren, Importe verwalten, Planungsposten oder Szenarien anlegen und durchrechnen. |
Finanz-API
REST/JSON unter http://127.0.0.1:8096/api/…, vollständig dokumentiert unter
http://127.0.0.1:8096/docs (OpenAPI/Swagger). Alle Endpunkte erfordern den
Header Authorization: Bearer <FB_API_KEY>.
Key extrahieren
KEY=$(grep '^FB_API_KEY=' $HOME/.local/share/finance_pod/.env | cut -d= -f2 | tr -d "'")
Verwende $KEY in allen folgenden Beispielen. Den Key niemals ausgeben,
loggen oder in Antworten an den Nutzer wiederholen.
Konten (/api/accounts)
GET (Liste inkl. aktuellem Saldo je Konto), GET /{id}, POST (Konto
anlegen: bank, iban, name, type).
curl -s -H "Authorization: Bearer $KEY" http://127.0.0.1:8096/api/accounts | jq
Buchungen (/api/transactions)
GET mit Filtern account_id, date_from, date_to, category_id, q
(Volltext auf Verwendungszweck/Gegenpartei), status (Default confirmed),
limit/offset. POST legt eine Buchung manuell an (force: true
überschreibt die Duplikat-Prüfung). PATCH /{id} ändert nur
category_id — echte Buchungen sonst nie verändern.
curl -s -H "Authorization: Bearer $KEY" \
"http://127.0.0.1:8096/api/transactions?date_from=2026-01-01&category_id=3&limit=50" | jq
Kategorien (/api/categories)
GET/POST (name).
curl -s -H "Authorization: Bearer $KEY" http://127.0.0.1:8096/api/categories | jq
curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"name": "Energie"}' \
http://127.0.0.1:8096/api/categories | jq
Kategorie-Regeln (/api/category-rules)
GET/POST (pattern, category_id, priority) und
DELETE /api/category-rules/{id}. Regeln kategorisieren künftige Importe
automatisch.
curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"pattern": "REWE", "category_id": 3, "priority": 50}' \
http://127.0.0.1:8096/api/category-rules | jq
Importe (/api/imports)
POST /upload (multipart, PDF), POST /scan-inbox (scannt die Inbox neu),
GET (Liste mit Status draft/confirmed/error), GET /{id}/preview
(Buchungen + Saldo-Check + Duplikat-Zahl), POST /{id}/confirm
(übernimmt die Vorschau endgültig), DELETE /{id}.
curl -s -X POST -H "Authorization: Bearer $KEY" \
http://127.0.0.1:8096/api/imports/scan-inbox | jq
Wiederkehrende Posten (/api/recurring)
GET/POST (name, amount, rhythm, due_day, start_date,
end_date, category_id), PATCH/DELETE /{id}, sowie
GET /recurring/suggestions (Muster-Erkennung aus importierten Buchungen).
curl -s -H "Authorization: Bearer $KEY" \
http://127.0.0.1:8096/api/recurring/suggestions | jq
Geplante Einmalposten (/api/planned)
GET/POST (name, amount, due, category_id), PATCH/DELETE /{id}.
curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"name": "Zahnarzt", "amount": -450.00, "due": "2026-09-01"}' \
http://127.0.0.1:8096/api/planned | jq
Kredite (/api/loans)
GET/POST (name, principal, annual_rate_pct, term_months,
payout_date, repayment_type: annuity|bullet), PATCH/DELETE /{id},
GET /{id}/schedule (Tilgungsplan: Rate, Zins, Tilgung, Restschuld je Termin).
curl -s -H "Authorization: Bearer $KEY" \
http://127.0.0.1:8096/api/loans/1/schedule | jq
Szenarien (/api/scenarios)
GET/POST (name, description, include_recurring, include_planned),
PATCH/DELETE /{id}. Kredit zuordnen: POST/DELETE /{id}/loans/{loan_id}. Modifikator hinzufügen: POST /{id}/modifiers mit
target_type (category|recurring), target_id, kind
(percent|absolute|remove), value; löschen über DELETE /{id}/modifiers/{mod_id}.
curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"name": "Basis-Szenario"}' \
http://127.0.0.1:8096/api/scenarios | jq
Durchrechnen (/api/scenarios/{id}/project)
POST, optionale Query-Parameter horizon_days und start_date. Antwort:
low_point_date, low_point_balance, below_zero_date,
below_threshold_date, series (Tagesreihe Datum/Saldo).
curl -s -X POST -H "Authorization: Bearer $KEY" \
"http://127.0.0.1:8096/api/scenarios/1/project?horizon_days=180" | jq