Интеграция с CRM Bitrix24

Раздел «Интеграция» в настройках системы позволяет подключить внешнюю CRM-систему (Bitrix24) для двустороннего обмена данными между Kalibro и вашей CRM. Интеграция работает в реальном времени и обеспечивает автоматическую синхронизацию заявок, статусов, параметров бланков и сотрудников.

• Подключение CRM-системы
  • Подготовка к подключению
  • Создание локального приложения в Bitrix24
  • Ввод доступов в Kalibro
  • Когда нужна переустановка приложения
  • Смена Client ID
• Настройка полей CRM
  • Сопоставление стадий сделки
  • Часовой пояс компании
  • Исходящее создание сделки
  • Импорт сотрудников из CRM
  • Новый список получателей
  • Направление данных
  • Сопоставление адреса
  • Сопоставление дат выполнения
  • Сопоставление бланка
  • Сопоставление задачи
  • Сопоставление инструкции/контакта
  • Получатель заявки
  • Исходящая запись в сделку
  • Статус заявки Kalibro
  • Обязательные поля для создания заявки
• Маркировка полей CRM в интерфейсе
  • Сопоставление параметров бланков
  • Создание полей и префиксы подписей
  • Контейнерные вопросы: Группа, Повтор, Вставка
  • Сопоставление вопросов бланка
• Синхронизация данных с CRM
  • Двусторонний обмен данными
  • Схема работы интеграции
  • Обработка ошибок синхронизации
• Обратная связь и техподдержка

Подключение CRM-системы

Подготовка к подключению

Перед началом настройки убедитесь, что:

• у вас есть доступ администратора к порталу Bitrix24;
• у вас есть доступ администратора к аккаунту Kalibro;
• в CRM уже созданы (или будут созданы автоматически) пользовательские поля для переноса параметров заявок;
• в Kalibro созданы бланки, которые будут использоваться исполнителями;
• определены статусы заявок в Kalibro и стадии сделок в CRM для сопоставления.

Создание локального приложения в Bitrix24

Для подключения Bitrix24 необходимо создать локальное приложение в вашем портале:

• Перейдите в раздел Разработчикам → Другое → Локальное приложение (иконка профиля → Разработчикам, либо через поиск «Приложения» → «Разработчикам»).
• Укажите название приложения (например, «Kalibro»).
• В разделе «Права доступа» отметьте необходимые права:

В разделе «URL-адреса» укажите:

• Путь для первоначальной установки: https://калибро.рф — сюда портал один раз, при сохранении приложения, сам присылает данные доступа.
• Путь вашего обработчика: https://калибро.рф/events — этот адрес портал использует постоянно, чтобы сообщать Kalibro о событиях в сделках (создание, изменение, удаление).

После сохранения формы Bitrix24 покажет Client ID и Client Secret.

Ввод доступов в Kalibro

• В разделе Настройки → Интеграция → Bitrix24 введите полученные Client ID и Client Secret в соответствующие поля.
• Нажмите «Сохранить».
• Если данные доступа ещё не пришли, откроется отдельный экран ожидания, который сам проверяет статус подключения каждые несколько секунд.

Когда нужна переустановка приложения

Кнопка «Переустановить» в Bitrix24 необходима в следующих случаях:

• приложение уже существовало до того, как вы зашли на вкладку подключения в Kalibro;
• вы изменили список прав доступа в приложении;
• портал не прислал данные установки — тогда после переустановки он пришлёт их повторно.

После переустановки портал повторно присылает данные доступа, и Kalibro донастраивается автоматически.

Смена Client ID

Если ввести Client ID, отличающийся от уже сохранённого (обычно это значит, что приложение в Bitrix24 пересоздали), Kalibro предупредит: подключение (токены доступа) будет сброшено и потребуется заново подтвердить установку в Bitrix24. Все настройки сопоставления полей, стадий и бланков сохранятся — их не нужно вводить заново.

Рекомендуемый порядок действий при симптоме «перетаскивание сделки перестало создавать заявку»: сначала «Обновить подключение», и только если это не помогло — полное удаление интеграции через корзину в списке интеграций.

Настройка полей CRM

Сопоставление стадий сделки

У каждого статуса заявки Kalibro — своя стадия сделки Bitrix24. Сопоставление работает не одинаково для первого статуса и для всех остальных:

• Первый статус — это точка создания заявки. Как только сделка попадает на сопоставленную с ним стадию, Kalibro читает поля сделки и создаёт заявку (при условии, что выполнены три обязательных условия — см. раздел «Обязательные поля для создания заявки»).
• Остальные статусы работают только в одном направлении: когда заявка в Kalibro переходит в такой статус, Kalibro сам передвигает карточку связанной сделки на сопоставленную стадию в Bitrix24. Обратного действия нет — перетаскивание сделки по этим, более поздним стадиям в самом Bitrix24 не создаёт новых заявок и не меняет уже существующую.

Иными словами: первая стадия — входная точка, все остальные — то, куда Kalibro сам «докладывает» о ходе выполнения заявки.

Если какой-то статус не нужно отражать в Bitrix24 — оставьте для него значение «— не использовать —».

Часовой пояс компании

Свободное текстовое поле (по умолчанию Europe/Moscow), в котором можно указать часовой пояс компании. Влияет на то, как интерпретируются даты и время, приходящие из полей сделки Bitrix24.

Kalibro хранит момент заполнения бланка как unix-время (UTC), а показывать и записывать в Bitrix24 его нужно в местном времени компании. При ошибке в написании применяется Europe/Moscow по умолчанию.

Исходящее создание сделки

Отдельный переключатель, который управляет тем, может ли Kalibro сам создавать новые сделки в Bitrix24 (например, когда заявка создаётся не из самого Bitrix24, а вручную в Kalibro, через мобильное приложение и т. п.).

Направление «Bitrix24 → Kalibro» от этого переключателя не зависит и работает всегда.

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

Отметьте пункт «Создавать сделку в Bitrix24 при создании заявки в Kalibro», если это поведение вам подходит.

Импорт сотрудников из CRM

Список сотрудников Bitrix24, сгруппированный по отделам, с чекбоксами. Отмеченные сотрудники заводятся в Kalibro как Исполнители.

Импорт работает по e-mail и учитывает три ситуации:

• Новый сотрудник — заводится в Kalibro как Исполнитель, ему автоматически генерируется пароль.
• Сотрудник уже импортирован ранее — повторно не задваивается; повторный импорт безопасен.
• Сотрудник уже существует в Kalibro, но в другой компании или с другой ролью — он не добавляется. После сохранения появится предупреждение со списком таких сотрудников: «Эти сотрудники не были добавлены. Они уже есть в Kalibro в других компаниях или с другими ролями: ‹имена›».

Это сделано осознанно: компания и роль уже существующего пользователя не перезаписываются.

Пароль импортированного сотрудника. Пароль не показывается в интерфейсе Kalibro — он отправляется сотруднику автоматическим письмом на e-mail, по которому он был сопоставлен. Если сотрудник не получил письмо — попросите проверить папку «Спам» или сбросьте пароль через стандартный сценарий восстановления.

Отметьте нужных сотрудников и нажмите «Сохранить настройки».

Создание в Bitrix24 нового списка получателей

Для случаев, когда исполнители не заведены в Bitrix24 как пользователи (и заводить их не нужно), используйте блок «Создать в Bitrix24 новый список и перенести в него для выбора получателей».

Одной кнопкой Kalibro заводит в Bitrix24 новый список и сразу назначает его параметром «Получатель заявки» в сопоставлении параметров — без импорта сотрудников и без ручного создания справочника в CRM.

• Имя списка: «Kalibro: получатель (авто)».
• Если список уже был создан этой кнопкой ранее — она дополнит его недостающими пунктами, ничего не удаляя.
• Если отмечены оба пункта — список будет смешанным: исполнители как есть, группы — с префиксом «Группа: ».
• Это заменит текущую настройку «Получатель заявки», если она была сопоставлена с другим параметром.

Направление данных

Направление передачи данных обозначено бейджем у каждого раздела:

• «В Kalibro ← из Bitrix24» — Kalibro читает это поле из сделки (обычно в момент создания заявки; часть параметров, например «Задача» и «Инструкция», Kalibro к тому же обновляет обратно при последующих изменениях заявки). Так работают блоки «Адрес», «Дата выполнения», «Бланк», «Задача», «Инструкция / контакт», «Получатель заявки».
• «Из Kalibro → в Bitrix24» — поле только пишется Kalibro в сделку и никогда не читается оттуда. Так работает блок «Исходящая запись в сделку» и параметр «Статус заявки Kalibro».

Сопоставление адреса

Три режима, которые выбираются в самом верху раздела:

• Не использовать адрес — заявки создаются без адреса.
• Единое поле типа «Адрес» — если в вашей CRM адрес объекта хранится в одном стандартном поле Bitrix24 типа «Адрес» (текст и координаты вместе).
• Отдельные поля — текст адреса, широта и долгота сопоставляются по отдельности, независимо друг от друга. Этот режим стоит использовать, если у части заявок есть только координаты без текстового адреса (например, у выездных сотрудников) — в таком случае поле текста адреса можно оставить несопоставленным: адрес не обязателен, заявка создастся и без него.

Отдельно есть необязательное поле «Второй адрес» — на случай, если в заявке нужен ещё один адрес помимо основного.

Сопоставление дат выполнения

«Дата начала» и «Дата окончания» — можно оставить сопоставленными со стандартными полями сделки («Дата начала»/«Дата завершения») либо выбрать любые другие поля.

Если заявка создаётся без даты, поля первое время пустые; как только исполнитель сам укажет дату/время в мобильном приложении, значение запишется в сделку — в те же сопоставленные поля.

Сопоставление бланка

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

• Сопоставленное поле сделки — если в этом разделе выбрано конкретное поле (обычно список бланков компании), заявка берёт бланк из значения этого поля в сделке. Это нужно только компаниям с несколькими бланками, у которых на разных сделках должен использоваться разный бланк.
• «Бланк по умолчанию» — если поле не сопоставлено (или в конкретной сделке не заполнено), используется бланк, указанный в Настройках → Параметры компании как бланк по умолчанию. Эта настройка общая для всей компании и не привязана именно к Bitrix24.
• Единственный бланк компании — если в компании физически заведён только один бланк, он подставляется автоматически, без какой-либо настройки.

Если ни один из трёх вариантов не сработал — заявка не создаётся, в сделку добавляется комментарий с объяснением, каких полей не хватает (см. раздел «Обязательные поля для создания заявки»).

Ниже, если поле для бланка уже сопоставлено и сохранено, появляется кнопка «Обновить список бланков в Bitrix24» — она добавляет в список Bitrix24 бланки, которых там ещё нет (например, только что созданные в Kalibro), ничего не удаляя и не переименовывая уже существующие пункты. Если поля ещё нет — кнопка сначала создаёт его, оформляет как список для выбора и только потом наполняет.

Подпись кнопки меняется в зависимости от ситуации:

• «Создать поле "Kalibro: Бланк" и выгрузить бланки» — если поля ещё нет.
• «Обновить список бланков в поле "Kalibro: Бланк"» — если поле уже создано.
• «...и сопоставить» — добавляется, если поле ещё не сопоставлено.

Сопоставление задачи

Текстовое поле сделки, из которого Kalibro берёт формулировку задания для заявки. Это поле, как и «Инструкция» ниже, Kalibro не только читает при создании заявки, но и продолжает синхронизировать при последующих изменениях сделки.

Сопоставление инструкции/контакта

Если в Настройках → Параметры не включено разделение параметра «Инструкция» на отдельные пункты — здесь одно поле, из которого целиком читается текст инструкции/контакта.

Если разделение включено, здесь появляется список пунктов инструкции (по одному на каждый настроенный пункт), и каждый сопоставляется со своим полем сделки отдельно — можно оставить сопоставленными не все.

Редактирование после завершения заявки и передача в сделку в реальном времени. Часть пунктов разделённой инструкции могут быть отмечены как не передаваемые в мобильное приложение (предназначенные только для офиса/CRM, исполнитель их не видит).

Такие пункты остаются доступны для редактирования прямо в карточке заявки даже после того, как заявка завершена. Как только значение такого пункта отредактировано в карточке заявки, Kalibro сразу же передаёт обновлённое значение в соответствующее сопоставленное поле сделки Bitrix24 — без дополнительных действий и без ожидания следующей смены статуса.

Получатель заявки

Определяет, кому в Kalibro уйдёт заявка, созданная из сделки. Есть два принципиально разных режима:

• «Все» (пункт по умолчанию, если поле не выбрано) — заявка уходит всем доступным исполнителям, без разбора по конкретному полю сделки.
• Конкретное поле сделки — и здесь снова два варианта, в зависимости от типа выбранного поля: поле-«Сотрудник CRM» (например, стандартное поле «Ответственный») — заявка уходит пользователю Kalibro с тем же e-mail, что и у этого сотрудника в Bitrix24. Сопоставление строго по e-mail, не по имени: e-mail сотрудника Bitrix24 должен точно совпадать с e-mail его же аккаунта в Kalibro, иначе получатель не определится и заявка не создастся (см. раздел «Обязательные поля для создания заявки»); либо поле-список — заявка уходит группе Kalibro с таким же названием, как выбранный пункт списка. В таком списке зарезервирован специальный пункт «Всем» — если в конкретной сделке выбран именно он, заявка уйдёт всем доступным исполнителям (это осознанный выбор «для этой конкретной сделки», а не признак того, что получатель не настроен).

Если сотрудники не заведены в Bitrix24 как пользователи (и заводить их специально не нужно), есть более быстрый путь: блок с двумя чекбоксами — «Исполнителей Kalibro» и «Группы» — и кнопка «Создать список и назначить получателем». Она одним действием заводит в Bitrix24 новое поле-список «Kalibro: получатель (авто)», наполняет его отмеченными пунктами и сразу сопоставляет это поле как получателя. Если такое поле уже создавалось этой кнопкой раньше, повторное нажатие только дополнит список недостающими пунктами, ничего не удаляя.

Как только поле-список для получателя сопоставлено и сохранено, вместо блока создания появляется кнопка «Обновить список групп в поле...» — она дописывает в список Bitrix24 группы Kalibro, которых там ещё нет, не трогая уже существующие пункты (в том числе пункт «Всем» — при повторном обновлении списка он остаётся первым, его положение поддерживается автоматически).

Если выбрано поле-«Сотрудник CRM» — список пользователей в нём ведёт сам Bitrix24, никакой кнопки обновления не требуется: получатель ищется в Kalibro по e-mail в момент создания заявки.

Исходящая запись в сделку

Три параметра, которые Kalibro только пишет в сделку (при каждом обновлении статуса заявки), но никогда не читает из неё:

• Цена заявки — Kalibro: цена заявки [double] (UF_CRM_KPRICE).
• Исполнитель — Kalibro: исполнитель [string] (UF_CRM_KEXECUTOR).
• Начисление исполнителю — Kalibro: начисление [enumeration] (UF_CRM_KSTATUS), показывается только если хотя бы у одного бланка или этапа в компании включены начисления исполнителю. Это множественное поле — при каждом начислении добавляется новая запись, старые значения не затираются (важно для многоэтапных заявок с несколькими начислениями).

Статус заявки Kalibro

Отдельное поле, в которое пишется текущий статус заявки (как значение поля сделки — не путать со стадией сделки, которая передвигается отдельно, см. раздел «Сопоставление стадий сделки»).

Обязательные поля для создания заявки

Заявка создаётся из сделки только если заполнены и определены три вещи: Задание, Бланк и Получатель.

Если хотя бы одно из них не удалось определить (пустое поле, не сопоставлен бланк ни одним из способов из раздела «Сопоставление бланка», не нашёлся получатель по e-mail или по списку) — заявка не создаётся, а в сделку добавляется комментарий с точным перечнем того, чего не хватает. Это осознанное поведение: раньше в таких случаях заявка всё равно создавалась, но с пустыми/дефолтными значениями, которые пользователь явно не подтверждал.

Маркировка полей CRM в интерфейсе

Сопоставление параметров бланков

Здесь настраивается, куда попадают ответы исполнителя из мобильного приложения (по конкретному бланку) при завершении заявки — в поля сделки либо в комментарий к сделке. Это сопоставление отдельное для каждого бланка компании — сначала бланк нужно выбрать в самом верху вкладки.

Создание полей по бланку и префиксы подписей

Кнопка «Создать» заводит в Bitrix24 сразу поля для всех вопросов выбранного бланка (по принципу «всё или ничего»). Если поля по этому бланку уже создавались раньше, повторное нажатие их не задваивает — обновятся только подписи.

Поскольку в повторяющихся блоках, группах и вставках названия вопросов бланка могут совпадать (например, несколько позиций с одинаковым названием параметра), для различения одноимённых полей в общем списке полей Bitrix24 используется свой текстовый префикс для каждого типа блока:

Значения префиксов можно менять на свои перед созданием полей; кнопка «Сбросить префиксы» возвращает все четыре к значениям по умолчанию.

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

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

Контейнерные вопросы: Группа, Повтор, Вставка

В бланках Kalibro могут быть вопросы, которые ссылаются на другие бланки:

• Группа — вложенный бланк, отображаемый в отдельном активити.
• Повторяющийся блок (Повтор) — вложенный бланк, поля которого можно заполнять несколько раз (несколько экземпляров).
• Вставка — вложенный фрагмент.

При сопоставлении эти контейнеры разворачиваются: поля дочернего бланка показываются в общем списке с префиксом-подсказкой, например:

• Группа: Введите параметр 1 → Введите строку
• Повтор: Наименование → Введите строку
• Вставка: Название → Введите строку

Так проще понять, из какого блока пришёл конкретный вопрос.

Заголовок и Описание (а также Группа без ссылки на бланк) в этом списке не пропадают — они показываются подписью раздела на своём месте, без выпадающего списка: сопоставлять их нечего.

Сопоставление вопросов бланка

Для каждого вопроса бланка можно выбрать одно из трёх:

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

Для фото-типов (Фото, Камера, Галерея, Рисунок) в списке показываются только файловые поля сделки, а также варианты «— не использовать —» и «— Комментарий в сделке —». Если для вопроса создано файловое поле в Bitrix24, его можно выбрать — тогда фото попадут прямо в это поле. Если выбрано «— Комментарий в сделке —» — фото добавляются вложением в комментарий.

Для повторяющегося блока доступны только два варианта: «— не использовать —» и «— Комментарий в сделке —» (несколько экземпляров одних и тех же вопросов затёрли бы друг друга в одном поле сделки). Во втором случае при завершении заявки в комментарий уходит сводка по каждому экземпляру с нумерацией, если экземпляров больше одного.

Если в бланке есть вложенные блоки (группы, повторы, вставки), появляется чекбокс «Добавлять к значениям уровень вложенности» — он включает в текст значения указание на то, из какого именно повторения/вложенного блока пришёл ответ (полезно, когда один и тот же вопрос встречается несколько раз, например в повторяющемся списке позиций, и все ответы собираются в одно и то же поле или один и тот же комментарий).

Если бланк содержит позиции с ценой, отдельно доступен параметр «Итоговая сумма бланка» — посчитанная сумма по всем позициям с ценой, не привязанная к конкретному вопросу.

Значение по умолчанию для фото и повторов. Для вопросов, у которых нет прямого поля сделки (фото-типы и повторяющийся блок), по умолчанию выбран вариант «— Комментарий в сделке —». Логика: раз поле заполняется — значит, оно нужно в CRM. Если вы раньше осознанно выбирали «не использовать» для таких вопросов — после обновления страница может показать «Комментарий в сделке» выбранным, хотя фактическое поведение не изменится, пока форму не пересохранить. После обновления стоит пройтись по таким бланкам и подтвердить выбор осознанно.

Заголовок отчёта в комментарии. Перед списком значений в комментарии сделки добавляется заголовок «Отчёт по заполняемым полям заявки» — чтобы в таймлайне было понятно, к чему относится блок.

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

Синхронизация данных с CRM

Двусторонний обмен данными

Интеграция работает в обе стороны между сделкой Bitrix24 и заявкой Kalibro и позволяет:

• добавлять пользователей из CRM Bitrix24 в Kalibro для дальнейшей раздачи заявок в работу выездным сотрудникам (Исполнителям);
• работать с исполнителями, не подключёнными к CRM;
• работать операторам, не подключённым к CRM, в Kalibro — создаваемые ими заявки будут создаваться в CRM;
• экспортировать названия бланков из Kalibro в CRM для дальнейшего заполнения нужного бланка Исполнителем;
• автоматически создавать пользовательские поля в CRM по параметрам заявки и параметрам бланков. Удобно при проектировании и тестировании бланка в Kalibro и дальнейшего быстрого добавления и сопоставления в CRM;
• на определённом статусе сделки создавать заявку в Kalibro;
• при создании заявки в Kalibro создавать сделку в CRM;
• передавать в CRM данные, заполняемые Исполнителем через мобильное приложение;
• поддерживать многоэтапные бланки (поочерёдное заполнение этапов бланка разными исполнителями);
• переносить рассчитанную в Kalibro стоимость материалов и услуг;
• переносить начисленные премии и бонусы;
• дублировать переписку чата заявки в комментарии сделки Bitrix24.

Схема работы интеграции

• В Kalibro создаются бланки, которые могут заполняться через мобильное устройство Исполнителем.
• В настройках Kalibro подключаются необходимые модули.
• При переводе сделки в CRM в определённый статус в Kalibro автоматически создаётся заявка. В интеграционных настройках выберите, при каком статусе должна создаваться заявка в Kalibro.
• В случае ручного создания заявки в Kalibro в CRM автоматически создаётся сделка. Все параметры заявки переносятся в поля сделки, сопоставленные в настройках.
• При изменении статуса заявки (Открыта, Принята, Начата, Завершена, На модерации, Удалена) у сделок прописываются статусы, сопоставленные в настройках. Параметры заявки переносятся в сопоставленные поля сделки после выполнения заявки. В случае несовпадения типов параметров заявки и полей сделки и возникновения ошибок они записываются в комментарии сделки. Все фото, добавленные к заявке, дублируются в журнал сделки. Переписка в чате дублируется в журнал сделки.
• Дополнительные параметры инструкции в заявке, которые не отправляются в мобильное приложение, могут редактироваться в карточке заявки после завершения заявки. Отредактированные данные в режиме реального времени переносятся в сопоставленные поля сделки.

Обработка ошибок синхронизации

В случае возникновения ошибок при синхронизации данных (например, несовпадение типов полей, отсутствие обязательных параметров) Kalibro добавляет подробный комментарий в сделку Bitrix24 с описанием проблемы. Это позволяет оператору быстро выявить и устранить причину сбоя.

Типичные ошибки:

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

Обратная связь и техподдержка

При выявлении некорректного поведения интеграции или при необходимости доработки функционала под специфические задачи рекомендуется обратиться в техническую поддержку: kalibro@binommobile.ru.

В обращении желательно указать:

• краткое описание задачи или проблемы;
• шаги, которые привели к проблеме (если это ошибка);
• скриншот или текст ошибки;
• название компании и контактное лицо для обратной связи.

Подробное описание позволяет быстрее воспроизвести ситуацию и предложить решение.