שילוב חידון ל-Bitrix24 CRM: הגדרת Webhook ו-REST API

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

ה-handler בשרת שלכם:

// /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]);

יצירת ליד ב-Bitrix24 דרך 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;
    }
}

שדות מותאמים אישית ומיפוי

שדות מותאמים אישית ב-Bitrix24 לחידון

שדות נוצרים דרך REST API או בממשק Bitrix24:

// Создание пользовательского поля для лида через 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 של Bitrix24 (אלטרנטיבה)

אם בונים חידון מאפס, השתמשו בטופס CRM של Bitrix24 עם שדות נסתרים. השלב האחרון שולח נתונים ישירות ל-endpoint של טופס ה-CRM. ודאו שמזהה הטופס נכון ובדקו היטב.

מה כלול בשילוב (תוצרים)

• תיעוד מפורט של השילוב (endpoints של webhook, מיפוי שדות, הערות קוד)
• הגדרת שדות מותאמים אישית ב-Bitrix24 לתשובות חידון ותגי UTM
• פיתוח והעלאה של ה-webhook handler (PHP) לשרת שלכם
• יצירת פעילות אוטומטית (משימת התקשרות) לכל ליד חדש
• בדיקת הזרימה המלאה: הגשת חידון → יצירת ליד → יצירת פעילות
• העברת גישה (פאנל ניהול, token סודיים של webhook) והדרכה של 30 דקות
• אחריות ל-6 חודשים על השילוב

שיטות עבודה מומלצות וטעויות נפוצות

למה העברת תגי UTM חשובה

ללא תגי UTM, אי אפשר לדעת איזה ערוץ הביא את הלקוח המטרה. אנחנו מעבירים את UF_ROOM_TYPE ו-UF_URGENCY לשדות נפרדים, מה שמאפשר דוחות קמפיין פרסומי בתוך ה-CRM. טעויות נפוצות שיש להימנע מהן:

• ללא אימות webhook – כל אחד יכול לשלוח לידים מזויפים.
• מיפוי רק לתגובות – תשובות הולכות לאיבוד.
• התעלמות מתגי UTM – אובדן ייחוס.
• ללא משימה אוטומטית – לידים נתקעים.

אנחנו נמנעים מאלה בכל פרויקט.

איך שילוב טופס חידון מאיץ עיבוד לידים

בעיבוד ידני, המנהל מבזבז זמן על התקשרויות חוזרות ובירור צרכים. עם השילוב, כל התשובות כבר בכרטיס הליד: תקציב, דחיפות, סוג נכס — כשדות נפרדים. המנהל יכול מיד להחליט אם להתקשר בדחיפות או לשלוח הצעה מסחרית. הוספת פעילות משימה אוטומטית "התקשרות חוזרת תוך שעתיים" מפחיתה אובדן לידים ב-60% (בהתבסס על נתוני הפרויקטים שלנו).

מחירים וקצת עלינו

• Webhook בסיסי (חידון אחד, 3 שדות, ללא UTM) – מ-$500, 3-7 ימים.
• הגדרה מלאה (שדות מותאמים, פעילות, UTM, מספר חידונים) – $1,200–$2,500, 1-2 שבועות.

צרו קשר להערכת פרויקט — נשלח הצעה מסחרית תוך יום. הזמינו את השילוב וקבלו פתרון מוכן עם אחריות ל-6 חודשים.

יש לנו ניסיון של 10+ שנים עם Bitrix24 והשלמנו מעל 50 פרויקטי שילוב. הצוות שלנו מתמחה באוטומציה של CRM ופיתוח מותאם אישית. אנו מספקים תמיכה מלאה ותחזוקה לאחר ההשקה.