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

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

Основы работы с API заказов Битрикс24

Битрикс24 предоставляет REST API для работы с заказами через семейство методов crm.deal. Эти методы позволяют создавать, читать, обновлять и удалять заказы, а также управлять связанными с ними данными.

Аутентификация и подключение

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

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

Пример подключения через веб-хук:

$webhook = "https://your-domain.bitrix24.ru/rest/1/webhook_code/";
$method = "crm.deal.list";
$params = [
"select" => ["ID", "TITLE", "STAGE_ID", "OPPORTUNITY"]
];
$url = $webhook . $method . "?" . http_build_query($params);
$response = file_get_contents($url);
$data = json_decode($response, true);

Основные методы API для работы с заказами

crm.deal.list — получение списка заказов

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

$params = [
"select" => ["ID", "TITLE", "STAGE_ID", "OPPORTUNITY", "CURRENCY_ID", "DATE_CREATE"],
"filter" => [
"STAGE_ID" => "NEW",
">=OPPORTUNITY" => 10000
],
"order" => ["DATE_CREATE" => "DESC"],
"start" => 0
];

crm.deal.get — получение конкретного заказа

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

$params = [
"id" => 123,
"select" => ["*", "UF_*"] // все поля включая пользовательские
];

crm.deal.add — создание нового заказа

Создание заказа с обязательными и дополнительными полями:

$params = [
"fields" => [
"TITLE" => "Новый заказ от API",
"STAGE_ID" => "NEW",
"OPPORTUNITY" => 50000,
"CURRENCY_ID" => "RUB",
"CONTACT_ID" => 1,
"COMPANY_ID" => 1,
"ASSIGNED_BY_ID" => 1,
"COMMENTS" => "Заказ создан через API"
]
];

crm.deal.update — обновление заказа

Обновление существующего заказа:

$params = [
"id" => 123,
"fields" => [
"STAGE_ID" => "PREPAYMENT_INVOICE",
"OPPORTUNITY" => 75000,
"COMMENTS" => "Обновлено через API"
]
];

Работа с дополнительными данными заказов

Товарные позиции в заказе

Для работы с товарными позициями используются методы crm.deal.productrows:

// Получение товарных позиций
$params = [
"id" => 123 // ID сделки
];
$method = "crm.deal.productrows.get";
// Установка товарных позиций
$params = [
"id" => 123,
"rows" => [
[
"PRODUCT_ID" => 1,
"PRICE" => 1000,
"QUANTITY" => 2,
"DISCOUNT_TYPE_ID" => 2, // процент
"DISCOUNT_RATE" => 10,
"TAX_RATE" => 20,
"TAX_INCLUDED" => "Y"
]
]
];
$method = "crm.deal.productrows.set";

Работа с файлами и документами

Прикрепление файлов к заказу:

// Сначала загружаем файл
$file_content = base64_encode(file_get_contents("/path/to/file.pdf"));
$params = [
"id" => 123,
"fields" => [
"UF_CRM_DEAL_FILE" => [
"fileData" => [
"name" => "document.pdf",
"type" => "application/pdf",
"content" => $file_content
]
]
]
];

Управление воронками и стадиями

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

Для работы с воронками используются методы crm.category:

$method = "crm.category.list";
$params = [
"entityTypeId" => 2 // 2 - для сделок
];

Получение стадий воронки

$method = "crm.status.list";
$params = [
"filter" => [
"ENTITY_ID" => "DEAL_STAGE"
]
];

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

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

Пример полной синхронизации заказов:

class Bitrix24OrderSync {
private $webhook;
public function __construct($webhook) {
$this->webhook = $webhook;
}
public function syncOrder($externalOrder) {
// Проверяем, существует ли заказ
$existingDeal = $this->findDealByExternalId($externalOrder['external_id']);
if ($existingDeal) {
return $this->updateDeal($existingDeal['ID'], $externalOrder);
} else {
return $this->createDeal($externalOrder);
}
}
private function findDealByExternalId($externalId) {
$params = [
"filter" => [
"UF_CRM_DEAL_EXTERNAL_ID" => $externalId
],
"select" => ["ID"]
];
$response = $this->callAPI("crm.deal.list", $params);
return $response['result'][0] ?? null;
}
private function createDeal($orderData) {
$params = [
"fields" => [
"TITLE" => $orderData['title'],
"STAGE_ID" => $this->mapStage($orderData['status']),
"OPPORTUNITY" => $orderData['amount'],
"CURRENCY_ID" => $orderData['currency'],
"UF_CRM_DEAL_EXTERNAL_ID" => $orderData['external_id'],
"COMMENTS" => $orderData['comments']
]
];
$response = $this->callAPI("crm.deal.add", $params);
if ($response['result'] && !empty($orderData['products'])) {
$this->setProductRows($response['result'], $orderData['products']);
}
return $response['result'];
}
private function callAPI($method, $params) {
$url = $this->webhook . $method;
$postData = http_build_query($params);
$context = stream_context_create([
'http' => [
'method' => 'POST',
'header' => 'Content-Type: application/x-www-form-urlencoded',
'content' => $postData
]
]);
$response = file_get_contents($url, false, $context);
return json_decode($response, true);
}
}

Автоматическое создание заказов из лидов

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

public function convertLeadToDeal($leadId) {
// Получаем данные лида
$lead = $this->callAPI("crm.lead.get", ["id" => $leadId]);
if (!$lead['result']) {
return false;
}
$leadData = $lead['result'];
// Создаем сделку на основе лида
$dealParams = [
"fields" => [
"TITLE" => "Заказ из лида: " . $leadData['TITLE'],
"STAGE_ID" => "NEW",
"OPPORTUNITY" => $leadData['OPPORTUNITY'] ?? 0,
"CURRENCY_ID" => $leadData['CURRENCY_ID'] ?? "RUB",
"CONTACT_ID" => $leadData['CONTACT_ID'],
"COMPANY_ID" => $leadData['COMPANY_ID'],
"ASSIGNED_BY_ID" => $leadData['ASSIGNED_BY_ID'],
"COMMENTS" => "Автоматически создано из лида #" . $leadId,
"UF_CRM_DEAL_LEAD_ID" => $leadId
]
];
$deal = $this->callAPI("crm.deal.add", $dealParams);
if ($deal['result']) {
// Обновляем лид, отмечая что он конвертирован
$this->callAPI("crm.lead.update", [
"id" => $leadId,
"fields" => [
"STATUS_ID" => "CONVERTED",
"UF_CRM_LEAD_DEAL_ID" => $deal['result']
]
]);
}
return $deal['result'];
}

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

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

Основные ошибки и способы их решения:

• ACCESS_DENIED — проверьте права доступа веб-хука или приложения
• INVALID_PARAMETER — проверьте корректность переданных параметров
• NOT_FOUND — объект с указанным ID не найден
• QUOTA_EXCEEDED — превышен лимит запросов, используйте паузы

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

Пример системы логирования API-запросов:

class BitrixAPILogger {
private $logFile;
public function __construct($logFile = '/var/log/bitrix24_api.log') {
$this->logFile = $logFile;
}
public function logRequest($method, $params, $response) {
$logEntry = [
'timestamp' => date('Y-m-d H:i:s'),
'method' => $method,
'params' => $params,
'response' => $response,
'success' => isset($response['result']),
'error' => $response['error'] ?? null
];
file_put_contents($this->logFile, json_encode($logEntry) . "\n", FILE_APPEND);
}
public function getErrorStats($period = '24 hours') {
$lines = file($this->logFile);
$errors = [];
$cutoff = strtotime("-{$period}");
foreach ($lines as $line) {
$entry = json_decode($line, true);
if ($entry && strtotime($entry['timestamp']) > $cutoff && !$entry['success']) {
$errors[] = $entry;
}
}
return $errors;
}
}

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

Батчевые запросы

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

$batch = [
"halt" => 0,
"cmd" => []
];
// Добавляем несколько команд в batch
for ($i = 0; $i < 10; $i++) {
$batch["cmd"]["deal_create_{$i}"] = "crm.deal.add?" . http_build_query([
"fields" => [
"TITLE" => "Массовый заказ #{$i}",
"STAGE_ID" => "NEW",
"OPPORTUNITY" => 1000 * ($i + 1)
]
]);
}
$response = $this->callAPI("batch", $batch);

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

Пример кеширования справочной информации:

class BitrixCache {
private $cacheDir = '/tmp/bitrix24_cache/';
private $ttl = 3600; // 1 час
public function get($key) {
$file = $this->cacheDir . md5($key) . '.cache';
if (file_exists($file) && (time() - filemtime($file)) < $this->ttl) {
return json_decode(file_get_contents($file), true);
}
return null;
}
public function set($key, $data) {
if (!is_dir($this->cacheDir)) {
mkdir($this->cacheDir, 0755, true);
}
$file = $this->cacheDir . md5($key) . '.cache';
file_put_contents($file, json_encode($data));
}
public function getCachedStages() {
$cacheKey = 'deal_stages';
$stages = $this->get($cacheKey);
if (!$stages) {
$response = $this->callAPI("crm.status.list", [
"filter" => ["ENTITY_ID" => "DEAL_STAGE"]
]);
$stages = $response['result'] ?? [];
$this->set($cacheKey, $stages);
}
return $stages;
}
}

Веб-хуки и автоматизация

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

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

// Регистрация обработчика события
$params = [
"event" => "ONCRMDEALADD",
"handler" => "https://your-domain.com/webhook/deal-add",
"auth_type" => 1
];
$response = $this->callAPI("event.bind", $params);

Обработка входящих веб-хуков

Пример обработчика входящих уведомлений:

class BitrixWebhookHandler {
public function handleDealAdd($data) {
$dealId = $data['data']['FIELDS']['ID'];
$dealData = $this->getDealData($dealId);
// Выполняем необходимые действия
$this->notifyManager($dealData);
$this->updateExternalSystem($dealData);
$this->logActivity($dealId, 'deal_created');
}
public function handleDealUpdate($data) {
$dealId = $data['data']['FIELDS']['ID'];
$dealData = $this->getDealData($dealId);
// Проверяем изменение стадии
if ($this->isStageChanged($data)) {
$this->processStageChange($dealData);
}
}
private function processStageChange($dealData) {
switch ($dealData['STAGE_ID']) {
case 'WON':
$this->processWonDeal($dealData);
break;
case 'LOSE':
$this->processLostDeal($dealData);
break;
default:
$this->updateDealProgress($dealData);
}
}
}

Интеграция с внешними системами

Синхронизация с интернет-магазином

Пример интеграции с популярными CMS:

class EcommerceIntegration {
private $bitrix24;
private $shopAPI;
public function syncOrderFromShop($shopOrderId) {
$shopOrder = $this->shopAPI->getOrder($shopOrderId);
if (!$shopOrder) {
return false;
}
// Создаем или обновляем контакт
$contactId = $this->syncCustomer($shopOrder['customer']);
// Создаем сделку
$dealData = [
"TITLE" => "Заказ #{$shopOrder['id']} с сайта",
"STAGE_ID" => $this->mapOrderStatus($shopOrder['status']),
"OPPORTUNITY" => $shopOrder['total'],
"CURRENCY_ID" => $shopOrder['currency'],
"CONTACT_ID" => $contactId,
"COMMENTS" => "Заказ с сайта, номер: {$shopOrder['id']}",
"UF_CRM_DEAL_SHOP_ORDER_ID" => $shopOrderId
];
$deal = $this->bitrix24->callAPI("crm.deal.add", ["fields" => $dealData]);
if ($deal['result']) {
// Добавляем товарные позиции
$this->syncOrderProducts($deal['result'], $shopOrder['items']);
}
return $deal['result'];
}
private function syncCustomer($customerData) {
// Ищем существующий контакт по email
$existingContact = $this->bitrix24->callAPI("crm.contact.list", [
"filter" => ["EMAIL" => $customerData['email']],
"select" => ["ID"]
]);
if (!empty($existingContact['result'])) {
return $existingContact['result'][0]['ID'];
}
// Создаем новый контакт
$contactData = [
"NAME" => $customerData['first_name'],
"LAST_NAME" => $customerData['last_name'],
"EMAIL" => [["VALUE" => $customerData['email'], "VALUE_TYPE" => "WORK"]],
"PHONE" => [["VALUE" => $customerData['phone'], "VALUE_TYPE" => "WORK"]],
"COMMENTS" => "Клиент с сайта"
];
$contact = $this->bitrix24->callAPI("crm.contact.add", ["fields" => $contactData]);
return $contact['result'];
}
}

Интеграция с платежными системами

Пример обработки платежей:

class PaymentIntegration {
public function processPaymentCallback($paymentData) {
$dealId = $this->findDealByPaymentId($paymentData['order_id']);
if (!$dealId) {
return false;
}
switch ($paymentData['status']) {
case 'success':
$this->markDealAsPaid($dealId, $paymentData);
break;
case 'failed':
$this->markPaymentFailed($dealId, $paymentData);
break;
case 'pending':
$this->markPaymentPending($dealId, $paymentData);
break;
}
}
private function markDealAsPaid($dealId, $paymentData) {
// Обновляем стадию сделки
$this->bitrix24->callAPI("crm.deal.update", [
"id" => $dealId,
"fields" => [
"STAGE_ID" => "PREPAYMENT_INVOICE",
"COMMENTS" => "Платеж подтвержден: {$paymentData['payment_id']}"
]
]);
// Добавляем дело
$this->bitrix24->callAPI("crm.activity.add", [
"fields" => [
"OWNER_TYPE_ID" => 2, // Сделка
"OWNER_ID" => $dealId,
"TYPE_ID" => 1, // Звонок
"SUBJECT" => "Платеж получен",
"DESCRIPTION" => "Платеж на сумму {$paymentData['amount']} получен",
"COMPLETED" => "Y",
"RESPONSIBLE_ID" => 1
]
]);
}
}

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

Защита API-ключей

Рекомендации по безопасности:

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

Управление правами доступа

Пример проверки прав доступа:

class BitrixSecurityManager {
private $allowedMethods = [
'read' => ['crm.deal.list', 'crm.deal.get'],
'write' => ['crm.deal.add', 'crm.deal.update'],
'delete' => ['crm.deal.delete']
];
public function checkPermission($userRole, $method) {
foreach ($this->allowedMethods as $permission => $methods) {
if (in_array($method, $methods)) {
return $this->hasPermission($userRole, $permission);
}
}
return false;
}
private function hasPermission($userRole, $permission) {
$rolePermissions = [
'admin' => ['read', 'write', 'delete'],
'manager' => ['read', 'write'],
'viewer' => ['read']
];
return in_array($permission, $rolePermissions[$userRole] ?? []);
}
}

Мониторинг и аналитика

Отслеживание KPI через API

Пример сбора аналитики по заказам:

class BitrixAnalytics {
public function getDealStats($dateFrom, $dateTo) {
$params = [
"filter" => [
">=DATE_CREATE" => $dateFrom,
"<=DATE_CREATE" => $dateTo
],
"select" => ["ID", "STAGE_ID", "OPPORTUNITY", "CURRENCY_ID", "DATE_CREATE", "ASSIGNED_BY_ID"]
];
$deals = $this->getAllDeals($params);
return [
'total_deals' => count($deals),
'total_amount' => $this->calculateTotalAmount($deals),
'conversion_rate' => $this->calculateConversionRate($deals),
'average_deal_size' => $this->calculateAverageDealSize($deals),
'deals_by_stage' => $this->groupDealsByStage($deals),
'deals_by_manager' => $this->groupDealsByManager($deals)
];
}
private function getAllDeals($params) {
$deals = [];
$start = 0;
do {
$params['start'] = $start;
$response = $this->bitrix24->callAPI("crm.deal.list", $params);
if ($response['result']) {
$deals = array_merge($deals, $response['result']);
$start += 50;
}
} while (!empty($response['result']));
return $deals;
}
private function calculateConversionRate($deals) {
$wonDeals = array_filter($deals, function($deal) {
return $deal['STAGE_ID'] === 'WON';
});
return count($deals) > 0 ? (count($wonDeals) / count($deals)) * 100 : 0;
}
}

Заключение

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

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

• Используйте batch-запросы для обработки больших объемов данных
• Реализуйте надежную систему обработки ошибок
• Кешируйте справочную информацию для повышения производительности
• Следуйте принципам безопасности при работе с API-ключами
• Мониторьте производительность и ведите логи всех операций

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