Как добавить лид в Bitrix24 через REST API на PHP: рабочий пример

Сайт собирает заявки через форму, а в CRM их нужно вносить руками — копировать имя, телефон, источник из письма и вставлять в Bitrix24. На 20 заявок в день это час потерянного времени менеджера и регулярные опечатки в номере телефона. Один правильно написанный PHP-скрипт с вызовом REST API закрывает эту задачу полностью: заявка появляется в CRM за секунду после отправки формы.

В статье разберём рабочий пример добавления лида в Bitrix24 через REST API на PHP — с реальным кодом, частыми ошибками и тем, на что обычно не хватает внимания в документации. Материал для разработчиков, которые уже работают с PHP и нужно подключить Bitrix24 rest api для добавления лида.

Что понадобится перед началом

• Входящий webhook с правами на CRM (создаётся в разделе «Разработчикам» → «Другое» → «Входящий вебхук», подробно описано в нашей статье про настройку webhook) или OAuth-приложение, если работаете от имени пользователя
• PHP 7.4+ с включённым расширением curl
• Понимание структуры полей лида в Bitrix24 (TITLE, NAME, PHONE, EMAIL, SOURCE_ID и так далее)
• Тестовый портал Bitrix24 для отладки — не тестируем на рабочей CRM с реальными клиентами

Основная часть: добавляем лид через REST API

Шаг 1. Получаем URL входящего вебхука

Если webhook ещё не создан — заходим в «Разработчики» → «Другое» → «Входящий вебхук», выдаём права crm, сохраняем. Получаем URL вида https://yourportal.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/. Этот URL и токен в нём — секретные данные, держите их в переменных окружения, а не в коде.

Частая ошибка: вставляют URL вебхука прямо в код и коммитят в публичный репозиторий. Токен из URL даёт прямой доступ к CRM — относитесь к нему как к паролю.

Шаг 2. Формируем массив полей лида

Метод REST API для создания лида называется crm.lead.add. Он принимает массив fields с полями лида. Минимально нужны TITLE (название лида) и хотя бы один контакт — телефон или email.

$fields = [
    'TITLE' => 'Заявка с сайта',
    'NAME' => 'Иван',
    'LAST_NAME' => 'Петров',
    'PHONE' => [
        ['VALUE' => '+79991234567', 'VALUE_TYPE' => 'WORK'],
    ],
    'EMAIL' => [
        ['VALUE' => 'ivan@example.com', 'VALUE_TYPE' => 'WORK'],
    ],
    'SOURCE_ID' => 'WEB', // источник лида, должен существовать в справочнике источников
];

Частая ошибка: пытаются передать телефон строкой 'PHONE' => '+79991234567'. Bitrix24 ждёт массив с конкретной структурой — простая строка будет проигнорирована без явной ошибки, и лид создастся без телефона.

Шаг 3. Отправляем запрос через cURL

function addLead(string $webhookUrl, array $fields): array
{
    $url = $webhookUrl . 'crm.lead.add.json';

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['fields' => $fields]));
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 10); // не ждём ответ дольше 10 секунд

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        throw new RuntimeException('Bitrix24 вернул код ' . $httpCode);
    }

    return json_decode($response, true);
}

$webhookUrl = getenv('BITRIX_WEBHOOK_URL');
$result = addLead($webhookUrl, $fields);

Шаг 4. Проверяем ответ и обрабатываем ошибки

Bitrix24 при ошибке возвращает HTTP 200, но в теле ответа будет поле error, а не result. Проверка только по HTTP-коду не покажет реальную проблему с данными.

if (isset($result['error'])) {
    // Здесь будет, например, "ERROR_CORE" с описанием в error_description
    error_log('Ошибка Bitrix24: ' . $result['error_description']);
} else {
    $leadId = $result['result'];
    echo "Лид создан, ID: {$leadId}";
}

Частая ошибка: проверяют только HTTP-код 200 и считают, что лид создан. Из-за этого ошибки валидации полей (например, неправильный SOURCE_ID) остаются незамеченными — лид просто не создаётся, а в логах ничего нет.

Шаг 5. Добавляем повторные попытки при сетевых сбоях

Bitrix24 — облачный сервис, и иногда отвечает с задержкой или временной ошибкой 503. Если это критичная заявка (например, оплаченный заказ), стоит сделать 2-3 попытки с небольшой паузой перед тем, как считать отправку неуспешной.

function addLeadWithRetry(string $webhookUrl, array $fields, int $attempts = 3): array
{
    for ($i = 1; $i <= $attempts; $i++) {
        try {
            return addLead($webhookUrl, $fields);
        } catch (RuntimeException $e) {
            if ($i === $attempts) {
                throw $e;
            }
            sleep(2); // пауза перед повтором
        }
    }
}

Шаг 6. Учитываем лимиты запросов

У Bitrix24 есть ограничение на количество запросов к REST API в секунду (зависит от тарифа портала, обычно 2 запроса в секунду на одно приложение). При массовой загрузке лидов (например, импорт базы) нужно делать паузы между запросами или использовать пакетный метод batch, который объединяет до 50 вызовов в один HTTP-запрос.

Частые ошибки и как их избежать

Ошибка: дублирование лидов при повторной отправке формы. Возникает, когда пользователь два раза нажимает кнопку «Отправить» или форма отправляется повторно при сбое сети. Решение: на стороне сайта блокировать повторную отправку формы до получения ответа, либо проверять на дубли по телефону/email перед созданием лида через метод crm.duplicate.findbycomm.

Ошибка: лид создаётся без привязки к ответственному менеджеру. Возникает, если поле ASSIGNED_BY_ID не указано — Bitrix24 назначает ответственного по умолчанию (обычно того, кто настраивал интеграцию), и лид может потеряться. Решение: явно указывать ASSIGNED_BY_ID, либо настроить правило распределения лидов в самом Bitrix24.

Ошибка: неправильная кодировка кириллицы в полях. Возникает при отправке данных не в UTF-8. Решение: убедиться, что весь проект и база данных работают в UTF-8, и что json_encode не превращает кириллицу в escape-последовательности некорректно (обычно это не проблема, но стоит проверить заголовок Content-Type).

Итог

Теперь у вас есть рабочий скрипт, который создаёт лид в Bitrix24 через REST API, проверяет ответ и переживает временные сбои сети. Этого достаточно, чтобы подключить любую форму на сайте напрямую к CRM без ручного переноса данных. Если на каком-то шаге застряли — опишите ситуацию в комментарии или напишите нам напрямую.

CTA

Нужна интеграция сайта с Bitrix24 под вашу задачу — запишитесь на консультацию.