Интеграция с Bitrix24

Доступ: Настройки → Servicedesk → Bitrix24 Integration
URL: /servicedesk/bitrix24/integrations/

Интеграция связывает заявки ASK с задачами корпоративного портала Битрикс24 (облако или on-premise). Синхронизируются статусы, крайний срок, приоритет, название заявки и комментарии — с учётом правил, описанных ниже.

Каждая интеграция привязана к одному клиенту ASK и работает только с его заявками.

6.1. Создание и редактирование интеграции

Нажмите Add Integration (Добавить интеграцию) или откройте существующую запись для редактирования.

Важно: домен в Webhook URL должен соответствовать полю Bitrix24 Domain.

После сохранения интеграции UUID записи понадобится для исходящего вебхука Bitrix (см. раздел 6.2).

6.2. Настройка вебхуков в Bitrix24

Входящий вебхук (ASK → Bitrix)

Приложения → Входящий вебхук

Права доступа:

• Задачи (tasks) — создание и обновление задач
• Пользователи (user) — поиск пользователей по email
• Комментарии (task.commentitem) — публикация комментариев в ленте задачи
• Чат и уведомления (im) — чтение сообщений чата задачи (актуально для порталов, где комментарии уходят в чат; tasks ≥ 25.700)

Скопированный URL укажите в поле Webhook URL интеграции ASK.

Исходящий вебхук (Bitrix → ASK)

Приложения → Исходящий вебхук

• URL обработчика: https://<домен-ASK>/servicedesk/bitrix24/webhook/<uuid-интеграции>/
• События:
• ✅ ONTASKADD — создание задачи
• ✅ ONTASKUPDATE — обновление задачи
• ❌ ONTASKCOMMENTADD — не требуется (комментарии из Bitrix подтягиваются периодическим опросом REST, см. раздел 6.6)

UUID интеграции виден в URL страницы редактирования: /servicedesk/bitrix24/integrations/<uuid>/update/.

6.3. Whitelist исполнителей (Responsible Emails)

Список Responsible Emails — центральное правило интеграции. На него завязаны почти все сценарии.

Создание заявки в ASK из задачи Bitrix

Заявка создаётся (по событию ONTASKADD или при периодическом опросе), только если исполнитель задачи в Bitrix входит в Responsible Emails.

Двусторонняя синхронизация по связанной задаче

Пока исполнитель задачи в Bitrix не из whitelist:

• изменения заявки из ASK не отправляются в Bitrix (статус, срок, комментарии и т.д.);
• поля заявки из Bitrix не подтягиваются в ASK (кроме автоотмены — см. ниже).

Когда исполнитель снова из whitelist — синхронизация возобновляется.

Смена исполнителя в Bitrix на пользователя вне whitelist

Заявка в ASK автоматически переводится в статус «Отменена» (с системным комментарием о причине). Задача в Bitrix при этом не закрывается — работа в Bitrix может продолжаться.

Исключение: задача в Bitrix уже в завершённом статусе (4/5), а заявка в ASK — «Выполнен»; тогда автоотмена не выполняется.

Сопоставление пользователей

Пользователи в ASK и Bitrix сопоставляются по email (без учёта регистра). Email в обеих системах должны совпадать.

6.4. Направления синхронизации

ASK → Bitrix

Название задачи в Bitrix при создании из ASK берётся из заголовка заявки (без префикса «Заявка #ID»). При обновлении из ASK тема задачи в Bitrix не меняется.

Bitrix → ASK

Изменения, пришедшие из Bitrix, не отправляются обратно в Bitrix (защита от циклов).

Дополнительно работает периодический опрос Bitrix (Celery-задача sync_bitrix24_tasks, интервал 5 минут).

6.5. Синхронизация статусов

Стандартные технические статусы задач Bitrix:

Из ASK в Bitrix

Из Bitrix в ASK

Если заявка в ASK уже «Отменена», статус из Bitrix не перетирает её, пока задача в Bitrix снова не «откроется» с исполнителем из whitelist.

При входящих изменениях из Bitrix в журнал заявки пишутся записи о смене статуса, крайнего срока, исполнителя и приоритета.

6.6. Синхронизация комментариев

ASK → Bitrix

В задачу Bitrix попадают:

• публичные комментарии (is_public — включён переключатель «виден клиенту», иконка глаза в ленте);
• резюме при закрытии заявки;
• ответы в цепочке к комментарию, импортированному из Bitrix (с краткой цитатой исходного текста).

Не отправляются:

• внутренние комментарии (без флага видимости для клиента);
• служебные комментарии (например, «создана задача по заявке»);
• комментарии при редактировании уже созданного комментария (синхронизация только при первом создании).

Автор в Bitrix определяется по email автора в ASK (AUTHOR_ID); при отсутствии совпадения используется исполнитель задачи.

Вложения (файлы)

Файлы, прикреплённые к комментарию в ASK, в Bitrix не передаются. В задачу уходит только текст комментария.

Исключение: изображение, вставленное в текст редактора (paste), конвертируется в ссылку в теле комментария. Файлы, прикреплённые через скрепку (чипы под редактором), в Bitrix не появятся, даже если текст комментария ушёл успешно.

По умолчанию переключатель видимости для клиента выключен — для отправки в Bitrix его нужно включить перед отправкой.

Bitrix → ASK

Комментарий импортируется в заявку, если:

1. исполнитель задачи в Bitrix входит в Responsible Emails, и
2. в тексте комментария есть @упоминание сотрудника из того же списка.

Распознаются, в частности: BBCode [USER=id], ссылки data-user-id, /personal/user/{id}/, а также [URL=mailto:email@domain]…[/URL].

Описание задачи из Bitrix (с версии 2.1.0): при импорте заявки HTML-разметка описания задачи Bitrix конвертируется в текст/Markdown для поля описания заявки в ASK — сохраняются абзацы и базовое форматирование, служебные теги удаляются.

Импорт выполняется опросом REST (каждые 5 минут), не через исходящий вебхук ONTASKCOMMENTADD. Для порталов с чатом задач дополнительно читается im.dialog.messages.get (нужно право im у входящего вебхука).

6.7. Синхронизация приоритета

Связь приоритета ASK «Высокий» с полем priority=2 в задаче Bitrix:

• Bitrix → ASK: только через периодический опрос; приоритет в ASK меняется, если priority в Bitrix изменился с прошлого опроса.
• ASK → Bitrix: сразу после сохранения заявки (при исполнителе в whitelist).

6.8. Проверка работы интеграции

1. Создайте тестовую заявку для клиента с активной интеграцией.
2. Если включён Create Tasks From Requests — в Bitrix должна появиться задача с заголовком заявки.
3. Назначьте в Bitrix исполнителя из Responsible Emails — должна создаться (или связаться) заявка в ASK.
4. Измените статус заявки в ASK — статус задачи в Bitrix должен обновиться.
5. Добавьте публичный комментарий с текстом — он должен появиться в задаче Bitrix (файл при этом не передаётся).
6. Завершите задачу в Bitrix — заявка в ASK должна перейти в «Выполнен».

Диагностика конкретного комментария:

• в ленте ASK у комментария есть иконка глаза (публичный);
• в системной админке Django есть связь Bitrix24Comment для этого комментария;
• исполнитель задачи в Bitrix в Responsible Emails.

6.9. Устранение неполадок

Задачи не создаются в Bitrix из ASK

• Проверьте флаг Create Tasks From Requests (по умолчанию выключен).
• Интеграция активна, webhook URL корректен, у вебхука есть права tasks.
• Заявка не черновик и привязана к клиенту интеграции.

Заявки не создаются в ASK из Bitrix

• Email исполнителя задачи есть в Responsible Emails.
• Настроен исходящий вебхук (ONTASKADD) или дождитесь периодического опроса (до 5 минут).
• Интеграция активна.

Статусы или поля не синхронизируются

• Исполнитель задачи в Bitrix в whitelist (см. раздел 6.3).
• В ASK есть статусы с ожидаемыми названиями (Новая, К исполнению, В работе, Ответ клиента, Выполнен, Отменена).
• Для «Выполнен» учитывайте TASK_CONTROL в задаче Bitrix.

Комментарии не синхронизируются

ASK → Bitrix:

• Комментарий публичный (включён переключатель видимости при отправке).
• Исполнитель задачи в Bitrix в whitelist.
• Комментарий создан заново, а не отредактирован позже.
• Ожидайте только текст; вложения в Bitrix не передаются.

Bitrix → ASK:

• Событие ONTASKCOMMENTADD не нужно — проверьте периодический опрос и право im для чата задач.
• В комментарии есть @упоминание сотрудника из whitelist.
• Исполнитель задачи в whitelist.

Исполнитель не назначается

• Email пользователя заполнен в ASK и совпадает с Bitrix.
• Пользователь существует в Bitrix (вебхук с правом user).

Просмотр логов

Ищите записи с префиксом servicedesk.bitrix24 в логах Django:

• пропуск add_comment — исполнитель вне whitelist;
• Error adding comment / Error syncing comment — ошибка API Bitrix.

6.10. Ограничения

1. Черновики заявок не синхронизируются.
2. Один клиент — одна интеграция с одним доменом Bitrix (уникальная пара client + domain).
3. Вложения комментариев из ASK в Bitrix не передаются.
4. Редактирование комментария не вызывает повторную отправку в Bitrix.
5. Синхронизация исходящих изменений выполняется после commit транзакции (небольшая задержка возможна).
6. При удалении интеграции связи ASK↔Bitrix разрываются; задачи в Bitrix не удаляются.

6.11. Управление интеграциями

• Редактирование: кнопка Edit в списке интеграций.
• Отключение: снимите Is Active — настройки сохранятся.
• Удаление: кнопка Delete (с подтверждением); связи разрываются, задачи в Bitrix остаются.

Связи заявок и комментариев с Bitrix также доступны в системной админке Django: модели Bitrix24Task и Bitrix24Comment.