Создать новую сделку crm.deal.add
Выберите инструмент для разработки с AI-агентом:
- используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
- используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации
Scope:
crmКто может выполнять метод: любой пользователь с правом «добавления» сделок
DEPRECATED
Развитие метода остановлено. Используйте crm.item.add.
Метод crm.deal.add создает новую сделку.
Параметры метода
|
Название |
Описание |
|
fields |
Объект формата:
где:
Список доступных полей описан ниже |
|
params |
Объект, содержащий дополнительный набор параметров (подробное описание) |
Параметр fields
|
Название |
Описание |
|
TITLE |
Название сделки. По умолчанию генерируется по шаблону |
|
TYPE_ID |
Строковый идентификатор типа сделки. Список доступных типов сделки можно узнать с помощью метода crm.status.list, применив фильтр По умолчанию — первый доступный тип сделки |
|
CATEGORY_ID |
Идентификатор воронки. Обязательно больше или равен 0. Список доступных воронок можно узнать с помощью метода crm.category.list, передав По умолчанию — идентификатор воронки по умолчанию |
|
STAGE_ID |
Стадия сделки. Список доступных стадий можно узнать с помощью метода crm.status.list, применив фильтр:
По умолчанию — первая доступная стадия относительно воронки |
|
IS_RECURRING |
Является ли сделка шаблоном регулярной сделки. Возможные значения:
По умолчанию |
|
IS_RETURN_CUSTOMER |
Является ли сделка повторной. Возможные значения:
По умолчанию |
|
IS_REPEATED_APPROACH |
Является ли сделка повторным обращением. Возможные значения:
По умолчанию |
|
PROBABILITY |
Вероятность, % |
|
CURRENCY_ID |
Валюта. Список доступных валют можно узнать с помощью метода crm.currency.list |
|
OPPORTUNITY |
Сумма. По умолчанию |
|
IS_MANUAL_OPPORTUNITY |
Включен ли режим ручного подсчета суммы. Возможные значения:
По умолчанию |
|
TAX_VALUE |
Сумма налога. По умолчанию |
|
COMPANY_ID |
Идентификатор компании, привязанной к сделке. Список компаний можно узнать с помощью метода crm.item.list, передав |
|
CONTACT_ID |
Контакт. Устаревшее |
|
CONTACT_IDS |
Список привязанных к сделке контактов. Список контактов можно узнать с помощью метода crm.item.list, передав |
|
BEGINDATE |
Дата начала. По умолчанию — дата создания сделки |
|
CLOSEDATE |
Дата завершения. По умолчанию — дата создания сделки плюс 7 дней |
|
OPENED |
Доступна ли сделка для всех. Возможные значения:
По умолчанию |
|
CLOSED |
Является ли сделка закрытой. Возможные значения:
По умолчанию |
|
COMMENTS |
Комментарий. Поддерживает bb-коды |
|
ASSIGNED_BY_ID |
Ответственный. По умолчанию — пользователь, вызывающий данный метод |
|
SOURCE_ID |
Строковый идентификатор типа источника. Список доступных источников можно узнать с помощью метода crm.status.list, применив фильтр По умолчанию — первый доступный тип источника |
|
SOURCE_DESCRIPTION |
Дополнительно об источнике |
|
ADDITIONAL_INFO |
Дополнительная информация |
|
LOCATION_ID |
Местоположение клиента. Служебное поле |
|
ORIGINATOR_ID |
Идентификатор источника данных. Используется только для привязки к внешнему источнику |
|
ORIGIN_ID |
Идентификатор элемента в источнике данных. Используется только для привязки к внешнему источнику |
|
UTM_SOURCE |
Рекламная система (Google-Adwords и другие) |
|
UTM_MEDIUM |
Тип трафика. Возможные значения:
|
|
UTM_CAMPAIGN |
Обозначение рекламной кампании |
|
UTM_CONTENT |
Содержание кампании. Например, для контекстных объявлений |
|
UTM_TERM |
Условие поиска кампании. Например, ключевые слова контекстной рекламы |
|
TRACE |
Информация для сквозной аналитики — подробнее читайте в статье Как передать данные в сквозную аналитику CRM |
|
UF_CRM_... |
Пользовательские поля. Например, В зависимости от настроек портала у сделок может быть набор пользовательских полей определенных типов. Добавить пользовательское поле в сделку можно с помощью метода crm.deal.userfield.add |
|
PARENT_ID_... |
Поля связей. Если на портале есть смарт-процессы, связанные со сделками, для каждого такого смарт-процесса существует поле, хранящее связь между этим смарт-процессом и сделкой. Само поле хранит идентификатор элемента такого смарт-процесса. Например, поле |
Параметр params
|
Название |
Описание |
|
REGISTER_SONET_EVENT |
Зарегистрировать ли событие добавления сделки в живой ленте. Возможные значения:
По умолчанию |
Примеры кода
Как использовать примеры в документации
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"FIELDS":{"TITLE":"Новая сделка #1","TYPE_ID":"COMPLEX","CATEGORY_ID":0,"STAGE_ID":"PREPARATION","IS_RECURRING":"N","IS_RETURN_CUSTOMER":"Y","IS_REPEATED_APPROACH":"Y","PROBABILITY":99,"CURRENCY_ID":"EUR","OPPORTUNITY":1000000,"IS_MANUAL_OPPORTUNITY":"Y","TAX_VALUE":0.10,"COMPANY_ID":9,"CONTACT_IDS":[84,83],"BEGINDATE":"'"$(date --iso-8601=seconds)"'","CLOSEDATE":"'"$(date --iso-8601=seconds --date='+10 days')"'", "OPENED":"Y","CLOSED":"N","COMMENTS":"Пример комментария","SOURCE_ID":"CALLBACK","SOURCE_DESCRIPTION":"Дополнительно об источнике","ADDITIONAL_INFO":"Дополнительная информация","UTM_SOURCE":"google","UTM_MEDIUM":"CPC","PARENT_ID_1220":22,"UF_CRM_1721244482250":"Привет мир!"},"PARAMS":{"REGISTER_SONET_EVENT":"N"}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.deal.add
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"FIELDS":{"TITLE":"Новая сделка #1","TYPE_ID":"COMPLEX","CATEGORY_ID":0,"STAGE_ID":"PREPARATION","IS_RECURRING":"N","IS_RETURN_CUSTOMER":"Y","IS_REPEATED_APPROACH":"Y","PROBABILITY":99,"CURRENCY_ID":"EUR","OPPORTUNITY":1000000,"IS_MANUAL_OPPORTUNITY":"Y","TAX_VALUE":0.10,"COMPANY_ID":9,"CONTACT_IDS":[84,83],"BEGINDATE":"'"$(date --iso-8601=seconds)"'","CLOSEDATE":"'"$(date --iso-8601=seconds --date='+10 days')"'", "OPENED":"Y","CLOSED":"N","COMMENTS":"Пример комментария","SOURCE_ID":"CALLBACK","SOURCE_DESCRIPTION":"Дополнительно об источнике","ADDITIONAL_INFO":"Дополнительная информация","UTM_SOURCE":"google","UTM_MEDIUM":"CPC","PARENT_ID_1220":22,"UF_CRM_1721244482250":"Привет мир!"},"PARAMS":{"REGISTER_SONET_EVENT":"N"},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/crm.deal.add
// 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 } from '@bitrix24/b24jssdk'
declare const $b24: B24Frame
const day = 60 * 60 * 24 * 1000
const now = new Date()
const after10Days = new Date(now.getTime() + 10 * day)
try {
const response = await $b24.actions.v2.call.make<number>({
method: 'crm.deal.add',
params: {
fields: {
TITLE: 'New deal #1',
TYPE_ID: 'COMPLEX',
CATEGORY_ID: 0,
STAGE_ID: 'PREPARATION',
IS_RECURRING: 'N',
IS_RETURN_CUSTOMER: 'Y',
IS_REPEATED_APPROACH: 'Y',
PROBABILITY: 99,
CURRENCY_ID: 'EUR',
OPPORTUNITY: 1000000,
IS_MANUAL_OPPORTUNITY: 'Y',
TAX_VALUE: 0.10,
COMPANY_ID: 9,
CONTACT_IDS: [84, 83],
BEGINDATE: now.toISOString(),
CLOSEDATE: after10Days.toISOString(),
OPENED: 'Y',
CLOSED: 'N',
COMMENTS: '[B]Sample comment[/B]',
SOURCE_ID: 'CALLBACK',
SOURCE_DESCRIPTION: 'Additional information about the source',
ADDITIONAL_INFO: 'Additional information',
UTM_SOURCE: 'google',
UTM_MEDIUM: 'CPC',
PARENT_ID_1220: 22,
UF_CRM_1721244482250: 'Hello world!',
},
params: {
REGISTER_SONET_EVENT: 'N',
},
},
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('Created deal id:', result)
}
} 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 addDeal() {
try {
// Initialize the SDK inside a Bitrix24 frame
const $b24 = await B24Js.initializeB24Frame()
const day = 60 * 60 * 24 * 1000
const now = new Date()
const after10Days = new Date(now.getTime() + 10 * day)
const response = await $b24.actions.v2.call.make({
method: 'crm.deal.add',
params: {
fields: {
TITLE: 'New deal #1',
TYPE_ID: 'COMPLEX',
CATEGORY_ID: 0,
STAGE_ID: 'PREPARATION',
IS_RECURRING: 'N',
IS_RETURN_CUSTOMER: 'Y',
IS_REPEATED_APPROACH: 'Y',
PROBABILITY: 99,
CURRENCY_ID: 'EUR',
OPPORTUNITY: 1000000,
IS_MANUAL_OPPORTUNITY: 'Y',
TAX_VALUE: 0.10,
COMPANY_ID: 9,
CONTACT_IDS: [84, 83],
BEGINDATE: now.toISOString(),
CLOSEDATE: after10Days.toISOString(),
OPENED: 'Y',
CLOSED: 'N',
COMMENTS: '[B]Sample comment[/B]',
SOURCE_ID: 'CALLBACK',
SOURCE_DESCRIPTION: 'Additional information about the source',
ADDITIONAL_INFO: 'Additional information',
UTM_SOURCE: 'google',
UTM_MEDIUM: 'CPC',
PARENT_ID_1220: 22,
UF_CRM_1721244482250: 'Hello world!',
},
params: {
REGISTER_SONET_EVENT: 'N',
},
},
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('Created deal id:', result)
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
}
document.addEventListener('DOMContentLoaded', addDeal)
</script>
try {
$fields = [
'TITLE' => 'New Deal',
'TYPE_ID' => 'GIG',
'CATEGORY_ID' => '1',
'STAGE_ID' => 'C1:NEW',
'CURRENCY_ID' => 'USD',
'OPPORTUNITY' => '10000',
'BEGINDATE' => (new DateTime())->format(DateTime::ATOM),
'CLOSEDATE' => (new DateTime('+1 month'))->format(DateTime::ATOM),
'COMMENTS' => 'This is a test deal.',
];
$params = [
'REGISTER_SONET_EVENT' => 'Y',
];
$result = $serviceBuilder
->getCRMScope()
->deal()
->add($fields, $params);
print($result->getId());
} catch (Throwable $e) {
print('Error: ' . $e->getMessage());
}
const day = 60 * 60 * 24 * 1000;
const now = new Date();
const after10Days = new Date(now.getTime() + 10 * day);
BX24.callMethod(
'crm.deal.add',
{
fields: {
TITLE: "Новая сделка #1",
TYPE_ID: "COMPLEX",
CATEGORY_ID: 0,
STAGE_ID: "PREPARATION",
IS_RECURRING: "N",
IS_RETURN_CUSTOMER: "Y",
IS_REPEATED_APPROACH: "Y",
PROBABILITY: 99,
CURRENCY_ID: "EUR",
OPPORTUNITY: 1000000,
IS_MANUAL_OPPORTUNITY: "Y",
TAX_VALUE: 0.10,
COMPANY_ID: 9,
CONTACT_IDS: [84, 83],
BEGINDATE: now.toISOString(),
CLOSEDATE: after10Days.toISOString(),
OPENED: "Y",
CLOSED: "N",
COMMENTS: "[B]Пример комментария[/B]",
SOURCE_ID: "CALLBACK",
SOURCE_DESCRIPTION: "Дополнительно об источнике",
ADDITIONAL_INFO: "Дополнительная информация",
UTM_SOURCE: "google",
UTM_MEDIUM: "CPC",
PARENT_ID_1220: 22,
UF_CRM_1721244482250: "Привет мир!",
},
params: {
REGISTER_SONET_EVENT: "N",
},
},
(result) => {
result.error()
? console.error(result.error())
: console.info(result.data())
;
},
);
require_once('crest.php');
$result = CRest::call(
'crm.deal.add',
[
'FIELDS' => [
'TITLE' => 'Новая сделка #1',
'TYPE_ID' => 'COMPLEX',
'CATEGORY_ID' => 0,
'STAGE_ID' => 'PREPARATION',
'IS_RECURRING' => 'N',
'IS_RETURN_CUSTOMER' => 'Y',
'IS_REPEATED_APPROACH' => 'Y',
'PROBABILITY' => 99,
'CURRENCY_ID' => 'EUR',
'OPPORTUNITY' => 1000000,
'IS_MANUAL_OPPORTUNITY' => 'Y',
'TAX_VALUE' => 0.10,
'COMPANY_ID' => 9,
'CONTACT_IDS' => [84, 83],
'BEGINDATE' => (new DateTime())->format(DateTime::ATOM),
'CLOSEDATE' => (new DateTime('+10 days'))->format(DateTime::ATOM),
'OPENED' => 'Y',
'CLOSED' => 'N',
'COMMENTS' => 'Пример комментария',
'SOURCE_ID' => 'CALLBACK',
'SOURCE_DESCRIPTION' => 'Дополнительно об источнике',
'ADDITIONAL_INFO' => 'Дополнительная информация',
'UTM_SOURCE' => 'google',
'UTM_MEDIUM' => 'CPC',
'PARENT_ID_1220' => 22,
'UF_CRM_1721244482250' => 'Привет мир!',
],
'PARAMS' => [
'REGISTER_SONET_EVENT' => 'N',
],
]
);
echo '<PRE>';
print_r($result);
echo '</PRE>';
Пример
from b24pysdk.client import BaseClient
from b24pysdk.errors import BitrixAPIError, BitrixSDKException
client: BaseClient
try:
bitrix_response = client.crm.deal.add(
fields={
"TITLE": "Enterprise License Renewal",
"TYPE_ID": "SALE",
"CATEGORY_ID": 0,
"STAGE_ID": "NEW",
"CURRENCY_ID": "USD",
"OPPORTUNITY": 25000,
"IS_MANUAL_OPPORTUNITY": "Y",
"ASSIGNED_BY_ID": 1,
"OPENED": "Y",
"COMMENTS": "Renewal negotiation in progress",
"SOURCE_ID": "WEB",
"UTM_SOURCE": "google",
"UTM_MEDIUM": "cpc",
"UTM_CAMPAIGN": "q2_pipeline",
},
params={"REGISTER_SONET_EVENT": "Y"},
).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}")
Обработка ответа
HTTP-статус: 200
{
"result": 394,
"time": {
"start": 1725013197.635808,
"finish": 1725013198.580873,
"duration": 0.9450650215148926,
"processing": 0.6822988986968994,
"date_start": "2024-08-30T12:19:57+02:00",
"date_finish": "2024-08-30T12:19:58+02:00",
"operating": 0
}
}
Возвращаемые данные
|
Название |
Описание |
|
result |
Корневой элемент ответа, содержит идентификатор созданной сделки |
|
time |
Информация о времени выполнения запроса |
Обработка ошибок
HTTP-статус: 400
{
"error": "",
"error_description": "Parameter 'fields' must be array."
}
|
Название |
Описание |
|
error |
Строковый код ошибки. Может состоять из цифр, латинских букв и знака подчеркивания |
|
error_description |
Текстовое описание ошибки. Описание не предназначено для показа конечному пользователю в необработанном виде |
Возможные коды ошибок
|
Код |
Описание |
Значение |
|
|
|
В параметр |
|
|
|
В Параметр |
|
|
|
У пользователя нет прав на «добавление» сделок |
|
|
Исчерпан выделенный дисковый ресурс |
|
|
|
Неверное значение поля «Валюта» |
|
Статусы и коды системных ошибок
HTTP-статус: 20x, 40x, 50x
Описанные ниже ошибки могут возникнуть при вызове любого метода
|
Статус |
Код |
Описание |
|
|
|
Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24 |
|
|
|
Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24 |
|
|
|
Превышен лимит на интенсивность запросов |
|
|
|
Метод заблокирован из-за превышения лимита на ресурсоемкость запросов. Блокировка снимается автоматически через 10 минут |
|
|
|
Текущий метод не разрешен для вызова с помощью batch |
|
|
|
Превышена максимальная длина параметров, переданных в метод batch |
|
|
|
Неверный access-токен или код вебхука |
|
|
|
Для вызовов методов требуется использовать протокол HTTPS |
|
|
|
REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка, для снятия необходимо обращаться в техническую поддержку Битрикс24 |
|
|
|
REST API доступен только на коммерческих планах |
|
|
|
У пользователя, с чьим access-токеном или вебхуком был вызван метод, не хватает прав |
|
|
|
Манифест недоступен |
|
|
|
Запрос требует более высоких привилегий, чем предоставляет токен вебхука |
|
|
|
Предоставленный access-токен доступа истек |
|
|
|
Пользователь не имеет доступа к приложению. Это означает, что приложение установлено, но администратор портала разрешил доступ к этому приложению только конкретным пользователям |
|
|
|
Публичная часть сайта закрыта. Чтобы открыть публичную часть сайта на коробочной установке отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта |