System

Übersicht

Die System-Endpoints liefern org-spezifische Metadaten, die andere Ressourcen referenzieren — Stammdaten, Typen-Listen, Konfigurationswerte:

• GET /v3/system/relations — Liste aller Beziehungs-Typen, die in der Relations-Ressource↗ als type-Wert vorkommen können.
• GET /v3/system/sparten — Liste aller Sparten (Versicherungs- und Vertragskategorien), die in Verträgen↗ und Schäden↗ als sparte/art referenziert werden.
• GET|POST /v3/system/tags + GET|PATCH|DELETE /v3/system/tags/<id> — Tag-Katalog der Organisation. Tags werden hier definiert und an Resourcen (Customers, Products, Contracts, …) über deren tags-Annotation zugewiesen↗.

Beziehungs-Typen und Sparten sind lesegeschützt über die API (Pflege im UI). Der Tag-Katalog dagegen ist vollständig API-pflegbar — du kannst Tags anlegen, umbenennen und löschen.

Scopes

Alle System-Endpoints laufen über die Scope-Familie v3:system:*:

Auth-Mechanik und Fehler siehe Authentifizierung↗. Vollständige Scope-Referenz mit Token-Beispielen: Scopes↗.

Schema

{
  "id": 1,
  "name": "Ehepartner",
  "anrede": "Ehepartner/in",          // optionale Briefanrede
  "kreis": 1,                         // Folder/Gruppen-ID (z. B. Familie, Geschäft)
  "parent_id": null                   // Hierarchie-Parent (für gruppierte Typen)
}

{
  "items": [
    { "id": 1, "name": "Ehepartner",   "anrede": "Ehepartner/in",   "kreis": 1, "parent_id": null },
    { "id": 2, "name": "Lebenspartner","anrede": "Lebenspartner/in","kreis": 1, "parent_id": null },
    { "id": 3, "name": "Kind",         "anrede": "Kind",            "kreis": 1, "parent_id": null }
  ],
  "total": 32,
  "folders": [
    { "id": 1, "name": "Familie",    "parent_id": null },
    { "id": 2, "name": "Geschäft",   "parent_id": null }
  ],
  "pairs": [
    { "id": 5, "beziehung_zu": 1, "beziehung_von": 1 }   // Ehepartner ↔ Ehepartner
  ]
}

folders gruppiert die Typen logisch (Familie, Geschäft, Sonstige). pairs definiert reziproke Paarungen — wenn Customer A „Ehepartner von" B ist, ist B automatisch „Ehepartner von" A. Diese Auflösung passiert serverseitig, der Client muss nichts pairen.

Endpoints

Beziehungs-Typen abrufen

Liefert die vollständige Liste der in deiner Organisation konfigurierten Beziehungs-Typen, plus die zugehörigen Folder-Gruppen und reziproken Paarungen.

Query-Parameter: keine.

Response: 200 mit dem oben gezeigten Schema (items, total, folders, pairs).

curl https://www.api.i-planner.app/v3/system/relations \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

const types = await $fetch('https://www.api.i-planner.app/v3/system/relations', {
  headers: { Authorization: `Bearer ${process.env.IPLANNER_API_TOKEN}` },
})
console.log(`${types.total} Beziehungs-Typen verfügbar`)

Mögliche Fehler: 401 (Token fehlt/ungültig), 403 (v3:system:read fehlt), 500 (Datenbank/Cache nicht erreichbar). Volle Referenz in Fehler↗.

Sparten abrufen

Liefert die Liste aller Sparten (Versicherungs- und Vertragskategorien) deiner Organisation. Keine kid-Bindung, keine Pagination — der Endpoint liefert das Tenant-Sparten-Dictionary als kompaktes Array. Cache-freundlich auf Client-Seite.

Query-Parameter: keine.

Response-Schema:

{
  "total": 14,
  "items": [
    {
      "id": 1,
      "sparte": "krankenversicherung",
      "bereich": "personen",
      "name": "Krankenversicherung",
      "auto_verlaengerung": true,
      "kuendigungsfrist": 3,
      "bearbeitungszeitraum": 14,
      "steuersatz": 19.0,
      "standard": false
    }
  ]
}

curl 'https://www.api.i-planner.app/v3/system/sparten' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

Tag-Katalog listen

Alle in der Organisation definierten Tags. Tags werden hier definiert und über die tags-Annotation an Resourcen (z. B. /v3/customers/<kid>/tags↗) zugewiesen.

Response-Schema:

{
  "items": [
    {
      "id": 42,
      "kid": 12,
      "tag": "VIP-Kunde",
      "freigabe": 0,
      "insert_datum": "2025-04-12",
      "insert_user_id": 7
    }
  ]
}

freigabe — interner Sichtbarkeits-Marker (0 = privat, 1 = team-weit freigegeben). kid = User-ID des Erstellers.

Tag anlegen

Legt einen neuen Tag im Org-Katalog an. Scope: v3:system:write.

Body:

curl -X POST 'https://www.api.i-planner.app/v3/system/tags' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tag": "VIP-Kunde", "freigabe": 1 }'

Response: 201 Created mit dem neuen Tag-Objekt.

Einzelnen Tag abrufen

404 not_found falls die ID nicht existiert.

Tag aktualisieren

PATCH-Semantik. Body trägt nur die zu ändernden Felder (tag und/oder freigabe). Body darf keine anderen Felder enthalten (400 unrecognized_key).

Tag löschen

Soft-Delete. Bereits zugewiesene Tag-Verknüpfungen an Resourcen bleiben erhalten (sind aber nicht mehr neu setzbar).

Mögliche Fehler bei Tag-Endpoints: 400 validation_failed (ungültiger Body), 403 missing_required_scope (fehlender v3:system:write Scope), 404 not_found (ID existiert nicht). Volle Referenz in Fehler↗.