Bitrix24: подключение (сделки) и подготовка чата (Открытые линии)

Что дает интеграция

1. Ссылка на анкету сохраняется в сделке Bitrix24 (crm.deal) в пользовательское поле UF_CRM_....
2. Двусторонний чат: цель, чтобы оператор отвечал гостю из интерфейса Bitrix24 (Открытые линии). Это реализуется через OAuth-приложение и внешний коннектор. Ниже описаны подготовительные шаги (дальнейшая реализация может зависеть от выбранного канала/линии).

Важно про ключи (per-portal)

В Bitrix24 данные client_id / client_secret уникальны для каждого портала (каждого отеля).
Поэтому они хранятся в настройках интеграции конкретного отеля (в pmsConnection), а не в глобальном конфиге сервиса.

Часть 1. Фиксация ссылки на анкету в сделке (готово к использованию)

1) Создайте поле в сделке (crm.deal)

1. Откройте CRM → Сделки → Настройки → Пользовательские поля (названия могут отличаться по интерфейсу).
2. Создайте поле:
   • Тип: Ссылка (URL)
   • Название: Ссылка на онлайн-регистрацию (любое)
3. Скопируйте код поля вида UF_CRM_... (например: UF_CRM_69946920D038A).

2) Создайте входящий webhook (простой режим)

Если вы используете webhook-режим (рекомендуется для старта), вам нужен URL вида:

https://<portal>.bitrix24.ru/rest/<user_id>/<webhook_key>/

Пример (формат):

• base_domain: b24-8st03d.bitrix24.ru
• webhook_user_id: 1
• webhook_key: xxxxxxxxxxxxxxxx

Проверка, что webhook “живой”: Откройте в браузере (или curl) тестовый endpoint:

https://<portal>.bitrix24.ru/rest/<user_id>/<webhook_key>/profile

Если вернулся JSON с данными пользователя, webhook работает.

3) Подключите Bitrix24 в Concierge CRM

В Concierge CRM: Настройки → Интеграции → CRM → Bitrix24.

Заполните:

• Базовый домен (пример: b24-8st03d.bitrix24.ru)
• Webhook user id (пример: 1)
• Webhook key
• Код поля анкеты (UF_CRM_...) (пример: UF_CRM_69946920D038A)

После сохранения при формировании ссылки на анкету сервис:

1. Найдет/создаст контакт по телефону
2. Найдет/создаст сделку, связанную с контактом
3. Запишет ссылку в UF_CRM_... в сделке

Какие логи смотреть

Логи сервиса concierge-pms-integration-service (уровень INFO/DEBUG):

• BITRIX validateConnection: ... ok=true
• BITRIX findContactIdByPhone ...
• BITRIX createContact ...
• BITRIX findDealIdByContact ...
• BITRIX createDeal ...
• BITRIX updateDealField ... ok=true

Часть 2. Подготовка к двустороннему чату (OAuth + Открытые линии)

Цель: оператор общается в Bitrix24 (Открытые линии), а Concierge доставляет сообщения гостю и принимает входящие от гостя.

1) Создайте Открытую линию

1. Откройте Контакт-центр → Открытые линии.
2. Создайте линию (или выберите существующую).
3. Зафиксируйте ID линии (в URL обычно выглядит как LINE=1).

2) Создайте локальное серверное приложение (OAuth)

1. Откройте Разработчикам → Локальное приложение.
2. Тип: Серверное.
3. Укажите:
   • Путь вашего обработчика: https://api.cncrg.org/pms/bitrix/app/handler
   • Путь для первоначальной установки: https://api.cncrg.org/pms/bitrix/app/install
4. Включите чекбокс Использует только API.
5. Права (минимально необходимые для пилота):
   • CRM (crm)
   • Открытые линии (imopenlines)
   • REST (rest)
   • (для коннектора/чата обычно также требуется imconnector и/или im)
6. Сохраните приложение и скопируйте:
   • client_id (пример: local.69948104d27a03.28920460)
   • client_secret

Скриншоты (положить в репозиторий docs):

• concierge-docs/static/images/crm/integrations/bitrix/bitrix-local-app-form.png

3) Почему “200 OK” на install/handler важно

Bitrix24 при создании/установке приложения проверяет доступность URL.
Если install/handler не отвечают 200, установка/события будут ломаться.

Рекомендации по безопасности

• Никогда не храните реальные webhook_key, client_secret, access_token в документации.
• Если client_secret был опубликован/попал в чат, перевыпустите секрет в Bitrix24.