Finanzen

Finanzdaten eines Customers — Einnahmen, Ausgaben, Vermögensbestand, Verbindlichkeiten. Full-CRUD top-level über `/v3/finances/{id}` plus parent-scoped Listing/Create unter `/v3/customers/{kid}/finances`.

Zuletzt geprüft: 14. Mai 2026

Übersicht

Finanz-Datensätze sind die Bausteine einer Finanz-Analyse am Customer — monatliche Einkünfte, regelmäßige Ausgaben, Vermögenspositionen (Sparbuch, Depot, Immobilie), laufende Verbindlichkeiten (Kredite, Leasing).

Der Finanz-Eintrag hat eine global eindeutige id — alle CRUD-Operationen laufen daher top-level über /v3/finances/{id}, ohne Detour über den Customer:

Top-Level Full-CRUD — /v3/finances (List, Create) und /v3/finances/{id} (Read, Update, Delete). Für Reports, Cohort-Analysen, Provisions-Berechnungen.
Parent-scoped Listing + Create — GET /v3/customers/{kid}/finances und POST /v3/customers/{kid}/finances. Path-kid ist Source-of-Truth; Body darf kein kid-Feld tragen (sonst 400 body_kid_forbidden).

Beide Patterns nutzen denselben Scope v3:finances:* — Finanzen haben eine eigene Scope-Familie, unabhängig von Customers und Verträgen.

Scopes

Endpoint	Scope
`GET /v3/finances`	`v3:finances:read`
`POST /v3/finances`	`v3:finances:write`
`GET /v3/finances/<id>`	`v3:finances:read`
`PATCH /v3/finances/<id>`	`v3:finances:write`
`DELETE /v3/finances/<id>`	`v3:finances:write`
`GET /v3/customers/<kid>/finances`	`v3:finances:read`
`POST /v3/customers/<kid>/finances`	`v3:finances:write`

Auth-Mechanik siehe Authentifizierung. Vollständige Scope-Referenz: Scopes.

Pagination & Limits

Standard wie bei Customers.

Schema

DB-Tabelle: crm_finanzen. Body-Felder werden columnMap-gefiltert; unbekannte Spalten werden still verworfen.

json

{
  "id": 24,
  "kid": 12345,
  "bereich": 0,                       // numeric bucket — Einnahme/Ausgabe/Vermögen (siehe `fin_bereich` select)
  "ek_art": 4,                        // numeric Subkategorie der Einkommensart (siehe `ek_einnahme` select)
  "bezeichnung": "Gehalt Arbeitgeber Müller GmbH",
  "betrag": "4250.00",
  "est": "3800.00",                   // Steuer-/Einkommensteuer-Anteil
  "zahlweise": "monatlich",           // siehe `zahlweise` select
  "beginn": "2023-01-01",
  "ende": null,                       // null = unbefristet
  "stkl": 1,                          // Steuerklasse (integer)
  "zkf": "0.5",                       // Zahl der Kinderfreibeträge
  "gwv": "0.00", "vwl": "0.00", "vwl_ag": "0.00", "fb": "0.00",
  "re4": "0.00",                      // numerisch, spezifischer Berechnungsbaustein
  "bemerkung": "13. Gehalt im Dezember",
  "draft": 0,
  "insert_datum": "2023-01-15 10:00:00",
  "edit_datum":   "2024-01-15 11:00:00"
}

{
  "fields": {
    "bereich":     { "label": "Bereich",       "data_type": "number", "select_fields_name": "fin_bereich" },
    "ek_art":      { "label": "Einkommensart", "data_type": "number", "select_fields_name": "ek_einnahme" },
    "bezeichnung": { "label": "Bezeichnung",   "data_type": "string", "select_fields_name": null },
    "beginn":      { "label": "Beginn",        "data_type": "date",   "data_format": "0000-00-00" },
    "ende":        { "label": "Ende",          "data_type": "date",   "data_format": "0000-00-00" },
    "est":         { "label": "Einkommensteuer","data_type": "number","data_format": "0.00" },
    "zahlweise":   { "label": "Zahlweise",     "data_type": "string", "select_fields_name": "zahlweise" },
    "betrag":      { "label": "Betrag",        "data_type": "number", "data_format": "0.00" },
    "zkf":         { "label": "Kinderfreibetrag","data_type": "number" },
    "gwv":         { "label": "GWV",           "data_type": "number", "data_format": "0.00" },
    "vwl":         { "label": "VWL",           "data_type": "number", "data_format": "0.00" },
    "vwl_ag":      { "label": "VWL Arbeitgeber","data_type": "number","data_format": "0.00" },
    "fb":          { "label": "Freibetrag",    "data_type": "number", "data_format": "0.00" },
    "stkl":        { "label": "Steuerklasse",  "data_type": "number" }
  }
}

Endpoints

Finanzen org-weit abfragen

GET/v3/finances Im Playground testen ↗

Query-Parameter: page, limit, kid, art, kategorie, with_schema.

bash

# Alle Finanz-Eintraege eines Customers in Bereich 0 (Einnahmen — siehe `fin_bereich` select)
curl "https://www.api.i-planner.app/v3/finances?kid=12345&bereich=0" \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

Einzelnen Finanz-Eintrag abrufen

GET/v3/finances/<id> Im Playground testen ↗

404 not_found falls nicht existent.

Finanz-Eintrag top-level anlegen

POST/v3/finances Im Playground testen ↗

Customer-kid darf optional im Body stehen.

bash

curl -X POST 'https://www.api.i-planner.app/v3/finances' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kid": 12345,
    "bereich": 1,
    "ek_art": 0,
    "bezeichnung": "Miete Wohnung",
    "betrag": 1450.00,
    "zahlweise": "monatlich",
    "beginn": "2024-01-01"
  }'

Finanz-Eintrag am Kunden anlegen

POST/v3/customers/<kid>/finances Im Playground testen ↗

kid aus dem Pfad ist Source-of-Truth. Body darf kein kid tragen (400 body_kid_forbidden).

Finanzen eines Kunden listen

GET/v3/customers/<kid>/finances Im Playground testen ↗

Paginierte Liste; kid aus dem Pfad ist gesetzt.

Finanz-Eintrag aktualisieren

PATCH/v3/finances/<id> Im Playground testen ↗

PATCH-Semantik. Body trägt nur die zu ändernden Felder.

Finanz-Eintrag löschen

DELETE/v3/finances/<id> Im Playground testen ↗

Soft-Delete, idempotent. Volle Error-Tabelle in Fehler.

Annotations

Finanz-Einträge haben keine direkten Documents. Anhänge werden über Links auf einen Document-Datensatz verbunden.

/v3/finances/<id>/comments[/<rid>]   # 5-op: list, get, create, patch, delete
/v3/finances/<id>/followers[/<rid>]  # 3-op: list, create, delete
/v3/finances/<id>/tags[/<rid>]       # 3-op: list, create, delete
/v3/finances/<id>/links[/<rid>]      # 3-op: list, create, delete

/v3/finances/<id>/documents ist nicht verfügbar — der Endpoint antwortet 404 unsupported_sub_resource.