add_deal_note | Добавить заметку в ленту сделки: итог звонка, договорённость,
возражение. Заметку увидят менеджеры в карточке сделки. |
add_deal_tag | Поставить сделке метку по имени. Имя сравнивается без регистра и
с прежними именами меток; такой метки нет, она заводится. Если метка
в группе «одна из», прежняя метка группы снимается сама. Повторная
метка ничего не меняет. Событие ложится в ленту сделки. |
add_deal_task | Поставить задачу по сделке со сроком: позвонить, отправить договор.
Ответственный — хозяин ключа. Срок обязателен: задача без срока не
попадёт в «Сегодня» и будет забыта. |
check_funnelread-only | Та же проверка, что перед публикацией, но ничего не публикует.
errors: не опубликуется, пока не исправить; warnings: можно, но стоит
посмотреть. У каждой записи номер блока (node) и текст. |
cohort_progressread-only | По каждому ученику потока: процент курса (считается по обязательным
опубликованным урокам, как в кабинете), когда последний раз заходил
или проходил урок, сколько дней с тех пор. Плюс доходимость потока —
доля тех, кто дошёл до 100 %. Имена — только по ступени 3
(см. описание сервера), иначе «Ученик 14». |
create_course | Заводит курс-черновик: ученикам он не виден, пока не опубликован
через `publish_course`. Черновиков можно держать сколько угодно
на любом тарифе. Режим доступа: `open` — всё открыто сразу,
`cohort` — по расписанию потока, `sequence` — по прогрессу ученика.
Автор курса — хозяин ключа. Повтор с тем же Idempotency-Key
вернёт тот же курс, а не создаст второй. |
create_deal_tag | Новая метка в справочнике сделок. group: имя группы «одна из»
(у сделки одна метка группы, например «Урок»), новая группа заведётся.
is_source: метка говорит, откуда пришёл человек. Имя, занятое другой
меткой или её прежним именем, отказ: возьмите ту метку. |
create_funnel_draft | Новая воронка бота черновиком. Людям ничего не уходит: опубликовать
её может только человек в кабинете, ссылка в ответе (editor_url).
Формат воронки: get_funnel_format. В ответе проверка (errors,
warnings): исправьте ошибки правкой черновика. |
create_lead | Завести заявку: человек и сделка одним запросом. Нужна почта,
телефон или Telegram. Человек, который уже есть, не заводится второй
раз; повторная заявка про то же ложится заметкой в открытую сделку.
Заголовок `Idempotency-Key` защищает от двойной отправки. |
create_lesson | Урок встаёт в конец модуля. `document` — в формате TipTap
(`{"type": "doc", "content": [{"type": "heading", "attrs": {"level": 2},
"content": [{"type": "text", "text": "..."}]}, {"type": "paragraph",
"content": [...]}]}`); узлы перечислены у `get_lesson`, образец
отдаёт он же. Старый формат Editor.js (`{"blocks": [...]}`) тоже
принимается и переводится. Видео — провайдер и идентификатор, не
iframe. Неизвестное выбрасывается. |
create_module | Модуль встаёт в конец курса. Уроки добавляются в модуль отдельно,
`create_lesson`. Порядок модулей потом можно поменять в кабинете. |
create_sales_rule | Шаг правила продаж, ВСЕГДА выключенный: включает его владелец
в кабинете, до этого он ничего не делает. Повод: event tag (tag_id,
метка поставлена на сделку) или stage (stage_id, сделка перешла на
этап). delay_minutes: через сколько. action: bot (funnel_id, запустить
воронку бота), tag_add или tag_remove (target_tag_id), stage
(target_stage_id, «Оплачено» нельзя), task (task_text, task_days),
goal (цель Метрики). skip_if_replied: не делать, если человек ответил. |
create_sales_stage | Новый этап «в работе» в воронке продаж: сразу после after_stage_id,
а без него перед «Оплачено» и «Отказом». Цвет: secondary, azure,
blue, purple, yellow, orange, green, red. Людям это ничего не шлёт.
Удалить этап может только человек в кабинете. |
create_short_link | Короткая ссылка на домене школы: на адрес (url) или в бота
(bot_username и, если нужно, start_code: код воронки «Старта»).
platform (youtube, vk, rutube, telegram, direct, email, site, other)
ставит метки сама: utm_source, utm_medium, utm_campaign; свои метки
(utm: source, medium, campaign, content, term) главнее. path: свой
путь латиницей; без него система выберет понятный, варианты покажет
suggest_link_path. button: подпись кнопки под роликом, set_id: ролик
или кампания школы.
Та же ссылка (тот же адрес или бот с кодом, та же площадка, кнопка
и ролик) второй раз не заводится: вернётся прежняя, created=false.
Например: url https://it-ontime.ru/mikrotik, platform youtube →
short_url https://go.it-ontime.ru/mikrotik, метки youtube, video,
mikrotik. Ошибка (путь занят, адрес не тот, нет домена) приходит
ответом 400 с текстом для человека. |
create_test | Тест целиком за один вызов: параметры и вопросы по порядку.
Типы вопросов: `one` (один из списка, ровно один верный), `many`
(несколько верных), `text` и `number` (верный ответ в `correct_text`),
`open` (ответ своими словами; `reference_answer` и `criteria` помогают
проверке). Куда положить: `lesson_id` — блоком в конец урока,
`module_id` — итоговым тестом модуля; можно и то и другое, можно ничего. |
get_courseread-only | Один курс целиком: модули по порядку, в каждом — уроки по порядку
с типом (`lecture`, `practice`, `webinar`, `test`, `survey`),
длительностью и признаком обязательности. Итоговый тест модуля,
если есть, назван по номеру — его вопросы отдаёт `get_test`.
Текст уроков сюда не входит: за ним `get_lesson`. |
get_dealread-only | Одна сделка: поля, человек и последние 30 событий ленты (заметки
менеджеров, переводы, открытие доступа, оплаты). Помогает ответить,
что с человеком происходит и о чём с ним договорились. |
get_funnelread-only | Черновик и опубликованная версия воронки, номер версии черновика
(нужен для правки) и сколько людей сейчас стоит на каждом блоке
опубликованной версии. Люди считаются числом, без имён. |
get_funnel_formatread-only | Формат воронки: блоки, их настройки и стрелки. Прочитать до того,
как собирать или править воронку: черновик присылается целиком
в этом формате. |
get_lessonread-only | Документ урока в формате TipTap/ProseMirror (`document_format: "v2"`):
`{"type": "doc", "content": [узлы]}`. Узлы: `paragraph`, `heading`
(`attrs.level` 2–4), `bulletList`/`orderedList`/`taskList` из
`listItem`/`taskItem`, `blockquote`, `codeBlock` (`attrs.language`),
`table`, `image` (`attrs.attachmentId`), `video` (`attrs.provider`,
`attrs.videoId`), `file`, `test` (`attrs.testId`), `assignment`,
`survey`, `callout` (`attrs.style`), `details` (спойлер), `columns`,
`section`, `horizontalRule`. Текст — узлы `text` с `marks` (`bold`,
`italic`, `link` …). Ответ годится как образец для `create_lesson`.
Урок, ещё не открытый в редакторе, отдаётся тоже в этом формате. |
get_link_statsread-only | Что принесла одна ссылка за период. funnel: clicks (переходы),
people (разные люди), to_bot (пришли в бота), leads (заявки с сайта),
deals (сделки), payments (оплаты), revenue (рубли, строкой), returned
(вернулись в бота, были в нём раньше), filtered (отсеяны роботы
и повторы). daily: переходы по дням. paths: люди по каждому пути за
7 и 30 дней и всего, видно, идут ли ещё по старому пути. referrers:
откуда переходят, devices: с чего.
Период: since и until, даты ГГГГ-ММ-ДД включительно, по Москве; без
них последние days дней (по умолчанию 30), days=0 значит всё время.
Например, «сколько оплат дал ролик за сентябрь»: since=2026-09-01,
until=2026-09-30. |
get_school_summaryread-only | Название школы, тариф, сколько курсов и из них опубликовано,
сколько учеников и потоков, и что можно этому ключу.
ИИ вызывает это первым при подключении и представляется человеку
по-человечески: не списком инструментов, а тремя делами, ради
которых школа его подключила, и одним примером вопроса.
Цифры настоящие, из этого же ключа. |
get_testread-only | Тест целиком: порог зачёта, число попыток и вопросы по порядку.
У каждого вопроса тип (`one`, `many`, `text`, `number`, `open`),
варианты с отметкой верного либо верный текст. Верные ответы
отдаются, потому что ключ принадлежит сотруднику школы, а не ученику.
Владельцу и методисту — любой тест школы; остальным — только тест,
стоящий в их курсах. |
list_botsread-only | Боты школы в Telegram: номер, название, адрес и работает ли.
Номер бота нужен, чтобы читать его воронки и собирать новые. |
list_cohortsread-only | Потоки: курс, даты старта и окончания, сколько записано. Поток —
группа учеников с общим расписанием; прогресс по нему —
`cohort_progress`. Ученики вне потоков (запись без потока) сюда
не попадают — их ищет `stuck_students` без `cohort_id`. |
list_coursesread-only | Все курсы школы, включая черновики: название, опубликован ли,
сколько модулей и уроков. Звать первым, чтобы узнать номера курсов
для остальных запросов. Черновик отличается от опубликованного
полем `is_published`; ученики видят только опубликованные. |
list_dealsread-only | Сделки школы, новые сверху: этап, курс, сумма, метки, откуда пришёл
человек. Например, «какие сделки ждут оплаты»: отбор по этапу, «кто
молчит»: по метке (`tag`, имя метки или её прежнее имя). Люди без
имён, если у ключа нет области «имена» или школа не разрешила ИИ
персональные данные. Не больше 200 за раз. |
list_deal_tagsread-only | Справочник меток сделок школы: имя, цвет, группа «одна из» (у сделки
одна метка группы, новая снимает прежнюю), признак источника (откуда
пришёл человек), прежние имена и на скольких сделках метка стоит.
Нужен, чтобы поставить метку существующим именем, а не завести дубль. |
list_funnelsread-only | Воронки бота: состояние (draft — черновик, active — работает,
paused — остановлена), есть ли неопубликованные правки и чьи. |
list_sales_rulesread-only | Шаги правил продаж: повод (event tag или stage, с номером метки или
этапа), через сколько минут, что сделать (action: bot запустить
воронку бота, tag_add, tag_remove, stage, task, goal), включён ли и
почему может не сработать (problem). |
list_sales_stagesread-only | Этапы воронки продаж школы по порядку: номер, название и смысл
(open — в работе, won — успех, lost — отказ). Нужны, чтобы перевести
сделку или отобрать сделки на одном этапе. |
list_short_linksread-only | Короткие ссылки школы, новые сверху: короткий адрес, куда ведёт
(адрес или бот с кодом воронки), площадка, ролик или кампания, метки
и цифры за последние 30 дней в stats_30d: clicks (переходы), people
(разные люди), to_bot (пришли в бота), leads (заявки), deals (сделки),
payments (оплаты), revenue (рубли, строкой).
Отбор: q ищет в названии, адресе, кнопке, имени бота и пути;
platform: youtube, vk, rutube, telegram, direct, email, site, other;
set_id: ссылки одного ролика или кампании; archived=true: архив.
Например, «какая ссылка под роликами YouTube принесла больше денег»:
platform=youtube, затем сравнить stats_30d.revenue. Не больше 200
за раз, дальше offset; total показывает, сколько всего. |
move_deal | Перевести сделку на другой этап той же воронки. Для отказа можно
указать причину. Перевод пишется в ленту сделки с пометкой, что его
сделал ключ API сотрудника. |
publish_course | Открывает курс ученикам или возвращает в черновики. Публикация
идёт через лимит тарифа — ту же проверку, что кнопка в кабинете:
считаются только опубликованные курсы, черновики нет. Если лимит
исчерпан — 409 с текстом, что делать. Снять с публикации можно всегда. |
question_statsread-only | По каждому вопросу теста: сколько ответов и какая доля верных
по завершённым попыткам. Считаются ВСЕ попытки, а не последняя:
вопрос, на котором спотыкаются с первого раза, виден только так.
Ниже 50 % верных — вопрос стоит перечитать: он либо трудный, либо
сформулирован неясно. |
remove_deal_tag | Снять со сделки метку по имени (или прежнему имени). Метка остаётся
в справочнике и на других сделках. Если её на сделке не было, ответ
`changed: false`. |
review_queueread-only | Работы, которые ждут куратора: кто сдал, по какому заданию, когда
и сколько часов ждёт. Отсортировано от самых старых. Принять или
вернуть работу через API нельзя — только посмотреть очередь. |
stuck_studentsread-only | Ученики, которые не дошли до конца и ничего не делали дольше `days`
дней (ни входа, ни пройденного урока). Это адрес для куратора,
а не оценка ученика. `cohort_id` сужает до одного потока; без него —
вся школа, включая записи без потока. Черновики курсов не считаются. |
suggest_link_pathread-only | До трёх свободных понятных путей для новой ссылки, лучшие первыми:
латиница, дефисы, до 40 знаков (go.школа.ru/osi-minikurs вместо
go.школа.ru/k7Pq2a). Строятся из того, что передали: адрес, куда
вести (url), название ссылки (title), подпись кнопки под роликом
(button), название ролика (video_title) или ролик и кампания школы
(set_id), кампания (campaign), заголовок страницы (page_title), код
воронки бота (code), площадка (platform).
Ничего не создаёт. Выбранный путь передайте в create_short_link
(path); без path он выберет первый сам. Например: video_title
«Модель OSI», button «Мини-курс» → model-osi-minikurs, minikurs,
model-osi. |
update_deal_tag | Переименовать метку (прежнее имя запомнится, бот и правила по нему
её найдут), сменить цвет, группу (пустая строка убирает из группы)
или признак источника. Удалить и склеить метки можно только в кабинете. |
update_funnel_draftdestructive | Заменить черновик воронки целиком, в том числе у работающей:
люди идут по опубликованной версии, пока человек не опубликует
правки в кабинете (там он увидит их списком). draft_version из
get_funnel: если черновик успели поменять, ответ 409, прочитайте
воронку заново. В ответе задетые блоки и проверка. |
update_lessondestructive | Меняет название и/или документ урока. Прежний документ уходит
в историю версий урока (вернуть — в кабинете). При замене документа
ОБЯЗАТЕЛЬНО передать
`updated_at` из `get_lesson`: если урок с тех пор менялся —
отказ 409, а не затирание. Сначала `get_lesson`, потом правка. |
update_sales_rule | Поправить шаг правила, пока он выключен: только присланные поля.
Включённый шаг работает на людях, его меняет только владелец
в кабинете: ответ 409. |
update_sales_stage | Переименовать этап, сменить цвет или переставить: after_stage_id
это этап, после которого он встанет. Смысл этапа (в работе, успех,
отказ) меняется только в кабинете. |
update_short_linkdestructive | Поменять, куда ведёт ссылка (url), её название (title) или убрать
в архив (archived=true, вернуть: false). Короткий адрес не меняется:
новый url сразу получат все, кто нажмёт ссылку под роликами, в письмах
и в рекламе, поэтому сначала прочитайте ссылку (list_short_links)
и убедитесь, что меняете ту. Ссылку в бота url переводит на адрес.
Архивная ссылка продолжает вести людей, она только уходит из списка.
Например: {"url": "https://it-ontime.ru/mikrotik-2026"}. Удаления
нет: ссылка с переходами хранит историю. |
protogrid