Зависимые поля

Что делает приложение

В карточке CRM (Лид, Сделка, Контакт, Компания, Смарт-процесс) поля сами появляются и скрываются в зависимости от того, что менеджер выбрал в другом поле. Классический пример: при выборе в поле «Причина отказа» определённого значения снизу появляется поле «Комментарий к отказу» — оператору не нужно лишний раз думать «нужно заполнить или нет». Все настройки хранятся на вашем портале Битрикс24.

Два варианта вывода в карточке (можно использовать оба)

1. A. Отдельная вкладка «Зависимые поля». Вверху карточки — вкладка с формой: триггер и зависимые поля. Подходит для цепочек «список → список → список» (вложенные условия), нескольких полей сразу, существующих полей CRM.
2. B. Inline-поле в раскладке карточки. Приложение создаёт новое поле, которое само показывается/скрывается рядом со стандартными полями. Одно правило = одно зависимое поле и один триггер. Не управляет уже существующими списками в левой колонке.

Частая ошибка: настройки в блоке «Настройки зависимостей» не меняют видимость полей в основной форме карточки (слева). Они работают только после добавления вкладки (вариант A) и открытия вкладки «Зависимые поля». Для показа в левой колонке без вкладки — только inline (вариант B), с созданием нового поля приложения.

Вариант A — Отдельная вкладка «Зависимые поля» (цепочки и существующие поля)

Подходит, когда нужно связать несколько уже созданных полей CRM (в том числе списки) или построить цепочку «А → Б → В».

1. Выберите сущность сверху (для смарт-процесса — укажите тип).
2. Нажмите «Добавить настройку зависимых полей» → выберите поле-триггер → «+ Ветка по значению» → для каждого значения отметьте поля для показа. Для 3-го уровня — «+ Вложенное условие» внутри ветки (триггер — поле 2-го уровня).
3. Сохраните настройку.
4. В блоке «Вывод в карточке → A. Отдельная вкладка» нажмите «Добавить зависимые поля в карточку».
5. Откройте карточку → вкладка «Зависимые поля» → измените триггер — ниже появятся нужные поля → «Сохранить».

Вариант B — Inline-поле в карточке (без вкладки)

Сценарий «Причина отказа → Комментарий» (как у клиента):

1. Сверху выберите сущность (например, Лид).
2. Создайте поле-триггер «Причина отказа» (если ещё нет). Кнопка «Создать новое поле в CRM» → тип «Список» → введите варианты с новой строки → «Создать поле». Это обычное поле Битрикс24, его создают один раз.
3. Откройте любую карточку лида и через стандартное «Выбрать поле» в левой панели добавьте «Причина отказа» в раскладку карточки. «Применить ко всем» → Да.
4. Вернитесь в приложение → блок «Вывод в карточке» → раздел «B. Inline-поле прямо в самой карточке» → кнопка «Добавить inline-поле в карточку».
5. В модалке: Название — например, «Комментарий к отказу». Тип ввода — «Многострочный текст» (для длинных комментариев) или «Строка» (для коротких). Поле-триггер — выберите «Причина отказа» из списка (есть поиск). Показывать поле, когда триггер равен одному из: удерживая Ctrl, отметьте те причины отказа, при которых нужен комментарий. Либо включите «При любом непустом значении», если комментарий нужен всегда, как только причина выбрана.
6. Нажмите «Создать inline-поле». Приложение автоматически создаст в выбранной сущности поле с таким названием.
7. Откройте карточку лида → «Выбрать поле» → найдите «Комментарий к отказу» → добавьте в раскладку.
8. Готово. Меняете «Причина отказа» — поле «Комментарий к отказу» само появляется/скрывается; ввод сохраняется автоматически.

Управление inline-правилами — внизу блока «B. Inline-поле…»: список созданных правил, для каждого — кнопка «Удалить» (правило показа). При удалении правила само поле в CRM остаётся — если оно больше не нужно, удалите его в Битрикс24 вручную, чтобы случайно не потерять данные.

Как работает вложенность (цепочка)

Это цепочка, а не два независимых правила. Пример: основное поле (1) — «Тип», при значении «Отказ» показываем поле (2) «Причина отказа». Внутри этой ветки нажимаете «+ Вложенное условие» и выбираете второе поле-триггер — то же поле (2) «Причина отказа»: при значении «Другое» показываем поле (3) «Комментарий». В карточке: выбрали «Тип» = «Отказ» → показалось поле «Причина отказа»; выбрали в нём «Другое» → дополнительно показалось «Комментарий». То есть поле 2 зависит от поля 1, поле 3 зависит от поля 2.

Несколько направлений лидов (Первичный / Повторный) и категории сделок

В Битрикс24 «Лид» — это одна сущность, а «Первичный лид» и «Повторный лид» — это направления (категории) одной и той же сущности «Лид». То же самое для сделок: «Продажа услуг», «Продажа товаров» и т.д. — это категории сделки. Что это значит для приложения:

• Правило создаётся один раз на уровне сущности «Лид» (или «Сделка», «Контакт» и т.д.). Оно работает для всех направлений/категорий этой сущности — отдельных правил под каждое направление делать не нужно.
• Поле тоже создаётся один раз — оно автоматически становится доступным во всех направлениях сущности.
• А вот раскладка карточки (где какое поле стоит) у каждого направления своя. Поэтому после создания правила нужно в карточке каждого направления один раз через «Выбрать поле» добавить нужное поле в нужную секцию. Битрикс может предложить «Применить ко всем» — если согласиться, раскладка скопируется во все карточки этого направления автоматически.

Краткий чек-лист настройки «Причина отказа → Комментарий к отказу» с нуля для двух направлений лидов:

1. В приложении сверху выберите сущность «Лид».
2. Если поля «Причина отказа» ещё нет — нажмите «Создать новое поле в CRM», тип «Список», впишите варианты с новой строки, «Создать поле». Поле появится у всех направлений лидов.
3. Откройте любую карточку Первичного лида → «Выбрать поле» в нужном разделе → найдите «Причина отказа» → добавьте → «Применить ко всем». Повторите то же самое в карточке Повторного лида.
4. Вернитесь в приложение → блок «B. Inline-поле прямо в самой карточке» → «Добавить inline-поле в карточку». Название — «Комментарий к отказу», тип ввода — «Многострочный текст», триггер — «Причина отказа», отметьте те значения, при которых нужно показать комментарий. Создать.
5. Откройте карточку Первичного лида → «Выбрать поле» → найдите «Комментарий к отказу» → добавьте в тот же раздел, где «Причина отказа». «Применить ко всем». Повторите в карточке Повторного лида.
6. Готово. Откройте любой лид, поменяйте «Причина отказа» — поле «Комментарий к отказу» появится в течение ~2 секунд (приложение опрашивает значение триггера). Введите текст и кликните мимо — значение сохранится в БД (поле подсветится зелёным).

Почему inline-поле обновляется не моментально

Это особенность того, как Битрикс24 встраивает кастомные поля. Само поле работает в отдельном маленьком iframe, и Битрикс не передаёт нам события «значение другого поля карточки изменилось». Приложение раз в 1,5–3 секунды само опрашивает текущее значение триггера и при изменении показывает/скрывает зависимое поле. Поэтому небольшая задержка — это нормально. В первую минуту после открытия карточки опрос идёт чаще (1,5 с), потом реже (3 с).

Важное уточнение про режим редактирования карточки. Если оператор поменял значение триггера в дропдауне, но ещё не нажал «Сохранить» внизу карточки — новое значение хранится только в форме на экране, в БД его пока нет. Битрикс не разрешает встроенным полям приложений читать «несохранённые» значения других полей. Поэтому приложение увидит новое значение только после нажатия «Сохранить». На этот случай в плейсхолдере скрытого поля сразу появляется подсказка «Нажмите Сохранить в карточке».

Также в плейсхолдере есть кнопка «↻ Обновить» — если уверены, что значение уже сохранено, но поле не обновилось, кликните её для мгновенной перепроверки.

Polling приостанавливается, если вкладка браузера свёрнута — экономит запросы и батарею. Когда вы вернётесь на вкладку, опрос продолжится с обычной частотой.

Если что-то пошло не так

• Настроил зависимость, но в карточке ничего не меняется — проверьте: открыта ли вкладка «Зависимые поля» (вариант A), нажата ли «Добавить зависимые поля в карточку», выбрана ли та же сущность/смарт-процесс, что в настройке. Правила из «Настройки зависимостей» не скрывают поля в левой колонке основной формы.
• Ошибка «insufficient_scope (401)» — при установке из Маркета переустановите приложение из каталога. Если приложение развёрнуто на своём сервере — в настройках локального приложения нужны права CRM, пользовательских полей и встраивания.
• Inline-поле создалось, но в карточке его нет — нужно один раз добавить через стандартное «Выбрать поле» в карточке (как обычное поле Битрикс24). Если у вас несколько направлений — повторить в каждом.
• Inline-поле всегда показывает «скрыто условием» / «—» — текущее значение триггера не входит в список «Показывать когда». Откройте правило в приложении и проверьте. Можно навести курсор на «скрыто условием» и увидеть в тултипе текущее значение триггера и ожидаемые значения — это поможет быстро понять, почему поле скрыто.
• Поле в карточке вообще не скрывается / показано всегда, без нашего интерфейса (например, видите баннер Битрикса «До конца оплаченного периода…» или поле выглядит как стандартный input без логики) — это значит, что поле в CRM не управляется нашим приложением: оно было создано другим приложением или вручную. Откройте наш интерфейс → блок «B. Inline-поле…» → у соответствующего правила нажмите «Проверить настройку». Если результат «✗» — удалите это поле в Битрикс24, затем здесь удалите правило и создайте заново через «Добавить inline-поле в карточку» — поле будет с правильным типом, и условие сразу заработает.
• Выбрал значение триггера, а поле не появляется — подождите 2-3 секунды (это polling, см. раздел выше). Если не появилось — откройте F12 → Console → фильтр «df-inline» и пришлите вывод, мы посмотрим что не так.
• Во вкладке «Зависимые поля» виден сам интерфейс приложения (а не виджет с триггером) — нажмите «Очистить вкладки» → откройте любую карточку и F5 → в приложении снова «Добавить зависимые поля в карточку».
• В модалке нет поля «Тип ввода» или новых функций — старая версия в кеше браузера. Нажмите Ctrl+F5 в окне приложения.

Связь с порталом (для ИТ/ИБ-службы)

Если ваш Битрикс24 закрыт от внешнего интернета (reverse proxy, allow-list, корпоративный фаервол), системному администратору нужно знать, куда и как обращается приложение. Ниже — общая схема без перечисления конкретных REST-методов.

Куда обращается приложение со стороны нашего сервера (server-to-server, HTTPS, метод POST):

• https://<домен-вашего-портала>/rest/* — единственный путь на стороне портала, к которому обращается приложение. Все вызовы REST API идут только через этот префикс. К путям /bitrix/*, /admin/*, /upload/*, /disk/*, /im/* и прочим внутренним адресам портала приложение не обращается.
• https://oauth.bitrix.info/oauth/token/ — обновление OAuth-токена. Это облачный сервис самого Битрикса, не ваш сервер. На стороне портала ничего разрешать не нужно.

Источник запросов: наш сервер приложения dependent-fields.safekit.tech. Сервер работает в кластере, поэтому исходящий IP-адрес может меняться. Если для allow-list нужен фиксированный IP — напишите в нашу поддержку (контакты ниже), сообщим актуальное значение.

Что НЕ нужно открывать: WebSocket-соединений, длинных коннектов и постоянных пуллов приложение не использует. Все запросы — короткие синхронные HTTPS-вызовы.

Про iframe в браузере оператора: UI приложения встраивается в карточки CRM через стандартный механизм виджетов Битрикс24 — iframe грузится с нашего домена dependent-fields.safekit.tech (не с вашего портала). Сам iframe из браузера оператора тоже обращается к REST API портала, но через стандартный SDK BX24.callMethod() — с того же IP, с которого оператор и так заходит в Битрикс24. Дополнительных правил в reverse proxy для этого случая не требуется.