Интеграция 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 — отправить письмо из Битрикс с запросом оценки качества поддержки.

Сроки