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

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

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

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": "Авито",
  "stage": "Уфа",
  "assigned_by_id": 1
}

Поля

Поле	Обязательное	Описание
name	да	ФИО клиента. Разбивается на фамилию, имя и отчество при создании контакта.
phone	да	Номер телефона в любом формате, приводится к виду 7XXXXXXXXXX.
record_url	нет	Ссылка на запись разговора.
source	нет	Источник лида.
stage	нет	Стадия из заявки. По ней подбирается стадия «Новый лид …» согласно настройкам вебхука.
assigned_by_id	нет	ID ответственного на портале. Если не передан — берётся значение из настроек вебхука.

Допускаются альтернативные названия полей: full_name, fio, ФИО, телефон, источник, стадия, responsible_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), либо отмеченная вручную в настройках вебхука.

Формат 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

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