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

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

Usedesk — российский хелпдеск: единая очередь тикетов из email, чата, телефона, соцсетей. Интеграция с Битрикс нужна прежде всего для связи тикетов с заказами. Оператор не должен переключаться между Usedesk и Битрикс, чтобы понять, что конкретно купил клиент, написавший в поддержку.

API Usedesk

REST API Usedesk: https://api.usedesk.ru/. Авторизация — API-ключ в параметре api_token или заголовке Authorization: Token {api_token}. Основные сущности:

• tickets — тикеты (обращения)
• clients — клиенты
• comments — сообщения в тикете
• custom_fields — кастомные поля

Webhooks настраиваются в разделе «Настройки → Интеграции → API» Usedesk.

Синхронизация клиентов

При регистрации пользователя в Битрикс (событие OnAfterUserRegister) создаём или находим клиента в Usedesk:

AddEventHandler('main', 'OnAfterUserRegister', function(&$fields) {
    $email = $fields['LOGIN']; // В Битрикс логин часто = email

    // Ищем существующего клиента по email
    $response = $usedesk->get('/clients', ['email' => $email]);
    if (!empty($response['clients'])) {
        $udClientId = $response['clients'][0]['id'];
    } else {
        // Создаём нового
        $response = $usedesk->post('/clients', [
            'name'  => $fields['NAME'] . ' ' . $fields['LAST_NAME'],
            'email' => $email,
            'phone' => $fields['PERSONAL_PHONE'] ?? '',
            'custom_fields' => [
                ['id' => USEDESK_CF_BITRIX_USER_ID, 'value' => $fields['ID']],
            ],
        ]);
        $udClientId = $response['client']['id'];
    }

    // Сохраняем маппинг
    \CUser::SetUserField([], $fields['ID'], 'UF_USEDESK_CLIENT_ID', $udClientId);
});

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

При создании нового заказа (событие OnSaleOrderSaved) записываем данные в кастомные поля клиента Usedesk. Это обогащает карточку клиента историей покупок:

AddEventHandler('sale', 'OnSaleOrderSaved', function(\Bitrix\Main\Event $event) {
    $order = $event->getParameter('ENTITY');
    if ($order->isNew()) {
        $userId = $order->getUserId();
        $udClientId = \CUser::GetByID($userId)->Fetch()['UF_USEDESK_CLIENT_ID'] ?? null;
        if (!$udClientId) return;

        // Добавляем заметку к клиенту в Usedesk
        $usedesk->post("/clients/{$udClientId}/comments", [
            'message' => sprintf(
                'Новый заказ #%d на сумму %s руб. Статус: %s',
                $order->getId(),
                number_format($order->getPrice(), 2, ',', ' '),
                $order->getField('STATUS_ID')
            ),
            'type' => 'note',
        ]);
    }
});

Виджет Usedesk на сайте с персонализацией

Usedesk предоставляет JS-виджет. Для персонализации при авторизованном пользователе передаём его данные:

(function(d, w, c) {
    w.usedeskSettings = {
        company_id: "<?= USEDESK_COMPANY_ID ?>",
        <?php if ($USER->IsAuthorized()): ?>
        user: {
            name: "<?= htmlspecialchars($USER->GetFullName()) ?>",
            email: "<?= htmlspecialchars($USER->GetEmail()) ?>",
            fields: {
                custom_id: "<?= $USER->GetID() ?>"
            }
        },
        <?php endif; ?>
    };
    var s = d.createElement("script");
    s.type = "text/javascript"; s.async = true;
    s.src = "https://secure.usedesk.ru/widget.js";
    d.getElementsByTagName("head")[0].appendChild(s);
})(document, window);

Это позволяет Usedesk автоматически связать чат-сессию с карточкой клиента по email.

Обработка webhooks из Usedesk

При изменении статуса тикета Usedesk отправляет webhook на наш обработчик. Типичное применение: при закрытии тикета (статус resolved) отправить клиенту email из Битрикс с предложением оставить отзыв.

// /api/usedesk-webhook.php
$payload = json_decode(file_get_contents('php://input'), true);

// Верификация подписи
$sig = hash_hmac('sha256', file_get_contents('php://input'), USEDESK_WEBHOOK_SECRET);
if (!hash_equals($sig, $_SERVER['HTTP_X_USEDESK_SIGNATURE'] ?? '')) {
    http_response_code(403); exit;
}

if ($payload['event'] === 'ticket.resolved') {
    $email = $payload['ticket']['client']['email'] ?? '';
    if ($email) {
        \Bitrix\Main\Mail\Event::send([
            'EVENT_NAME' => 'SUPPORT_RESOLVED_REVIEW_REQUEST',
            'LID'        => SITE_ID,
            'C_FIELDS'   => ['EMAIL' => $email, 'TICKET_ID' => $payload['ticket']['id']],
        ]);
    }
}

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

В ЛК Битрикс добавляем раздел «Мои обращения». Компонент запрашивает тикеты клиента через Usedesk API по client_id:

$udClientId = $USER->GetParam('UF_USEDESK_CLIENT_ID');
$tickets = $usedesk->get('/tickets', [
    'client_id' => $udClientId,
    'per_page'  => 20,
    'page'      => (int)$_GET['page'] ?: 1,
]);

Список тикетов кэшируется на 60 секунд (\Bitrix\Main\Data\Cache).

Сроки