Лид или смарт-процесс в Битрикс24: куда записывать обращение и как спланировать проверку

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

Сначала определите жизненный цикл обращения, затем выберите лид или смарт-процесс. После этого согласуйте поля, маршрутизацию, обработку повторов и способ проверки записи на конкретном портале. Это даст требования, с которыми можно обсуждать разработку интеграции.

Когда выбор сущности становится рабочей проблемой

Выбор нужен до разработки, если обращения приходят с сайта, почты или бота, а сотрудники работают с ними в Битрикс24. Ошибка в маршруте проявляется по-разному:

• карточка не попадает в рабочую очередь отдела;
• обращение оказывается в процессе с неподходящими стадиями;
• контакт или текст сообщения не сохраняется;
• ответственный не соответствует правилу отдела;
• повторная доставка создаёт ещё одну карточку;
• интеграция сообщает об успехе, хотя часть значений не записана.

Задача не в том, чтобы найти универсально лучшую сущность. Нужно выбрать объект, который соответствует принятому в компании способу учёта. Результатом такого выбора становится не название метода API, а согласованное назначение карточки и требования к её созданию.

Как выбирать между лидом и смарт-процессом

Ниже — проектная матрица, а не официальное правило Битрикс24. Сравните назначение карточки, участников, состояния, итог обработки и место обращения в действующем процессе.

Лид подходит как кандидат, если компания уже ведёт первичные обращения через лиды. Смарт-процесс стоит рассмотреть, если обращение представляет отдельный объект: например, запрос определённого типа со своими состояниями и ответственными.

Официальная REST-документация Битрикс24 указывает, что идентификатор настроенного смарт-процесса для универсального метода можно узнать через crm.type.list. Это не доказывает, что нужный смарт-процесс уже создан или доступен технической учётной записи. Наличие объекта, его настройки и права нужно проверять на портале заказчика.

Какие данные согласовать до интеграции

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

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

Как задать маршрутизацию и ответственного

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

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

Как связать исходное событие с карточкой

У каждого обращения должен быть устойчивый идентификатор источника. Он связывает исходное событие, журнал интеграции и карточку CRM либо отдельную таблицу соответствий. Формат и место хранения определяют в проекте.

Сам идентификатор не означает, что Битрикс24 автоматически предотвратит дубль. Интеграции нужно собственное правило повторной доставки:

1. Получить идентификатор события.
2. Проверить, обрабатывалось ли оно раньше.
3. Найти связанную карточку подтверждённым способом.
4. Обновить её, пропустить повтор или передать ситуацию сотруднику.

Если после запроса результат неизвестен, не отправляйте то же событие повторно вслепую. Сначала установите, появилась ли карточка: иначе повтор может создать второй элемент.

Подробнее о проектировании повторов — в материале как предотвратить дубли при обработке событий.

Условный пример маршрута WEB-4821

Это синтетический учебный пример требований, а не клиентский кейс, выполненный тест или доказательство готовой интеграции Switch On AI.

С сайта поступило обращение:

У матрицы есть две возможные ветви.

Ветка с лидом. Если компания использует лиды как очередь первичных обращений, WEB-4821 направляют в лид. Для этой ветви отдельно устанавливают коды полей, начальную стадию, ответственного и место хранения идентификатора события.

Ветка со смарт-процессом. Если такое обращение относится к отдельному предмету учёта со своими состояниями и ответственными, рассматривают заранее настроенный смарт-процесс. До разработки проверяют его идентификатор, доступные поля, стадии и права технической учётной записи.

Ожидаемый рабочий результат одинаков по смыслу: сотрудник находит одну карточку выбранного типа, видит исходные данные, назначенного ответственного и связь с WEB-4821. Это ожидание будущего испытания, а не утверждение о полученном результате.

При повторной доставке WEB-4821 система сначала ищет ранее обработанное событие. Далее она выполняет заранее согласованное действие: обновляет найденную карточку, пропускает повтор или передаёт ситуацию сотруднику. Автоматическая защита Битрикс24 от такого повтора здесь не предполагается.

Как подготовить план проверки созданной карточки

Разделите три разных подтверждения:

1. Ответ API. Система получила технический результат вызова.
2. Факт создания. Карточка найдена в Битрикс24 подтверждённым для проекта способом.
3. Рабочий результат. Тип сущности, поля, стадия, ответственный и идентификатор исходного события совпали с требованиями.

Предоставленные источники подтверждают назначение crm.item.add, но не используются в этой статье как основание для объявления конкретного формата его успешного ответа или выбранного способа последующего чтения элемента. Эти детали нужно добавить в техническую спецификацию после проверки дополнительной официальной документации либо контролируемого испытания на конкретном портале.

План испытаний должен включать:

В документации Битрикс24 указано, что crm.item.add может проигнорировать некорректное поле в fields. Поэтому успешное выполнение запроса само по себе не подтверждает, что все значения сохранены. Нужна последующая сверка карточки.

Для общего шаблона испытаний используйте критерии приёмки автоматизации.

Ошибки, ограничения и следующий шаг

В будущем испытании возможны три результата:

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

Неподдерживаемое поле нельзя автоматически считать явной ошибкой: универсальный метод может его проигнорировать. При неопределённом результате нельзя считать безопасным и слепой повтор — сначала найдите карточку или подтвердите её отсутствие.

Документация Битрикс24 помечает crm.lead.add как устаревающий метод и рекомендует crm.item.add. Это техническая рекомендация по REST-методу, а не правило выбора бизнес-сущности. Она не определяет, должен ли объект стать лидом или элементом смарт-процесса, и не решает задачу повторов.

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

Для описанного маршрута достаточно обычной интеграции: ИИ-агент или чат-бот не обязателен. Switch On AI разрабатывает и внедряет автоматизацию, включая обмен между рабочими системами. На странице услуг автоматизации можно сравнить форматы решения.

Подготовьте один реальный маршрут: источник, предполагаемую сущность, поля, ответственного и правило обработки повтора. Отправьте описание через страницу контактов Switch On AI — обсудим процесс, проверку возможностей вашего портала и прототип ключевого сценария. Прототип не равен полноценному внедрению; состав работ, стоимость, сопровождение и ограничения согласуются отдельно.