Битрикс24 REST API в 2025: инструкция с примерами для начинающих разработчиков

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

Что такое Битрикс24 REST API

REST API Битрикс24 — это набор программных интерфейсов, позволяющих взаимодействовать с данными портала через HTTP-запросы. API дает возможность:

• Получать и изменять данные CRM (лиды, сделки, контакты, компании)
• Управлять задачами и проектами
• Работать с календарем и событиями
• Интегрироваться с внешними сервисами
• Автоматизировать рутинные операции

Подготовка к работе с API

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

Для работы с REST API необходимо получить токен доступа. Существует несколько способов авторизации:

• Входящий веб-хук — простой способ для внутренних интеграций
• Исходящий веб-хук — для получения уведомлений о событиях
• Локальное приложение — для создания собственных приложений
• OAuth 2.0 — для публичных приложений

Для начала работы создадим входящий веб-хук:

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

Основные методы работы с CRM

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

Лиды — это потенциальные клиенты в воронке продаж. Рассмотрим основные операции:

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

Пример запроса на получение списка лидов с фильтрацией:

// PHP пример
$webhook = 'https://your-domain.bitrix24.ru/rest/1/your-token/';
$queryUrl = $webhook . 'crm.lead.list';
$queryData = http_build_query(array(
'filter' => array(
'STATUS_ID' => 'NEW',
'>DATE_CREATE' => '2024-01-01T00:00:00'
),
'select' => array('ID', 'TITLE', 'NAME', 'LAST_NAME', 'PHONE', 'EMAIL'),
'order' => array('DATE_CREATE' => 'DESC')
));
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => $queryUrl,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $queryData,
));
$response = curl_exec($curl);
$responseData = json_decode($response, true);
if (isset($responseData['result'])) {
foreach ($responseData['result'] as $lead) {
echo "ID: " . $lead['ID'] . ", Название: " . $lead['TITLE'] . "\n";
}
}
curl_close($curl);

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

Пример создания лида с основными полями:

// JavaScript пример
const webhook = 'https://your-domain.bitrix24.ru/rest/1/your-token/';
const leadData = {
'TITLE': 'Новый лид из формы на сайте',
'NAME': 'Иван',
'LAST_NAME': 'Петров',
'PHONE': [{'VALUE': '+7 (999) 123-45-67', 'VALUE_TYPE': 'WORK'}],
'EMAIL': [{'VALUE': 'ivan@example.com', 'VALUE_TYPE': 'WORK'}],
'SOURCE_ID': 'WEB',
'STATUS_ID': 'NEW',
'COMMENTS': 'Заявка с сайта, интересуется услугами',
'UF_CRM_1234567890': 'Значение пользовательского поля'
};
fetch(webhook + 'crm.lead.add', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(leadData)
})
.then(response => response.json())
.then(data => {
if (data.result) {
console.log('Лид создан с ID:', data.result);
} else {
console.log('Ошибка:', data.error);
}
});

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

Сделки представляют активные продажи. Основные операции включают создание, обновление и получение данных.

Получение сделок с дополнительными данными

// Python пример
import requests
import json
webhook = 'https://your-domain.bitrix24.ru/rest/1/your-token/'
def get_deals():
url = webhook + 'crm.deal.list'
data = {
'filter': {
'CATEGORY_ID': 0,
'STAGE_ID': ['NEW', 'PREPARATION', 'PREPAIMENT']
},
'select': ['ID', 'TITLE', 'OPPORTUNITY', 'CURRENCY_ID', 'STAGE_ID', 'CONTACT_ID', 'COMPANY_ID'],
'order': {'DATE_CREATE': 'DESC'}
}
response = requests.post(url, json=data)
result = response.json()
if 'result' in result:
return result['result']
else:
print('Ошибка:', result.get('error', 'Неизвестная ошибка'))
return []
deals = get_deals()
for deal in deals:
print(f"Сделка: {deal['TITLE']}, Сумма: {deal['OPPORTUNITY']} {deal['CURRENCY_ID']}")

Обновление стадии сделки

// PHP пример обновления сделки
function updateDealStage($dealId, $newStage) {
global $webhook;
$queryUrl = $webhook . 'crm.deal.update';
$queryData = http_build_query(array(
'id' => $dealId,
'fields' => array(
'STAGE_ID' => $newStage,
'COMMENTS' => 'Стадия изменена через API ' . date('Y-m-d H:i:s')
)
));
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => $queryUrl,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $queryData,
));
$response = curl_exec($curl);
$responseData = json_decode($response, true);
curl_close($curl);
return isset($responseData['result']) ? $responseData['result'] : false;
}
// Использование
$result = updateDealStage(123, 'PREPARATION');
if ($result) {
echo "Сделка успешно обновлена";
} else {
echo "Ошибка при обновлении сделки";
}

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

Поиск контакта по email

// Node.js пример
const axios = require('axios');
const webhook = 'https://your-domain.bitrix24.ru/rest/1/your-token/';
async function findContactByEmail(email) {
try {
const response = await axios.post(webhook + 'crm.contact.list', {
filter: {
'EMAIL': email
},
select: ['ID', 'NAME', 'LAST_NAME', 'PHONE', 'EMAIL']
});
if (response.data.result && response.data.result.length > 0) {
return response.data.result[0];
}
return null;
} catch (error) {
console.error('Ошибка поиска контакта:', error);
return null;
}
}
// Использование
findContactByEmail('example@domain.com')
.then(contact => {
if (contact) {
console.log('Найден контакт:', contact.NAME + ' ' + contact.LAST_NAME);
} else {
console.log('Контакт не найден');
}
});

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

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

Получение списка пользовательских полей

// PHP пример получения пользовательских полей лидов
$queryUrl = $webhook . 'crm.lead.userfield.list';
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => $queryUrl,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
));
$response = curl_exec($curl);
$responseData = json_decode($response, true);
if (isset($responseData['result'])) {
foreach ($responseData['result'] as $field) {
echo "Поле: " . $field['FIELD_NAME'] . " - " . $field['LIST_COLUMN_LABEL'] . "\n";
}
}
curl_close($curl);

Обработка ошибок и отладка

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

Универсальная функция для API-запросов

// PHP класс для работы с Битрикс24 API
class Bitrix24API {
private $webhook;
public function __construct($webhook) {
$this->webhook = $webhook;
}
public function call($method, $params = array()) {
$queryUrl = $this->webhook . $method;
$queryData = http_build_query($params);
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => $queryUrl,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $queryData,
CURLOPT_TIMEOUT => 30,
CURLOPT_CONNECTTIMEOUT => 30,
));
$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$error = curl_error($curl);
curl_close($curl);
if ($error) {
throw new Exception('CURL Error: ' . $error);
}
if ($httpCode !== 200) {
throw new Exception('HTTP Error: ' . $httpCode);
}
$responseData = json_decode($response, true);
if (isset($responseData['error'])) {
throw new Exception('API Error: ' . $responseData['error_description']);
}
return $responseData;
}
}
// Использование
try {
$api = new Bitrix24API('https://your-domain.bitrix24.ru/rest/1/your-token/');
$result = $api->call('crm.lead.list', array(
'filter' => array('STATUS_ID' => 'NEW'),
'select' => array('ID', 'TITLE', 'NAME', 'LAST_NAME')
));
foreach ($result['result'] as $lead) {
echo "Лид: " . $lead['TITLE'] . "\n";
}
} catch (Exception $e) {
echo "Ошибка: " . $e->getMessage() . "\n";
}

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

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

Рассмотрим пример синхронизации лидов с внешней CRM-системой:

// Python пример синхронизации
import requests
import json
from datetime import datetime, timedelta
class BitrixSync:
def __init__(self, webhook):
self.webhook = webhook
self.session = requests.Session()
def get_new_leads(self, hours_back=24):
"""Получение новых лидов за последние N часов"""
date_filter = (datetime.now() - timedelta(hours=hours_back)).strftime('%Y-%m-%dT%H:%M:%S')
data = {
'filter': {
'>DATE_CREATE': date_filter
},
'select': ['ID', 'TITLE', 'NAME', 'LAST_NAME', 'PHONE', 'EMAIL', 'SOURCE_ID']
}
response = self.session.post(self.webhook + 'crm.lead.list', json=data)
result = response.json()
return result.get('result', [])
def update_lead_status(self, lead_id, status, comment=''):
"""Обновление статуса лида"""
data = {
'id': lead_id,
'fields': {
'STATUS_ID': status,
'COMMENTS': comment
}
}
response = self.session.post(self.webhook + 'crm.lead.update', json=data)
return response.json()
def sync_with_external_system(self):
"""Синхронизация с внешней системой"""
leads = self.get_new_leads()
for lead in leads:
try:
# Отправка данных во внешнюю систему
external_response = self.send_to_external_system(lead)
if external_response['success']:
# Обновление статуса в Битрикс24
self.update_lead_status(
lead['ID'],
'IN_PROCESS',
f"Синхронизирован с внешней системой: {external_response['external_id']}"
)
print(f"Лид {lead['ID']} успешно синхронизирован")
else:
print(f"Ошибка синхронизации лида {lead['ID']}: {external_response['error']}")
except Exception as e:
print(f"Ошибка при обработке лида {lead['ID']}: {str(e)}")
def send_to_external_system(self, lead):
"""Отправка данных во внешнюю систему (заглушка)"""
# Здесь должна быть логика отправки во внешнюю систему
return {'success': True, 'external_id': 'EXT_' + str(lead['ID'])}
# Использование
sync = BitrixSync('https://your-domain.bitrix24.ru/rest/1/your-token/')
sync.sync_with_external_system()

Создание отчетов и аналитики

Пример создания отчета по конверсии лидов в сделки:

// JavaScript пример создания отчета
class BitrixAnalytics {
constructor(webhook) {
this.webhook = webhook;
}
async getLeadConversionReport(dateFrom, dateTo) {
try {
// Получение лидов за период
const leadsResponse = await fetch(this.webhook + 'crm.lead.list', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
filter: {
'>=DATE_CREATE': dateFrom,
'<=DATE_CREATE': dateTo
},
select: ['ID', 'TITLE', 'SOURCE_ID', 'STATUS_ID', 'DATE_CREATE']
})
});
const leads = await leadsResponse.json();
// Получение сделок за период
const dealsResponse = await fetch(this.webhook + 'crm.deal.list', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
filter: {
'>=DATE_CREATE': dateFrom,
'<=DATE_CREATE': dateTo
},
select: ['ID', 'TITLE', 'LEAD_ID', 'STAGE_ID', 'OPPORTUNITY']
})
});
const deals = await dealsResponse.json();
// Анализ данных
const report = this.analyzeConversion(leads.result, deals.result);
return report;
} catch (error) {
console.error('Ошибка при создании отчета:', error);
return null;
}
}
analyzeConversion(leads, deals) {
const report = {
totalLeads: leads.length,
convertedLeads: 0,
conversionRate: 0,
totalDealAmount: 0,
averageDealAmount: 0,
sourceAnalysis: {}
};
// Подсчет конверсий
const convertedLeadIds = deals.map(deal => deal.LEAD_ID).filter(id => id);
report.convertedLeads = convertedLeadIds.length;
report.conversionRate = (report.convertedLeads / report.totalLeads * 100).toFixed(2);
// Анализ суммы сделок
report.totalDealAmount = deals.reduce((sum, deal) => sum + parseFloat(deal.OPPORTUNITY || 0), 0);
report.averageDealAmount = deals.length > 0 ? (report.totalDealAmount / deals.length).toFixed(2) : 0;
// Анализ по источникам
leads.forEach(lead => {
const source = lead.SOURCE_ID || 'UNKNOWN';
if (!report.sourceAnalysis[source]) {
report.sourceAnalysis[source] = {
totalLeads: 0,
convertedLeads: 0,
conversionRate: 0
};
}
report.sourceAnalysis[source].totalLeads++;
if (convertedLeadIds.includes(lead.ID)) {
report.sourceAnalysis[source].convertedLeads++;
}
});
// Расчет конверсии по источникам
Object.keys(report.sourceAnalysis).forEach(source => {
const sourceData = report.sourceAnalysis[source];
sourceData.conversionRate = (sourceData.convertedLeads / sourceData.totalLeads * 100).toFixed(2);
});
return report;
}
}
// Использование
const analytics = new BitrixAnalytics('https://your-domain.bitrix24.ru/rest/1/your-token/');
analytics.getLeadConversionReport('2024-01-01T00:00:00', '2024-01-31T23:59:59')
.then(report => {
console.log('Отчет по конверсии:');
console.log(`Всего лидов: ${report.totalLeads}`);
console.log(`Конвертировано: ${report.convertedLeads}`);
console.log(`Конверсия: ${report.conversionRate}%`);
console.log(`Средняя сумма сделки: ${report.averageDealAmount}`);
console.log('\nАнализ по источникам:');
Object.entries(report.sourceAnalysis).forEach(([source, data]) => {
console.log(`${source}: ${data.totalLeads} лидов, конверсия ${data.conversionRate}%`);
});
});

Оптимизация и производительность

Пакетные операции

Для повышения производительности используйте пакетные операции:

// PHP пример пакетного создания лидов
function createLeadsBatch($leads) {
global $webhook;
$commands = array();
foreach ($leads as $index => $leadData) {
$commands['lead_' . $index] = 'crm.lead.add?' . http_build_query(array('fields' => $leadData));
}
$queryUrl = $webhook . 'batch';
$queryData = http_build_query(array('cmd' => $commands));
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => $queryUrl,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $queryData,
));
$response = curl_exec($curl);
$responseData = json_decode($response, true);
curl_close($curl);
return $responseData;
}
// Пример использования
$leadsToCreate = array(
array(
'TITLE' => 'Лид 1',
'NAME' => 'Иван',
'LAST_NAME' => 'Петров',
'SOURCE_ID' => 'WEB'
),
array(
'TITLE' => 'Лид 2',
'NAME' => 'Анна',
'LAST_NAME' => 'Сидорова',
'SOURCE_ID' => 'CALL'
)
);
$result = createLeadsBatch($leadsToCreate);

Кэширование данных

Для часто используемых данных реализуйте кэширование:

// PHP пример с кэшированием
class BitrixCache {
private $webhook;
private $cache = array();
private $cacheTime = 300; // 5 минут
public function __construct($webhook) {
$this->webhook = $webhook;
}
public function getUsers() {
$cacheKey = 'users_list';
if (isset($this->cache[$cacheKey]) &&
time() - $this->cache[$cacheKey]['timestamp'] < $this->cacheTime) {
return $this->cache[$cacheKey]['data'];
}
// Получение данных из API
$queryUrl = $this->webhook . 'user.get';
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => $queryUrl,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
));
$response = curl_exec($curl);
$responseData = json_decode($response, true);
curl_close($curl);
if (isset($responseData['result'])) {
$this->cache[$cacheKey] = array(
'data' => $responseData['result'],
'timestamp' => time()
);
return $responseData['result'];
}
return array();
}
}

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

Защита токенов доступа

Важные правила безопасности при работе с API:

• Никогда не передавайте токены в URL — используйте POST-запросы
• Храните токены в переменных окружения — не включайте их в код
• Ограничивайте права доступа — давайте только необходимые разрешения
• Используйте HTTPS — всегда шифруйте соединение
• Логируйте запросы — ведите журнал для отладки и мониторинга

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

// PHP пример с обработкой лимитов
class BitrixRateLimiter {
private $webhook;
private $requestCount = 0;
private $lastRequestTime = 0;
private $maxRequestsPerSecond = 2;
public function __construct($webhook) {
$this->webhook = $webhook;
}
public function makeRequest($method, $params = array()) {
$this->checkRateLimit();
$queryUrl = $this->webhook . $method;
$queryData = http_build_query($params);
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => $queryUrl,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $queryData,
));
$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
$this->requestCount++;
$this->lastRequestTime = time();
if ($httpCode === 429) {
// Лимит превышен, ждем и повторяем
sleep(1);
return $this->makeRequest($method, $params);
}
return json_decode($response, true);
}
private function checkRateLimit() {
$currentTime = time();
if ($currentTime === $this->lastRequestTime) {
if ($this->requestCount >= $this->maxRequestsPerSecond) {
sleep(1);
$this->requestCount = 0;
}
} else {
$this->requestCount = 0;
}
}
}

Мониторинг и логирование

Для эффективной работы с API необходимо настроить мониторинг и логирование:

// PHP класс для логирования API-запросов
class BitrixLogger {
private $logFile;
public function __construct($logFile = 'bitrix_api.log') {
$this->logFile = $logFile;
}
public function log($level, $message, $context = array()) {
$timestamp = date('Y-m-d H:i:s');
$contextString = empty($context) ? '' : ' ' . json_encode($context);
$logEntry = "[$timestamp] [$level] $message$contextString" . PHP_EOL;
file_put_contents($this->logFile, $logEntry, FILE_APPEND | LOCK_EX);
}
public function logRequest($method, $params, $response, $executionTime) {
$this->log('INFO', "API Request: $method", array(
'params' => $params,
'response_size' => strlen(json_encode($response)),
'execution_time' => $executionTime . 'ms',
'success' => isset($response['result'])
));
}
public function logError($message, $context = array()) {
$this->log('ERROR', $message, $context);
}
}
// Использование
$logger = new BitrixLogger();
$startTime = microtime(true);
// Выполнение API-запроса
$response = $api->call('crm.lead.list', $params);
$endTime = microtime(true);
$executionTime = round(($endTime - $startTime) * 1000, 2);
$logger->logRequest('crm.lead.list', $params, $response, $executionTime);

Заключение

Битрикс24 REST API предоставляет мощные возможности для интеграции и автоматизации бизнес-процессов. Мы рассмотрели основные методы работы с CRM-данными, примеры создания интеграций, вопросы безопасности и оптимизации производительности.

Ключевые моменты для успешной работы с API:

• Правильная настройка авторизации и безопасности
• Использование пакетных операций для повышения производительности
• Реализация обработки ошибок и логирования
• Соблюдение лимитов API и лучших практик
• Тестирование и мониторинг интеграций

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