REST API PHP Битрикс24 в 2025: инструкция по интеграции и автоматизации бизнес-процессов

REST API Битрикс24 открывает широкие возможности для интеграции корпоративного портала с внешними системами и автоматизации бизнес-процессов. В этой статье мы рассмотрим практические аспекты работы с API через PHP, разберем способы авторизации, изучим основные методы и создадим рабочие примеры кода для решения типовых задач.

Что такое REST API Битрикс24 и зачем он нужен

REST API Битрикс24 — это интерфейс программирования приложений, который позволяет внешним системам взаимодействовать с данными и функциональностью корпоративного портала. Через API можно:

• Управлять лидами, сделками и контактами — создавать, изменять и получать данные CRM
• Синхронизировать информацию между Битрикс24 и другими системами
• Автоматизировать рутинные операции — массовые обновления, отчеты, уведомления
• Интегрировать с внешними сервисами — 1С, интернет-магазины, call-центры
• Создавать кастомные решения для специфических потребностей бизнеса

Способы авторизации в REST API Битрикс24

Битрикс24 предоставляет несколько методов авторизации для работы с API:

1. OAuth 2.0 авторизация

Наиболее безопасный способ для публичных приложений. Требует регистрации приложения в Битрикс24.Market и получения client_id и client_secret.

2. Входящий веб-хук

Простой способ для внутренних интеграций. Создается в настройках портала и предоставляет уникальный URL для API-запросов.

3. Локальное приложение

Для приложений, устанавливаемых на конкретный портал. Использует специальный токен доступа.

Настройка входящего веб-хука

Для быстрого старта воспользуемся входящим веб-хуком:

1. Перейдите в раздел Приложения → Разработчикам → Другое → Входящий веб-хук
2. Нажмите Создать веб-хук
3. Выберите пользователя, от имени которого будут выполняться запросы
4. Настройте права доступа к необходимым разделам
5. Скопируйте полученный URL веб-хука

URL будет иметь вид: https://your-domain.bitrix24.ru/rest/1/webhook_code/

Основы работы с REST API через PHP

Для выполнения запросов к API Битрикс24 создадим базовый класс:

<?php
class Bitrix24API {
private $webhook_url;
public function __construct($webhook_url) {
$this->webhook_url = rtrim($webhook_url, '/');
}
public function call($method, $params = []) {
$url = $this->webhook_url . '/' . $method;
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($params),
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Accept: application/json'
],
CURLOPT_SSL_VERIFYPEER => false,
CURLOPT_TIMEOUT => 30
]);
$response = curl_exec($curl);
$http_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($http_code !== 200) {
throw new Exception("HTTP Error: " . $http_code);
}
$result = json_decode($response, true);
if (isset($result['error'])) {
throw new Exception("API Error: " . $result['error_description']);
}
return $result;
}
public function batch($calls) {
return $this->call('batch', ['halt' => 0, 'cmd' => $calls]);
}
}
?>

Работа с лидами через REST API

Лиды — одна из основных сущностей CRM Битрикс24. Рассмотрим основные операции:

Создание лида

<?php
$api = new Bitrix24API('https://your-domain.bitrix24.ru/rest/1/webhook_code/');
// Создание нового лида
$lead_data = [
'TITLE' => 'Новый лид из внешней системы',
'NAME' => 'Иван',
'LAST_NAME' => 'Петров',
'EMAIL' => [['VALUE' => 'ivan@example.com', 'VALUE_TYPE' => 'WORK']],
'PHONE' => [['VALUE' => '+7 (999) 123-45-67', 'VALUE_TYPE' => 'MOBILE']],
'SOURCE_ID' => 'WEB',
'STATUS_ID' => 'NEW',
'OPPORTUNITY' => 50000,
'CURRENCY_ID' => 'RUB',
'COMMENTS' => 'Комментарий к лиду'
];
try {
$result = $api->call('crm.lead.add', ['fields' => $lead_data]);
echo "Лид создан с ID: " . $result['result'];
} catch (Exception $e) {
echo "Ошибка: " . $e->getMessage();
}
?>

Получение списка лидов

<?php
// Получение лидов с фильтрацией
$filter = [
'STATUS_ID' => 'NEW',
'>DATE_CREATE' => date('Y-m-d', strtotime('-7 days'))
];
$select = ['ID', 'TITLE', 'NAME', 'LAST_NAME', 'EMAIL', 'PHONE', 'DATE_CREATE'];
try {
$result = $api->call('crm.lead.list', [
'filter' => $filter,
'select' => $select,
'order' => ['DATE_CREATE' => 'DESC']
]);
foreach ($result['result'] as $lead) {
echo "ID: {$lead['ID']}, Название: {$lead['TITLE']}\n";
}
} catch (Exception $e) {
echo "Ошибка: " . $e->getMessage();
}
?>

Обновление лида

<?php
$lead_id = 123;
$update_data = [
'STATUS_ID' => 'IN_PROCESS',
'COMMENTS' => 'Лид взят в работу'
];
try {
$result = $api->call('crm.lead.update', [
'ID' => $lead_id,
'fields' => $update_data
]);
if ($result['result']) {
echo "Лид успешно обновлен";
}
} catch (Exception $e) {
echo "Ошибка: " . $e->getMessage();
}
?>

Работа со сделками

Сделки представляют коммерческие возможности и являются центральными элементами продаж:

Создание сделки

<?php
$deal_data = [
'TITLE' => 'Продажа оборудования',
'TYPE_ID' => 'SALE',
'STAGE_ID' => 'NEW',
'COMPANY_ID' => 1,
'CONTACT_ID' => 2,
'OPPORTUNITY' => 150000,
'CURRENCY_ID' => 'RUB',
'PROBABILITY' => 50,
'BEGINDATE' => date('Y-m-d'),
'CLOSEDATE' => date('Y-m-d', strtotime('+30 days')),
'ASSIGNED_BY_ID' => 1,
'COMMENTS' => 'Сделка создана через API'
];
try {
$result = $api->call('crm.deal.add', ['fields' => $deal_data]);
echo "Сделка создана с ID: " . $result['result'];
} catch (Exception $e) {
echo "Ошибка: " . $e->getMessage();
}
?>

Получение воронки продаж

<?php
try {
// Получение списка воронок
$categories = $api->call('crm.dealcategory.list');
foreach ($categories['result'] as $category) {
echo "Воронка: {$category['NAME']} (ID: {$category['ID']})\n";
// Получение этапов воронки
$stages = $api->call('crm.dealcategory.stage.list', [
'id' => $category['ID']
]);
foreach ($stages['result'] as $stage) {
echo "  - Этап: {$stage['NAME']} ({$stage['STATUS_ID']})\n";
}
}
} catch (Exception $e) {
echo "Ошибка: " . $e->getMessage();
}
?>

Работа с контактами и компаниями

Создание контакта

<?php
$contact_data = [
'NAME' => 'Анна',
'LAST_NAME' => 'Смирнова',
'TYPE_ID' => 'CLIENT',
'SOURCE_ID' => 'WEB',
'EMAIL' => [
['VALUE' => 'anna@company.ru', 'VALUE_TYPE' => 'WORK'],
['VALUE' => 'anna.personal@mail.ru', 'VALUE_TYPE' => 'HOME']
],
'PHONE' => [
['VALUE' => '+7 (495) 123-45-67', 'VALUE_TYPE' => 'WORK'],
['VALUE' => '+7 (906) 765-43-21', 'VALUE_TYPE' => 'MOBILE']
],
'POST' => 'Менеджер по закупкам',
'COMMENTS' => 'Ключевое лицо при принятии решений'
];
try {
$result = $api->call('crm.contact.add', ['fields' => $contact_data]);
echo "Контакт создан с ID: " . $result['result'];
} catch (Exception $e) {
echo "Ошибка: " . $e->getMessage();
}
?>

Создание компании

<?php
$company_data = [
'TITLE' => 'ООО "Рога и копыта"',
'COMPANY_TYPE' => 'CUSTOMER',
'INDUSTRY' => 'IT',
'EMPLOYEES' => 'EMPLOYEES_50',
'REVENUE' => 'REVENUE_1000000_5000000',
'EMAIL' => [['VALUE' => 'info@company.ru', 'VALUE_TYPE' => 'WORK']],
'PHONE' => [['VALUE' => '+7 (495) 123-45-67', 'VALUE_TYPE' => 'WORK']],
'WEB' => [['VALUE' => 'https://company.ru', 'VALUE_TYPE' => 'WORK']],
'ADDRESS' => 'г. Москва, ул. Примерная, д. 1',
'COMMENTS' => 'Перспективный клиент'
];
try {
$result = $api->call('crm.company.add', ['fields' => $company_data]);
echo "Компания создана с ID: " . $result['result'];
} catch (Exception $e) {
echo "Ошибка: " . $e->getMessage();
}
?>

Работа с пользовательскими полями

Пользовательские поля позволяют расширить стандартную функциональность CRM:

Создание пользовательского поля

<?php
$field_data = [
'ENTITY_ID' => 'CRM_LEAD',
'FIELD_NAME' => 'UF_LEAD_RATING',
'USER_TYPE_ID' => 'enumeration',
'EDIT_FORM_LABEL' => 'Рейтинг лида',
'LIST_COLUMN_LABEL' => 'Рейтинг',
'LIST_FILTER_LABEL' => 'Рейтинг',
'ERROR_MESSAGE' => 'Ошибка в поле рейтинг',
'HELP_MESSAGE' => 'Оценка качества лида',
'MULTIPLE' => 'N',
'MANDATORY' => 'N',
'SHOW_FILTER' => 'Y',
'SHOW_IN_LIST' => 'Y',
'EDIT_IN_LIST' => 'Y',
'IS_SEARCHABLE' => 'Y'
];
try {
$result = $api->call('crm.userfield.add', ['fields' => $field_data]);
$field_id = $result['result'];
// Добавление вариантов для списка
$enum_values = [
['VALUE' => 'Высокий', 'DEF' => 'N', 'SORT' => 100],
['VALUE' => 'Средний', 'DEF' => 'Y', 'SORT' => 200],
['VALUE' => 'Низкий', 'DEF' => 'N', 'SORT' => 300]
];
foreach ($enum_values as $enum_value) {
$api->call('crm.userfield.enumeration.add', [
'USER_FIELD_ID' => $field_id,
'fields' => $enum_value
]);
}
echo "Пользовательское поле создано с ID: " . $field_id;
} catch (Exception $e) {
echo "Ошибка: " . $e->getMessage();
}
?>

Батчевые операции

Для выполнения множественных операций эффективно использовать батчевые запросы:

<?php
// Создание нескольких лидов одним запросом
$batch_calls = [];
for ($i = 1; $i <= 5; $i++) {
$batch_calls["lead_$i"] = [
'method' => 'crm.lead.add',
'params' => [
'fields' => [
'TITLE' => "Лид № $i",
'NAME' => "Имя $i",
'LAST_NAME' => "Фамилия $i",
'EMAIL' => [['VALUE' => "email$i@example.com", 'VALUE_TYPE' => 'WORK']],
'STATUS_ID' => 'NEW'
]
]
];
}
try {
$result = $api->batch($batch_calls);
foreach ($result['result']['result'] as $key => $lead) {
echo "Лид $key создан с ID: " . $lead . "\n";
}
} catch (Exception $e) {
echo "Ошибка: " . $e->getMessage();
}
?>

Работа с файлами

API позволяет загружать и работать с файлами:

<?php
function uploadFile($api, $file_path, $filename) {
$file_content = base64_encode(file_get_contents($file_path));
$result = $api->call('disk.folder.uploadfile', [
'id' => 'upload', // ID папки или 'upload' для временной папки
'data' => [
'NAME' => $filename
],
'fileContent' => $file_content
]);
return $result['result'];
}
// Прикрепление файла к лиду
function attachFileToLead($api, $lead_id, $file_id) {
return $api->call('crm.lead.update', [
'ID' => $lead_id,
'fields' => [
'UF_CRM_LEAD_FILES' => [$file_id]
]
]);
}
// Пример использования
try {
$file_info = uploadFile($api, '/path/to/document.pdf', 'договор.pdf');
$result = attachFileToLead($api, 123, $file_info['ID']);
echo "Файл прикреплен к лиду";
} catch (Exception $e) {
echo "Ошибка: " . $e->getMessage();
}
?>

Работа с задачами

Создание и управление задачами через API:

<?php
$task_data = [
'TITLE' => 'Связаться с клиентом',
'DESCRIPTION' => 'Необходимо обсудить условия сделки',
'RESPONSIBLE_ID' => 1,
'CREATED_BY' => 1,
'DEADLINE' => date('c', strtotime('+3 days')),
'PRIORITY' => 2, // 1 - высокий, 2 - обычный
'GROUP_ID' => 0, // 0 - личная задача
'PARENT_ID' => 0, // ID родительской задачи
'DEPENDS_ON' => [], // массив ID задач, от которых зависит
'UF_CRM_TASK' => ['L_123'] // привязка к лиду с ID 123
];
try {
$result = $api->call('task.item.add', [
'arFields' => $task_data
]);
echo "Задача создана с ID: " . $result['result'];
} catch (Exception $e) {
echo "Ошибка: " . $e->getMessage();
}
?>

Обработка ошибок и лимитов

При работе с API важно учитывать ограничения и правильно обрабатывать ошибки:

<?php
class Bitrix24APIAdvanced extends Bitrix24API {
private $request_count = 0;
private $last_request_time = 0;
public function call($method, $params = []) {
// Соблюдение лимитов запросов (не более 2 запросов в секунду)
$current_time = time();
if ($current_time === $this->last_request_time) {
$this->request_count++;
if ($this->request_count >= 2) {
sleep(1);
$this->request_count = 0;
$this->last_request_time = time();
}
} else {
$this->request_count = 0;
$this->last_request_time = $current_time;
}
$max_retries = 3;
$retry_count = 0;
while ($retry_count < $max_retries) {
try {
return parent::call($method, $params);
} catch (Exception $e) {
$retry_count++;
// Если превышен лимит запросов, ждем
if (strpos($e->getMessage(), 'Query rate limit exceeded') !== false) {
sleep(1);
continue;
}
// Если это последняя попытка, выбрасываем исключение
if ($retry_count === $max_retries) {
throw $e;
}
// Ждем перед повторной попыткой
sleep(1);
}
}
}
}
?>

Практические примеры интеграции

Интеграция с формой обратной связи

<?php
// Обработка данных формы с сайта
if ($_POST['submit']) {
$name = $_POST['name'];
$email = $_POST['email'];
$phone = $_POST['phone'];
$message = $_POST['message'];
$api = new Bitrix24API('https://your-domain.bitrix24.ru/rest/1/webhook_code/');
// Поиск существующего контакта по email
$existing_contact = $api->call('crm.contact.list', [
'filter' => ['EMAIL' => $email],
'select' => ['ID', 'NAME', 'LAST_NAME']
]);
if (!empty($existing_contact['result'])) {
$contact_id = $existing_contact['result'][0]['ID'];
} else {
// Создание нового контакта
$contact_result = $api->call('crm.contact.add', [
'fields' => [
'NAME' => $name,
'EMAIL' => [['VALUE' => $email, 'VALUE_TYPE' => 'WORK']],
'PHONE' => [['VALUE' => $phone, 'VALUE_TYPE' => 'WORK']],
'SOURCE_ID' => 'WEB'
]
]);
$contact_id = $contact_result['result'];
}
// Создание лида
$lead_result = $api->call('crm.lead.add', [
'fields' => [
'TITLE' => 'Заявка с сайта: ' . $name,
'CONTACT_ID' => $contact_id,
'SOURCE_ID' => 'WEB',
'STATUS_ID' => 'NEW',
'COMMENTS' => $message
]
]);
// Создание задачи для менеджера
$api->call('task.item.add', [
'arFields' => [
'TITLE' => 'Обработать заявку: ' . $name,
'DESCRIPTION' => "Новая заявка с сайта:\nИмя: $name\nEmail: $email\nТелефон: $phone\nСообщение: $message",
'RESPONSIBLE_ID' => 1,
'DEADLINE' => date('c', strtotime('+1 hour')),
'PRIORITY' => 1,
'UF_CRM_TASK' => ['L_' . $lead_result['result']]
]
]);
echo "Заявка успешно отправлена!";
}
?>

Синхронизация с внешней системой

<?php
// Синхронизация заказов из интернет-магазина
function syncOrdersFromShop($api) {
// Получение заказов из внешней системы (например, из БД)
$orders = getOrdersFromExternalSystem();
foreach ($orders as $order) {
// Поиск существующей сделки по номеру заказа
$existing_deal = $api->call('crm.deal.list', [
'filter' => ['UF_CRM_ORDER_NUMBER' => $order['number']],
'select' => ['ID', 'STAGE_ID']
]);
if (!empty($existing_deal['result'])) {
// Обновление существующей сделки
$deal_id = $existing_deal['result'][0]['ID'];
$api->call('crm.deal.update', [
'ID' => $deal_id,
'fields' => [
'STAGE_ID' => mapOrderStatusToDealStage($order['status']),
'OPPORTUNITY' => $order['amount']
]
]);
} else {
// Создание новой сделки
$api->call('crm.deal.add', [
'fields' => [
'TITLE' => 'Заказ №' . $order['number'],
'STAGE_ID' => mapOrderStatusToDealStage($order['status']),
'OPPORTUNITY' => $order['amount'],
'CURRENCY_ID' => 'RUB',
'UF_CRM_ORDER_NUMBER' => $order['number'],
'BEGINDATE' => $order['date'],
'COMMENTS' => 'Заказ из интернет-магазина'
]
]);
}
}
}
function mapOrderStatusToDealStage($order_status) {
$mapping = [
'new' => 'NEW',
'paid' => 'PREPAYMENT_INVOICE',
'shipped' => 'PREPARATION',
'delivered' => 'WON',
'cancelled' => 'LOSE'
];
return $mapping[$order_status] ?? 'NEW';
}
?>

Отладка и логирование

Для эффективной отладки интеграций добавим логирование:

<?php
class Bitrix24APIWithLogging extends Bitrix24API {
private $log_file;
public function __construct($webhook_url, $log_file = 'bitrix24_api.log') {
parent::__construct($webhook_url);
$this->log_file = $log_file;
}
public function call($method, $params = []) {
$start_time = microtime(true);
try {
$result = parent::call($method, $params);
$this->log('SUCCESS', $method, $params, $result, microtime(true) - $start_time);
return $result;
} catch (Exception $e) {
$this->log('ERROR', $method, $params, $e->getMessage(), microtime(true) - $start_time);
throw $e;
}
}
private function log($status, $method, $params, $result, $execution_time) {
$log_entry = [
'timestamp' => date('Y-m-d H:i:s'),
'status' => $status,
'method' => $method,
'params' => $params,
'result' => $result,
'execution_time' => round($execution_time, 4)
];
file_put_contents(
$this->log_file,
json_encode($log_entry, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT) . "\n",
FILE_APPEND | LOCK_EX
);
}
}
?>

Безопасность и лучшие практики

При работе с REST API Битрикс24 следует соблюдать принципы безопасности:

• Никогда не храните токены доступа в открытом виде — используйте переменные окружения
• Используйте HTTPS для всех API-запросов
• Валидируйте входные данные перед отправкой в API
• Обрабатывайте ошибки корректно и не раскрывайте техническую информацию
• Соблюдайте лимиты запросов и используйте батчевые операции для массовых действий
• Регулярно обновляйте токены доступа при использовании OAuth

Мониторинг и производительность

Создадим класс для мониторинга производительности API:

<?php
class Bitrix24APIMonitor {
private $api;
private $metrics = [];
public function __construct($api) {
$this->api = $api;
}
public function call($method, $params = []) {
$start_time = microtime(true);
$start_memory = memory_get_usage();
try {
$result = $this->api->call($method, $params);
$this->recordMetric($method, true, microtime(true) - $start_time,
memory_get_usage() - $start_memory);
return $result;
} catch (Exception $e) {
$this->recordMetric($method, false, microtime(true) - $start_time,
memory_get_usage() - $start_memory);
throw $e;
}
}
private function recordMetric($method, $success, $execution_time, $memory_usage) {
if (!isset($this->metrics[$method])) {
$this->metrics[$method] = [
'calls' => 0,
'success' => 0,
'total_time' => 0,
'max_time' => 0,
'total_memory' => 0
];
}
$this->metrics[$method]['calls']++;
if ($success) $this->metrics[$method]['success']++;
$this->metrics[$method]['total_time'] += $execution_time;
$this->metrics[$method]['max_time'] = max($this->metrics[$method]['max_time'], $execution_time);
$this->metrics[$method]['total_memory'] += $memory_usage;
}
public function getMetrics() {
$result = [];
foreach ($this->metrics as $method => $data) {
$result[$method] = [
'calls' => $data['calls'],
'success_rate' => round($data['success'] / $data['calls'] * 100, 2),
'avg_time' => round($data['total_time'] / $data['calls'], 4),
'max_time' => round($data['max_time'], 4),
'avg_memory' => round($data['total_memory'] / $data['calls'])
];
}
return $result;
}
}
?>

Заключение

REST API Битрикс24 предоставляет мощные возможности для интеграции и автоматизации бизнес-процессов. Мы рассмотрели основные аспекты работы с API через PHP: от базовых операций с CRM-сущностями до создания сложных интеграций с внешними системами.

Ключевые моменты, которые следует помнить:

• Правильная авторизация — основа безопасной работы с API
• Соблюдение лимитов — залог стабильной работы интеграций
• Обработка ошибок — необходимый элемент надежного кода
• Логирование и мониторинг — инструменты для отладки и оптимизации
• Безопасность — защита данных и токенов доступа

Наша компания предоставляет полный спектр услуг по настройке и внедрению Битрикс24, включая разработку сложных интеграций через REST API. Мы поможем автоматизировать ваши бизнес-процессы, настроить синхронизацию с внешними системами и создать индивидуальные решения для максимальной эффективности работы с CRM.

Обращайтесь к нашим специалистам для получения персональной консультации и разработки решений, которые идеально подойдут для вашего бизнеса.