Beziehungen

Typisierte Beziehungen zwischen Customers — Familien-, Geschäfts- und Gruppen-Relationen für eine 360°-Sicht über zusammenhängende Datensätze. Im Unterschied zu Links (untyped) tragen Relations einen Beziehungs-Typ wie „Ehepartner" oder „Geschäftsführer".

Zuletzt geprüft: 12. Mai 2026

Übersicht

Eine Beziehung (Relation) verknüpft zwei Customer-Datensätze mit einem typisierten Verhältnis — z. B. „Anna ist Ehepartnerin von Bernd", „Klaus ist Geschäftsführer von Müller GmbH", „Lena ist Kind von Anna". Im Unterschied zur generischen Links-API (untyped) tragen Relations einen Beziehungs-Typ, dessen Liste über GET /v3/system/relations abrufbar ist.

Reziprozität: Relations werden automatisch beidseitig angelegt. Wenn du am Customer Anna (Path-kid = Anna) eine Beziehung zum Customer Bernd (Body-kid_beziehung = Bernd) anlegst, entsteht auch die Gegenseite. Die pairs-Liste in /v3/system/relations definiert ihren Beziehungstyp.

Scopes

Relations teilen die Scope-Familie mit Customers — sie sind ein Cross-Reference-Layer am Customer-Modell:

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

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

Schema

json

{
  "id": 65001,
  "kid": 12345,                       // Customer A
  "kid_beziehung": 12346,            // Customer B
  "beziehung": 28,                    // → /v3/system/relations
  "beziehung_name": "Geschäftspartner",
  "parent_id": 1002,
  "contact": { "kid": 12346, "name": "Bernd Beispiel" }
}

{
  "total": 1,
  "items": [
    { "id": 65001, "kid": 12345, "kid_beziehung": 12346, "beziehung": 28,
      "beziehung_name": "Geschäftspartner", "parent_id": 1002,
      "contact": { "kid": 12346, "name": "Bernd Beispiel" } }
  ]
}

Endpoints

Beziehungen abfragen

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

Liefert alle Beziehungen des durch den Path-<kid> referenzierten Customers. Anders als andere List-Endpoints kein Pagination-Envelope — die Response ist { total, items }, weil pro Customer selten mehr als ein paar Dutzend Beziehungen existieren.

Path-Parameter: <kid> (Customer-ID).

Die Liste unterstützt derzeit keine Query-Filter. Sie enthält alle Beziehungen des Customers.

bash

# Alle Beziehungen eines Customers
curl "https://www.api.i-planner.app/v3/customers/12345/relations" \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

const relations = await $fetch('https://www.api.i-planner.app/v3/customers/12345/relations', {
  headers: { Authorization: `Bearer ${process.env.IPLANNER_API_TOKEN}` },
})
console.log(`${relations.total} Beziehungen`)
for (const r of relations.items) {
  console.log(`- ${r.beziehung_name}: Customer ${r.kid_beziehung}`)
}

Beziehung anlegen

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

Legt eine typisierte Beziehung zwischen zwei Customers an. Source-Customer ist der Path-<kid> (= Customer „A"), Ziel-Customer ist kid_beziehung im Body (= Customer „B"). kid im Body ist verboten und führt zu 400 body_kid_forbidden. Die reziproke Gegenseite wird automatisch mit angelegt (siehe pairs in /v3/system/relations).

Body:

Feld	Typ	Beschreibung
`kid_beziehung`	int > 0	Ziel-Customer (Customer „B"). Source-Customer „A" wird aus dem Path-`kid` übernommen.
`beziehung`	int > 0	Beziehungs-Typ aus `/v3/system/relations`

Der Body enthält ausschließlich diese beiden Felder; zusätzliche Felder wie notiz werden mit 400 abgelehnt.

Response: 201 mit { success: true, id, reverse_id, beziehung, reverse_beziehung }. Die IDs bezeichnen die beiden gespeicherten Richtungen.

Fehler:

empty_body (400) — Body fehlt
validation_error (400) — kid_beziehung oder beziehung fehlt, ist ungültig oder der Body enthält zusätzliche Felder
customer_not_found / target_not_found (404) — ein Customer existiert nicht in der Org
self_relationship (400) — beide KIDs bezeichnen denselben Customer
invalid_relationship_type / no_reverse_pair (400) — Typ fehlt oder hat kein reziprokes Paar
duplicate_relation (409) — diese Beziehung mit dem Typ und ihrer Gegenseite existiert bereits

bash

curl -X POST https://www.api.i-planner.app/v3/customers/12345/relations \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kid_beziehung": 12346,
    "beziehung": 28
  }'

Beziehung löschen

DELETE/v3/customers/<kid>/relations/<id> Im Playground testen ↗

Path-Parameter: <kid> (KID eines der beiden verbundenen Customers), <id> (Relation-Row-ID).

Löscht eine Beziehung. Hard-Delete — die reziproke Gegenseite wird automatisch mit gelöscht. Idempotent: wiederholte DELETE-Aufrufe geben 404 not_found.

Response: 200 mit { success: true, deleted, id }.

bash

curl -X DELETE https://www.api.i-planner.app/v3/customers/12345/relations/65001 \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

Volle Error-Tabelle in Fehler.