Ansprechpartner

Übersicht

Ein Ansprechpartner (Contact-Person) ist eine natürliche Person, die als Kontakt bei einem Produktpartner geführt wird — etwa der zuständige Maklerbetreuer einer Versicherung oder der Account-Manager einer Bank. Jeder Ansprechpartner hängt über kid an einem Produktpartner.

Der Ansprechpartner hat eine global eindeutige id — alle CRUD-Operationen laufen daher top-level über /v3/contact-persons/{id}, ohne Detour über den Produktpartner:

1. Top-Level Full-CRUD — /v3/contact-persons (List, Create) und /v3/contact-persons/{id} (Read, Update, Delete).
2. Parent-scoped Listing + Create — GET /v3/products/{kid}/contact-persons und POST /v3/products/{kid}/contact-persons. Path-kid ist Source-of-Truth; Body darf kein kid-Feld tragen (sonst 400 body_kid_forbidden).

Beide Patterns teilen sich die Scope-Familie mit Produktpartnern: v3:products:*.

Scopes

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

Pagination & Limits

Standard wie bei Customers↗ — page, limit, Default 50, Max 5000.

Schema

{
  "id": 52001,
  "kid": 67890,                       // Customer-ID des Produktpartners
  "anrede": "Frau",
  "vorname": "Anna",
  "name": "Schmitt",
  "position": "Maklerbetreuerin Region Süd",
  "bereich": "Vertriebspartner-Management",
  "email": "a.schmitt@example-versicherer.de",
  "telefon": "+49 89 12345-678",
  "mobil": "+49 171 1234567",
  "insert_datum": "2023-08-12",
  "edit_datum": "2024-06-15"
}

Endpoints

Ansprechpartner abfragen

Liefert paginierte Liste aller Ansprechpartner deiner Organisation, optional auf einen Produktpartner gefiltert.

Query-Parameter:

curl "https://www.api.i-planner.app/v3/contact-persons?kid=67890" \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

Response: Standard-Envelope { page, page_size, total, items, fields?, select_fields? }.

Einzelnen Ansprechpartner abrufen

Liefert ein einzelnes Ansprechpartner-Objekt über seine numerische id. 404 not_found falls die ID nicht existiert oder soft-deleted ist.

curl https://www.api.i-planner.app/v3/contact-persons/52001 \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

Ansprechpartner top-level anlegen

Produktpartner-kid ist Pflicht-Feld im Body — ein Ansprechpartner ohne Produktpartner ergibt fachlich keinen Sinn.

curl -X POST 'https://www.api.i-planner.app/v3/contact-persons' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kid": 67890,
    "anrede": "Frau",
    "vorname": "Anna",
    "name": "Schmitt",
    "position": "Maklerbetreuerin Region Süd",
    "email": "a.schmitt@example-versicherer.de",
    "telefon": "+49 89 12345-678"
  }'

Ansprechpartner am Produktpartner anlegen

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

curl -X POST 'https://www.api.i-planner.app/v3/products/67890/contact-persons' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "anrede": "Frau",
    "vorname": "Anna",
    "name": "Schmitt",
    "position": "Maklerbetreuerin Region Süd",
    "email": "a.schmitt@example-versicherer.de",
    "telefon": "+49 89 12345-678"
  }'

Ansprechpartner aktualisieren

PATCH-Semantik.

Ansprechpartner löschen

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

Annotations

Ansprechpartner haben keine direkten Documents. Anhänge werden über Links↗ verbunden.

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

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