Сделки в CRM: обзор методов
Выберите инструмент для разработки с AI-агентом:
- используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
- используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации
Сделка — один из ключевых объектов CRM, в ней:
- можно управлять процессом продажи товара или услуги, включая отслеживание этапов и прием онлайн-платежей
- ведется диалог с клиентом: звонки, письма, чаты открытых линий
- вы можете просмотреть историю работы: дела, записи таймлайна
Быстрый переход: все методы и события
Пользовательская документация: сделки в Битрикс24
Связь сделок с другими объектами CRM
Клиент. Поле в карточке сделки, состоящее из связанных с ней компании и контактов. Все дела звонков, писем, чатов с контактом или компанией будут сохранены в карточке активной сделки. Компания в поле одна, обращение к ней происходит напрямую через поле сделки COMPANY_ID. Контактов может быть указано несколько, взаимодействие с ними ведется через отдельную группу методов crm.deal.contact.*.
Товары. Добавление, изменение, удаление товарных позиций в сделках возможно через группу методов crm.item.productrow.*.
Оплаты. Добавление, изменение, удаление документов оплаты в сделках возможно через группу методов crm.item.payment.*.
Пользовательская документация
Воронки и стадии сделок
Для сделок можно создавать различные воронки продаж и управлять ими через группу методов crm.category.* entityTypeId сделки = 2.
В каждой воронке будут свои стадии. Ими можно управлять через группу методов справочников CRM — crm.status.*. ENTITY_ID статусов сделок оригинальный у каждого направления — DEAL_STAGE_xx.
Получить историю движения сделки по стадиям можно через метод crm.stagehistory.list.
Пользовательская документация
Как изменить воронку сделки
Метод crm.deal.update может изменить только стадию сделки внутри текущей воронки. Если передать STAGE_ID, который не принадлежит текущей воронке, ничего не изменится.
Чтобы переместить сделку на стадию в другую воронку, используйте метод crm.item.update с параметрами:
entityTypeId—2для сделки,id—idсделки, которую перемещаете,categoryId—idворонки, куда перемещаете сделку. Получить можно методом crm.category.liststageId—idстадии в новой воронке. Получить можно методом crm.status.list
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"entityTypeId":2,"id":233,"fields":{"STAGE_ID":"EXECUTING","categoryId":0}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.item.update
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"entityTypeId":2,"id":233,"fields":{"STAGE_ID":"EXECUTING","categoryId":0},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/crm.item.update
// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame, ISODate } from '@bitrix24/b24jssdk'
declare const $b24: B24Frame
// crm.item.update (rest-v2) returns the updated element under `item`; fields per
// ../universal/crm-item-update.md
// Shape of the payload returned in result (the `item` object below)
type CrmItemUpdateResult = {
item: {
id: number
entityTypeId: number
title: string
categoryId: number
stageId: string
assignedById: number
opened: string
opportunity: number
currencyId: string
createdTime: ISODate
updatedTime: ISODate
}
}
try {
const response = await $b24.actions.v2.call.make<CrmItemUpdateResult>({
method: 'crm.item.update',
params: {
entityTypeId: 2,
id: 233,
fields: {
STAGE_ID: 'EXECUTING',
categoryId: 0,
},
},
requestId: Text.getUuidRfc4122()
})
// The payload is available only on a successful response
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
} else {
const result = response.getData()!.result
console.info('Updated item:', result.item.id, result.item.stageId)
}
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
async function updateDealStage() {
try {
// Initialize the SDK inside a Bitrix24 frame
const $b24 = await B24Js.initializeB24Frame()
const response = await $b24.actions.v2.call.make({
method: 'crm.item.update',
params: {
entityTypeId: 2,
id: 233,
fields: {
STAGE_ID: 'EXECUTING',
categoryId: 0,
},
},
requestId: B24Js.Text.getUuidRfc4122()
})
// The payload is available only on a successful response
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
return
}
const result = response.getData().result
console.info('Updated item:', result.item.id, result.item.stageId)
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
}
document.addEventListener('DOMContentLoaded', updateDealStage)
</script>
try {
$response = $b24Service
->core
->call(
'crm.item.update',
[
'entityTypeId' => 2,
'id' => 233,
'fields' => [
'STAGE_ID' => 'EXECUTING',
'categoryId' => 0
]
]
);
$result = $response
->getResponseData()
->getResult();
echo 'Success: ' . print_r($result, true);
processData($result);
} catch (Throwable $e) {
error_log($e->getMessage());
echo 'Error updating item: ' . $e->getMessage();
}
from b24pysdk.client import BaseClient
from b24pysdk.errors import BitrixAPIError, BitrixSDKException
client: BaseClient
try:
bitrix_response = client.crm.item.update(
bitrix_id=233,
fields={
"STAGE_ID": "EXECUTING",
"categoryId": 0,
},
entity_type_id=2,
).response
result = bitrix_response.result
print(result)
except BitrixAPIError as error:
print(
"Ошибка Bitrix API",
f"error: {error.error}",
f"error_description: {error.error_description}",
sep="\n",
)
except BitrixSDKException as error:
print(f"Ошибка Bitrix SDK: {error.message}")
except Exception as error:
print(f"Непредвиденная ошибка: {error}")
BX24.callMethod(
"crm.item.update",
{
entityTypeId: 2,
id: 233,
fields:
{
"STAGE_ID": "EXECUTING",
"categoryId": 0
},
},
(result) => {
result.error()
? console.error(result.error())
: console.info(result.data());
}
);
require_once('crest.php');
$result = CRest::call(
'crm.item.update',
[
'entityTypeId' => 2,
'id' => 233,
'fields' => [
'STAGE_ID' => 'EXECUTING',
'categoryId' => 0
]
]
);
echo '<PRE>';
print_r($result);
echo '</PRE>';
Карточка сделки
Основное рабочее пространство в сделке — это вкладка Общее ее карточки. Она состоит из двух частей:
-
левая, в ней располагаются поля с информацией. Если системных полей недостаточно, вы можете создать собственные пользовательские поля. Они позволяют хранить информацию в различных форматах данных: строка, число, ссылка, адрес и другие . Для создания, изменения, получения или удаления пользовательских полей сделок используется группа методов crm.deal.userfield.*
-
правая, в ней располагается таймлайн сделки. В нем можно создавать, редактировать, фильтровать, удалять дела CRM — группа методов crm.activity.*, и записи таймлайна — группа методов crm.timeline.*
Параметрами карточки сделки можно управлять в зависимости от воронки через группу методов crm.deal.details.configuration.*.
Пользовательская документация
Виджеты
В карточку сделки можно встроить приложение. Благодаря встраиванию можно будет использовать приложение и не покидать карточку сделки.
Есть два сценария встройки:
- Использовать специальные места встраивания. Например, через создание своей вкладки
- Создать пользовательское поле, в которое будет загружается интерфейс вашего приложения
Частые кейсы и сценарии
Регулярные сделки
Автоматическое создание однотипных регулярных сделок по шаблонам. Для управлениям шаблонами используется группа методов crm.deal.recurring.*.
Обзор методов и событий
Scope:
crmКто может выполнять метод: в зависимости от метода
Основные
|
Метод |
Описание |
|
Создает новую сделку |
|
|
Изменяет сделку |
|
|
Возвращает сделку по идентификатору |
|
|
Возвращает список сделок по фильтру |
|
|
Удаляет сделку и все связанные с ней объекты |
|
|
Возвращает описание полей сделки |
|
|
Добавляет товары в сделку |
|
|
Возвращает товары сделки |
|
Событие |
Вызывается |
|
При создании сделки |
|
|
При изменении сделки |
|
|
При удалении сделки |
|
|
При изменении воронки сделки |
Регулярные сделки
|
Метод |
Описание |
|
Создает новую регулярную сделку |
|
|
Возвращает список полей шаблона регулярной сделки |
|
|
Создает новую сделку из шаблона |
|
|
Изменяет существующие настройки для шаблона регулярной сделки |
|
|
Получает поля настройки шаблона регулярной сделки по Id |
|
|
Получает список настроек шаблонов регулярных сделок |
|
|
Удаляет существующие настройки для шаблона регулярной сделки |
|
Событие |
Вызывается |
|
При создании новой регулярной сделки |
|
|
При изменении регулярной сделки |
|
|
При удалении регулярной сделки |
|
|
При создании новой сделки из регулярной сделки |
Пользовательские поля
|
Метод |
Описание |
|
Создает новое пользовательское поле для сделок |
|
|
Изменяет существующее пользовательское поле сделок |
|
|
Получает пользовательское поле сделок по Id |
|
|
Получает списка пользовательских полей сделок |
|
|
Удаляет пользовательское поле сделок |
|
Событие |
Вызывается |
|
При добавлении пользовательского поля |
|
|
При изменении пользовательского поля |
|
|
При удалении пользовательского поля |
|
|
При изменении набора значений для пользовательского поля списочного типа |
Контакты сделки
|
Метод |
Описание |
|
Добавляет контакт к сделке |
|
|
Добавляет несколько контактов к сделке |
|
|
Возвращает поля связи сделка-контакт |
|
|
Получает набор контактов, связанных со сделкой |
|
|
Удаляет контакт из указанной сделки |
|
|
Удаляет набор контактов, связанных с указанной сделкой |
Управление карточками сделок
|
Метод |
Описание |
|
Получает настройки карточки сделок |
|
|
Сбрасывает настроек карточки сделок |
|
|
Позволяет установить настройки карточки сделок |
|
|
Принудительно устанавливает общую карточку сделок для всех пользователей |