> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velesagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Настройка устанавливаемого навыка для безопасного чтения и изменения данных локального портала Битрикс24 ALOR через входящий вебхук и зашифрованные секреты Велеса.

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

`alor-bitrix24` — устанавливаемый навык для работы с локальным порталом Битрикс24 по адресу
`https://portal.alorbroker.ru`.

Установите его в панели «Навыки» из одного из предустановленных каталогов ALOR. После
установки файлы находятся в `<workspace>/skills/alor-bitrix24`; в пакет Велеса они не входят.

Навык основан на открытом проекте
[vrtalex/bitrix24-skill](https://github.com/vrtalex/bitrix24-skill), но адаптирован для
Велеса: адрес портала закреплён в помощнике, авторизация выполняется только через входящий
вебхук, а его данные передаются из зашифрованного хранилища секретов только на время ответа.

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

Навык помогает Велесу:

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

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

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

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

Адрес входящего вебхука имеет вид:

```text theme={null}
https://portal.alorbroker.ru/rest/<идентификатор-пользователя>/<код-вебхука>/
```

В Велесе полный адрес сохранять не нужно. Из него используются только два значения:

* `<идентификатор-пользователя>`;
* `<код-вебхука>`.

Не отправляйте полный адрес вебхука или его код в чат.

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

Откройте панель секретов и заполните две обязательные цели:

* `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`. Проверьте корпоративную службу имён, сетевой маршрут и доверие
к сертификату портала из того же контейнера или узла, где работает Велес.

Если встроенная защита Велеса блокирует обращения к частным адресам, для доверенной внутренней
среды можно явно разрешить такие обращения:

```json theme={null}
{
  "tools": {
    "blockPrivateNetworks": false
  }
}
```

Это ослабляет общую сетевую защиту инструментов, поэтому меняйте настройку только для среды,
где доступ к внутренним узлам действительно необходим. Не отключайте проверку сертификата.

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

После настройки попросите Велес выполнить безопасную проверку, например:

> Проверь подключение к Битрикс24 ALOR и покажи текущего пользователя.

Навык вызовет метод `user.current`, который только читает данные. Затем можно попросить, например:

* «Найди активные сделки с таким названием»;
* «Покажи мои незавершённые задачи»;
* «Подготовь перенос сделки 123 на такую-то стадию»;
* «Найди контакт по рабочему телефону».

Для чтения больших списков Велес должен выбирать только нужные поля, ограничивать размер
вывода и обрабатывать все страницы результата, если пользователь запросил полный список.

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

Помощник создаёт в текущей рабочей области каталог `.runtime` для:

* журнала операций;
* временных планов изменений;
* защиты от повторного выполнения;
* состояния ограничения частоты запросов.

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

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

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

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

* [Секреты и токены](/basics/secrets_ru)
* [Настройка Велеса](/configuration_ru)
* [Инструменты, веб-поиск и MCP](/dive-deeper/tools_web_mcp_ru)
* [Навыки Велеса: подробный справочник](/skills/reference_ru)