claritos
deenru

Создание планов сопровождения

Как практика создаёт, проверяет и утверждает свои планы сопровождения через API или ИИ-агента, а затем сопровождает по ним клиентов, на примере «Black Swan® Metabolic Balance Protokoll - 3 Monate».

Что такое план сопровождения

Шаблон практики из фаз и сессий. У каждой сессии есть тип приёма, длительность, при желании сценарий разговора и временное окно после предыдущей сессии (от minDays до maxDays). У шаблонов есть версии: черновик можно изменять, утверждённая версия неизменна и доступна для запуска, изменения дают новую версию. Сопровождение ведёт клиента по одной версии и хранит её копию. Права: careplans:read/careplans:write и лицензионное право практики. Сопровождения относятся к данным клиентов и требуют дополнительно clients:read/clients:write и разрешения данных клиентов в организации.

1. Получить выбор

GET /care-plans/options перечисляет типы приёмов, которые могут нести сессию (бронируются для одного клиента, с их длительностями), и сценарии разговора. Если подходящего типа приёма нет, его создают через /appointment-types, сценарий через /call-guides.

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

2. Описать план целиком

Заголовок, фазы и сессии передаются одним вызовом, в порядке списков. phase указывает на позицию фазы (с 1). У сессии 1 нет временного окна; начиная с сессии 2 обязательны minDays и maxDays, интервал в календарных днях до начала предыдущей сессии. Пример представляет собой выдержку из черновика шаблона Black Swan. Сессии «Willkommen» в нём нет, потому что интервал от неё до «Dein Plan» зависит от сроков лаборатории. Действующую версию ведёт сама практика. Если план начинается с онбординга («Willkommen» в шаблоне Black Swan), укажите firstSessionIsOnboarding: true; интерфейс тогда считает его сессией 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>" }
  ]
}

Модули и варианты

Части шаблона, которые попадают в сопровождение только по рекомендации, — это модули: modules с key и name. Фаза относится к модулю через moduleKey вместе со своими сессиями; собственный модуль сессия получает только в фазе без модуля. Если фазы или сессии в том же вызове указывают на новый модуль, задайте его key сами (строчные буквы, цифры, дефис); после этого он не меняется, потому что правила рекомендуют модуль по нему. Сессия может иметь по одному варианту на модуль (variants с moduleKey, callGuideId, durationMinutes): если модуль выбран, действуют сценарий и длительность варианта. Если в черновике есть модули или варианты, они должны быть в каждом изменении; без них API отвечает 422, а не удаляет их незаметно. При запуске modules называет выбранные ключи, без указания ни одного; какие рекомендованы, сообщает 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. Пробный прогон

POST /care-plans/validate проверяет дерево так же, как при создании, ничего не сохраняя. Ошибка приходит как 422 с путём (например, body.sessions.2.maxDays). При успехе возвращаются пробелы до утверждения (gaps), например сессия без типа приёма. С ?planId= проверка идёт по существующему черновику. Зелёный результат означает: POST /care-plans (новый) или PUT /care-plans/{id} (замена черновика) пройдёт.

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. Утверждение и новые версии

POST /care-plans/{id}/release делает черновик неизменным и доступным для запуска. Как и в интерфейсе, это может только лицо с правом утверждения или ORG_ADMIN. Если у плана ещё есть пробелы, API отвечает 409 plan-has-gaps со списком. Чтобы изменить позже: POST /care-plans/{id}/versions создаёт следующую версию как черновик; текущие сопровождения сохраняют свою копию. Отзыв через …/retire; удалить можно только то, что ни разу не использовалось.

5. Сопровождать клиентов

POST /care-enrollments начинает сопровождение по утверждённой версии: карта клиента, коуч, день начала и цель словами клиента. При этом создаётся серия приёмов, но ничего не бронируется. Приёмы появляются через предложение (…/appointment-proposal, scope=next или all) и бронирование (…/appointments, всё или ничего). GET /care-enrollments/{id} показывает хронологию со светофором; он становится жёлтым, никогда не красным. Срыв это событие (POST …/events, type setback), а не перезапуск. Пауза, продолжение, завершение или прерывание через …/status; завершение и прерывание отменяют будущие приёмы.

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. Проведение сессий

POST /care-enrollments/{id}/sessions/open открывает сессию плана по её позиции в копии; при первом вызове она создаётся, затем возвращается та же. Вне плана, например при кризисе, POST /care-enrollments/{id}/sessions создаёт внеплановую сессию (adHoc, без позиции), пока сопровождение активно или приостановлено. POST /care-sessions/{id}/start начинает сессию; running тогда четыре часа равно true. PATCH /care-sessions/{id} задаёт тип сессии (standard, safety, gentle, catch-up, relief) с краткой причиной. GET /care-enrollments/{id}/sessions выводит открытые сессии. Сценарий разговора коуч проходит в приложении; ID прохождения указан в guideRunId. Права как у сопровождений.

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" }

С ИИ-агентом

Для создания шаблона лучше всего подходит компактный адрес /api/mcp/v1/compact (для отдельной организации /api/mcp/v1/compact/o/<orgId>): четыре инструмента вместо одного на каждый endpoint; при полном доступе у обычного адреса их больше 600. Порядок для агента: прочитать это руководство (guide с topic care-plans), получить выбор, проверять дерево пробным прогоном, пока он не станет зелёным, затем создать. Утверждать план должно ответственное лицо само, прочитав его.

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": "…" } }