Інтеграція CRM-системи Бітрікс24 з сайтом

Інтеграція CRM-системи Bitrix24 з сайтом

Bitrix24 — корпоративна платформа з вбудованою CRM, завданнями та комунікаціями. Інтеграція сайту з Bitrix24 зводиться до двох завдань: відправка лідів/угод з форм сайту в CRM та синхронізація даних в обох напрямках через REST API.

REST API Bitrix24

Bitrix24 надає REST API на основі webhook або OAuth-додатків. Для зовнішніх сайтів найпростіше використовувати вхідні webhook:

1. У Bitrix24: Налаштування → Інтеграції → Вебхуки → Додати вебхук
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());

        // Відправляємо в Bitrix24
        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: оновлення статусу

Коли менеджер змінює статус угоди в Bitrix24 — сайт повинен оновити статус замовлення. Налаштуйте вихідний webhook з Bitrix24:

// 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 {
        // Bitrix24 передає auth[member_id] — перевіряємо за токеном
        $memberId = $request->input('auth.member_id');
        if ($memberId !== config('bitrix24.member_id')) {
            abort(403);
        }
        return $next($request);
    }
}

Пакетні запити (batch)

Bitrix24 обмежує 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 методів.

Терміни реалізації

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