Добавляем лид в CRM Битрикс24 через API

Важное обновление

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

Введение

У Битрикс24 есть API, который позволяет делать определенные полезные штуки. Одна из них – отправка лида в CRM. Т.е. мы можем запрограммировать отправку данных из любой формы своего сайта в свой Битрикс24. Супер! Разберемся, как это сделать.

Создание вебхука

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

Открылась форма добавления вебхука. В поле Название вводим произвольное название, например Получение лидов с сайта. Поле Описание заполняем по своему желанию. В списке Права доступа отмечаем чекбокс CRM:

Вводим название и выбираем права доступа

Больше ничего отмечать не нужно, нажимаем кнопку Сохранить (находится под списком прав доступа):

Перед нами открывается страница с кодом вебхука:

Сохраните этот код, он понадобится нам далее. Код никому не показывайте, это конфиденциальная информация.

Пример 1: передаем имя и телефон

В целях экономии вашего времени, во всех примерах я приведу только код отправки данных в CRM. Как привязать его к своей форме — вы точно знаете.

Начнем с самого простого примера: передадим в CRM имя и номер телефона:

<?php
	$b24Url = "https://alfavitkademo.bitrix24.ru";	// укажите URL своего Битрикс24
	$b24UserID = "1";						// ID пользователя, от имени которого будем добавлять лид
	$b24WebHook = "pov9pr28k5i2v2vc";		// код вебхука, который мы только что получили
	
	// формируем URL, на который будем отправлять запрос
	$queryURL = "$b24Url/rest/$b24UserID/$b24WebHook/crm.lead.add.json";	
	
	// формируем параметры для создания лида	
	$queryData = http_build_query(array(
		"fields" => array(
			"TITLE" => "Лид с нашего сайта",	// название лида
			"NAME" => "Меган Фокс",				// имя ;)
			"PHONE" => array(	// телефон в Битрикс24 = массив, поэтому даже если передаем 1 номер, то передаем его в таком формате
				"n0" => array(
					"VALUE" =>  "+7 (123) 456-78-99",	// ненастоящий номер Меган Фокс
					"VALUE_TYPE" => "MOBILE",			// тип номера = мобильный
				),
			),
		),
		'params' => array("REGISTER_SONET_EVENT" => "Y")	// Y = произвести регистрацию события добавления лида в живой ленте. Дополнительно будет отправлено уведомление ответственному за лид.	
	));

	// отправляем запрос в Б24 и обрабатываем ответ
	$curl = curl_init();
	curl_setopt_array($curl, array(
		CURLOPT_SSL_VERIFYPEER => 0,
		CURLOPT_POST => 1,
		CURLOPT_HEADER => 0,
		CURLOPT_RETURNTRANSFER => 1,
		CURLOPT_URL => $queryURL,
		CURLOPT_POSTFIELDS => $queryData,
	));
	$result = curl_exec($curl);
	curl_close($curl);
	$result = json_decode($result,1); 
 
	// если произошла какая-то ошибка - выведем её
	if(array_key_exists('error', $result))
	{      
		die("Ошибка при сохранении лида: ".$result['error_description']);
	}
	
	echo "Лид добавлен, отличная работа :)";
?>

Комментарии добавил прямо в код, думаю вопросов быть не должно. Если запустим этот код — в Битрикс24 появится уведомление о создании нового лида:

В CRM зайдем в лид и увидим всю информацию, которую мы передали:

Супер! В примере мы заполнили только Название лида, Имя и Номер телефона. Но в CRM Б24 доступно намного больше полей. Их список можно посмотреть в документации по ссылке: https://dev.1c-bitrix.ru/rest_help/crm/leads/crm_lead_fields.php — обязательно ознакомьтесь с этой табличкой.

Пример 2: передаем пользовательские свойства

Немного дополним наш пример, передадим значения двух пользовательских полей. Предположим, что в CRM у нас есть поле Ждет звонка типа Да/Нет (содержит информацию о том, нужно ли перезвонить этому клиенту). И поле Дополнительное сообщение типа Строка, в котором мы передаем сообщение, оставленное пользователем:

Нам нужно получить коды этих свойств. Узнать их можно через просмотр кода элемента. Вот код нашего первого свойства:

А вот код второго:

Узнаем код второго пользовательского поля

Добавим их в наш код и получим следующее:

<?php
	$b24Url = "https://alfavitkademo.bitrix24.ru";	// укажите URL своего Битрикс24
	$b24UserID = "1";						// ID пользователя, от имени которого будем добавлять лид
	$b24WebHook = "pov9pr28k5i2v2vc";		// код вебхука, который мы только что получили
	
	// формируем URL, на который будем отправлять запрос
	$queryURL = "$b24Url/rest/$b24UserID/$b24WebHook/crm.lead.add.json";	
	
	// формируем параметры для создания лида	
	$queryData = http_build_query(array(
		"fields" => array(
			"TITLE" => "Лид с нашего сайта",	// название лида
			"NAME" => "Меган Фокс",				// имя ;)
			"PHONE" => array(	// телефон в Битрикс24 = массив, поэтому даже если передаем 1 номер, то передаем его в таком формате
				"n0" => array(
					"VALUE" =>  "+7 (123) 456-78-99",	// ненастоящий номер Меган Фокс
					"VALUE_TYPE" => "MOBILE",			// тип номера = мобильный
				),
			),
			"UF_CRM_1575410143732" => true,	// первое пользовательское свойство: передадим "Да"
			"UF_CRM_1575410440471" => "Перезвони :*",	// второе пользовательское свойство, передаем этот текст
		),
		'params' => array("REGISTER_SONET_EVENT" => "Y")	// Y = произвести регистрацию события добавления лида в живой ленте. Дополнительно будет отправлено уведомление ответственному за лид.	
	));

	// отправляем запрос в Б24 и обрабатываем ответ
	$curl = curl_init();
	curl_setopt_array($curl, array(
		CURLOPT_SSL_VERIFYPEER => 0,
		CURLOPT_POST => 1,
		CURLOPT_HEADER => 0,
		CURLOPT_RETURNTRANSFER => 1,
		CURLOPT_URL => $queryURL,
		CURLOPT_POSTFIELDS => $queryData,
	));
	$result = curl_exec($curl);
	curl_close($curl);
	$result = json_decode($result,1); 
 
	// если произошла какая-то ошибка - выведем её
	if(array_key_exists('error', $result))
	{      
		die("Ошибка при сохранении лида: ".$result['error_description']);
	}
	
	echo "Лид добавлен, отличная работа :)";
?>

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

Значения пользовательских свойств сохранены

Пользовательские поля корректно сохранились в Битрикс24.

Пример 3: передаем UTM-метки

Передача UTM-меток ничем не отличается от передачи обычных полей. Но я решил вынести этот пример в отдельный блок, т.к. в свое время сам не знал о существовании специальных полей для UTM-меток в CRM Битрикс24. А они есть, это следующие поля:

UTM_SOURCE
UTM_MEDIUM
UTM_CAMPAIGN

Дополним наш код исходя из этой информации: вытянем UTM-метки из урла и отправим их в лид:

<?php
	// получаем текущий урл и упаковываем параметры в массив
	$url = basename($_SERVER['REQUEST_URI']);
	$url_components = parse_url($url); 
	parse_str($url_components['query'], $params); 
	
	$b24Url = "https://alfavitkademo.bitrix24.ru";	// укажите URL своего Битрикс24
	$b24UserID = "1";						// ID пользователя, от имени которого будем добавлять лид
	$b24WebHook = "pov9pr28k5i2v2vc";		// код вебхука, который мы только что получили
	
	// формируем URL, на который будем отправлять запрос
	$queryURL = "$b24Url/rest/$b24UserID/$b24WebHook/crm.lead.add.json";	
	
	// формируем параметры для создания лида	
	$queryData = http_build_query(array(
		"fields" => array(
			"TITLE" => "Лид с нашего сайта",	// название лида
			"NAME" => "Меган Фокс",				// имя ;)
			"PHONE" => array(	// телефон в Битрикс24 = массив, поэтому даже если передаем 1 номер, то передаем его в таком формате
				"n0" => array(
					"VALUE" =>  "+7 (123) 456-78-99",	// ненастоящий номер Меган Фокс
					"VALUE_TYPE" => "MOBILE",			// тип номера = мобильный
				),
			),
			"UF_CRM_1575410143732" => true,	// первое пользовательское свойство: передадим "Да"
			"UF_CRM_1575410440471" => "Перезвони :*",	// второе пользовательское свойство, передаем этот текст
			"UTM_SOURCE"=>$params["utm_source"],
			"UTM_MEDIUM"=>$params["utm_medium"],
			"UTM_CAMPAIGN"=>$params["utm_campaign"],
		),
		'params' => array("REGISTER_SONET_EVENT" => "Y")	// Y = произвести регистрацию события добавления лида в живой ленте. Дополнительно будет отправлено уведомление ответственному за лид.	
	));

	// отправляем запрос в Б24 и обрабатываем ответ
	$curl = curl_init();
	curl_setopt_array($curl, array(
		CURLOPT_SSL_VERIFYPEER => 0,
		CURLOPT_POST => 1,
		CURLOPT_HEADER => 0,
		CURLOPT_RETURNTRANSFER => 1,
		CURLOPT_URL => $queryURL,
		CURLOPT_POSTFIELDS => $queryData,
	));
	$result = curl_exec($curl);
	curl_close($curl);
	$result = json_decode($result,1); 
 
	// если произошла какая-то ошибка - выведем её
	if(array_key_exists('error', $result))
	{      
		die("Ошибка при сохранении лида: ".$result['error_description']);
	}
	
	echo "Лид добавлен, отличная работа :)";
?>

Отправим лид со страницы со следующим набором значений в урле:

?utm_medium=cpc&utm_source=Yandex&utm_campaign=AlfavitkaDemo

В итоге получим этот набор UTM-меток в соответствующих полях лида:

Пример сообщения об ошибке

У нас в коде есть блок, который отвечает за вывод ошибок, вот он:

// если произошла какая-то ошибка - выведем её
if(array_key_exists('error', $result))
{      
	die("Ошибка при сохранении лида: ".$result['error_description']);
}

Давайте попробуем получить какую-нибудь ошибку. Например, укажем несуществующего пользователя в переменной $b24UserID:

$b24UserID = 999; // пользователя с таким ID не существует

Запустив код с неправильным ID пользователя, мы получим следующее сообщение:

Ошибка при сохранении лида: Invalid request credentials

А в ячейке $result[‘error’] будет храниться код ошибки, в данном случае INVALID_CREDENTIALS.

Возможно, это поможет кому-то при дебаге.

Блог Саши Синявского

Создаем лид в Битрикс24 через API