# Finance API v1 (2026-10-12)

Schnittstelle zum Bereich **Finanzen** in Mindavio – für Jarvis und andere eigene Tools.
Alle Beträge in **Cent** (Ganzzahl), Daten als `YYYY-MM-DD`, Monate als `YYYY-MM`. Zeitzone für „heute“: Europe/Berlin.

## Zugriff – Rechte pro Bereich (seit 2026-10-13)
- Bearer-Token aus **Mindavio → Developers**. Pro Token und Bereich: **No access / Read / Read + write**
  für Tasks, Projects, Calendar, Journal, Notes, Leads, Reminders, Finances und Vault (Vault nur lesen).
- Schnellwahl: „Read everything“, „Read + write everything“, „No access“. Bestehende Tokens: „Edit rights“ (nur wer den Token angelegt hat, nur mit Login).
- Alte Tokens ohne gespeicherte Rechte verhalten sich wie bisher (alle Bereiche nach Access level, Finances/Vault aus).
- Finanzen gehören immer der Person, die den Token angelegt hat – auch bei Team-Tokens.
- Ohne Recht → `401`. **Kein Löschen per API.** Abos werden mit `{"is_active": false}` beendet.
- **Vault:** `GET /api/v1/vault/documents?q=&entity_type=&limit=&offset=` – Dokumentenliste (Name, Typ, Größe, Datum, verknüpfte Aufgabe/Notiz/Projekt), keine Inhalte, keine Download-Links.

## Endpunkte
| Methode | Pfad | Recht | Zweck |
|---|---|---|---|
| GET | `/api/v1/finances/transactions?month=&from=&to=&type=&category=&external_ref=&limit=&offset=` | read | Buchungen (neueste zuerst, max. 500) |
| POST | `/api/v1/finances/transactions` | read_write | Buchung anlegen. Mit `external_ref` idempotent (gleiche Referenz → 200 + vorhandene Buchung) |
| GET | `/api/v1/finances/transactions/{id}` | read | eine Buchung |
| PATCH | `/api/v1/finances/transactions/{id}` | read_write | Felder ändern: type, title, description, category, amount_cents, currency, transaction_date, status |
| GET | `/api/v1/finances/recurring?active=true` | read | Abos / Fixkosten / regelmäßige Einnahmen |
| POST | `/api/v1/finances/recurring` | read_write | anlegen (Standard: expense, monthly, aktiv) |
| PATCH | `/api/v1/finances/recurring/{id}` | read_write | ändern / beenden (`is_active: false`) |
| GET / POST | `/api/v1/finances/categories` | read / read_write | Kategorien; POST mit vorhandenem Namen → 200 + vorhandene |
| GET / PUT | `/api/v1/finances/budgets?month=` | read / read_write | Budget je Kategorie + Monat (PUT = anlegen oder überschreiben) |
| GET | `/api/v1/finances/summary?month=YYYY-MM` | read | Einnahmen/Ausgaben je Kategorie, Budget vs. Ist, offene Buchungen, fällige Abos (30 Tage) |

Beispiel:
```bash
curl -X POST https://www.mindavio.de/api/v1/finances/transactions \
  -H "Authorization: Bearer $MINDAVIO_API_KEY" -H "Content-Type: application/json" \
  -d '{"type":"expense","title":"OneDrive","category":"Abos","amount_cents":200,"transaction_date":"2026-10-03"}'
```
Buchungen per API haben `source = 'api'`, in der App angelegte `source = 'app'`.

## Ausrollen (Reihenfolge wichtig)
1. **Migrationen** `20261012000002_finance_api_access.sql` und `20261013000001_developer_token_scopes.sql` anwenden (rein additiv, mehrfach ausführbar).
   Ohne Migration bleibt alles lauffähig: Finanz-Endpunkte antworten 401, die Token-Liste zeigt kein Finanz-Recht.
2. Code auf den Server, `npm ci && npm run build`, App neu starten.
3. In Mindavio → Developers beim Jarvis-Token „Edit rights“ → Rechte setzen → „Save rights“.

## Prüfung
- `npm run test:finance` – Prüfregeln + Rechte-Logik (12 Tests)
- `bash docs/finance-api/verification/setup.sh <leerer-temp-ordner>` – Migrationen + echte Routen + echte Token-Prüfung gegen Postgres 17 (PGlite), ohne Produktionsdatenbank (17 Tests)