Aktivitäten

Übersicht

Eine Aktivität ist ein zeitbezogener Eintrag an einem CRM-Objekt — Termin, Aufgabe, Anruf, Notiz, ToDo. Aktivitäten haben einen Typ (art), einen Status (offen/erledigt), einen Owner-User, ein Datum und einen Bezug zum Parent (kid — Customer, Produktpartner oder Benutzer).

Die Aktivität hat eine global eindeutige id — alle CRUD-Operationen laufen daher top-level über /v3/activities/{id}, ohne Detour über den Parent:

1. Top-Level Full-CRUD — /v3/activities (List, Create) und /v3/activities/{id} (Read, Update, Delete). Für Cross-Customer-Reports, Kalender-Sync, Workflow-Engines. kid steht optional im Body beim Top-Level-POST bzw. als Filter-Query (?kid=…) beim GET-List.
2. Parent-scoped Listing + Create — GET/POST /v3/customers/{kid}/activities, GET/POST /v3/products/{kid}/activities und GET/POST /v3/users/{kid}/activities. Path-kid ist Source-of-Truth; Body darf kein kid-Feld tragen (sonst 400 body_kid_forbidden). Update und Delete laufen ausschließlich über die Top-Level-Route mit der Activity-id.

Alle Varianten nutzen denselben Scope v3:activities:* und dasselbe Datenmodell — die parent-scoped Routen unter /v3/products/{kid} und /v3/users/{kid} brauchen also v3:activities:*, nicht v3:products:*/v3:users:*.

Scopes

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

Pagination & Limits

Identisch zu Customers > Pagination & Limits↗. Aktivitäten-Listen können in größeren Orgs sehr groß werden — mit ?limit=5000 arbeiten und im Idealfall mit Datum-Filtern eingrenzen.

Schema

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

{
  "id": 9395,
  "kid": 12345,                       // Customer-ID (optional)
  "kategorie": 15,                    // numerische Aktivitäts-Kategorie (siehe `aktKategorie` select)
                                      // POST/PATCH: STRING ('aufgabe', 'termin', 'email', 'telefon', 'notiz')
                                      // — der Handler nutzt sie als Lookup-Key für erlaubte Felder
  "titel": "Beratungstermin Vorsorge",
  "beschreibung": "Wunsch: BU-Versicherung prüfen, Riester-Rente checken.",
  "start": "2024-06-20 10:00:00",     // timestamp (DB: `start`)
  "ende":  "2024-06-20 11:30:00",     // timestamp (DB: `ende`)
  "status": 0,                        // numeric (siehe `aktStatus` select)
  "verantwortlich": 4001,             // kid des zugewiesenen Benutzers (DB: `verantwortlich`)
  "ersteller": 1485503904,            // kid des Erstellers (auto, aus Auth)
  "erledigt_am": null,
  "erledigt_kid": 0,
  "ind_10000012": "Custom-Wert",      // 0-N benutzerdefinierte Felder
  "insert_datum": "2024-06-12 08:42:00",
  "edit_datum":   "2024-06-15 14:20:00"
}

{
  "fields": {
    "status":         { "label": "Status",         "data_type": "number", "select_fields_name": "aktStatus" },
    "verantwortlich": { "label": "Verantwortlich", "data_type": "number", "select_fields_name": "vermittler" },
    "kategorie":      { "label": "Typ",            "data_type": "number", "select_fields_name": "aktKategorie" },
    "start":          { "label": "Start",          "data_type": "date",   "data_format": "0000-00-00 00:00:00" },
    "ende":           { "label": "Ende",           "data_type": "date",   "data_format": "0000-00-00 00:00:00" }
  },
  "select_fields": {
    "aktKategorie": [
      { "value": 0,  "display": "Meldung" },
      { "value": 1,  "display": "Störfall" },
      { "value": 6,  "display": "E-Mail" },
      { "value": 11, "display": "Notiz" },
      { "value": 12, "display": "Telefonat" },
      { "value": 15, "display": "Aufgabe" },
      { "value": 16, "display": "Brief" },
      { "value": 17, "display": "Verkauf" },
      { "value": 18, "display": "Termin" },
      { "value": 19, "display": "Chat" }
    ]
  }
}

Endpoints

Aktivitäten abfragen

Liefert paginierte Liste. Query-Parameter: page, limit, kid (Customer-Filter), kategorie (Integer aus aktKategorie), status (Integer aus aktStatus, einschließlich 0), verantwortlich (User-kid), with_comments, with_documents, with_contracts, with_damages, with_schema und flat. Kategorie und Status filtern die Liste in der Datenbank; bei gleichzeitiger Angabe gelten beide Filter.

# Offene Aufgaben für einen User (Aufgabe = kategorie 15, Status offen = 0)
curl "https://www.api.i-planner.app/v3/activities?kategorie=15&status=0&verantwortlich=4001" \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

Einzelne Aktivität abrufen

404 not_found falls nicht existent oder soft-deleted.

Aktivität anlegen

Body folgt dem Customer-POST-Pattern↗ (Single, nicht Batch). Pflicht-Feld: kategorie (string, siehe Warning oben). Optional: kid (Customer-Verknüpfung), titel, start, ende, status, verantwortlich, beschreibung, ind_* Custom-Felder.

curl -X POST https://www.api.i-planner.app/v3/activities \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kid": 12345,
    "kategorie": "termin",
    "titel": "Jahresgespräch",
    "start": "2024-07-15 09:00:00",
    "ende":  "2024-07-15 10:00:00",
    "verantwortlich": 4001,
    "status": 0
  }'

Response: 201 mit { success, id }.

Aktivität aktualisieren

Verhalten wie Customer-PATCH↗. Response: { success, updated }.

curl -X PATCH https://www.api.i-planner.app/v3/activities/71001 \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "erledigt" }'

Aktivität löschen

Soft-Delete. Response: { success, soft_deleted, id }. Wiederholte DELETE-Aufrufe geben 404 not_found — idempotent. Volle Error-Tabelle in Fehler↗.

Parent-scoped Listing & Create

Aktivitäten lassen sich unter drei Parents listen und anlegen — Customer, Produktpartner und Benutzer. Praktisch für Detail-UIs, Workflow-Knoten mit kid aus dem Trigger-Kontext und Integrations-Pipelines, die zu einem konkreten Parent schreiben.

Update und Delete dagegen laufen ausschließlich über die Top-Level-Routen↓ (PATCH /v3/activities/<id>, DELETE /v3/activities/<id>) — die Activity-id ist global eindeutig.

Path-Parameter: <kid> (Customer-, Product- oder User-ID, persistente Geschäfts-ID).

Body-Regel: POST-Bodies dürfen kid nicht tragen — Path-kid ist Source-of-Truth. Body-kid führt zu 400 body_kid_forbidden.

Listing-Filter: Zusätzlich zu page/limit unterstützen die parent-scoped GET-Listen den Query-Parameter ?verantwortlich=<userId> — filtert auf den Owner-User der Aktivität. Praktisch für „meine offenen Aufgaben am Customer X"-Workflows.

curl -X POST 'https://www.api.i-planner.app/v3/customers/12345/activities' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kategorie": "termin",
    "titel": "Jahresgespräch",
    "start": "2024-07-15 09:00:00",
    "ende":  "2024-07-15 10:00:00",
    "verantwortlich": 4001
  }'

curl -X POST 'https://www.api.i-planner.app/v3/products/67890/activities' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kategorie": "telefon",
    "titel": "Maklerbetreuer-Call",
    "start": "2024-07-15 14:00:00",
    "verantwortlich": 4001
  }'

curl 'https://www.api.i-planner.app/v3/customers/12345/activities?status=0&limit=50' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

Response-Shapes sind identisch zur top-level Variante. Volle Error-Tabelle in Fehler↗.

Annotationen

Aktivitäten haben eigene Annotationen — Comments, Followers und Tags. Verhalten, Felder und Response-Bodies sind identisch zu den Customer-Annotation-Pendants (siehe Customers > Comments↗ / Followers↗ / Tags↗). Beim Kommentar-POST ist autor_kid optional: mit einer aktiven Berater-KID wird dieser Berater als Autor angezeigt, ohne sie der Organisationstoken. Der Token bleibt in beiden Fällen im Änderungsprotokoll als ausführender Zugang erkennbar. Pfad-Pattern:

/v3/activities/<id>/{comments|followers|tags}[/<annotationId>]

• <id> — Activity-Row-ID (global eindeutig)
• <annotationId> — <commentId> / <followerId> / <tagId> je nach Annotation-Typ

Scope: v3:activities:* — die Berechtigung hängt an den Annotation-Daten, nicht am Parent. POST/PATCH-Bodies dürfen kein kid-Feld tragen (400 body_kid_forbidden).

curl -X POST 'https://www.api.i-planner.app/v3/activities/71001/comments' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Termin verlegt auf nächsten Montag.", "autor_kid": 7 }'

{ "success": true, "id": 95201 }