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

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

Квиз-форма (опросник с вопросами и вариантами ответов) конвертирует лучше обычной формы заявки, потому что вовлекает пользователя в диалог перед запросом контактных данных. Результаты квиза несут информацию о потребностях клиента — это ценные данные для менеджера по продажам. Проблема в том, что большинство квиз-сервисов (Marquiz, Qform, Tilda Quiz) отправляют данные в собственную CRM или на email, не интегрируясь нативно с Битрикс24. Задача — передать ответы квиза в сделку/лид Битрикс24 так, чтобы менеджер видел не просто «клиент заполнил форму», а конкретные ответы с контекстом.

Подходы к интеграции

Вариант 1: Webhook от квиз-сервиса → Битрикс24. Большинство квиз-платформ умеют отправлять webhook при завершении квиза. Данные приходят на ваш эндпоинт, вы создаёте лид через REST API Битрикс24.

Вариант 2: Кастомный квиз на сайте → прямая интеграция с Битрикс24 REST. Квиз написан своими силами (React/Vue), последний шаг — отправка данных через REST API.

Вариант 3: Битрикс24 CRM-формы с мультишагом. Встроенный инструмент Битрикс24, не требует разработки. Ограничен по кастомизации дизайна.

Разберём Вариант 1 как наиболее распространённый.

Webhook-обработчик: Marquiz → Битрикс24

Marquiz отправляет POST с JSON-пейлоадом при завершении квиза:

{
  "quiz_id": "abc123",
  "quiz_name": "Подбор окон",
  "contact": {
    "name": "Иван",
    "phone": "+79161234567",
    "email": "[email protected]"
  },
  "answers": [
    {"question": "Тип помещения", "answer": "Квартира"},
    {"question": "Количество окон", "answer": "3"},
    {"question": "Срочность", "answer": "В течение месяца"},
    {"question": "Бюджет", "answer": "50 000 – 100 000 руб."}
  ],
  "result": "Стандартный пакет",
  "utm": {
    "utm_source": "yandex",
    "utm_campaign": "windows_brand"
  }
}

Обработчик на стороне вашего сервера (посредника между Marquiz и Битрикс24):

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

header('Content-Type: application/json');

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

// Верификация по секретному токену в заголовке
$token  = $_SERVER['HTTP_X_QUIZ_TOKEN'] ?? '';
$secret = \Bitrix\Main\Config\Option::get('local.quiz', 'webhook_secret_marquiz');

if (!hash_equals($secret, $token)) {
    http_response_code(403);
    exit(json_encode(['error' => 'Unauthorized']));
}

$integrator = new \Local\Quiz\Bx24Integrator();
$result     = $integrator->createLeadFromQuiz($payload);

echo json_encode(['success' => true, 'lead_id' => $result]);

Создание лида в Битрикс24 через REST

namespace Local\Quiz;

use Local\Bx24\RestClient;

class Bx24Integrator
{
    private RestClient $bx24;

    public function __construct()
    {
        // Входящий вебхук Битрикс24 с правами crm.lead.add
        $webhookUrl = \Bitrix\Main\Config\Option::get('local.quiz', 'bx24_webhook_url');
        $this->bx24 = new RestClient($webhookUrl);
    }

    public function createLeadFromQuiz(array $data): int
    {
        $contact = $data['contact'] ?? [];
        $answers = $data['answers'] ?? [];

        // Формируем блок комментария с ответами квиза
        $comments = $this->buildQuizComment($data['quiz_name'] ?? '', $answers, $data['result'] ?? '');

        $leadFields = [
            'TITLE'          => ($data['quiz_name'] ?? 'Квиз') . ': ' . ($contact['phone'] ?? ''),
            'NAME'           => $contact['name'] ?? '',
            'PHONE'          => [['VALUE' => $contact['phone'] ?? '', 'VALUE_TYPE' => 'WORK']],
            'EMAIL'          => [['VALUE' => $contact['email'] ?? '', 'VALUE_TYPE' => 'WORK']],
            'SOURCE_ID'      => 'WEB',
            'STATUS_ID'      => 'NEW',
            'COMMENTS'       => $comments,
            'UF_QUIZ_ID'     => $data['quiz_id'] ?? '',
            'UF_QUIZ_RESULT' => $data['result'] ?? '',
            'UF_UTM_SOURCE'  => $data['utm']['utm_source'] ?? '',
            'UF_UTM_CAMPAIGN'=> $data['utm']['utm_campaign'] ?? '',
        ];

        // Добавляем отдельные поля под конкретные вопросы квиза
        $leadFields = $this->mapAnswersToFields($leadFields, $answers);

        $result = $this->bx24->call('crm.lead.add', ['fields' => $leadFields]);

        $leadId = (int)($result['result'] ?? 0);

        if ($leadId) {
            // Добавляем задачу менеджеру
            $this->bx24->call('crm.activity.add', [
                'fields' => [
                    'TYPE_ID'       => 2, // звонок
                    'SUBJECT'       => 'Позвонить по квизу: ' . ($contact['phone'] ?? ''),
                    'OWNER_TYPE_ID' => 1, // лид
                    'OWNER_ID'      => $leadId,
                    'DEADLINE'      => date('c', strtotime('+2 hours')),
                ],
            ]);
        }

        return $leadId;
    }

    private function buildQuizComment(string $quizName, array $answers, string $result): string
    {
        $lines = ["=== Квиз: {$quizName} ==="];

        foreach ($answers as $answer) {
            $lines[] = ($answer['question'] ?? '?') . ': ' . ($answer['answer'] ?? '—');
        }

        if ($result) {
            $lines[] = '';
            $lines[] = "Результат квиза: {$result}";
        }

        return implode("\n", $lines);
    }

    private function mapAnswersToFields(array $fields, array $answers): array
    {
        // Маппинг конкретных вопросов в пользовательские поля Битрикс24
        $mapping = [
            'Количество окон'    => 'UF_WINDOWS_COUNT',
            'Тип помещения'      => 'UF_ROOM_TYPE',
            'Бюджет'             => 'UF_BUDGET_RANGE',
            'Срочность'          => 'UF_URGENCY',
        ];

        foreach ($answers as $answer) {
            $question = $answer['question'] ?? '';
            $fieldCode = $mapping[$question] ?? null;

            if ($fieldCode) {
                $fields[$fieldCode] = $answer['answer'] ?? '';
            }
        }

        return $fields;
    }
}

Кастомные поля в Битрикс24 для квиза

Поля создаются через REST API или в интерфейсе Битрикс24 (CRM → Настройки → Пользовательские поля):

// Создание пользовательского поля для лида через REST
$this->bx24->call('crm.userfield.add', [
    'fields' => [
        'ENTITY_ID'   => 'CRM_LEAD',
        'FIELD_NAME'  => 'UF_QUIZ_RESULT',
        'USER_TYPE_ID'=> 'string',
        'XML_ID'      => 'QUIZ_RESULT',
        'EDIT_FORM_LABEL' => ['ru' => 'Результат квиза'],
        'LIST_COLUMN_LABEL' => ['ru' => 'Результат квиза'],
        'MANDATORY'   => 'N',
    ],
]);

Интеграция через CRM-форму Битрикс24

Если квиз разрабатывается с нуля — альтернативный подход: CRM-форма Битрикс24 со скрытыми полями. Последний шаг квиза отправляет данные напрямую в форму через API:

// Финальный шаг квиза: отправляем данные в CRM-форму Битрикс24
async function submitQuizToBx24(answers, contact) {
    const formData = new FormData();

    // Поля CRM-формы
    formData.append('fields[NAME]', contact.name);
    formData.append('fields[PHONE][0][VALUE]', contact.phone);
    formData.append('fields[UF_QUIZ_RESULT]', getQuizResult(answers));
    formData.append('fields[COMMENTS]', formatAnswers(answers));

    // ID формы из настроек Битрикс24
    const formId = document.getElementById('quiz-container').dataset.bx24FormId;

    await fetch(`https://your-domain.bitrix24.ru/crm/webform/import/form/${formId}/`, {
        method: 'POST',
        body: formData,
    });
}

Состав работ

• Webhook-обработчик для квиз-сервиса (Marquiz, Qform или кастомный)
• Клиент Битрикс24 REST API: создание лидов, активностей
• Создание пользовательских полей под ответы квиза
• Маппинг вопросов квиза → поля CRM
• Формирование структурированного комментария с ответами
• Передача UTM-меток в поля лида
• Тестирование сценария: заполнение квиза → карточка лида в Битрикс24

Сроки: интеграция одного квиз-сервиса через webhook — 3–7 дней. Полная схема с кастомными полями и несколькими квизами — 1–2 недели.