Интеграция 1С-Битрикс с HelpDeskEddy

Интеграция 1С-Битрикс с HelpDeskEddy

Клиент оформил заказ в интернет-магазине на Битрикс, написал в поддержку через виджет на сайте, потом уточнил по email, потом позвонил. Без интеграции оператор видит три несвязанных обращения в HelpDeskEddy и не знает, что это один человек с одним заказом. Интеграция связывает тикеты в HelpDeskEddy с заказами и клиентами в Битрикс — оператор открывает тикет и сразу видит историю покупок.

Архитектура взаимодействия

HelpDeskEddy предоставляет REST API (https://{domain}.helpdeskeddy.com/api/v1/). Авторизация — API-ключ в заголовке Authorization: Bearer {token}. Основные сущности: тикеты (tickets), пользователи (users), сообщения (messages), кастомные поля (custom_fields).

Битрикс со стороны предоставляет данные о заказах через модуль sale и о пользователях через модуль main. Интеграция строится на двух потоках данных:

1. Битрикс → HelpDeskEddy: при создании заказа или регистрации пользователя данные передаются в HelpDeskEddy для обогащения профиля клиента.
2. HelpDeskEddy → Битрикс: при создании или обновлении тикета webhook уведомляет Битрикс, и данные тикета отображаются в административной панели или личном кабинете.

Синхронизация пользователей

При регистрации пользователя в Битрикс (событие OnAfterUserRegister) обработчик создаёт или обновляет контакт в HelpDeskEddy через POST /api/v1/users. Ключ связи — email. Дополнительно передаются: имя, телефон, ID пользователя в Битрикс (в кастомное поле HelpDeskEddy).

Обратная синхронизация: при создании тикета от неизвестного email HelpDeskEddy отправляет webhook. Обработчик на стороне Битрикс проверяет, есть ли пользователь с таким email в b_user. Если есть — связывает. Если нет — создаёт минимальный профиль или оставляет как анонимное обращение.

Хранение маппинга: таблица custom_hde_user_map (или UF-поле UF_HDE_USER_ID в таблице b_user) связывает ID пользователя Битрикс с ID контакта в HelpDeskEddy. Это нужно для быстрого поиска без запроса к API при каждом действии.

Передача данных заказа в тикет

Когда оператор открывает тикет в HelpDeskEddy, ему нужны данные заказа. Два подхода:

Подход 1: Push при создании заказа. Обработчик события OnSaleOrderSaved модуля sale отправляет в HelpDeskEddy данные заказа — номер, сумма, статус, список товаров — в кастомные поля контакта или как внутреннюю заметку. Преимущество: данные доступны офлайн. Недостаток: при изменении статуса заказа нужно обновлять данные в HelpDeskEddy.

Подход 2: Pull по запросу. В HelpDeskEddy настраивается виджет (iframe), который подгружает данные с Битрикс по API. Оператор нажимает кнопку — виджет запрашивает /api/orders/?user_id=123 на стороне Битрикс и показывает список заказов. Преимущество: данные всегда актуальны. Недостаток: требует API-эндпоинт на стороне Битрикс.

Рекомендуемая стратегия — комбинированная: push основных данных (номер, сумма, статус) + pull для детализации (состав заказа, история статусов).

Виджет обратной связи на сайте

HelpDeskEddy предоставляет JavaScript-виджет для встраивания на сайт. Код виджета добавляется в шаблон сайта Битрикс (файл footer.php или через \Bitrix\Main\Page\Asset::getInstance()->addString()).

Для персонализации передайте данные авторизованного пользователя в виджет:

window.HDE_CONFIG = {
    user_email: '<?= $USER->GetEmail() ?>',
    user_name: '<?= $USER->GetFullName() ?>',
    custom_fields: {
        bitrix_user_id: '<?= $USER->GetID() ?>'
    }
};

Это избавит клиента от повторного ввода email и свяжет тикет с профилем автоматически.

Отображение тикетов в личном кабинете

В личном кабинете Битрикс (/personal/) добавьте раздел «Мои обращения». Кастомный компонент запрашивает тикеты через GET /api/v1/tickets?user_id={hde_user_id} и выводит список: номер тикета, тема, статус, дата последнего ответа. Клик по тикету открывает переписку.

Кэшируйте список тикетов на 60 секунд — API HelpDeskEddy имеет rate limit (обычно 60 запросов в минуту), и при активном личном кабинете легко его превысить.

Webhooks и обработка событий

HelpDeskEddy отправляет webhooks при событиях: создание тикета, новое сообщение, смена статуса. Настройка — в админке HelpDeskEddy, раздел «Интеграции → Webhooks».

На стороне Битрикс создайте обработчик /api/hde-webhook.php, который:

1. Проверяет подпись запроса (HMAC-SHA256 с секретным ключом).
2. Парсит JSON-тело.
3. По типу события выполняет действие: обновляет UF-поле заказа, отправляет email-уведомление менеджеру, создаёт задачу в CRM.

Сроки