Интеграция CRM-системы Битрикс24 с сайтом

Интеграция CRM-системы Битрикс24 с сайтом

Битрикс24 — корпоративная платформа с встроенной CRM, задачами и коммуникациями. Интеграция сайта с Битрикс24 сводится к двум задачам: отправка лидов/сделок из форм сайта в CRM и синхронизация данных в обоих направлениях через REST API.

REST API Битрикс24

Битрикс24 предоставляет REST API на основе webhook или OAuth-приложений. Для внешних сайтов проще всего использовать исходящие webhook:

1. В Битрикс24: Настройки → Интеграции → Вебхуки → Добавить вебхук
2. Выбираем нужные разрешения (CRM, Задачи)
3. Получаем URL вида https://your-company.bitrix24.ru/rest/1/abc123xyz/

Создание лида из формы

class Bitrix24Client {
    private string $webhookUrl;

    public function __construct() {
        $this->webhookUrl = config('bitrix24.webhook_url');
    }

    public function callMethod(string $method, array $params = []): array {
        $response = Http::timeout(15)
            ->post($this->webhookUrl . $method, $params);

        if ($response->failed()) {
            throw new \RuntimeException('Bitrix24 API error: ' . $response->status());
        }

        $data = $response->json();
        if (!empty($data['error'])) {
            throw new \RuntimeException('Bitrix24: ' . $data['error_description']);
        }

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

    public function createLead(array $fields): int {
        return $this->callMethod('crm.lead.add', [
            'fields' => $fields,
            'params' => ['REGISTER_SONET_EVENT' => 'Y'],
        ]);
    }
}

Обработчик формы обратной связи:

class ContactFormController extends Controller {
    public function submit(ContactFormRequest $request): JsonResponse {
        // Сохраняем в свою базу
        $contact = ContactRequest::create($request->validated());

        // Отправляем в Битрикс24
        try {
            $bitrix = app(Bitrix24Client::class);
            $leadId = $bitrix->createLead([
                'TITLE'         => 'Заявка с сайта: ' . $request->name,
                'NAME'          => $request->name,
                'PHONE'         => [['VALUE' => $request->phone, 'VALUE_TYPE' => 'WORK']],
                'EMAIL'         => [['VALUE' => $request->email, 'VALUE_TYPE' => 'WORK']],
                'COMMENTS'      => $request->message,
                'SOURCE_ID'     => 'WEB',
                'SOURCE_DESCRIPTION' => 'Форма: ' . $request->form_id,
                'ASSIGNED_BY_ID' => config('bitrix24.default_responsible_id'),
                'UF_CRM_UTM_SOURCE' => session('utm_source'),
                'UF_CRM_UTM_MEDIUM' => session('utm_medium'),
                'UF_CRM_UTM_CAMPAIGN' => session('utm_campaign'),
            ]);
            $contact->update(['bitrix_lead_id' => $leadId]);
        } catch (\Exception $e) {
            Log::error('Bitrix24 lead creation failed', ['error' => $e->getMessage()]);
            // Не прерываем флоу — заявка сохранена в нашей базе
        }

        return response()->json(['success' => true]);
    }
}

Сделки вместо лидов

Для интернет-магазинов часто нужна сделка (Deal) вместо лида:

public function createDealFromOrder(Order $order): void {
    $bitrix = app(Bitrix24Client::class);

    // Находим или создаём контакт
    $contacts = $bitrix->callMethod('crm.contact.list', [
        'filter' => ['PHONE' => $order->customer_phone],
        'select' => ['ID', 'NAME'],
    ]);

    $contactId = $contacts[0]['ID'] ?? $bitrix->callMethod('crm.contact.add', [
        'fields' => [
            'NAME'  => $order->customer_name,
            'PHONE' => [['VALUE' => $order->customer_phone, 'VALUE_TYPE' => 'WORK']],
            'EMAIL' => [['VALUE' => $order->customer_email, 'VALUE_TYPE' => 'WORK']],
        ],
    ]);

    // Создаём сделку
    $dealId = $bitrix->callMethod('crm.deal.add', [
        'fields' => [
            'TITLE'          => 'Заказ #' . $order->number,
            'CONTACT_ID'     => $contactId,
            'OPPORTUNITY'    => $order->total,
            'CURRENCY_ID'    => 'RUB',
            'STAGE_ID'       => 'NEW',
            'COMMENTS'       => $this->buildOrderComment($order),
        ],
    ]);

    // Привязываем товары к сделке
    $productRows = $order->items->map(fn($item) => [
        'PRODUCT_NAME' => $item->product->name,
        'PRICE'        => $item->price,
        'QUANTITY'     => $item->quantity,
        'MEASURE_NAME' => 'шт.',
    ])->toArray();

    $bitrix->callMethod('crm.deal.productrows.set', [
        'id'   => $dealId,
        'rows' => $productRows,
    ]);

    $order->update(['bitrix_deal_id' => $dealId]);
}

Входящий webhook: обновление статуса

Когда менеджер меняет статус сделки в Битрикс24 — сайт должен обновить статус заказа. Настраиваем исходящий webhook из Битрикс24:

// routes/api.php
Route::post('/webhooks/bitrix24', [Bitrix24WebhookController::class, 'handle'])
    ->middleware('bitrix24.signature');

class Bitrix24WebhookController extends Controller {
    public function handle(Request $request): Response {
        $event = $request->input('event');
        $data  = $request->input('data');

        match ($event) {
            'ONCRMDEALSTAGEUPDATED' => $this->onDealStageUpdated($data),
            'ONCRMLEADADD'          => $this->onLeadAdded($data),
            default                 => null,
        };

        return response('OK');
    }

    private function onDealStageUpdated(array $data): void {
        $dealId  = $data['FIELDS']['ID'];
        $stageId = $data['FIELDS']['STAGE_ID'];

        $order = Order::where('bitrix_deal_id', $dealId)->first();
        if (!$order) return;

        $statusMap = [
            'WON'        => 'completed',
            'LOSE'       => 'cancelled',
            'IN_PROCESS' => 'processing',
        ];

        if ($status = $statusMap[$stageId] ?? null) {
            $order->update(['status' => $status]);
        }
    }
}

Middleware проверки подписи

class Bitrix24SignatureMiddleware {
    public function handle(Request $request, Closure $next): Response {
        // Битрикс24 передаёт auth[member_id] — проверяем по токену
        $memberId = $request->input('auth.member_id');
        if ($memberId !== config('bitrix24.member_id')) {
            abort(403);
        }
        return $next($request);
    }
}

Пакетные запросы (batch)

Битрикс24 ограничивает REST API: 2 запроса в секунду на webhook. Для массовых операций используем метод batch:

$batch = [
    'get_lead'    => 'crm.lead.get?id=' . $leadId,
    'get_contact' => 'crm.contact.list?filter[EMAIL]=' . urlencode($email),
];

$results = $bitrix->callMethod('batch', [
    'halt'  => 0,
    'cmd'   => $batch,
]);
// $results['result']['get_lead'], $results['result']['get_contact']

Один вызов batch содержит до 50 методов.

Сроки реализации

Базовая интеграция: лиды из форм в Битрикс24, сохранение ID в локальной базе: 1–2 дня. Двусторонняя синхронизация (сделки, контакты, входящие webhook, UTM-метки): 3–4 дня. Синхронизация каталога товаров + интеграция телефонии Битрикс24 с формами обратного звонка: плюс 2–3 дня.