Лид (crm.lead) — первичная точка входа в CRM Битрикс24: сюда попадают необработанные заявки с сайта, из форм и телефонии. Семейство REST-методов crm.lead.* позволяет полностью управлять этой сущностью из внешних систем — от создания до конвертации в сделку и контакт.
Состав методов crm.lead
Все операции над лидами выполняются одноимённым семейством методов. Они однотипны и повторяют логику остальных CRM-сущностей, поэтому, освоив crm.lead, вы легко перейдёте к сделкам и контактам.
| Метод | Назначение |
|---|---|
crm.lead.add | Создать лид |
crm.lead.get | Получить лид по ID |
crm.lead.list | Выборка с фильтром и сортировкой |
crm.lead.update | Изменить поля лида |
crm.lead.delete | Удалить лид |
crm.lead.fields | Описание всех полей, включая пользовательские |
Перед разработкой интеграции всегда вызывайте crm.lead.fields — он возвращает актуальный состав полей конкретного портала вместе с типами и признаками isRequired, isMultiple, isReadOnly.
Вебхук и формат запроса
Простейший способ авторизации для серверных интеграций — входящий вебхук. URL метода строится по схеме портал + токен + имя метода + формат ответа:
https://your-portal.bitrix24.ru/rest/1/xxxxxxxxxxxxxx/crm.lead.add.json
Параметры передаются в теле POST-запроса. Ответ приходит в JSON с ключами result, time, а при ошибке — error и error_description.
crm. Без него все вызовы crm.lead.* вернут ошибку insufficient scope..json— ответ в JSON (рекомендуется);.xml— ответ в XML;- без суффикса — сериализованный формат Bitrix.
Создание лида: crm.lead.add
Метод принимает объект fields с данными лида и необязательный params. В ответе возвращается числовой ID нового лида.
Пример тела запроса (JSON):
{ "fields": { "TITLE": "Заявка с сайта", "NAME": "Иван", "LAST_NAME": "Петров", "STATUS_ID": "NEW", "SOURCE_ID": "WEB", "OPPORTUNITY": 45000, "CURRENCY_ID": "RUB", "ASSIGNED_BY_ID": 1, "PHONE": [ { "VALUE": "+79001234567", "VALUE_TYPE": "WORK" } ] }, "params": { "REGISTER_SONET_EVENT": "Y" } }
Ключевые поля лида:
TITLE— название лида (обязательное);STATUS_ID— стадия обработки (справочник STATUS);SOURCE_ID— источник (справочник SOURCE);OPPORTUNITYиCURRENCY_ID— сумма и валюта;ASSIGNED_BY_ID— ответственный менеджер.
REGISTER_SONET_EVENT: "Y" публикует событие в живой ленте, но не защищает от дублей. Контроль дублей на входе из внешней системы реализуйте отдельно через crm.duplicate.findbycomm.Выборка: filter, select, order, start
Метод crm.lead.list отдаёт данные постранично — по 50 записей за вызов. Управление выборкой через четыре параметра:
select— список нужных полей; чтобы получить пользовательские, добавьтеUF_*или*;filter— условия отбора с префиксами операторов;order— сортировка (ASC/DESC);start— смещение страницы (0, 50, 100...).
Префиксы фильтра работают так же, как во всех CRM-методах:
| Префикс | Смысл |
|---|---|
>=, <= | больше/меньше или равно |
% | поиск подстроки (LIKE) |
! | не равно |
@ | вхождение в массив (IN) |
Пример: { "filter": { "STATUS_ID": "NEW", ">=DATE_CREATE": "2026-07-01T00:00:00" }, "select": ["ID","TITLE","OPPORTUNITY"], "order": { "DATE_CREATE": "DESC" }, "start": 0 }
start: -1 и листайте по значению ID — так вы избежите деградации на десятках тысяч лидов.Множественные поля: телефон и e-mail
Контактные данные лида — это множественные поля (multifield). Они хранятся массивом объектов, а не строкой, поэтому передавать в них простую строку нельзя.
Структура одного значения: { "VALUE": "info@example.ru", "VALUE_TYPE": "WORK" }. Допустимые типы: WORK, HOME, MOBILE, FAX, OTHER.
crm.lead.update его ID: PHONE: [{ "ID": 122, "VALUE": "+79990000000" }]. Чтобы удалить значение — передайте объект с VALUE пустой строкой и его ID.К множественным относятся PHONE, EMAIL, WEB, IM (мессенджеры). Признак множественности у поля виден в crm.lead.fields как isMultiple: true.
Статусы и конвертация лида
Стадии лида — это справочник STATUS. Получить его список: crm.status.list с фильтром { "filter": { "ENTITY_ID": "STATUS" } }. Финальные статусы CONVERTED (сконвертирован) и JUNK (некачественный) имеют особую семантику.
Конвертация лида в сделку/контакт/компанию через REST выполняется не отдельным «магическим» вызовом, а сценарием: вы читаете данные лида, создаёте на их основе контакт (crm.contact.add) и сделку (crm.deal.add), связываете их и переводите лид в статус CONVERTED через crm.lead.update.
- Прочитать лид:
crm.lead.get. - Создать контакт и/или компанию.
- Создать сделку с привязкой
CONTACT_ID/COMPANY_IDиLEAD_ID. - Перевести лид в статус
CONVERTED.
Итог
Семейство crm.lead.* закрывает весь жизненный цикл лида: приём заявки, обработку, выборку и конвертацию. Ключевые нюансы — множественные поля контактов, постраничная выборка и осознанная работа со статусами и дублями. Аккуратная интеграция экономит менеджерам часы ручного ввода и не плодит мусорные записи.
Мы в B2Bsite проектируем и разрабатываем такие интеграции под ключ: приём заявок с сайта в CRM, обмен с 1С, контроль дублей и логику конвертации. Если нужна надёжная связка внешней системы с Битрикс24 — поможем спроектировать API-слой и внедрить его без потерь данных.
Частые вопросы
Чем лид отличается от сделки в Битрикс24?
Лид — это необработанный первичный контакт (заявка, звонок), а сделка — уже квалифицированная продажа с суммой и стадиями воронки. Лид после квалификации конвертируется в контакт, компанию и сделку.
Можно ли отключить лиды и работать только со сделками?
Да, это называется простой режим CRM. В нём заявки сразу попадают в сделки, а методы crm.lead становятся неактуальными. Режим переключается в настройках CRM портала.
Как массово загрузить лиды из внешней системы?
Используйте метод batch — он выполняет до 50 команд crm.lead.add за один HTTP-запрос. Для больших объёмов разбивайте загрузку на пачки и следите за лимитами частоты запросов.
Почему телефон не сохраняется при crm.lead.add?
Поле PHONE множественное и требует массив объектов вида [{VALUE, VALUE_TYPE}]. Если передать строку, значение будет отброшено без ошибки.
Как отфильтровать лиды по пользовательскому полю?
Укажите код поля с префиксом UF_CRM_ в filter и обязательно добавьте его в select. Для списочных полей фильтруйте по ID элемента перечисления.
Что вернёт метод при удалении несуществующего лида?
crm.lead.delete вернёт ошибку с кодом и error_description. Перед удалением рекомендуется проверять существование записи через crm.lead.get.
Поможем с настройкой и поддержкой Для разработчиков
Поможем с настройкой, доработкой и поддержкой Для разработчиков.