Инструкция по эксплуатации

Основные принципы работы продукта

Основой продукта является входящий канал. Входящий канал — это совокупность условий и настроек для получения внешних оповещений с вашего сайта или иного сервиса для дальнейшей обработки и записи в CRM «Битрикс24» в качестве Лида или Сделки. Любой входящий канал, который вы регистрируете в нашем приложении, имеет свой адрес обработчика. На этот адрес вы сможете настроить отправку данных со стороны вашего сайта или иного сервиса посредством методов GET или POST (во втором случае тело запроса может быть как передано в формате полей POST, так и в виде JSON-форматированного текста). Тип данных, передаваемых с вашего сайта, приложение определит автоматически — указывать его где-либо в настройках не потребуется, даже более того — вы можете отправлять запросы к одному и тому же входящему каналу одновременно всеми доступными способами (но, безусловно, не в рамках одного запроса).

Где находится приложение и как его настроить

Размещение в Битрикс24 После осуществления установки приложения, в зону уведомлений «Битрикс24» будет отправлено сообщение об успешном завершении всех процессов, связанных с установкой. После этого, на вашем портале «Битрикс24» появится кнопка «Интеграция с сайтом».
Кнопка располагается в правом верхнем углу страницы, на которую выводится список Лидов или Сделок (независимо от режима — канбан или список), слева от кнопки «Роботы».

Обратите внимание, если помимо нашего приложения на вашем портале установлены другие приложения, размещающие свою кнопку доступа к настройкам на этом же месте, «Битрикс24» будет группировать кнопки и главной среди них будет та, которая появилась раньше всех. Если вы не видите на этом месте кнопку «Интеграция с сайтом», нажмите на стрелочку вниз, расположенную в правой части находящейся на данном месте кнопки — кнопка доступа к настройкам универсальной интеграции с сайтом будет среди других вариантов в выпадающем списке.

Различия облачной и коробочной версий

Данное приложение работает исключительно с REST API вашего портала «Битрикс24», поэтому версия портала (коробочная или облачная) не оказывает никакого влияния на работу приложения.

Стоит заметить, что для доступа к REST API коробочной версии портала он должен быть размещён на публично доступном домене и отвечать на запросы по публично маршрутизируемому IP-адресу.

Таким образом, мы не сможем работать с вашими входящими каналами, если коробочная версия вашего портала работает:

В локальной сети предприятия без доступа в Интернет или с доступом только через приватное частное соединение;
На домене или субдомене, который подлежит резолвингу только внутри вашей сети (например, bitrix24.local или portal.example);
С существенными ограничениями фаервола, которые пресекают возможность соединения с порталом с использованием адресов, не включённых в «белый список» вашего фаервола.

При этом если первые два пункта являются полностью исключающими любую возможность работы со внешними приложениями по REST API, то третий пункт полностью управляется администратором вашей сети. По запросу мы можем предоставить вам список сетей, с которых наше приложение может подключаться к REST API для добавления данных сетей в «белый список» вашего фаервола. Ваша политика безопасности требует более жёстких правил доступа? В таком случае мы можем предложить аренду полностью выделенного IP-адреа, посредством которого приложение будет соединяться с вашим и только с вашим порталом «Битрикс24» (тарифицируется отдельно).

Основные настройки входящих каналов

Наименование канала

Определяет, как входящий канал будет отображаться в ваших настройках интеграции. Не влияет на работу канала и генерируется автоматически, если при создании входящего канала поле осталось не заполненным.

Тип сущности для данного канала

Устанавливает, с какими CRM-сущностями вы желаете работать в рамках данного входящего канала. Если выбраны Сделки, то система будет создавать новые сделки по факту поступивших посредством данного входящего канала запросов и искать существующие сделки, если это предусмотрено настройками (подробности данного режима будут описаны далее).

Механика работы канала

Определяет, нужна ли защита от дублей для Сделок/Лидов, поступающих посредством данного входящего канала. Если включён режим «Всегда создавать новый лид/сделку», система всегда будет создавать новый Лид или Сделку в вашей CRM независимо от наличия у данного контакта других открытых сущностей. При этом, если вы активируете режим «Сперва искать существующий лид/сделку для обновления» и укажете статусы, в которых следует осуществить поиск, система сперва найдёт Контакт, а затем попытается найти другие его сделки в указанных вами статусах. Если открытых сделок в данных стадиях нет — будет создана новая, если сделки найдены — они могут быть либо обновлены информацией из нового запроса, либо данный входящий запрос может быть проигнорирован. Для того, чтобы при обнаружении открытой сделки по входящему запросу статус существующей сделки изменился на предусмотренный настройками — необходимо включить параметр «Изменять статус при обновлении». Если вы также желаете, чтобы поля сделки обновились новыми данными из последнего входящего запроса — потребуется также включить параметр «Обновление дополнительных полей». Если вы также желаете, чтобы обновлялись и дополнительные поля Контакта, включите параметр «Обновление контакта».

При этом заметьте, что найденный контакт независимо от значения параметра «Обновление контакта» будет дополнен новыми контактными данными, если они в нём отсутствуют. К примеру, если Контакт найден по номеру телефона, а во входящем запросе есть ещё и адрес электронной почты, который в Контакте отсутствует — он будет записан в Контакт.

Ответственный за лид/сделку

Устанавливает пользователя, который будет ответственным за создаваемые приложением новые сущности. Желаете распределять входящие обращения с сайта автоматически между менеджерами по каким-либо условиям или графику? Взгляните на другой наш продукт, «Распределение лидов/сделок».

Статус для создания/обновления лида/сделки

Определяет статус Лида или Сделки (зависимо от выбранной в настройках канала сущности), в котором новые сущности будут создаваться, а при включённом параметре «Изменять статус при обновлении» также определяет статус, в который существующая сущность будет перемещена в случае поступления по ней входящего запроса.

Заполнение дополнительных полей

Данный блок определяет самое основное — то, как поля Контакта, Лида или Сделки будут заполняться входящей информацией. В данном блоке вы можете сопоставить поля из тела входящего запроса с полями Контактов, Лидов и Сделок, а также установить для них флаг поиска.

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

Флаг поиска работает также и для Сделок/Лидов, расширяя функциональность механизма защиты от дублей. Аналогично Контакту, для поиска по Лидам или Сделкам следует использовать только поля, имеющие уникальные значения. К примеру, для Сделок адекватным вариантом будет искать в CRM другие Сделки с тем же номером заказа или тем же идентификатором обращения, но совершенно нелогично будет искать сделки с таким же бюджетом.

Добавление комментариев

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

Создание нового дела

Данный параметр позволяет автоматически создавать новое дело на ответственного при создании новой сущности или внесении правок в существующую сущность на основании входящего запроса.

Входящий канал по умолчанию

Позволяет перехватывать запросы с других входящих каналов вашего аккаунта в том случае, если они были удалены из системы. Удобный вариант на случай, если вы уже настроили на своём сайте прежний канал, а затем решили принимать заявки с него посредством другого канала — в таком случае адрес для приёма входящих запросов можно не обновлять на стороне вашего сайта, система автоматически переадресует все запросы на канал, в настройках которого стоит флаг «Входящий канал по умолчанию».

Формирование и обработка входящих запросов

Как уже говорилось выше, приложение «Универсальная интеграция с сайтом» может принимать от вас на указанный в настройках входящего канала адрес обработчика запросы трёх типов: GET, POST с полями и POST с JSON-массивом в теле запроса. Давайте рассмотрим каждый из этих вариантов и посмотрим, как правильно добавить поля из запроса в блок настроек «Заполнение дополнительных полей».

Предположим, что адрес обработчика входящих обращений, который вы получили при создании нового канала, следующий: https://bitrix.example/in/some-incoming-channel, а вы желаете передать на этот входящий канал запрос, содержащий данные некоего нового заказа, а именно номер телефона заказчика, его имя, номер заказа и его сумму:

	[
		'client_phone': 74712773120,
		'client_name': 'Мария',
		'order_id': 6510,
		'order_amount': 3500
	]

1. POST

С отправкой запроса методом POST всё просто: вы просто отправляете собранный массив на предоставленный адрес обработчика без необходимости какой-либо дополнительной обработки.

2. POST c JSON-массивом в теле запроса

Отличие данного способа от первого заключается только в том, что вместе с запросом вам потребуется передать заголовок Content-Type: application/json, а тело запроса закодировать в JSON. Если вы формируете запрос на PHP, с этим отлично справится функция json_encode.

	{
		'client_phone': 74712773120,
		'client_name': 'Мария',
		'order_id': 6510,
		'order_amount': 3500
	}

3. GET

Отправка данных методом GET является наименее желательной в виду того, что метод GET предназначен для передачи небольшого объёма данных в качестве параметров. Для приведённого выше примера данный метод подходит, однако если вам потребуется передать существенно больший объём данных — GET не будет лучшим вариантом.
Заметьте также, что данные, передаваемые методом GET и включающие при этом в себя какие-либо иные символы, кроме цифр и букв латинского алфавита, нуждаются в URL-кодировании для корректной передачи.

	https://bitrix.example/in/some-incoming-channel?client_phone=74712773120&client_name=%D0%9C%D0%B0%D1%80%D0%B8%D1%8F&order_id=6510&order_amount=3500

Как видите, в данном примере Мария превратилась в последовательность знаков %D0%9C%D0%B0%D1%80%D0%B8%D1%8F, что обеспечит корректную передачу имени независимо от используемых во время передачи кодировок.

Обработка дополнительных полей

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

Поля «Имя» и «Телефон» принадлежат Контакту. Поиск происходит по полю «Телефон», таким образом, если в вашей CRM уже есть Контакт с таким номером телефона, он будет использован вместо создания нового, в ином же случае будет создан новый Контакт с именем Мария и контактным телефоном +74712773120.

Заполнение поля «Название» предложенным на скриншоте способом позволит создать новую сделку с подстановкой в её заголовок ID заказа в магазине, т.е. в данном примере будет создана сделка с заголовком «Заказ №6510». Дополнительное поле сделки «ID заказа в магазине», отмеченное для поиска, защитит от создания новых сделок по одному и тому же заказу. Система будет создавать новые сделки по нему лишь в том случае, если в вашей CRM ещё нет сделок, в которых значение поля «ID заказа в магазине» было бы равно 6510. Заполнение полей «Сумма» и «Валюта» позволит передать в сделку текущую сумму заказа клиента в качестве бюджета.

Таким образом, мы разобрались, что значения из тела входящего запроса можно подставить в качестве значения заполняемых дополнительных полей Лида/Сделки или Контакта, взяв название параметра в фигурные скобки. В качестве значения дополнительного поля может быть записано как исключительно значение из тела запроса, так и фиксированное текстовое значение и комбинированное значение, содержащее как фиксированный текст, так и значение из тела входящего запроса.