Для разработчиков

Начало API

Ниже то, чем кабинет уже отвечает. Почту, финансы и инвентаризацию назовём следующими: пути есть, тела ещё соберём.

Контракт

Как устроен запрос

Отдельного ключа разработчика пока нет: запрос узнаёт человека по сессии кабинета. Вызов идёт с cloncy.com. С docs.cloncy.com cookie сессии не уходит.

База

https://cloncy.com

Тело и ответ — JSON, UTF-8. У ответа стоит Cache-Control: no-store.

Сессия

Cookie turan_shell

HttpOnly, Secure, SameSite=Lax, Path=/. Её ставит вход и снимает выход.

Ошибка

{ "message": "…" }

401 — нужен вход. 400 — запрос не разобран. 402 — лимит или план. 423 — кабинет закрыт кодом. 429 — слишком часто. 503 — оболочка ещё не готова.

Успех

{ "ok": true }

Рядом лежат данные раздела. Без сессии кабинет отвечает «Нужен вход».

Сессия

Вход принимает почту и пароль. Если кабинету нужен код из письма, первый ответ приходит со step: "code", второй — с тем же телом и полем code из шести цифр. modules: null значит, что открыты все личные модули. Массив — только перечисленные. Пока значение null, смена набора отвечает «Модули уже все на месте».

Вход

await fetch("https://cloncy.com/shell/login", {
  method: "POST",
  credentials: "include",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    email: "[email protected]",
    password: "<пароль>"
  })
});

Ответ входа

{
  "ok": true,
  "step": "done",
  "account": {
    "email": "[email protected]",
    "first": "Анна",
    "last": "",
    "login": "anna",
    "modules": ["reminders", "calendar", "mail"]
  }
}

Вызов	Что делает	Поля
`GET /shell/session`	Кто вошёл и закрыт ли кабинет	`—`
`POST /shell/login`	Войти и получить cookie	`email, password, code`
`POST /shell/logout`	Снять сессию	`—`
`POST /shell/modules`	Оставить часть личных модулей	`modules`

Задачи

GET /shell/reminders отдаёт задачи, папки и заодно события календаря. POST ходит с полем op. Срок at — миллисекунды. Приоритет: high, normal, low. Напоминание за lead минут: 0, 5, 15, 30, 60 или 1440. Повтор: hour, day, week, month, year.

Новая задача

{
  "op": "add",
  "title": "Собрать смету",
  "notes": "",
  "priority": "high",
  "remind": true,
  "lead": 30
}

Задача в ответе

{
  "ok": true,
  "items": [{
    "id": "ab12cd34ef567890",
    "title": "Собрать смету",
    "notes": "",
    "at": 0,
    "done": false,
    "list": "a1b2c3d4e5f67890",
    "parent": "",
    "priority": "high",
    "remind": true,
    "lead": 30,
    "repeat": ""
  }],
  "lists": [{ "id": "a1b2c3d4e5f67890", "name": "Общая", "parent": "" }]
}

Вызов	Что делает	Поля
`add`	Новая задача в папке	`title, notes, list, at, priority, remind, lead, repeat, until, parent`
`update`	Правка	`id и те же поля`
`delete`	Убрать в корзину	`id`
`restore`	Вернуть из корзины	`kind, id`
`reorder`	Порядок в списке	`ids`
`addList`	Новая папка	`name, parent`
`updateList`	Имя и вид папки	`id, name`
`deleteList`	Убрать папку	`id`

Календарь

События читаются из GET /shell/reminders, поле events. Запись идёт в POST /shell/events. start — миллисекунды. timed: true ставит время внутри дня.

Событие

{
  "op": "add",
  "title": "Созвон",
  "start": 1794254400000,
  "timed": true
}

В списке

{
  "id": "ab12cd34ef567890",
  "title": "Созвон",
  "start": 1794254400000,
  "timed": true,
  "pinned": false
}

Вызов	Что делает	Поля
`add`	Новое событие	`title, start, timed`
`update`	Правка	`id, title, start, timed`
`delete`	Удалить	`id`

Проекты

GET /shell/works?brief=1 возвращает комнаты: id, title, текущий talk, список talks и url опубликованной страницы. Комната создаётся названием. Реплика уходит в текущий чат. Поток GET /shell/works/live — text/event-stream. Событие live несёт ход, поле step равно think, plan или edit. Событие done закрывает поток.

Комната

{
  "works": [{
    "id": "ab12cd34ef567890",
    "title": "Северный",
    "talk": "c1d2e3f4a5b67890",
    "url": "https://cloncy.app/ab12cd34ef567890/",
    "talks": [{ "id": "c1d2e3f4a5b67890", "title": "Новый чат" }]
  }]
}

Реплика

{
  "id": "ab12cd34ef567890",
  "talk": "c1d2e3f4a5b67890",
  "text": "Собери страницу с часами работы"
}

Вызов	Что делает	Поля
`GET /shell/works?brief=1`	Список комнат	`—`
`POST /shell/works`	Новая комната	`title`
`POST /shell/works/message`	Реплика в чат	`id, talk, text`
`GET /shell/works/live`	Поток хода	`id, talk в строке запроса`

Следующий заход

Пути, которые уже отвечают

Тела этих запросов ещё не расписаны. Здесь только то, что сессия уже может открыть.

Вызов	Что делает	Поля
`GET, POST /shell/mail`	Ящики почты	`boxes, current`
`GET, POST /shell/finance`	Личные финансы	`categories, expenses, incomes`
`GET, POST /shell/inventory`	Инвентаризация	`domains`
`GET /shell/assistant`	Помощник кабинета	`история, если она включена`

Пароли, студия и админка кабинета в этот контракт не входят. Их экраны остаются внутри сессии.