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

Ранее мы уже рассматривали механизмы создания лида и создания компании и сделки через API в коробочной версии Битрикс24. В данной статье я опубликую несколько полезных функций, которые позволяют осуществить предварительный поиск компании по номеру телефона или электронной почте в CRM Битрикс24. Все примеры относятся к коробочной версии продукта и не затрагивают REST API.

Суть проблемы, которую мы решаем в данном случае состоит в следующем: приведенные выше решения для создания лидов и сделок не учитывают того, что в CRM уже могут существовать компании с точно такими же контактными данными. В случае с лидами — будет создан новый лид, который пройдет по стадиям воронки и на этапе конвертации его в сделку и компанию может появиться дубликат уже существующей в рамках вашего портала компании. Причина проста: на этапе конвертации лида никаких проверок на дубли не осуществляется, оно и понятно: менеджер некоторое количество времени общался с потенциальным клиентом, не выявил проблем и решил конвертировать лид.

Как избежать появления дубликатов в CRM в данном случае. Разберем теорию вопроса, она максимально проста: на этапе конвертации выполнять проверки на дубликаты — поздно, данные проверки должны выполняться в процессе создания лида (или сделки).

Поиск компании по номеру телефона или e-mail

От теории переходим к практике. С поиском по телефону есть сложности: номер может быть написан в самых различных форматах. Например:

• +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:

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);

Общая логика работы должна быть следующей:

• перед созданием компании выполняем поиск по номеру телефона
• если поиск не дал результатов — выполняем поиск по E-MAIL
• если и он не дал результатов — создаем компанию, либо создаем лид без привязки к компании (в зависимости от вашей задачи)

Пример кода:

//поиск по номеру телефона
$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 содержится идентификатор ответственного за компанию менеджера. Подразумевается, что на этапе создания лида он может быть назначен ответственным.

Отдельное внимание тут стоит уделить небольшой, но крайне полезной фиче: записи комментариев в таймлайн (историю) лида или сделки. Обратите внимание на ключ BINDINGS. Это комментария привязка к сущности CRM: ENTITY_TYPE_ID — тип сущности CRM (1- Лид, 2 — Сделка), ENTITY_ID — идентификатор элемента, к которому будут осуществлена привязка комментария.

Выглядеть такая запись будет следующим образом: