REST: crm.contact и дедупликация

Дубли контактов — главная боль любой CRM-интеграции: одна и та же заявка приходит с сайта, из мессенджера и по телефону, и без контроля в базе появляются три карточки одного клиента. REST-методы crm.contact.* и crm.duplicate.findbycomm позволяют проверить наличие клиента ещё до создания записи.

Модель данных контакта

Контакт (crm.contact) описывает физлицо. Ключевая особенность модели — множественные коммуникационные поля: телефон, e-mail, мессенджеры и веб-адреса хранятся массивами, где у каждого значения есть тип.

POST /rest/1/xxxxxxxx/crm.contact.add.json
{
  "fields": {
    "NAME": "Иван",
    "LAST_NAME": "Петров",
    "PHONE": [ { "VALUE": "+79001234567", "VALUE_TYPE": "WORK" } ],
    "EMAIL": [ { "VALUE": "ivan@example.com", "VALUE_TYPE": "WORK" } ]
  },
  "params": { "REGISTER_SONET_EVENT": "Y" }
}

Полный список полей и допустимых типов значений вернёт crm.contact.fields. Обратите внимание: попытка передать телефон строкой, а не массивом объектов, приведёт к его потере.

Поиск дублей: crm.duplicate.findbycomm

Штатный способ найти существующий контакт по телефону или почте — метод crm.duplicate.findbycomm. Он ищет по нормализованным коммуникациям и возвращает идентификаторы совпадений.

POST /rest/1/xxxxxxxx/crm.duplicate.findbycomm.json
{
  "type": "PHONE",
  "values": [ "+79001234567" ],
  "entity_type": "CONTACT"
}

Ответ выглядит так:

{ "result": { "CONTACT": [ 145, 302 ] } }

Сценарий upsert без дублей

Правильный порядок действий при приёме заявки — «проверить, потом создать или обновить». Псевдологика интеграции:

1. Нормализовать входящие телефон и e-mail;
2. Вызвать crm.duplicate.findbycomm по телефону, затем по e-mail;
3. Если найдены ID — взять первый и обновить контакт через crm.contact.update;
4. Если совпадений нет — создать контакт через crm.contact.add;
5. Привязать контакт к сделке через crm.deal.contact.add.

Такой upsert исключает гонку данных, когда одна заявка успевает создать карточку, а вторая — её дубликат. Для нагрузочных сценариев оборачивайте цепочку в batch, но помните: findbycomm внутри батча выполняется на состоянии до текущих операций, поэтому проверку дубля лучше делать отдельным вызовом.

Встроенный контроль дублей

Помимо ручного поиска, у Битрикс24 есть встроенный механизм контроля дублей. При создании через add можно управлять его поведением параметром params:

• "params": { "DUPLICATE_CONTROL": { "ENABLE": "Y" } } — включить проверку на стороне сервера;
• если совпадение найдено, запрос вернёт ошибку с кодом, а не создаст запись.

Для массового слияния уже накопленных дублей используются интерфейсные инструменты «Обработка дубликатов», а из REST доступны низкоуровневые методы работы со списком коммуникаций. На практике для интеграций надёжнее полагаться на явный findbycomm перед записью — так вы контролируете логику выбора «главной» карточки.

Выборка и фильтрация контактов

Метод crm.contact.list поддерживает фильтры, сортировку и постраничность шагом 50 записей. Фильтрация по телефону выполняется по служебному полю PHONE с оператором вхождения:

POST /rest/1/xxxxxxxx/crm.contact.list.json
{
  "filter": { "%PHONE": "9001234567" },
  "select": ["ID", "NAME", "LAST_NAME", "PHONE", "EMAIL"],
  "order": { "DATE_CREATE": "DESC" }
}

Для перебора всей базы используйте параметр start; при больших объёмах эффективнее «быстрый» обход с "start": -1 и фильтром по возрастанию ID.

Частые ошибки и как их избежать

Отдельно стоит следить за правами: методам дедупликации нужен доступ к области crm. Без него вебхук вернёт ошибку доступа ещё до выполнения поиска.

Ещё один тонкий момент — множественность коммуникаций при обновлении. Если вы передаёте в crm.contact.update поле PHONE целиком, старый набор номеров будет заменён на новый. Чтобы добавить телефон, не потеряв существующие, сначала прочитайте текущие значения через crm.contact.get, дополните массив и отправьте обратно полный список. У каждого элемента при этом сохраняется технический ID значения — передавая его, вы редактируете конкретный номер, а не создаёте дубль внутри карточки. Игнорирование этой механики — вторая по частоте причина «раздувания» контактов после ошибки с форматом номера.

Итог

Чистая база контактов начинается с дисциплины на входе. Множественные поля телефона и e-mail нужно передавать массивами, а перед каждым созданием карточки — прогонять значения через crm.duplicate.findbycomm, который сам нормализует номера и находит совпадения по контактам, компаниям и лидам. Схема upsert «проверил — обновил или создал» надёжнее любой постфактум-обработки дублей.

Мы выстраиваем такую логику в интеграциях сайта и Битрикс24: заявки с форм попадают в CRM без задвоений, а контакты корректно связываются со сделками. Если нужен отлаженный поток заявок без ручной чистки дублей — поможем спроектировать и внедрить обмен.