136 lines
4.7 KiB
Markdown
136 lines
4.7 KiB
Markdown
---
|
|
name: finanz-api
|
|
description: 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
|
|
|
|
```bash
|
|
KEY=$(grep '^FB_API_KEY=' /home/wlfb/bin/finance/.env | cut -d= -f2)
|
|
```
|
|
|
|
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`).
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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`).
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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}`.
|
|
|
|
```bash
|
|
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).
|
|
|
|
```bash
|
|
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}`.
|
|
|
|
```bash
|
|
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).
|
|
|
|
```bash
|
|
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}`.
|
|
|
|
```bash
|
|
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).
|
|
|
|
```bash
|
|
curl -s -X POST -H "Authorization: Bearer $KEY" \
|
|
"http://127.0.0.1:8096/api/scenarios/1/project?horizon_days=180" | jq
|
|
```
|