Ziele

Übersicht

Ein Ziel (Goal) ist eine finanzielle Zielsetzung eines Customers — Eigenheim-Sparen, Altersvorsorge, Berufsunfähigkeits-Absicherung, Ausbildungs-Sparvertrag. Ziele haben einen Zielbetrag, einen Zeitrahmen und können einem oder mehreren Verträgen zugeordnet sein.

Das Ziel hat eine global eindeutige id — alle CRUD-Operationen laufen daher top-level über /v3/goals/{id}, ohne Detour über den Customer:

1. Top-Level Full-CRUD — /v3/goals (List, Create) und /v3/goals/{id} (Read, Update, Delete). Für Goal-Reports, Konversions-Analyse, Cross-Customer-Auswertungen.
2. Parent-scoped Listing + Create — GET /v3/customers/{kid}/goals und POST /v3/customers/{kid}/goals. Path-kid ist Source-of-Truth; Body darf kein kid-Feld tragen (sonst 400 body_kid_forbidden).

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

Scopes

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

Pagination & Limits

Standard wie bei Customers↗.

Schema

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

{
  "id": 9,
  "kid": 12345,
  "type": 0,                          // Bereich/Kategorie — numeric (siehe `zieleType` select)
  "subject": "Eigenheim 2032",        // Freitext-Bezeichnung
  "priority": 0,                      // numeric (siehe `zielePriority` select)
  "end": "2032-12-31",                // Stichtag/Zieldatum (date)
  "value": "250000.00",               // Bedarf/Zielbetrag (numeric)
  "payment": "monatlich",             // Zufluss-Rhythmus — string (siehe `zahlweise` select)
  "description": "Eigenheim in Sued-Bayern, 4-Zimmer",
  "draft": 0,
  "insert_datum": "2024-01-10 10:00:00",
  "edit_datum":   "2024-06-01 11:00:00"
}

{
  "fields": {
    "type":      { "label": "Bereich",      "data_type": "number", "select_fields_name": "zieleType" },
    "subject":   { "label": "Bezeichnung",  "data_type": "string", "select_fields_name": null },
    "priority":  { "label": "Prioritaet",   "data_type": "number", "select_fields_name": "zielePriority" },
    "end":       { "label": "Stichtag",     "data_type": "date",   "data_format": "0000-00-00" },
    "value":     { "label": "Bedarf",       "data_type": "number" },
    "payment":   { "label": "Zufluss",      "data_type": "string", "select_fields_name": "zahlweise" }
  },
  "select_fields": {
    "zieleType": [
      { "value": 0, "display": "Allgemein" }
    ],
    "zielePriority": [
      { "value": 0, "display": "Sehr wichtig" }
    ],
    "zahlweise": [
      { "value": "monatlich", "display": "Monatlich" }
    ]
  }
}

Es gibt keine separaten ansparbetrag/status-Spalten — falls Ansparstand/-Status verfolgt werden sollen, geht das ueber description oder einen verknuepften comments-Eintrag.

Endpoints

Ziele org-weit abfragen

Liefert paginierte Liste, optional auf Customer / Bereich / Prioritaet gefiltert.

Query-Parameter: page, limit, kid (Filter auf Customer), with_schema, plus Custom-Filter auf Schema-Spalten (z. B. type=0, priority=0).

# Alle Ziele eines Customers im Bereich 0 (siehe `zieleType` select)
curl "https://www.api.i-planner.app/v3/goals?kid=12345&type=0" \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

Einzelnes Ziel abrufen

404 not_found falls nicht existent.

Ziel top-level anlegen

Customer-kid darf optional im Body stehen.

curl -X POST 'https://www.api.i-planner.app/v3/goals' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kid": 12345,
    "type": 0,
    "subject": "Hauskauf",
    "priority": 0,
    "end": "2030-06-01",
    "value": 400000.00,
    "payment": "monatlich"
  }'

Ziel am Kunden anlegen

kid im Pfad ist Source-of-Truth; Body darf kein kid tragen.

Ziele eines Kunden listen

Ziel aktualisieren

PATCH-Semantik.

Ziel löschen

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

Annotations

Ziele haben keine direkten Documents. Anhänge werden über Links↗ auf einen Document-Datensatz verbunden.

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

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