Документация — Контроль дублей

Адрес вебхука

Каждый созданный в интерфейсе вебхук получает собственный адрес вида:

POST https://<домен>/hook/<token>

Метод GET запрещён. При обращении по GET сервер отвечает HTTP 403 и телом:

{"error":"Доступ к GET запросам запрещен, используйте POST запросы или обратитесь к документации"}

Формат входящих данных

Тело запроса — JSON, заголовок Content-Type: application/json.

{
  "name": "Иванов Иван Иванович",
  "phone": "+7 900 123-45-67",
  "record_url": "https://example.com/records/12345.mp3",
  "source": "UC_0D79KG",
  "stage": "Уфа",
  "comment": "Клиент просил перезвонить после 18:00",
  "assigned_by_id": 1,
  "client_id": "CID-00001",
  "ym_counter_id": "YM-00000001"
}

Поля

Поле	Обязательное	Описание
name	да	ФИО клиента. Разбивается на фамилию, имя и отчество при создании контакта.
phone	да	Номер телефона в любом формате, приводится к виду 7XXXXXXXXXX.
record_url	нет	Ссылка на запись разговора.
source	нет	Код источника Битрикс24, а не название: `UC_0D79KG`, `CALL`, `WEB` и т.п. Записывается в поле сделки, выбранное в настройке вебхука («ИСТОЧНИК», по умолчанию системное `SOURCE_ID`). Список кодов портала есть в тестовом запросе (`_source_options`).
stage	нет	Стадия из заявки. По ней подбирается стадия «Новый лид …» согласно настройкам вебхука.
comment	нет	Комментарий из заявки. Записывается в поле сделки, выбранное в настройке вебхука («КОММЕНТАРИЙ», по умолчанию системное `COMMENTS`), вместе с отметкой о дубле или повторном обращении.
assigned_by_id	нет	ID ответственного на портале. Если не передан — берётся значение из настроек вебхука.
client_id	нет	Произвольный идентификатор клиента. Записывается в поле сделки, выбранное в настройке вебхука («CLIENT_ID»), если оно указано.
ym_counter_id	нет	Номер счётчика Яндекс.Метрики. Записывается в поле сделки, выбранное в настройке вебхука («Счётчик Яндекс.Метрики»), если оно указано.

Допускаются альтернативные названия полей: full_name, fio, ФИО, телефон, источник, стадия, комментарий, responsible_id, yandex_metrica, metrika_id и т.п.

Ответы сервера

202 Accepted — {"status":"accepted","request_id":"123"}: заявка принята и поставлена в очередь.
403 Forbidden — обращение методом GET.
404 Not Found — вебхук с таким токеном не существует.
409 Conflict — вебхук отключён в интерфейсе.
422 Unprocessable Entity — не хватает обязательных полей или номер некорректен.

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

Логика обработки

Номер телефона нормализуется и проверяется по таблицам лидов всех порталов.
Если лид найден — берётся последнее вхождение по номеру, и на портале, где оно найдено, запрашивается текущая стадия сделки:
- стадия не провальная → на портале вебхука создаётся контакт + сделка в стадии «Дубль», в комментарии указывается дата предыдущего обращения;
- стадия провальная (Неликвид, Недозвон и др.) → создаётся контакт + сделка в стадии нового лида, в комментарии указывается, что лид в работе повторно.
В обоих случаях счётчик дублей вебхука увеличивается на 1.
Если сделка по этому вхождению удалена на портале (Битрикс отвечает «Not found») — проверяется предыдущее вхождение по тому же номеру, и так далее. Записи с удалёнными сделками помечаются в базе и в дальнейшем не проверяются. Если удалены сделки по всем вхождениям — заявка проводится как новый лид.
Если лид не найден — создаётся контакт + сделка в стадии нового лида (стадия подбирается по полю stage, затем по source, иначе берётся стадия по умолчанию).

Провальной считается стадия, помеченная в Битрикс24 как проигрышная (SEMANTICS = F), либо отмеченная вручную в настройках вебхука.

Поля сделки (системные и пользовательские) и справочник источников подтягиваются с портала при синхронизации. В настройке вебхука выбирается, в какое поле сделки писать код источника и в какое — комментарий.

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

Если у портала в настройках включена «Замкнутый контур контроля дублей», лиды, приходящие на этот портал, проверяются на дубли не по всем порталам, а только среди сделок этого же портала — другие порталы при этом игнорируются. Если такой же номер уже есть на другом портале, сделка на этом портале всё равно создаётся как новая (без пометки «Дубль»/«Повтор»), но в общей аналитике лид всё равно считается дублем. Остальные порталы (без этой настройки) по-прежнему ищут дубли по всем порталам, включая те, где замкнутый контур включён.

CRM-формы

Для каждого вебхука можно создать одну или несколько CRM-форм — публичных страниц вида /form/<token>, куда часть полей скрыта и подставляется значением по умолчанию. Заполненная и отправленная форма проходит ровно ту же обработку, что и обычный POST-запрос на вебхук (дубли, очередь, создание сделки в Битрикс24).

Формат CSV для загрузки текущих лидов

deal_id;contact_id;phone;name;source;created_at
1024;2048;+79001234567;Иванов Иван;Авито;01.02.2026 12:30
1025;;79007654321;Петров Пётр;Сайт;2026-02-03T09:15:00+03:00

Разделитель определяется автоматически (,, ; или табуляция). Строки с некорректным телефоном пропускаются, повторная загрузка той же сделки не создаёт дубль записи.