Битрикс24: как найти компанию по номеру телефона или e-mail через API

Зачем искать компанию перед созданием лида или сделки

При автоматическом создании лидов и сделок через API в коробочной версии Битрикс24 легко получить дубликаты компаний в CRM. Проблема возникает, когда обращение приходит от клиента, чьи контактные данные — телефон или e-mail — уже есть в системе, но скрипт создания лида этого не проверяет.

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

Ниже — рабочее решение на PHP для коробочной версии Битрикс24 (не REST API), которое ищет компанию по телефону, а если не находит — по электронной почте.

Сложность поиска по номеру телефона

Главная трудность в том, что один и тот же номер телефона в CRM может храниться в разных форматах:

• +7 123 456 7890

• 8 123 456 7890

• 123 456 7890

• 8 (123) 45-67-890

Чтобы поиск сработал независимо от формата ввода, номер нужно предварительно нормализовать: убрать все символы, кроме цифр, и оставить последние 10 знаков (актуально для российской нумерации).

Функция нормализации телефона

function translate_phone($phone){
    $result = preg_replace('/[^0-9,.]/', '', $phone);
    if(strlen($result) > 10){
        $result = substr($result, (strlen($result) - 10));
    }
    return $result;
}

Пример использования:

$phone_number = translate_phone("+7 123 456 7890");
// результат: 1234567890

Учтите: метод рассчитан на российские номера и не подойдёт без модификации для международных форматов с переменной длиной.

Функция поиска компании по телефону или e-mail

Поиск реализован через метод CCrmCompany::GetListEx с фильтром по полю FM (реквизиты компании). Для телефона используется поиск по частичному совпадению (%VALUE), для почты — точное совпадение (=%VALUE).

function company($type, $value){

    $searchCondition = '=%VALUE';

    if($type == 'PHONE')
    {
        $searchCondition = '%VALUE';
    }

    $arFilter = array(
        'FM' => array(
            array(
                'TYPE_ID' => $type,
                $searchCondition => $value
            )
        ),
        'CHECK_PERMISSIONS' => 'N'
    );
    $obCompany = \CCrmCompany::GetListEx(
        array('ID' => 'ASC'),
        $arFilter,
        false,
        false,
        array('*')
    );
    $arResult = [];
    while($arCompany = $obCompany->Fetch()){
        $arResult[] = $arCompany;
    }
    return $arResult;
}

Вызов функции:

// поиск по номеру телефона
$result = company("PHONE", $phone_number);

// поиск по электронной почте
$result = company("EMAIL", $mail);

Логика проверки перед созданием лида

Правильный порядок действий такой:

1. Сначала ищем компанию по номеру телефона.
2. Если по телефону ничего не найдено — ищем по e-mail.
3. Если результата нет и по почте — создаём новую компанию (или лид без привязки, в зависимости от бизнес-логики проекта).

// поиск по номеру телефона
$search = company("PHONE", translate_phone($_REQUEST['phone']));
$company_id = $search[0]['ID'];
if (!empty($company_id)) {
    $comments = "Компания была найдена по номеру телефона";
    $manager_id = $search[0]['ASSIGNED_BY_ID'];
}

// поиск по e-mail
if (empty($company_id)) {
    $search = company("EMAIL", $_REQUEST['email']);
    $company_id = $search[0]['ID'];
    if (!empty($company_id)) {
        $comments = "Компания была найдена по E-MAIL";
        $manager_id = $search[0]['ASSIGNED_BY_ID'];
    }
}

/* далее запускаем создание компании и лида */

// запись найденного совпадения в таймлайн лида
if ($comments) {
    \Bitrix\Crm\Timeline\CommentEntry::create(
        array(
            'TEXT' => $comments,
            'SETTINGS' => array('HAS_FILES' => 'N'),
            'AUTHOR_ID' => 1, // ID пользователя, от имени которого добавляется комментарий
            'BINDINGS' => array(array('ENTITY_TYPE_ID' => 1, 'ENTITY_ID' => $LEAD_ID))
        ));
}

Переменная $manager_id хранит идентификатор ответственного менеджера найденной компании — его можно автоматически назначить ответственным и за новый лид, чтобы клиент вёлся у того же сотрудника.

Полезная деталь: привязка комментария к таймлайну

Отдельно стоит обратить внимание на класс \Bitrix\Crm\Timeline\CommentEntry — он позволяет программно добавлять запись в историю (таймлайн) лида или сделки. Ключевой параметр здесь — BINDINGS:

• ENTITY_TYPE_ID — тип сущности CRM (1 — лид, 2 — сделка);

• ENTITY_ID — идентификатор конкретного элемента, к которому привязывается комментарий.

Такая запись в таймлайне полезна для менеджера: он сразу видит в истории лида, что система нашла совпадение по контактным данным, и по какому именно признаку — телефону или почте.

Ограничения метода и альтернатива

Поиск через CCrmCompany::GetListEx с фильтром по маске работает надёжно, но на больших объёмах данных может быть ресурсозатратным. В качестве альтернативы в REST API существует метод crm.duplicate.findbycomm, который ищет дубли без предварительной нормализации номера. У него, впрочем, своя особенность: на больших выборках он показывает не всегда предсказуемые результаты, поэтому перед внедрением в продакшен стоит протестировать оба варианта на реальных данных вашего портала.

Часто задаваемые вопросы

Подходит ли решение для REST API Битрикс24?
Нет, приведённый код рассчитан на коробочную версию и использует внутренние классы CCrmCompany и \Bitrix\Crm\Timeline\CommentEntry. Для облачной версии или работы через REST потребуется метод crm.duplicate.findbycomm или аналогичные REST-обёртки.

Что делать с номерами не из России?
Функцию translate_phone нужно адаптировать: убрать жёсткое ограничение в 10 цифр и учитывать код страны отдельно, иначе для международных номеров результат поиска будет некорректным.

Можно ли искать сразу и по телефону, и по e-mail одним запросом?
Технически можно объединить условия в одном фильтре FM, но раздельный поиск (сначала телефон, затем почта) даёт более предсказуемый и управляемый результат, особенно когда нужно понимать, по какому признаку найдено совпадение.