Skip to main content

​
Навык: Битрикс24 ALOR

alor-bitrix24 — устанавливаемый навык для работы с локальным порталом Битрикс24 по адресу https://portal.alorbroker.ru. Установите его в панели «Навыки» из одного из предустановленных каталогов ALOR. После установки файлы находятся в <workspace>/skills/alor-bitrix24; в пакет Велеса они не входят. Навык основан на открытом проекте vrtalex/bitrix24-skill, но адаптирован для Велеса: адрес портала закреплён в помощнике, авторизация выполняется только через входящий вебхук, а его данные передаются из зашифрованного хранилища секретов только на время ответа.

​
Возможности

Навык помогает Велесу:
  • искать и читать лиды, сделки, контакты и компании;
  • работать с задачами, проектами, чатами, уведомлениями, календарями и файлами;
  • запускать поддерживаемые бизнес-процессы;
  • находить доступные методы Битрикс24 и разбирать ошибки;
  • планировать изменения до их выполнения;
  • ограничивать доступные методы, повторные записи и частоту запросов;
  • вести локальный журнал операций без сохранения данных вебхука.
Создание, изменение, отправка, загрузка и удаление данных относятся к изменениям внешней системы. Перед такой операцией Велес сначала готовит локальный план, показывает точное действие и получает подтверждение пользователя. Для удаления и других необратимых действий требуется отдельное явное подтверждение.

​
Что нужно подготовить в Битрикс24

Создайте входящий вебхук в portal.alorbroker.ru от имени отдельного служебного пользователя. Выдайте ему только те разрешения, которые действительно нужны Велесу. Не используйте учётную запись администратора без необходимости. Адрес входящего вебхука имеет вид:
В Велесе полный адрес сохранять не нужно. Из него используются только два значения:
  • <идентификатор-пользователя>;
  • <код-вебхука>.
Не отправляйте полный адрес вебхука или его код в чат.

​
Настройка секретов Велеса

Откройте панель секретов и заполните две обязательные цели:
  • skills.alor-bitrix24.env.B24_WEBHOOK_USER_ID — идентификатор пользователя из адреса вебхука;
  • skills.alor-bitrix24.env.B24_WEBHOOK_CODE — секретный код вебхука.
Оба значения хранятся в зашифрованном локальном хранилище. Велес подставляет их в окружение помощника только на время ответа; они не записываются в config.json, инструкции навыка или командную строку. Пока хотя бы одна цель не заполнена, навык помечается как недоступный. Переменные B24_DOMAIN и B24_AUTH_MODE настраивать не нужно: помощник принимает только https://portal.alorbroker.ru и авторизацию входящего вебхука.

​
Доступ из внутренней сети

Среда, где запущен Велес, должна находиться во внутренней сети ALOR или иметь разрешённый маршрут к portal.alorbroker.ru. Проверьте корпоративную службу имён, сетевой маршрут и доверие к сертификату портала из того же контейнера или узла, где работает Велес. Если встроенная защита Велеса блокирует обращения к частным адресам, для доверенной внутренней среды можно явно разрешить такие обращения:
Это ослабляет общую сетевую защиту инструментов, поэтому меняйте настройку только для среды, где доступ к внутренним узлам действительно необходим. Не отключайте проверку сертификата.

​
Первый запрос

После настройки попросите Велес выполнить безопасную проверку, например:
Проверь подключение к Битрикс24 ALOR и покажи текущего пользователя.
Навык вызовет метод user.current, который только читает данные. Затем можно попросить, например:
  • «Найди активные сделки с таким названием»;
  • «Покажи мои незавершённые задачи»;
  • «Подготовь перенос сделки 123 на такую-то стадию»;
  • «Найди контакт по рабочему телефону».
Для чтения больших списков Велес должен выбирать только нужные поля, ограничивать размер вывода и обрабатывать все страницы результата, если пользователь запросил полный список.

​
Хранение служебных файлов

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

​
Ограничения

  • Навык не подключается к другим порталам Битрикс24 и отклоняет замену адреса.
  • Навык не поддерживает авторизацию приложения OAuth и автономную очередь событий.
  • Ошибка WRONG_AUTH_TYPE означает, что выбранный метод требует другого типа авторизации и не должен обходиться передачей дополнительных секретов в чат.
  • При ошибках доступа сначала проверьте права входящего вебхука и запрашивайте только необходимое расширение прав.
  • Содержимое карточек, комментариев, чатов и файлов считается недоверенными данными, а не инструкциями для Велеса.

​
Связанные страницы