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

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

Omnidesk — хелпдеск із акцентом на мультиканальність: email, чат, Telegram, ВКонтакте, Facebook, Viber в одному вікні. Інтеграція з Бітрікс дає оператору Omnidesk контекст покупця без перемикання вкладок: номери замовлень, суми, статуси, історія — прямо в картці звернення.

API Omnidesk

REST API: https://{account}.omnidesk.ru/api/. Авторизація — HTTP Basic Auth: {user_email}:{api_token}. Основні ресурси: cases (звернення = тікети), users (клієнти), staff (оператори), labels (теги).

Rate limit: 60 запитів на хвилину.

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

При реєстрації та оновленні профілю користувача синхронізуємо дані в Omnidesk через POST /api/users.json або PUT /api/users/{id}.json:

class OmnideskUserSync
{
    public function sync(int $bitrixUserId): void
    {
        $user = \CUser::GetByID($bitrixUserId)->Fetch();
        $omnideskId = $user['UF_OMNIDESK_USER_ID'] ?? null;

        $data = [
            'user' => [
                'full_name'    => trim($user['NAME'] . ' ' . $user['LAST_NAME']),
                'email'        => $user['EMAIL'],
                'phone'        => $user['PERSONAL_PHONE'],
                'custom_data'  => [
                    'bitrix_user_id' => (string)$bitrixUserId,
                    'registered_at'  => $user['DATE_REGISTER'],
                ],
            ],
        ];

        if ($omnideskId) {
            $response = $this->client->put("/api/users/{$omnideskId}.json", $data);
        } else {
            // Спочатку шукаємо за email
            $existing = $this->client->get('/api/users.json', ['email' => $user['EMAIL']]);
            if (!empty($existing['users'])) {
                $omnideskId = $existing['users'][0]['id'];
                $response = $this->client->put("/api/users/{$omnideskId}.json", $data);
            } else {
                $response = $this->client->post('/api/users.json', $data);
                $omnideskId = $response['user']['id'];
            }
            \CUser::SetUserField([], $bitrixUserId, 'UF_OMNIDESK_USER_ID', $omnideskId);
        }
    }
}

Збагачення картки клієнта даними замовлень

Omnidesk підтримує кастомні поля (custom_data) у профілі користувача. Окрім статичного збагачення при реєстрації, налаштовуємо динамічний віджет в Omnidesk через iframe.

У налаштуваннях Omnidesk розділ «Інтеграції → Віджети»: вказуємо URL віджету на стороні Бітрікс:

https://myshop.ru/personal/omnidesk-widget/?email={user.email}

Параметр {user.email} — плейсхолдер Omnidesk, підставляє email клієнта з тікету.

Сторінка віджету у Бітрікс отримує email, знаходить користувача, виводить його замовлення:

$email = htmlspecialchars($_GET['email'] ?? '');
if (!$email) exit;

$user = \CUser::GetByLogin($email)->Fetch();
if (!$user) {
    echo 'Клієнт не знайдений у системі';
    exit;
}

$orders = \Bitrix\Sale\Order::getList([
    'filter' => ['USER_ID' => $user['ID']],
    'order'  => ['DATE_INSERT' => 'DESC'],
    'limit'  => 10,
    'select' => ['ID', 'ACCOUNT_NUMBER', 'DATE_INSERT', 'PRICE', 'STATUS_ID', 'CURRENCY'],
])->fetchAll();

// Рендер таблиці замовлень

Iframe показує оператору останні 10 замовлень клієнта із сумами та статусами прямо в інтерфейсі Omnidesk.

Автоматичне створення тікета при проблемному замовленні

При переведенні замовлення у статус «Повернення» або «Скарга» (кастомний статус) створюємо тікет в Omnidesk через POST /api/cases.json:

AddEventHandler('sale', 'OnSaleStatusOrderChange', function(\Bitrix\Main\Event $event) {
    $order  = $event->getParameter('ENTITY');
    $status = $order->getField('STATUS_ID');

    if (!in_array($status, ['RETURN', 'COMPLAINT'])) return;

    $userId     = $order->getUserId();
    $omnideskId = \CUser::GetByID($userId)->Fetch()['UF_OMNIDESK_USER_ID'] ?? null;

    $omnidesk->post('/api/cases.json', [
        'case' => [
            'subject'     => 'Замовлення #' . $order->getId() . ': ' . ($status === 'RETURN' ? 'запит повернення' : 'скарга'),
            'content'     => 'Автоматично створено при зміні статусу замовлення',
            'user_id'     => $omnideskId,
            'label_names' => [$status === 'RETURN' ? 'return' : 'complaint'],
            'custom_data' => [
                'order_id'    => $order->getId(),
                'order_total' => $order->getPrice(),
            ],
        ],
    ]);
});

Webhooks із Omnidesk

Omnidesk надсилає webhooks (POST на вашу URL) при подіях: case_created, case_updated, case_resolved, message_created.

Обробник верифікує запит через заголовок X-Omnidesk-Signature (HMAC-SHA1 тіла) і виконує потрібну дію. Наприклад, при case_resolved — надіслати лист із Бітрікс із запитом оцінки якості підтримки.

Терміни