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

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

Основы работы с API сделок Битрикс24

API сделок в Битрикс24 предоставляет полный набор инструментов для управления воронкой продаж. Основные возможности включают:

• Создание новых сделок
• Получение списка существующих сделок
• Обновление данных сделки
• Удаление сделок
• Работа с дополнительными полями
• Управление связанными объектами

Авторизация и подготовка к работе

Для работы с API необходимо получить токен доступа. Это можно сделать несколькими способами:

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

Метод crm.deal.add: создание новых сделок

Основной метод для создания сделок — crm.deal.add. Он позволяет добавлять новые записи с заполнением всех необходимых полей.

Синтаксис и параметры

Базовый синтаксис запроса:

POST https://ваш-портал.bitrix24.ru/rest/crm.deal.add.json

Обязательные параметры:

• TITLE — название сделки
• STAGE_ID — идентификатор стадии воронки
• CATEGORY_ID — идентификатор направления (воронки)

Пример создания сделки

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

{
"fields": {
"TITLE": "Новая сделка из API",
"STAGE_ID": "NEW",
"CATEGORY_ID": 0,
"OPPORTUNITY": 50000,
"CURRENCY_ID": "RUB",
"CONTACT_ID": 123,
"COMPANY_ID": 456,
"ASSIGNED_BY_ID": 1,
"COMMENTS": "Сделка создана через API",
"SOURCE_ID": "WEB",
"SOURCE_DESCRIPTION": "Заявка с сайта"
}
}

Работа с дополнительными полями

Битрикс24 позволяет создавать пользовательские поля для сделок. Для работы с ними используется префикс UF_CRM_:

{
"fields": {
"TITLE": "Сделка с доп. полями",
"STAGE_ID": "NEW",
"UF_CRM_CUSTOM_FIELD": "Значение пользовательского поля",
"UF_CRM_DATETIME_FIELD": "2025-01-15T10:30:00+03:00"
}
}

Получение данных о сделках

Метод crm.deal.get

Для получения информации о конкретной сделке используется метод crm.deal.get:

GET https://ваш-портал.bitrix24.ru/rest/crm.deal.get.json?id=123

Метод crm.deal.list

Для получения списка сделок с возможностью фильтрации применяется crm.deal.list:

{
"filter": {
"STAGE_ID": "NEW",
"ASSIGNED_BY_ID": 1,
">=OPPORTUNITY": 10000
},
"select": ["ID", "TITLE", "OPPORTUNITY", "STAGE_ID", "DATE_CREATE"],
"order": {"DATE_CREATE": "DESC"},
"start": 0
}

Обновление существующих сделок

Метод crm.deal.update

Для изменения данных сделки используется метод crm.deal.update:

{
"id": 123,
"fields": {
"STAGE_ID": "PREPAYMENT_INVOICE",
"OPPORTUNITY": 75000,
"COMMENTS": "Обновлено через API"
}
}

Массовое обновление

Для обновления нескольких сделок одновременно можно использовать пакетные запросы:

{
"halt": 0,
"cmd": {
"deal_1": "crm.deal.update?id=123&fields[STAGE_ID]=PREPAYMENT_INVOICE",
"deal_2": "crm.deal.update?id=124&fields[STAGE_ID]=PREPAYMENT_INVOICE"
}
}

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

Получение описания полей

Для получения полного списка доступных полей используется метод crm.deal.fields:

GET https://ваш-портал.bitrix24.ru/rest/crm.deal.fields.json

Основные поля сделок

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

• ID — уникальный идентификатор
• TITLE — название сделки
• STAGE_ID — стадия воронки
• CATEGORY_ID — направление (воронка)
• OPPORTUNITY — сумма сделки
• CURRENCY_ID — валюта
• PROBABILITY — вероятность закрытия
• CONTACT_ID — связанный контакт
• COMPANY_ID — связанная компания
• ASSIGNED_BY_ID — ответственный
• CREATED_BY_ID — кто создал
• MODIFY_BY_ID — кто изменил
• DATE_CREATE — дата создания
• DATE_MODIFY — дата изменения
• BEGINDATE — дата начала
• CLOSEDATE — дата закрытия
• CLOSED — признак закрытой сделки
• SOURCE_ID — источник
• SOURCE_DESCRIPTION — описание источника

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

Создание сделки из формы на сайте

Типичный сценарий — создание сделки при отправке формы с сайта:

function createDealFromForm($formData) {
$dealData = [
'fields' => [
'TITLE' => 'Заявка с сайта: ' . $formData['service'],
'STAGE_ID' => 'NEW',
'CATEGORY_ID' => 0,
'OPPORTUNITY' => $formData['budget'] ?? 0,
'CURRENCY_ID' => 'RUB',
'ASSIGNED_BY_ID' => 1,
'SOURCE_ID' => 'WEB',
'SOURCE_DESCRIPTION' => 'Форма обратной связи',
'COMMENTS' => 'Телефон: ' . $formData['phone'] .
'\nEmail: ' . $formData['email'] .
'\nСообщение: ' . $formData['message'],
'UF_CRM_PHONE' => $formData['phone'],
'UF_CRM_EMAIL' => $formData['email']
]
];
// Отправка запроса к API
return sendRequest('crm.deal.add', $dealData);
}

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

Пример синхронизации данных из внешней CRM:

function syncExternalDeals($externalDeals) {
$results = [];
foreach ($externalDeals as $externalDeal) {
// Проверяем, существует ли сделка
$existingDeal = findDealByExternalId($externalDeal['external_id']);
$dealData = [
'TITLE' => $externalDeal['title'],
'OPPORTUNITY' => $externalDeal['amount'],
'STAGE_ID' => mapExternalStage($externalDeal['stage']),
'UF_CRM_EXTERNAL_ID' => $externalDeal['external_id'],
'DATE_MODIFY' => date('Y-m-d H:i:s')
];
if ($existingDeal) {
// Обновляем существующую сделку
$results[] = updateDeal($existingDeal['ID'], $dealData);
} else {
// Создаем новую сделку
$results[] = createDeal($dealData);
}
}
return $results;
}

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

Типичные ошибки при работе с API

Наиболее частые проблемы и их решения:

• Неверный STAGE_ID — проверьте актуальные стадии через crm.status.list
• Отсутствие прав доступа — убедитесь в корректности токена
• Неверный формат данных — проверьте типы полей через crm.deal.fields
• Превышение лимитов — используйте пакетные запросы для массовых операций

Логирование и мониторинг

Рекомендуется вести логи всех операций с API:

function logApiRequest($method, $params, $response) {
$logData = [
'timestamp' => date('Y-m-d H:i:s'),
'method' => $method,
'params' => $params,
'response' => $response,
'success' => !isset($response['error'])
];
file_put_contents('api_log.json', json_encode($logData) . "\n", FILE_APPEND);
}

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

Пакетные запросы

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

{
"halt": 0,
"cmd": {
"deal_1": "crm.deal.add?fields[TITLE]=Сделка 1&fields[STAGE_ID]=NEW",
"deal_2": "crm.deal.add?fields[TITLE]=Сделка 2&fields[STAGE_ID]=NEW",
"deal_3": "crm.deal.add?fields[TITLE]=Сделка 3&fields[STAGE_ID]=NEW"
}
}

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

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

function getStagesList($useCache = true) {
$cacheKey = 'bitrix24_stages';
$cacheTime = 3600; // 1 час
if ($useCache && $cached = getFromCache($cacheKey)) {
return $cached;
}
$stages = sendRequest('crm.status.list', [
'filter' => ['ENTITY_ID' => 'DEAL_STAGE']
]);
if ($useCache) {
setToCache($cacheKey, $stages, $cacheTime);
}
return $stages;
}

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

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

Основные рекомендации по безопасности:

• Храните токены в переменных окружения
• Используйте HTTPS для всех запросов
• Регулярно обновляйте токены
• Ограничивайте права доступа по принципу минимальных привилегий
• Ведите аудит всех операций

Валидация данных

Всегда проверяйте входящие данные перед отправкой в API:

function validateDealData($data) {
$errors = [];
if (empty($data['TITLE'])) {
$errors[] = 'Название сделки обязательно';
}
if (empty($data['STAGE_ID'])) {
$errors[] = 'Стадия сделки обязательна';
}
if (isset($data['OPPORTUNITY']) && !is_numeric($data['OPPORTUNITY'])) {
$errors[] = 'Сумма должна быть числом';
}
if (isset($data['CURRENCY_ID']) && !in_array($data['CURRENCY_ID'], ['RUB', 'USD', 'EUR'])) {
$errors[] = 'Неверный код валюты';
}
return $errors;
}

Интеграция с вебхуками

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

Настройка вебхуков

Основные события для отслеживания:

• ONCRMDEALUPDATE — обновление сделки
• ONCRMDEALDELETE — удаление сделки
• ONCRMDEALADD — добавление сделки

Обработка событий

function handleDealWebhook($eventData) {
switch ($eventData['event']) {
case 'ONCRMDEALUPDATE':
handleDealUpdate($eventData['data']);
break;
case 'ONCRMDEALADD':
handleDealAdd($eventData['data']);
break;
case 'ONCRMDEALDELETE':
handleDealDelete($eventData['data']);
break;
}
}

Заключение

Работа с API сделок Битрикс24 открывает широкие возможности для автоматизации и интеграции. Основные методы — crm.deal.add, crm.deal.update, crm.deal.get и crm.deal.list — позволяют полноценно управлять воронкой продаж программными средствами.

При разработке интеграций важно учитывать особенности API, правильно обрабатывать ошибки и следовать лучшим практикам безопасности. Использование пакетных запросов и кэширования поможет обеспечить высокую производительность решения.

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