Інтеграція 1С-Бітрікс з HelpDeskEddy

Інтеграція 1С-Bitrix з HelpDeskEddy

Клієнт оформив замовлення в інтернет-магазині на Bitrix, написав у підтримку через віджет на сайті, потім уточнив по email, потім позвонив. Без інтеграції оператор бачить три несв'язані звернення у HelpDeskEddy й не знає, що це одна людина з одним замовленням. Інтеграція пов'язує тикети у HelpDeskEddy з замовленнями й клієнтами у Bitrix — оператор відкриває тикет й одразу бачить історію покупок.

Архітектура взаємодії

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

Bitrix зі сторони надає дані про замовлення через модуль sale й про користувачів через модуль main. Інтеграція будується на двох потоках даних:

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

Синхронізація користувачів

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

Зворотна синхронізація: при створенні тикета від невідомого email HelpDeskEddy відправляє webhook. Обробник на стороні Bitrix перевіряє, чи є користувач з таким email у b_user. Якщо є — пов'язує. Якщо ні — створює мінімальний профіль або залишає як анонімне звернення.

Зберігання маппінгу: таблиця custom_hde_user_map (або UF-поле UF_HDE_USER_ID у таблиці b_user) пов'язує ID користувача Bitrix з ID контакту у HelpDeskEddy. Це потрібно для швидкого пошуку без запиту до API при кожній дії.

Передача даних замовлення у тикет

Коли оператор відкриває тикет у HelpDeskEddy, йому потрібні дані замовлення. Два підходи:

Підхід 1: Push при створенні замовлення. Обробник події OnSaleOrderSaved модуля sale відправляє у HelpDeskEddy дані замовлення — номер, сума, статус, список товарів — у кастомні поля контакту або як внутрішню заміну. Перевага: дані доступні офлайн. Недолік: при зміні статусу замовлення потрібно оновлювати дані у HelpDeskEddy.

Підхід 2: Pull за запитом. У HelpDeskEddy настраюється віджет (iframe), який підгружає дані з Bitrix за API. Оператор натискає кнопку — віджет запитує /api/orders/?user_id=123 на стороні Bitrix й показує список замовлень. Перевага: дані завжди актуальні. Недолік: вимагає API-ендпоінт на стороні Bitrix.

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

Віджет зворотного зв'язку на сайті

HelpDeskEddy надає JavaScript-віджет для вбудовування на сайт. Код віджета додається в шаблон сайту Bitrix (файл 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 й пов'яже тикет з профілем автоматично.

Відображення тикетів у особистому кабінеті

У особистому кабінеті Bitrix (/personal/) додайте розділ «Мої звернення». Кастомний компонент запитує тикети через GET /api/v1/tickets?user_id={hde_user_id} й виводить список: номер тикета, тема, статус, дата останньої відповіді. Клік по тикету відкриває переписку.

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

Webhooks та обробка подій

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

На стороні Bitrix створіть обробник /api/hde-webhook.php, який:

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

Терміни