Betreuungspläne bauen

Wie eine Praxis ihre Betreuungspläne über die API oder einen KI-Agenten anlegt, prüft, freigibt und Klienten danach begleitet, durchgerechnet am Beispiel „Black Swan® Metabolic Balance Protokoll - 3 Monate“.

Was ein Betreuungsplan ist

Eine Vorlage der Praxis aus Phasen und Sitzungen. Jede Sitzung hat eine Terminart, eine Dauer, optional einen Gesprächsleitfaden und ein Zeitfenster nach der vorigen Sitzung (minDays bis maxDays). Vorlagen haben Fassungen: Ein Entwurf ist änderbar, eine freigegebene Fassung ist fest und startbar, Änderungen ergeben eine neue Fassung. Eine Betreuung begleitet einen Klienten nach einer Fassung und trägt deren Abschrift. Rechte: careplans:read/careplans:write und das Lizenzrecht Praxisbetrieb. Betreuungen sind Klientendaten und brauchen zusätzlich clients:read/clients:write und die Klientendaten-Freigabe der Organisation.

1. Auswahl holen

GET /care-plans/options nennt die Terminarten, die eine Sitzung tragen können (für einen Klienten buchbar, mit ihren Dauern), und die Gesprächsleitfäden. Fehlt eine passende Terminart, legt man sie über /appointment-types an, einen Leitfaden über /call-guides.

curl

curl https://www.claritos.io/api/v1/care-plans/options -H "Authorization: Bearer capi_…"

2. Den Plan als Ganzes beschreiben

Kopf, Phasen und Sitzungen gehen in einem Aufruf, in der Reihenfolge der Listen. phase zeigt auf die Position der Phase (ab 1). Sitzung 1 hat kein Zeitfenster; ab Sitzung 2 sind minDays und maxDays Pflicht, der Abstand in Kalendertagen zum Beginn der vorigen Sitzung. Das Beispiel ist ein Auszug aus dem Entwurf der Black-Swan-Vorlage. Die Sitzung „Willkommen“ fehlt, weil der Abstand von ihr bis „Dein Plan“ an der Laufzeit des Labors hängt. Die gültige Fassung pflegt die Praxis selbst. Beginnt der Plan mit einem Onboarding (in der Black-Swan-Vorlage „Willkommen“), steht firstSessionIsOnboarding: true; die Oberfläche zählt es dann als Sitzung 0.

json

{
  "name": "Black Swan® Metabolic Balance Protokoll - 3 Monate",
  "version": "1.0",
  "description": "Drei Monate, ein Ziel in den eigenen Worten des Klienten. Rückschläge sind Daten, kein Neustart.",
  "phases": [
    { "name": "Vorbereitungsphase", "description": "Zwei Tage." },
    { "name": "Strenge Umstellungsphase", "description": "Mindestens 14 Tage." },
    { "name": "Entspannte Umstellungsphase", "description": "Mehrere Wochen." },
    { "name": "Erhaltungsphase", "description": "Beginnt mit dem Abschluss der Begleitung." }
  ],
  "sessions": [
    { "name": "Dein Plan", "phase": 1, "durationMinutes": 60, "appointmentTypeId": "<id>",
      "goal": "Der Klient kann seinen Plan lesen, kennt die acht Regeln und hat ein Startdatum." },
    { "name": "Die erste Woche", "phase": 2, "minDays": 6, "maxDays": 17, "durationMinutes": 45, "appointmentTypeId": "<id>" },
    { "name": "Bilanz der strengen Phase", "phase": 2, "minDays": 8, "maxDays": 19, "durationMinutes": 60, "appointmentTypeId": "<id>" },
    { "name": "Freiheit mit System", "phase": 3, "minDays": 18, "maxDays": 38, "durationMinutes": 45, "appointmentTypeId": "<id>" },
    { "name": "Dein Weg danach", "phase": 3, "minDays": 24, "maxDays": 48, "durationMinutes": 60, "appointmentTypeId": "<id>" }
  ]
}

Bausteine und Varianten

Teile einer Vorlage, die nur auf Empfehlung in eine Betreuung kommen, sind Bausteine: modules mit key und name. Eine Phase gehört über moduleKey samt ihren Sitzungen zu einem Baustein; eine Sitzung bekommt einen eigenen nur in einer Phase ohne. Zeigen Phasen oder Sitzungen im selben Aufruf auf einen neuen Baustein, setzt du seinen key selbst (Kleinbuchstaben, Ziffern, Bindestrich); danach bleibt er, denn Regeln empfehlen den Baustein über ihn. Eine Sitzung kann je Baustein eine Variante tragen (variants mit moduleKey, callGuideId, durationMinutes): Ist der Baustein gewählt, gelten deren Leitfaden und Dauer. Hat ein Entwurf Bausteine oder Varianten, gehören sie in jedes Ändern; fehlen sie, antwortet die API 422, statt sie still zu entfernen. Beim Start nennt modules die gewählten Schlüssel, ohne Angabe keiner; welche empfohlen sind, sagt GET /clients/{id}/care-plan-suggestions.

json

{
  "modules": [{ "key": "schlaf-modul", "name": "Schlaf-Modul" }],
  "phases": [
    { "name": "Grundlagen" },
    { "name": "Schlaf", "moduleKey": "schlaf-modul" }
  ],
  "sessions": [
    { "name": "Auftakt", "phase": 1, "durationMinutes": 60, "appointmentTypeId": "<id>" },
    { "name": "Erste Bilanz", "phase": 1, "minDays": 7, "maxDays": 14, "durationMinutes": 45, "appointmentTypeId": "<id>",
      "variants": [{ "moduleKey": "schlaf-modul", "durationMinutes": 60 }] },
    { "name": "Schlafprotokoll", "phase": 2, "minDays": 7, "maxDays": 14, "durationMinutes": 45, "appointmentTypeId": "<id>" }
  ]
}

json

POST /care-enrollments
{ "clientId": "<akte>", "planId": "<fassung>", "coachUserId": "<coach>",
  "startDate": "2026-11-02", "modules": ["schlaf-modul"] }

3. Probelauf

POST /care-plans/validate prüft den Baum wie das Anlegen, ohne zu speichern. Ein Fehler kommt als 422 mit Pfad (etwa body.sessions.2.maxDays). Bei Erfolg kommen die Lücken zur Freigabe (gaps), etwa eine Sitzung ohne Terminart. Mit ?planId= prüft er gegen einen vorhandenen Entwurf. Grün heisst: POST /care-plans (neu) oder PUT /care-plans/{id} (Entwurf ersetzen) geht durch.

curl

curl -X POST https://www.claritos.io/api/v1/care-plans/validate \
  -H "Authorization: Bearer capi_…" -H "Content-Type: application/json" \
  -d @black-swan.json

json

{ "releasable": true, "gaps": [] }

4. Freigeben und neue Fassungen

POST /care-plans/{id}/release macht den Entwurf fest und startbar. Das darf wie in der Oberfläche nur eine Person mit dem Freigabe-Recht oder ORG_ADMIN. Hat der Plan noch Lücken, antwortet die API 409 plan-has-gaps mit der Liste. Später ändern: POST /care-plans/{id}/versions legt die nächste Fassung als Entwurf an; laufende Betreuungen behalten ihre Abschrift. Zurückziehen mit …/retire; löschen lässt sich nur, was nie benutzt wurde.

5. Klienten begleiten

POST /care-enrollments startet eine Betreuung nach einer freigegebenen Fassung: Klientenakte, Coach, Starttag und das Ziel in den Worten des Klienten. Die Terminserie entsteht dabei, gebucht wird noch nichts. Termine kommen über einen Vorschlag (…/appointment-proposal, scope=next oder all) und die Buchung (…/appointments, alles oder nichts). GET /care-enrollments/{id} zeigt die Zeitleiste mit Ampel; sie wird gelb, nie rot. Ein Rückschlag ist ein Ereignis (POST …/events, type setback), kein Neustart. Pausieren, fortsetzen, abschliessen oder abbrechen über …/status; Abschluss und Abbruch sagen künftige Termine ab.

json

POST /care-enrollments
{ "clientId": "<akte>", "planId": "<fassung>", "coachUserId": "<coach>",
  "startDate": "2026-10-19", "clientGoal": "In den eigenen Worten des Klienten" }

GET  /care-enrollments/<id>/appointment-proposal?scope=next
POST /care-enrollments/<id>/appointments
{ "appointments": [{ "position": 2, "startsAt": "2026-10-27T09:00:00Z" }] }

6. Sitzungen führen

Eine Sitzung des Plans öffnet POST /care-enrollments/{id}/sessions/open mit ihrer Position in der Abschrift; beim ersten Mal wird sie angelegt, danach kommt dieselbe zurück. Ausserhalb des Plans, etwa bei einer Krise, legt POST /care-enrollments/{id}/sessions eine spontane Sitzung an (adHoc, ohne Position), solange die Betreuung läuft oder pausiert. POST /care-sessions/{id}/start beginnt die Sitzung, running ist dann vier Stunden lang true. PATCH /care-sessions/{id} setzt den Sitzungstyp (standard, safety, gentle, catch-up, relief) mit kurzem Grund. GET /care-enrollments/{id}/sessions listet die geöffneten Sitzungen. Den Gesprächsleitfaden geht der Coach in der Oberfläche durch; die Kennung des Laufs steht in guideRunId. Rechte wie bei den Betreuungen.

json

POST  /care-enrollments/<id>/sessions/open
{ "position": 2 }

POST  /care-sessions/<sitzung>/start
PATCH /care-sessions/<sitzung>
{ "type": "gentle", "typeReason": "Schlechte Stimmung beim Wiegen" }

POST  /care-enrollments/<id>/sessions
{ "name": "Krisengespräch", "type": "relief", "typeReason": "Rückfall nach Urlaub" }

Mit einem KI-Agenten

Für den Bau einer Vorlage eignet sich die kompakte Adresse /api/mcp/v1/compact (je Organisation /api/mcp/v1/compact/o/<orgId>): vier Werkzeuge statt eines je Endpunkt; bei vollem Zugriff hat die normale Adresse über 600. Der Ablauf für den Agenten: diese Anleitung lesen (guide mit topic care-plans), die Auswahl holen, den Baum im Probelauf prüfen, bis er grün ist, dann anlegen. Freigeben sollte die verantwortliche Person selbst, nachdem sie den Plan gelesen hat.

json

{ "name": "guide", "arguments": { "topic": "care-plans" } }
{ "name": "call_endpoint", "arguments": { "id": "careplans.options" } }
{ "name": "call_endpoint", "arguments": { "id": "careplans.validate", "body": { … } } }
{ "name": "call_endpoint", "arguments": { "id": "careplans.create", "body": { … }, "idempotencyKey": "…" } }