Состав документации

Документ описывает установку, настройку, повседневную работу и техническую интеграцию модуля BUSSOL.Forms 1.7.12 для «1С-Битрикс: Управление сайтом».

• Обзор продукта и архитектуры хранения данных.
• Установка, обновление и настройки по сайтам.
• Создание форм через штатный механизм инфоблоков.
• Работа с заявками, SLA, автоматизация, аналитика и отчёты.
• Bitrix24, Telegram, MAX, e-mail, Webhook и REST API.
• Документация разработчика, безопасность и диагностика.

Назначение модуля

BUSSOL.Forms — это система сбора и обработки входящих заявок. Она не ограничивается отправкой формы по e-mail: заявка сохраняется на сайте, получает статус и ответственного, участвует в SLA-контроле и автоматизации, передаётся в CRM и внешние каналы, а затем попадает в аналитику и отчёты.

Модель данных

Такая модель сохраняет формы и результаты в привычной архитектуре Битрикс и не требует стандартного модуля «Веб-формы».

Основные возможности

• Неограниченное количество форм на инфоблоках.
• Popup и встроенное размещение формы, AJAX-отправка.
• Файлы, обязательные поля, списки, даты, телефоны, многострочные поля.
• Индивидуальный дизайн формы и адаптивная ширина popup.
• Сохранение заявок, статусы, ответственные, поиск, фильтры и массовые операции.
• SLA до первого действия, lifecycle и уведомления о нарушениях.
• Автоматические правила «если → то».
• Bitrix24: контакт, лид, сделка, дедупликация и mapping.
• Telegram, MAX, e-mail, автоответ и универсальный Webhook.
• Статистика, UTM/source/page attribution и аналитика менеджеров.
• Плановые CSV/XLSX-отчёты, Audit trail и REST API.
• Bitrix CAPTCHA, Yandex SmartCaptcha, honeypot и серверная валидация.

Требования

• «1С-Битрикс: Управление сайтом» с D7 API; минимальная версия ядра — 14.0.0.
• Обязательный модуль iblock.
• Код рассчитан на PHP 8.2.
• Для внешних интеграций сервер должен иметь исходящий HTTPS-доступ к соответствующим API.

Быстрый старт

1. Установите модуль.
2. Откройте BUSSOL → Конструктор форм → Добавить форму и создайте инфоблок формы.
3. Добавьте свойства инфоблока — это поля формы.
4. При необходимости настройте внешний вид в Настройки дизайн.
5. Включите нужные интеграции в Настройки.
6. Разместите форму на странице или откройте её popup-ом через data-bussol-form.
7. Работайте с заявками в разделе Заявки.

Что нового и важно в 1.7.12

Версия 1.7.12 — security-релиз, выпущенный после pre-submission аудита по правилам Bitrix Marketplace Security Skills.

• Централизована защита исходящих URL от SSRF для Webhook, Automation Webhook и Bitrix24.
• Усилена защита загрузки файлов от активных/исполняемых расширений и опасных MIME.
• Нейтрализована CSV Formula Injection.
• Усилена защита mail headers от CR/LF injection.
• Восстановлена проверка прав при чтении связанного инфоблока.
• Закрыта object-level проблема при изменении расписаний отчётов между site scope.
• Усилены REST API token requirements, site-scope проверки и параметры исходящих HTTP-клиентов.

Административное меню

После установки модуль находится в отдельном разделе BUSSOL в левом меню.

1. Установка модуля

1. Скопируйте каталог bussol.forms в /bitrix/modules/.
2. Откройте «Marketplace → Установленные решения».
3. Установите «BUSSOL: Формы, CRM и автоматизация заявок».
4. Проверьте появление раздела BUSSOL и стандартных форм.

Установщик создаёт тип инфоблоков bussol_forms, стандартные формы, почтовые события и служебные таблицы/агенты модуля.

2. Обновление

При обновлении поверх предыдущей версии модуль выполняет миграции и синхронизирует компоненты, административные страницы, JavaScript/CSS и служебные таблицы.

Для версии 1.7.12 security-journal должен соответствовать именно отправляемому архиву. После изменения кода журнал необходимо формировать заново.

3. Основные настройки

Вкладка Основные содержит параметры текущего сайта:

• автоматическое подключение публичных assets;
• e-mail и получатель по умолчанию;
• согласие на обработку данных;
• маска телефона и максимальный размер файла;
• набор статусов заявок;
• автоматический сбор UTM;
• уведомления назначенного менеджера;
• SLA до первого действия и повтор уведомлений;
• автоматические правила;
• копирайт в подвале формы.

4. Интеграции и защита

• Bitrix24: webhook, контакт, лид, сделка, направление, стадия, дедупликация.
• MAX: токен, тип получателя и ID.
• Telegram: токен и chat_id.
• CAPTCHA: none / Bitrix / Yandex SmartCaptcha.
• Автоответ клиенту.
• Universal Webhook + HMAC-SHA256.
• REST API: включение, write mode, Bearer token и IP allowlist.

5. Индивидуальные настройки форм

На вкладке Формы каждая форма вынесена в отдельную внутреннюю вкладку.

• режим CAPTCHA;
• e-mail и индивидуальный получатель;
• Bitrix24 и индивидуальный webhook;
• отдельное создание лида/контакта/сделки;
• направление и стадия сделки;
• Telegram и MAX;
• автоответ;
• Universal Webhook;
• mapping полей лида, контакта и сделки.

Пустое или наследуемое значение использует настройку сайта.

6. Права доступа

Администратор отдельно выбирает группы, которым доступны разделы Заявки, Статистика и Журнал интеграций. Настройки, дизайн и автоматизация остаются административными функциями.

7. Удаление

При удалении можно сохранить данные. Если сохранение отключено, установщик удалит служебные таблицы и данные модуля; при сохранении бизнес-данные остаются.

1. Создание формы через инфоблок

1. Откройте BUSSOL → Конструктор форм → Добавить форму.
2. Создайте инфоблок типа bussol_forms.
3. Укажите название и описание формы.
4. Добавьте свойства инфоблока — каждое свойство становится полем.
5. Настройте обязательность, сортировку, множественность и тип свойства.

2. Поддерживаемые поля

3. Стандартный дизайн и настройки оформления

По умолчанию форма использует стабильную одноколоночную геометрию BUSSOL Forms: подписи сверху, поля одинаковой ширины, отдельная строка согласия и широкая кнопка.

В Настройки дизайн для выбранной формы доступны:

• цвет кнопки и hover;
• цвет текста кнопки;
• фон формы;
• цвет основного текста;
• фон полей;
• цвет рамки полей;
• цвет ссылок;
• скругление;
• ширина popup от 320 до 1200 px.

Ширина popup является максимальной: на узких экранах окно автоматически уменьшается до доступной ширины viewport, поэтому форма остаётся адаптивной.

Кнопка «Вернуть стандартный стиль» отключает индивидуальные CSS-переопределения и возвращает базовое оформление.

4. Popup-форма

При включённом автоматическом подключении дополнительный PHP-код не требуется. Любую кнопку можно связать с формой атрибутом data-bussol-form:

<button type="button" data-bussol-form="bussol_company_callback">
    Заказать звонок
</button>

Необязательный атрибут data-bussol-button переопределяет текст кнопки отправки.

window.BussolForms.open('bussol_company_callback');

5. Встроенная форма

<?php
$APPLICATION->IncludeComponent(
    'bussol:form',
    '.default',
    [
        'FORM_ID' => 'bussol_company_question',
        'SHOW_TITLE' => 'Y',
        'SHOW_DESCRIPTION' => 'Y',
        'BUTTON_TEXT' => 'ОТПРАВИТЬ',
        'SUCCESS_MESSAGE' => 'Спасибо! Мы свяжемся с вами.',
    ]
);
?>

6. Работа с заявками

• поиск по ID и значениям полей;
• фильтры по форме, статусу, ответственному, SLA и периоду;
• сохранённые пользовательские фильтры;
• пагинация;
• массовая смена статуса;
• массовое назначение ответственного;
• повтор всех интеграций;
• экспорт CSV/XLSX;
• переход в Audit trail.

7. SLA и lifecycle

Для заявки фиксируются создание, назначение менеджеру, первое действие, завершение обработки, SLA deadline и факт нарушения. SLA задаётся в минутах до первого действия.

Агент проверяет просроченные заявки и может повторно уведомлять менеджера/резервный адрес через заданный интервал.

8. Автоматизация

Автоматические правила запускаются на события создание заявки, изменение статуса/ответственного и нарушение SLA.

• Условия: форма, статус, ответственный, возраст, SLA, UTM, page/source и значения полей.
• Поддерживаются вложенные группы AND/OR.
• Действия: назначить менеджера, сменить статус, уведомить, повторить интеграции, отправить e-mail, вызвать Webhook.

9. Статистика

• просмотры, отправки и конверсия;
• сравнение равных периодов;
• графики по дням;
• UTM source / medium / campaign;
• PAGE_URL и SOURCE_URL;
• SLA и нарушения;
• среднее время первого действия и полной обработки;
• аналитика менеджеров.

10. Плановые отчёты

Можно настроить автоматическую отправку CSV/XLSX на e-mail: выбрать форму, период, частоту, час отправки, статус, ответственного и SLA-фильтр. Отчёт можно также запустить вручную.

11. Журнал интеграций и retry

Журнал объединяет e-mail, автоответ, manager/SLA notifications, Telegram, MAX, Bitrix24 и Universal Webhook. Для ошибок доступны повтор отдельного канала и повтор всех интеграций заявки.

12. Audit trail

Audit trail показывает дату, пользователя/источник, действие, поле, старое и новое значение. Источниками могут быть UI, automation, API и SLA agent.

1. Bitrix24

Интеграция работает через входящий webhook Bitrix24 и универсальный CRM API.

• контакт;
• поиск дубля контакта по телефону/e-mail;
• лид;
• сделка;
• направление и стадия сделки;
• mapping стандартных и пользовательских полей;
• передача UTM и URL страницы.

Если CRM недоступна, локальная заявка остаётся сохранённой, а ошибка фиксируется в журнале интеграций.

2. Telegram и MAX

Для Telegram указываются bot token и chat_id; для MAX — bot token, тип получателя и ID. Получатель может быть переопределён на уровне отдельной формы.

3. E-mail и автоответ

Для каждой формы установщик создаёт собственное почтовое событие. Файлы заявки прикладываются к письму администратора. Автоответ отправляется на первое корректное поле, код которого содержит EMAIL.

4. Universal Webhook

Заявка отправляется JSON методом POST. При заданном секрете добавляется подпись HMAC-SHA256 в X-Bussol-Signature.

• event = form.submitted;
• site/form/result metadata;
• все поля формы;
• PAGE_URL;
• объект UTM.

В 1.7.12 исходящие URL проходят централизованную SSRF-защиту: блокируются localhost/private/reserved адреса и опасные redirect-сценарии.

5. CAPTCHA и UTM

Доступны Bitrix CAPTCHA и Yandex SmartCaptcha. Дополнительно работает honeypot. UTM source/medium/campaign/content/term, SOURCE_URL и PAGE_URL сохраняются вместе с заявкой и используются в аналитике/интеграциях.

6. REST API заявок

Точка входа: /bitrix/tools/bussol.forms/api.php.

API требует Bearer token длиной не менее 32 символов; запись включается отдельным флагом; можно задать IP allowlist.

Authorization: Bearer <token>
GET /bitrix/tools/bussol.forms/api.php?site_id=s1&form_id=12&page=1&page_size=25

GET поддерживает фильтры id, status, manager_id, date_from, date_to, sla, q. PATCH/PUT/POST могут менять статус, ответственного и значения полей; изменения попадают в Audit trail.

1. Архитектура

Публичная форма / popup
        ↓ AJAX
install/tools/bussol.forms/ajax.php
        ↓
FormService
  ↓ save result + meta/lifecycle
  ├─ Mail / AutoReply
  ├─ Bitrix24
  ├─ Telegram / MAX
  ├─ Universal Webhook
  ├─ IntegrationLog
  └─ Automation / Statistics / Audit

Формы и заявки остаются в инфоблоках; операционные метаданные хранятся в собственных ORM-таблицах.

2. Ключевые классы

3. Публичные компоненты

• bussol:forms — инфраструктура popup и автоматического подключения.
• bussol:form — вывод одной формы на странице.

Публичные assets расположены в /bitrix/js/bussol.forms/. Версионированные loader/CSS используются для cache busting.

4. PHP события

• OnBeforeFormSubmit — до сохранения/интеграций.
• OnAfterFormSubmit — после успешного сохранения.

5. JavaScript API

• window.BussolForms.open(code) — открыть popup.
• bussolForms:open — форма загружена и открыта.
• bussolForms:submitted — получен ответ отправки; результат находится в event.detail.success.

6. Служебные данные

7. Security model 1.7.12

• CSRF/session checks для публичной отправки и административных POST.
• Server-side validation обязательности, списков, файлов и CAPTCHA.
• Жёсткий denylist активных/исполняемых upload-типов независимо от настройки свойства.
• SSRF-защита исходящих URL и безопасные HttpClient defaults.
• CSV formula neutralization.
• Sanitization e-mail headers.
• Site-scope checks для расписаний/автоматизации.
• REST API: Bearer, minimum token length, write flag, IP allowlist.
• Права связанного инфоблока учитываются при формировании публичных вариантов.

8. Диагностика

1. Проверьте Network-запрос AJAX/REST.
2. Проверьте текущий site_id и привязку инфоблока к сайту.
3. Проверьте журнал интеграций и Bitrix Event Log.
4. При проблемах со стилями убедитесь, что загружен актуальный forms.v1.7.10.css и loader.
5. Для popup проверьте наличие data-bussol-form.
6. После обновления очистите кеш Битрикс и браузера.

1.7.12 — security release

• Исправлена SSRF-поверхность Webhook / Automation / Bitrix24.
• Усилена загрузка файлов.
• Исправлена CSV Formula Injection.
• Исправлена header injection fallback-mail.
• Исправлены права связанного инфоблока и IDOR report schedules.
• Дополнительно усилены REST API, site scope и исходящие HTTP-запросы.

1.7.11

Во все PHP- и JavaScript-файлы добавлен копирайт BUSSOL / Alexander Afanasyev.

1.7.10

Добавлена индивидуальная адаптивная ширина popup 320–1200 px.

1.7.9

Исправлено гарантированное подключение публичного CSS и восстановлен стабильный базовый стиль формы.

1.7.4

Визуальный конструктор удалён; создание формы возвращено в штатный механизм инфоблоков; «Настройки дизайн» оставлены для оформления.

1.7.0 / 1.6.0

В этих релизах сформирован текущий operational layer: SLA, automation, reports, audit, API, групповые права, расширенный список заявок и аналитика.

Чек-лист после обновления

1. Проверить номер версии в install/version.php.
2. Очистить кеш Битрикс.
3. Сделать hard refresh браузера.
4. Открыть тестовый popup и встроенную форму.
5. Отправить тестовую заявку.
6. Проверить сохранение элемента в инфоблоке.
7. Проверить e-mail и включённые интеграции.
8. Проверить журнал интеграций и retry.
9. При использовании API проверить токен, site_id и IP allowlist.
10. При публикации в Marketplace использовать security-journal именно этой сборки.