Schäden

Schadensfälle quer durch alle Customer-Verträge — Stammdaten, Status, beteiligte Personen. Full-CRUD top-level über `/v3/damages/{id}` plus parent-scoped Listing/Create unter `/v3/customers/{kid}/damages`.

Zuletzt geprüft: 14. Mai 2026

Übersicht

Ein Schaden (Damage) ist ein Versicherungs- oder Garantiefall — z. B. KFZ-Unfall, Wohngebäudeschaden, Berufsunfähigkeit. Schäden hängen am Customer und können über vid einen Produktpartner referenzieren. Eine Vertragsverknüpfung ist eine eigene Beziehung über den Links-Endpunkt.

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

Top-Level Full-CRUD — /v3/damages (List, Create) und /v3/damages/{id} (Read, Update, Delete). Eignet sich für Schadens-Reports, Reklamations-Analyse, Provisions-Stornos und für Workflow-Knoten, die mit der Schaden-id arbeiten.
Parent-scoped Listing + Create — GET /v3/customers/{kid}/damages (Schäden eines Kunden) und POST /v3/customers/{kid}/damages (Schaden unter einem Kunden anlegen). Path-kid ist Source-of-Truth; Body darf kein kid-Feld tragen (sonst 400 body_kid_forbidden).

Beide Patterns nutzen denselben Scope v3:damages:* — Schäden haben eine eigene Scope-Familie, unabhängig von Verträgen und Customers. Der Scope hängt an den Daten, nicht am URL-Pfad.

Scopes

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

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

Pagination & Limits

Standard wie bei Customers.

Schema

DB-Tabelle: crm_schaeden. Schreibbare Body-Felder werden anhand der konfigurierten Spalten und Formularfelder geprüft. Unbekannte oder geschützte Felder führen zu HTTP 400.

json

{
  "id": 22,
  "kid": 12345,                       // Customer-ID (Pfad bei POST unter customer)
  "vid": 1300201989,                  // optional: KID eines Produktpartners (crm_kontakte.kid, kontakt_bereich=2)
  "art": "Haftpflichtschaden",        // Freitext-Schadenart
  "nummer": "S-2024-00123",           // Schaden-Nummer (extern)
  "nummer_intern": "INT-00045",       // Schaden-Nummer (intern)
  "anschrift_strasse": "A8 km 132",
  "anschrift_plz": "85540",
  "anschrift_ort": "Haar",
  "datum_schaden": "2024-05-10",
  "datum_meldung_makler": "2024-05-12",
  "datum_meldung_gesellschaft": "2024-05-14",
  "datum_erledigt": null,
  "polizei_dienststelle": "PI München-Ost",
  "polizei_nummer": "AZ-2024-7842",
  "betrag": "7500.00",                // Schaden-Höhe (numeric)
  "reserve": "0.00",                  // Schaden-Reserve
  "leistung": "0.00",                 // bisher gezahlte Leistung
  "serviceportal": 0,                 // 0/1 Flag
  "draft": 0,                         // 0/1 Draft-Flag
  "insert_datum": "2024-05-12 10:00:00",
  "edit_datum":   "2024-06-02 11:00:00"
}

vid ist keine Vertrags-ID und keine Berater-KID. Die v4-Datenhaltung verwendet hier die KID eines Produktpartners. null entfernt die Zuordnung. Die KID muss zu einem aktiven Produktpartner derselben Organisation gehören; eine falsche KID liefert 400 invalid_select_value. Bei with_schema=true kennzeichnet fields.vid.select_fields_name die Auswahl als produktpartner. Die Liste select_fields.produktpartner enthält bei einem konkreten Schaden nur den bereits gewählten Partner und ist kein vollständiges Suchverzeichnis. Produktpartner lassen sich über /v3/products suchen.

bemerkung ist schreibgeschützt. Freitext zum Schaden gehört in /v3/damages/{id}/comments.

{
  "fields": {
    "art":                        { "label": "Schadenart",                 "data_type": "string", "select_fields_name": null },
    "vid":                        { "label": "Produktpartner",              "data_type": "number", "select_fields_name": "produktpartner" },
    "nummer":                     { "label": "Schaden-Nr.",                "data_type": "string", "select_fields_name": null },
    "nummer_intern":              { "label": "Schaden-Nr. (intern)",       "data_type": "string", "select_fields_name": null },
    "anschrift_strasse":          { "label": "Schadensort — Straße",       "data_type": "string", "select_fields_name": null },
    "anschrift_plz":              { "label": "Schadensort — PLZ",          "data_type": "string", "select_fields_name": null },
    "anschrift_ort":              { "label": "Schadensort — Ort",          "data_type": "string", "select_fields_name": null },
    "datum_schaden":              { "label": "Schaden-Datum",              "data_type": "date",   "data_format": "0000-00-00" },
    "datum_meldung_makler":       { "label": "Meldung an Makler",          "data_type": "date",   "data_format": "0000-00-00" },
    "datum_meldung_gesellschaft": { "label": "Meldung an Gesellschaft",    "data_type": "date",   "data_format": "0000-00-00" },
    "datum_erledigt":             { "label": "Erledigt am",                "data_type": "date",   "data_format": "0000-00-00" },
    "polizei_dienststelle":       { "label": "Polizei — Dienststelle",     "data_type": "string", "select_fields_name": null },
    "polizei_nummer":             { "label": "Polizei — Aktenzeichen",     "data_type": "string", "select_fields_name": null },
    "betrag":                     { "label": "Schaden-Höhe",               "data_type": "number", "data_format": "0.00" },
    "reserve":                    { "label": "Reserve",                    "data_type": "number", "data_format": "0.00" },
    "leistung":                   { "label": "Bisherige Leistung",         "data_type": "number", "data_format": "0.00" },
    "serviceportal":              { "label": "Serviceportal",              "data_type": "number", "select_fields_name": "janein" }
  }
}

Es gibt keinen dokumentierten status/sparte-Filter am Schaden. Diese Angaben liegen am Vertrag, der bei Bedarf separat verknüpft wird.

Endpoints

Schäden org-weit abfragen

GET/v3/damages Im Playground testen ↗

Liefert paginierte Liste aller Schäden deiner Organisation, optional auf einen Customer gefiltert.

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

bash

# Alle Schäden der Sparte "Haftpflicht" — Filter über die echte Spalte `art`
curl "https://www.api.i-planner.app/v3/damages?art=Haftpflichtschaden&limit=100" \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

const damages = await $fetch('https://www.api.i-planner.app/v3/damages', {
  query: { kid: 12345 },
  headers: { Authorization: `Bearer ${process.env.IPLANNER_API_TOKEN}` },
})
console.log(`${damages.total} Schäden am Customer 12345`)

Einzelnen Schaden abrufen

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

Liefert einen einzelnen Schaden über seine numerische id. 404 not_found falls nicht existent.

bash

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

Schaden top-level anlegen

POST/v3/damages Im Playground testen ↗

Legt einen oder mehrere Schäden an. Der Customer-kid darf optional im Body stehen — das ordnet den Schaden direkt einem Customer zu.

bash

curl -X POST 'https://www.api.i-planner.app/v3/damages' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kid": 12345,
    "vid": 1300201989,
    "art": "Haftpflichtschaden",
    "datum_schaden": "2026-04-21",
    "datum_meldung_makler": "2026-04-22",
    "anschrift_ort": "München",
    "betrag": 1250.00,
    "nummer_intern": "INT-00045"
  }'

Response: 201 mit { success, id }; Batch 200 mit inserted[] + failed[]-Envelope.

Schaden am Kunden anlegen

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

Legt einen Schaden unter einem konkreten Customer an. Der kid steht im Pfad — kid im Body ist verboten und führt zu 400 body_kid_forbidden.

bash

curl -X POST 'https://www.api.i-planner.app/v3/customers/12345/damages' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vid": 1300201989,
    "art": "Haftpflichtschaden",
    "datum_schaden": "2026-04-21",
    "betrag": 1250.00,
    "nummer_intern": "INT-00045"
  }'

Schäden eines Kunden listen

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

Paginierte Liste aller Schäden eines Customers. kid steht im Pfad — kein zusätzlicher Query-Filter.

Schaden aktualisieren

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

PATCH-Semantik (nur die mitgeschickten Felder werden überschrieben).

bash

curl -X PATCH 'https://www.api.i-planner.app/v3/damages/81001' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "vid": 1300201989 }'

Schaden löschen

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

Soft-Delete. Wiederholter Aufruf antwortet mit 404 not_found (idempotent). Volle Error-Tabelle in Fehler.

Annotations

Comments, Followers, Tags und Documents hängen top-level an der Schaden-id. Schäden sind eine der wenigen Sektionen mit direkten Documents (eigener Document-FK im DB-Modell):

/v3/damages/<id>/comments[/<rid>]   # 5-op: list, get, create, patch, delete
/v3/damages/<id>/followers[/<rid>]  # 3-op: list, create, delete
/v3/damages/<id>/tags[/<rid>]       # 3-op: list, create, delete
/v3/damages/<id>/documents[/<rid>]  # Full-CRUD inkl. File-Upload
/v3/damages/<id>/links[/<rid>]      # 3-op: list, create, delete

Felder, Methods und Response-Bodies entsprechen den Customer-Level-Pendants — kein kid-Body-Feld, kein kid-Query-Param, beides ergibt sich aus dem Pfad.