.. _bitrix24-label: ===================== Интеграция с Bitrix24 ===================== .. |галка| image:: media/galka.png :width: 21 :alt: alternative text Сервис Torrow интегрирован с CRM Bitrix24. Чтобы передавать заказы из приложения или виджета в Bitrix24, выполните настройку в Bitrix24, затем подключите интеграцию в Torrow. В интеграции используются два объекта Bitrix24: - **Сделки** — элемент CRM с информацией о продаже (название, сумма, стадия, клиент). В сделках сохраняются данные заказа Torrow. Подробнее: `Сделки: что это и как с ними работать `_. - **Контакты** — элемент CRM с данными клиента (ФИО, телефон, e-mail). Контакт создаётся или находится по номеру телефона или электронной почте заказчика заказа и привязывается к сделке. Подробнее: `Контакты: что это и как с ними работать `_. Интеграция Torrow с Bitrix24 создаёт и обновляет контакты и сделки, привязывает контакты к сделкам и синхронизирует статусы заказов со стадиями воронки. В Torrow настраиваются события Услуги, по которым вызывается webhook в Bitrix24. ---------------------------------- Настройка Bitrix24 ---------------------------------- Перед подключением в Torrow необходимо: создать входящий вебхук; при необходимости — настроить пользовательское поле сделки **torrow_id** (ID заказа Torrow), остальные поля и воронку со стадиями. 1. Создание входящего вебхука ---------------------------------- 1.1. В Bitrix24 откройте в главной панели **Ещё** (шестерёнка) → **Настройки** → раздел **Интеграции** → **REST API** → **Другое**. .. figure:: media/bitrix24/01-developer-settings-1.jpg :scale: 60 % :alt: Настройки → Интеграции → REST API → Другое :align: center Переход в раздел Интеграции и REST API .. figure:: media/bitrix24/01-developer-settings-2.jpg :scale: 60 % :alt: Добавление вебхука :align: center Добавление вебхука ---------------------------------- 1.2. Нажмите **Входящий вебхук**. .. figure:: media/bitrix24/02-incoming-webhook-create.jpg :scale: 60 % :alt: Создать входящий вебхук :align: center Создание входящего вебхука ---------------------------------- 1.3. В открытом окне будет сгенерирован URL вебхука. Внизу формы выберите права **CRM (crm)** и нажмите кнопку **Сохранить**. .. figure:: media/bitrix24/03-create-webhook-1.jpg :scale: 60 % :alt: Форма создания входящего вебхука :align: center Форма создания входящего вебхука .. figure:: media/bitrix24/03-create-webhook-2.jpg :scale: 60 % :alt: Выбор прав и сохранение вебхука :align: center Выбор прав и сохранение вебхука ---------------------------------- 1.4. Скопируйте **URL вебхука**. Из него понадобятся три значения: - **domain** — поддомен организации (часть перед ``.bitrix24.ru``), например ``b24-yzh937`` из ``https://b24-yzh937.bitrix24.ru/rest/1/gyho1ed1r7fqgcm8/`` - **user_id** — число после ``/rest/`` (в примере ``1``) - **webhook_code** — строка после ``user_id/`` до конца (в примере ``gyho1ed1r7fqgcm8``) Эти значения нужно будет подставить в ссылку для Torrow (см. раздел «Подключение в Torrow»). .. figure:: media/bitrix24/04-webhook-url-copy.jpg :scale: 60 % :alt: Копирование URL вебхука :align: center Копирование URL вебхука ---------------------------------- 2. Пользовательские поля сделки ---------------------------------- - **torrow_id** — строка. ID заказа Torrow, тип поля: текст (например, символьный код ``TorrowId``) - **Время начала** — дата/время - **Время окончания** — дата/время - **Дата заказа** — дата или текст - **Услуга** — текст (название услуги) - **Детали заказа** — текст, многострочное (описание/детали) 2.1. В Bitrix24 откройте список пользовательских полей сделки: **Ещё** → **Настройки** → **Настройки CRM** → **Настройки форм и отчетов** → **Пользовательские поля**. .. figure:: media/bitrix24/05-deal-custom-fields-1.jpg :scale: 60 % :alt: Ещё → Настройки → Настройки CRM :align: center Настройки форм и отчетов .. figure:: media/bitrix24/05-deal-custom-fields-2.jpg :scale: 60 % :alt: Настройки форм и отчетов → Пользовательские поля :align: center Пользовательские поля .. figure:: media/bitrix24/05-deal-custom-fields-3.jpg :scale: 60 % :alt: Создать пользовательское поле сделки :align: center Создание пользовательского поля сделки ---------------------------------- 2.2. Добавьте поле для ID заказа Torrow и при необходимости остальные поля. Заполните **Название** и **Тип** каждого поля и нажмите кнопку **Сохранить**. .. figure:: media/bitrix24/06-add-deal-field-1.jpg :scale: 60 % :alt: Добавление пользовательского поля сделки (название поля) :align: center Добавление пользовательского поля сделки (название поля) .. figure:: media/bitrix24/06-add-deal-field-2.jpg :scale: 60 % :alt: Добавление пользовательского поля сделки (тип поля) :align: center Добавление пользовательского поля сделки (тип поля) ---------------------------------- 3. Воронка продаж и стадии ---------------------------------- Интеграция сопоставляет состояния заказа в Torrow со стадиями сделки в Bitrix24. Обязательно нужно указать название воронки и названия стадий в параметрах вебхука. 3.1. Узнайте **название воронки** и **названия стадий** в Bitrix24: в разделе **Сделки** раскрыть фильтр **Все сделки** и выбрать пункт **Воронки и туннели продаж** и для выбранной воронки посмотрите названия стадий (Новая, В работе, Успешно завершена и т.д.). .. figure:: media/bitrix24/07-funnel-stages-1.jpg :scale: 60 % :alt: Раздел Сделки → Фильтр Все сделки :align: center Раздел Сделки → Фильтр Все сделки .. figure:: media/bitrix24/07-funnel-stages-2.jpg :scale: 60 % :alt: Фильтр Все сделки → Воронки и туннели продаж :align: center Фильтр Все сделки → Воронки и туннели продаж .. figure:: media/bitrix24/07-funnel-stages-3.jpg :scale: 60 % :alt: Воронка продаж и стадии сделки :align: center Воронка продаж и стадии сделки ---------------------------------- Параметры (передаются в URL при настройке в Torrow): - **pipeline** — название воронки (например, «Продажа услуг»). - **booking** — стадия для состояния «Бронирование». - **approving** — стадия для «Согласование». - **confirmed** — стадия для «Подтверждено». - **cancelled** — стадия для «Отменено». - **completed** — стадия для «Завершено». Параметры **pipeline**, **booking**, **approving**, **confirmed**, **cancelled**, **completed** обязательно нужно указать в параметрах вебхука в Torrow. ---------------------------------- Подготовка URL вебхука ---------------------------------- Все параметры передаются в URL при настройке интеграции в Torrow (в поле URL вебхука). Ниже — полный перечень параметров по ТЗ интеграции. .. note:: В URL пробелы в значениях параметров (например, в названиях воронок, стадий или полей) нужно заменить на ``%20``. **Параметры аутентификации (обязательные)** Используются для доступа к Bitrix24 через входящий вебхук. +-------------------+--------+-----------------------------------------+----------------------+ | Параметр | Тип | Описание | Пример | +===================+========+=========================================+======================+ | ``domain`` | string | Домен Bitrix24 (без .bitrix24.ru) | ``b24-yzh937`` | +-------------------+--------+-----------------------------------------+----------------------+ | ``user_id`` | string | ID пользователя вебхука из URL Bitrix24 | ``1`` | +-------------------+--------+-----------------------------------------+----------------------+ | ``webhook_code`` | string | Код входящего вебхука Bitrix24 | ``gyho1ed1r7fqgcm8`` | +-------------------+--------+-----------------------------------------+----------------------+ **Параметр для отправки уведомлений (обязательный)** Используются для уведомлений об ошибках синхронизации. +------------------+--------+------------------------------------------------------------------+---------------------------+ | Параметр | Тип | Описание | Пример | +==================+========+==================================================================+===========================+ | ``error_email`` | string | Адрес почты для отправки уведомлений при ошибке синхронизации | ``admin@company.ru`` | +------------------+--------+------------------------------------------------------------------+---------------------------+ **Параметры воронки и статусов (обязательные)** Определяют воронку продаж и маппинг стадий сделки на состояния заказа Torrow. Если указан текст — используется поиск по названию стадии; если стадия не найдена — возвращается ошибка валидации. +----------------+--------+----------------------------------------------------+---------------------------+ | Параметр | Тип | Описание | Пример | +================+========+====================================================+===========================+ | ``pipeline`` | string | Название воронки продаж | ``Продажа услуг`` | +----------------+--------+----------------------------------------------------+---------------------------+ | ``deal_type`` | string | Название типа сделки | ``Продажа`` | +----------------+--------+----------------------------------------------------+---------------------------+ | ``booking`` | string | Стадия для состояния «Бронирование» | ``Новая`` | +----------------+--------+----------------------------------------------------+---------------------------+ | ``approving`` | string | Стадия для состояния «Согласование» | ``Подготовка документов`` | +----------------+--------+----------------------------------------------------+---------------------------+ | ``confirmed`` | string | Стадия для состояния «Подтверждено» | ``В работе`` | +----------------+--------+----------------------------------------------------+---------------------------+ | ``cancelled`` | string | Стадия для состояния «Отменено» | ``Сделка провалена`` | +----------------+--------+----------------------------------------------------+---------------------------+ | ``completed`` | string | Стадия для состояния «Завершено» | ``Сделка успешна`` | +----------------+--------+----------------------------------------------------+---------------------------+ **Параметры кастомных полей сделки** Задают названия пользовательских полей Bitrix24, в которые записываются данные заказа. Поля должны существовать в Bitrix24. +---------------------+-------------+-----------------------------------------------------+---------------------------+ | Параметр | Тип | Описание | Пример | +=====================+=============+=====================================================+===========================+ | ``torrow_id`` | string | Название поля для ID заказа Torrow (необязательно) | ``TorrowId`` | +---------------------+-------------+-----------------------------------------------------+---------------------------+ | ``start_date`` | string | Название поля для даты/времени начала заказа | ``Время начала`` | +---------------------+-------------+-----------------------------------------------------+---------------------------+ | ``end_date`` | string | Название поля для даты/времени окончания заказа | ``Время окончания`` | +---------------------+-------------+-----------------------------------------------------+---------------------------+ | ``order_date`` | string | Название поля для даты заказа | ``Дата заказа`` | +---------------------+-------------+-----------------------------------------------------+---------------------------+ | ``service_name`` | string | Название поля для названия услуги | ``Услуга`` | +---------------------+-------------+-----------------------------------------------------+---------------------------+ | ``order_details`` | string | Название поля для деталей заказа | ``Детали заказа`` | +---------------------+-------------+-----------------------------------------------------+---------------------------+ Пример полного URL с параметрами аутентификации, воронки и полей: .. code-block:: text https://hooks.torrow.net/webhook/bitrix24?domain=b24-yzh937&user_id=1&webhook_code=gyho1ed1r7fqgcm8&error_email=admin@company.ru&torrow_id=TorrowId&pipeline=Продажа%20услуг&booking=Новая&approving=Подготовка&confirmed=В%20работе&cancelled=Провалена&completed=Успешно&start_date=Время%20начала&end_date=Время%20окончания&service_name=Услуга&order_details=Детали%20заказа ---------------------------------- Подключение в Torrow ---------------------------------- 1. Откройте свою услугу в приложении Torrow и перейдите в **Общие настройки** → **Интеграции**. .. figure:: media/bitrix24/08-torrow-integrations-1.jpg :scale: 60 % :alt: Услуга :align: center Услуга .. figure:: media/bitrix24/08-torrow-integrations-2.jpg :scale: 60 % :alt: Общие настройки :align: center Общие настройки .. figure:: media/bitrix24/08-torrow-integrations-3.jpg :scale: 60 % :alt: Интеграции :align: center Интеграции ---------------------------------- 5. В списке интеграций выберите **Webhook**. .. figure:: media/bitrix24/09-torrow-webhook-choice.jpg :scale: 60 % :alt: Выбор интеграции Webhook :align: center Выбор интеграции Webhook ---------------------------------- 6. Заполните форму WebHook: укажите название WebHook, в поле **URL** вставьте ссылку для Bitrix24 в соответствии с подготовленным URL вебхука выше и укажите события, при которых будет отправляться webhook. Сохраните изменения, нажав |галка|. .. figure:: media/bitrix24/10-torrow-webhook-form.jpg :scale: 60 % :alt: Заполнение формы WebHook :align: center Заполнение формы WebHook .. hint:: Список рекомендуемых для выбора событий: - Запись на заказ/событие (CheckIn) - Отмена участия в заказе/событии (CancelCaseParticipation) - Заказ/событие отклонен(о) (CaseReject) - Вернуть в работу (CaseDeclineWork) - Заказ запланирован (CasePlan) - Заказ отменен (CaseCancel) - Заказ взят в работу (CaseTakeInWork) - Заказ завершен (CaseComplete) - Заказ принят (CaseAccept) - Изменено время заказа/события (UpdateCaseTime) - Изменено место заказа/события (UpdateCasePlace) - Подтверждение участия (смена состояний) (ApproveCaseParticipation) - Подтверждение участия в заказе/событии (ConfirmCaseParticipation) - Подтверждение оплаты (ApproveMoneyReceive) - Отклонение оплаты (RejectMoneyReceive) - Заказ возвращен на проверку (CaseReturnToVerification) ---------------------------------- 7. После сохранения интеграция отобразится в списке со статусом **Активный**. .. figure:: media/bitrix24/11-torrow-integration-active.jpg :scale: 60 % :alt: Активная интеграция Bitrix24 :align: center Активная интеграция Bitrix24 ---------------------------------- Справочная информация ---------------------------------- **Объекты Bitrix24 в интеграции:** - `Сделки: что это и как с ними работать `_ - `Контакты: что это и как с ними работать `_ **Документация Bitrix24 REST API (для разработчиков):** - `Обзор REST API `_ - `Входящий вебхук `_ - `Сделки (crm.deal) `_ - `Контакты (crm.contact) `_ ---------------------------------- .. raw:: html .. raw:: html