Интеграции: ИИ-ассистент, API и webhook

Цель. Подключить Assist к другим программам: спрашивать данные у ИИ-помощника, создавать задачи и записывать время из скриптов, получать события в свои системы.

Кто выполняет. Сотрудник, которому нужно подключение. Для работы с чужими ключами нужны права администратора.

Что нужно до начала. Определите, что нужно сделать:

Задача	Способ
Спрашивать ИИ-помощника о проектах, задачах, часах	MCP (только чтение)
Создавать задачи, записывать время, менять данные программно	REST API
Получать события в свою систему	Webhook

Справочник для разработчика: «API и интеграции».

Часть 1. Создайте API-ключ

Ключ нужен для MCP и REST API.

1. Нажмите API-ключи в шапке кабинета.
2. Нажмите Создать ключ.

3. Введите Название, например «Интеграция с CRM».
4. Выберите Роль. Ключ получит права именно этой роли. Выбрать можно свою роль или роль с более низким приоритетом.
5. Выберите Срок действия: «Бессрочно», 30, 90 или 365 дней.
6. Нажмите Создать ключ.

7. Скопируйте токен вида thor_sk_… и сохраните в надёжном месте. Второй раз его не покажут.

Внимание

Токен — как пароль. Не отправляйте его в мессенджерах и не храните в репозитории. Давайте ключу роль с минимально нужными правами и заводите отдельный ключ для каждой интеграции.

Часть 2. Подключите ИИ-ассистента (MCP)

MCP работает только на чтение: ассистент не может ничего создать или изменить.

1. На странице «API-ключи» нажмите Подключить к ИИ.
2. Выберите роль. Ассистент увидит ровно то, что видит эта роль.
3. Кабинет создаст ключ и покажет окно Подключение ИИ-ассистента (MCP) с вкладками Cursor, Claude Code, Codex, Другой харнесс и Проверка (curl).
4. Нажмите Копировать и вставьте конфигурацию в настройки своего ИИ-клиента.
5. Проверьте подключение на вкладке «Проверка (curl)».

Ключ в окне показывается один раз.

Примеры вопросов к ассистенту:

• «Какие задачи по проекту RGM сейчас в работе и у кого?»
• «Сколько часов ушло на релиз 2.4 за неделю?»
• «Кто отвечает за интеграцию с платёжной системой?»

Для точных ответов заполните «Зоны ответственности» участников в настройках проекта: «Проект. Настройки».

Часть 3. Работайте через REST API

Принципы:

• Адрес: https://<адрес-кабинета>/api.
• Заголовок Authorization: Bearer thor_sk_….
• Права определяются ролью ключа. При нехватке прав API возвращает 403.
• Для изменяющих запросов добавляйте Idempotency-Key, чтобы повтор не создал дубликат.
• Лимит: 180 запросов в минуту.

Пример: создать задачу.

curl -X POST "https://<адрес-кабинета>/api/projects/<ID_ПРОЕКТА>/tasks" \
  -H "Authorization: Bearer thor_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-import-001" \
  -d '{"title": "Задача из CRM"}'

Остальные методы и примеры: «API и интеграции».

Часть 4. Подключите webhook

1. Откройте Профиль → Каналы уведомлений, блок Ваши webhook.
2. Введите Название webhook и URL webhook. Адрес должен быть публичным и начинаться с https://.
3. Нажмите Создать webhook.
4. Один раз кабинет покажет секрет. Скопируйте его и нажмите «Я скопировал секрет».
5. Включите канал Webhook для нужных событий на вкладке Настройка уведомлений: «Настройка уведомлений».

В вашей системе проверяйте заголовок X-Assist-Signature: sha256= и HMAC-SHA256 от тела запроса с вашим секретом. Пример проверки: «API и интеграции».

Часть 5. Перевыпуск и отзыв ключей

• Перевыпустить: новый токен, старый перестаёт работать сразу. Обновите токен в интеграциях.
• Отозвать: ключ перестаёт работать навсегда.
• Создавать, перевыпускать и отзывать ключи можно только в интерфейсе.
• Ограничено число активных ключей: при достижении лимита кабинет сообщит.

Как проверить результат

• Ассистент отвечает на вопрос о проектах.
• Тестовый запрос GET /api/me возвращает ваш профиль и права ключа.
• В «API-ключах» у ключа появилось значение в колонке «Использован».

Типичные ошибки

Ситуация	Причина	Решение
401	Нет или недействителен ключ	Проверьте токен и срок действия
403	Ключу не хватает прав	Выберите другую роль или попросите администратора
404	Запись вне охвата роли	Проверьте скоуп роли
429	Превышен лимит	Подождите, см. retry-after
Webhook отклоняет адрес	Адрес частный или не HTTPS	Используйте публичный HTTPS

Что дальше

• Экран «API-ключи».
• Сессии и безопасность.