Интеграция 1С-Битрикс с сервисами онлайн-записи (YCLIENTS)

Интеграция 1С-Битрикс с сервисами онлайн-записи (YCLIENTS)

YCLIENTS — отраслевая платформа для онлайн-записи в сервисные бизнесы: салоны красоты, медицинские клиники, фитнес, автосервисы. Когда сайт на 1С-Битрикс, а система управления записями — в YCLIENTS, возникает классический разрыв: клиент записывается через виджет YCLIENTS на сайте, но его данные не попадают в Битрикс CRM. Маркетинг не знает, с какого объявления пришёл клиент, лиды не создаются, история взаимодействий разрознена. Задача интеграции — синхронизировать эти системы.

Что интегрируем

YCLIENTS предоставляет REST API v2. Ключевые сущности: records (записи), clients (клиенты), services (услуги), staff (персонал), bookforms (формы записи). Для интеграции с Битрикс нас интересуют прежде всего записи и клиенты.

Сценарии:

1. Новая запись в YCLIENTS → лид/сделка в Битрикс CRM (приоритетный)
2. Клиент из Битрикс CRM → карточка клиента в YCLIENTS (двунаправленная синхронизация)
3. Отмена записи в YCLIENTS → обновление сделки в Битрикс
4. Витрина услуг YCLIENTS на сайте Битрикс — через виджет или API

YCLIENTS API: авторизация

YCLIENTS использует Bearer-токен, получаемый в обмен на логин/пароль. Токен живёт долго (несколько месяцев), храним в настройках модуля.

namespace Local\YClients;

class ApiClient
{
    private string $baseUrl = 'https://api.yclients.com/api/v1';
    private string $partnerToken; // токен партнёра YCLIENTS
    private string $userToken;    // токен конкретного пользователя

    public function __construct()
    {
        $this->partnerToken = \Bitrix\Main\Config\Option::get('local.yclients', 'partner_token');
        $this->userToken    = \Bitrix\Main\Config\Option::get('local.yclients', 'user_token');
    }

    public function request(string $method, string $path, array $data = []): array
    {
        $url = $this->baseUrl . $path;
        $ch  = curl_init();

        curl_setopt_array($ch, [
            CURLOPT_URL            => $url,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT        => 15,
            CURLOPT_HTTPHEADER     => [
                'Authorization: Bearer ' . $this->partnerToken . ', User ' . $this->userToken,
                'Accept: application/vnd.yclients.v2+json',
                'Content-Type: application/json',
            ],
        ]);

        if ($method === 'POST') {
            curl_setopt($ch, CURLOPT_POST, true);
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        } elseif ($method === 'PUT') {
            curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        }

        $response = json_decode(curl_exec($ch), true);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($httpCode >= 400) {
            throw new \RuntimeException("YCLIENTS API error {$httpCode}: " . ($response['meta']['message'] ?? 'unknown'));
        }

        return $response['data'] ?? $response;
    }
}

Webhook: новая запись → лид в Битрикс

YCLIENTS поддерживает вебхуки на события: record_created, record_updated, record_cancelled, client_created. Настройка в ЛК YCLIENTS: Интеграции → Webhook.

// /local/api/yclients-webhook.php
require_once($_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php');

$payload = json_decode(file_get_contents('php://input'), true);

// Верификация: YCLIENTS отправляет X-Yclients-Hook-Signature
$signature = $_SERVER['HTTP_X_YCLIENTS_HOOK_SIGNATURE'] ?? '';
$body      = file_get_contents('php://input');
$secret    = \Bitrix\Main\Config\Option::get('local.yclients', 'webhook_secret');

if (hash_hmac('sha256', $body, $secret) !== $signature) {
    http_response_code(403);
    exit;
}

$eventType = $payload['resource'] ?? '';
$data      = $payload['data'] ?? [];

match ($eventType) {
    'record_created'   => (new \Local\YClients\RecordHandler())->onCreate($data),
    'record_cancelled' => (new \Local\YClients\RecordHandler())->onCancel($data),
    'record_updated'   => (new \Local\YClients\RecordHandler())->onUpdate($data),
    default            => null,
};

http_response_code(200);

Обработчик записи:

namespace Local\YClients;

class RecordHandler
{
    public function onCreate(array $record): void
    {
        $client = $record['client'] ?? [];
        $phone  = $this->normalizePhone($client['phone'] ?? '');

        $services = array_map(
            fn($s) => $s['title'],
            $record['services'] ?? []
        );

        $staffName = $record['staff']['name'] ?? '—';
        $datetime  = $record['date'] ?? '';

        // Ищем существующий контакт/лид по телефону
        $existingLeadId = $this->findLeadByPhone($phone);

        $fields = [
            'TITLE'                => 'Запись YCLIENTS: ' . implode(', ', $services),
            'PHONE'                => [['VALUE' => $phone, 'VALUE_TYPE' => 'WORK']],
            'NAME'                 => $client['name'] ?? '',
            'SOURCE_ID'            => 'OTHER',
            'STATUS_ID'            => 'NEW',
            'COMMENTS'             => sprintf(
                "YCLIENTS запись #%d\nУслуга: %s\nМастер: %s\nДата: %s",
                $record['id'],
                implode(', ', $services),
                $staffName,
                $datetime
            ),
            'UF_YCLIENTS_RECORD_ID' => (string)$record['id'],
            'UF_YCLIENTS_DATE'      => $datetime,
        ];

        $lead = new \CCrmLead(false);

        if ($existingLeadId) {
            $lead->Update($existingLeadId, ['COMMENTS' => $fields['COMMENTS']], true);
        } else {
            $lead->Add($fields, true);
        }
    }

    public function onCancel(array $record): void
    {
        $ycId = (string)$record['id'];

        // Ищем лид по UF_YCLIENTS_RECORD_ID
        $res = \CCrmLead::GetList(
            [],
            ['UF_YCLIENTS_RECORD_ID' => $ycId],
            false,
            ['nTopCount' => 1],
            ['ID']
        );

        if ($row = $res->Fetch()) {
            $lead = new \CCrmLead(false);
            $lead->Update($row['ID'], ['STATUS_ID' => 'JUNK', 'COMMENTS' => 'Отменено клиентом в YCLIENTS'], true);
        }
    }
}

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

При создании сделки в Битрикс (если клиент заинтересован в услуге) — автоматически создаём/обновляем клиента в YCLIENTS:

namespace Local\YClients;

class ClientSync
{
    private ApiClient $api;
    private int $companyId; // ID компании в YCLIENTS

    public function syncFromBitrix(int $bxLeadId): ?int
    {
        $lead  = \CCrmLead::GetByID($bxLeadId);
        $phone = $this->getLeadPhone($bxLeadId);

        if (!$phone) return null;

        // Ищем клиента в YCLIENTS по телефону
        $existing = $this->api->request('GET',
            "/clients/{$this->companyId}?phone=" . urlencode($phone)
        );

        $clientData = [
            'name'    => trim($lead['NAME'] . ' ' . $lead['LAST_NAME']),
            'phone'   => $phone,
            'email'   => $lead['EMAIL'] ?? '',
            'comment' => 'Источник: Битрикс CRM, лид #' . $bxLeadId,
        ];

        if (!empty($existing)) {
            // Обновляем
            $ycClientId = $existing[0]['id'];
            $this->api->request('PUT', "/client/{$this->companyId}/{$ycClientId}", $clientData);
        } else {
            // Создаём нового
            $result     = $this->api->request('POST', "/clients/{$this->companyId}", $clientData);
            $ycClientId = $result['id'];
        }

        // Сохраняем ID клиента YCLIENTS в поле лида
        $lead = new \CCrmLead(false);
        $lead->Update($bxLeadId, ['UF_YCLIENTS_CLIENT_ID' => $ycClientId], true);

        return $ycClientId;
    }
}

Виджет YCLIENTS на сайте Битрикс

Самый простой способ разместить форму записи — стандартный виджет YCLIENTS. Он вставляется через компонент Битрикс в нужном месте шаблона.

Кастомизация: виджет YCLIENTS поддерживает параметры через JS API — можно предзаполнить выбранную услугу или мастера, если пользователь перешёл с карточки товара/услуги Битрикс.

Таблица пользовательских полей

Состав работ

• Настройка YCLIENTS API: получение партнёрского токена, пользовательского токена
• Webhook-эндпоинт с верификацией подписи
• Создание/обновление лидов по входящим записям
• Синхронизация клиентов Битрикс → YCLIENTS
• Создание пользовательских полей в CRM
• (Опционально) Встройка виджета YCLIENTS в шаблоны компонентов Битрикс

Сроки: базовая интеграция (webhook → лид) — 1–2 недели. Двусторонняя синхронизация клиентов и витрина услуг — 3–5 недель.