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

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

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

Що інтегруємо

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

Сценарії:

1. Новий запис у YCLIENTS → лід/угода в Bitrix CRM (пріоритетний)
2. Клієнт із Bitrix 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' => 'Джерело: Bitrix 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 тижнів.