crm.deal.add
Создать новую сделку
Описание
Метод crm.deal.add создает новую сделку.
Параметры
fields
object
необязательный
Объект формата:
{
field_1: value_1,
field_2: value_2,
...,
field_n: value_n,
}
где:
- field_n — название поля
- value_n — значение поля
Список доступных полей описан ниже
params
object
необязательный
Объект, содержащий дополнительный набор параметров (подробное описание)
Параметр fields
TITLE
string
необязательный
Название сделки.
По умолчанию генерируется по шаблону Сделка #{id}, где id — идентификатор элемента
TYPE_ID
crm_status
необязательный
Строковый идентификатор типа сделки.
Список доступных типов сделки можно узнать с помощью метода crm.status.list, применив фильтр { ENTITY_ID: 'DEAL_TYPE' }.
По умолчанию — первый доступный тип сделки
CATEGORY_ID
crm_category
необязательный
Идентификатор воронки. Обязательно больше или равен 0.
Список доступных воронок можно узнать с помощью метода crm.category.list, передав entityTypeId = 2.
По умолчанию — идентификатор воронки по умолчанию
STAGE_ID
crm_status
необязательный
Стадия сделки.
Список доступных стадий можно узнать с помощью метода crm.status.list, применив фильтр:
- { ENTITY_ID: "DEAL_STAGE" } — если сделка находится в общей воронке (направлении)
- { ENTITY_ID: "DEAL_STAGE_{categoryId}" } — если сделка находится не в общей воронке, где categoryId — это идентификатор воронки сделки
По умолчанию — первая доступная стадия относительно воронки
IS_RECURRING
char
необязательный
Является ли сделка шаблоном регулярной сделки. Возможные значения:
- Y — да
- N — нет
По умолчанию N
IS_RETURN_CUSTOMER
char
необязательный
Является ли сделка повторной. Возможные значения:
- Y — да
- N — нет
По умолчанию N
IS_REPEATED_APPROACH
char
необязательный
Является ли сделка повторным обращением. Возможные значения:
- Y — да
- N — нет
По умолчанию N
PROBABILITY
integer
необязательный
Вероятность, %
CURRENCY_ID
crm_currency
необязательный
Валюта.
Список доступных валют можно узнать с помощью метода crm.currency.list
OPPORTUNITY
double
необязательный
Сумма.
По умолчанию 0.00
IS_MANUAL_OPPORTUNITY
char
необязательный
Включен ли режим ручного подсчета суммы. Возможные значения:
- Y — да
- N — нет
По умолчанию N
TAX_VALUE
double
необязательный
Сумма налога.
По умолчанию 0.00
COMPANY_ID
crm_company
необязательный
Идентификатор компании, привязанной к сделке.
Список компаний можно узнать с помощью метода crm.item.list, передав entityTypeId = 4
CONTACT_ID
crm_contact
необязательный
Контакт. Устаревшее
CONTACT_IDS
crm_contact[]
необязательный
Список привязанных к сделке контактов.
Список контактов можно узнать с помощью метода crm.item.list, передав entityTypeId = 3
BEGINDATE
date
необязательный
Дата начала.
По умолчанию — дата создания сделки
CLOSEDATE
date
необязательный
Дата завершения.
По умолчанию — дата создания сделки плюс 7 дней
OPENED
char
необязательный
Доступна ли сделка для всех. Возможные значения:
- Y — да
- N — нет
По умолчанию Y. Значение по умолчанию может быть изменено в настройках CRM
CLOSED
char
необязательный
Является ли сделка закрытой. Возможные значения:
- Y — да
- N — нет
По умолчанию N
COMMENTS
string
необязательный
Комментарий. Поддерживает bb-коды
ASSIGNED_BY_ID
user
необязательный
Ответственный.
По умолчанию — пользователь, вызывающий данный метод
SOURCE_ID
crm_status
необязательный
Строковый идентификатор типа источника.
Список доступных источников можно узнать с помощью метода crm.status.list, применив фильтр { ENTITY_ID: "SOURCE" }.
По умолчанию — первый доступный тип источника
SOURCE_DESCRIPTION
string
необязательный
Дополнительно об источнике
ADDITIONAL_INFO
string
необязательный
Дополнительная информация
LOCATION_ID
location
необязательный
Местоположение клиента. Служебное поле
ORIGINATOR_ID
string
необязательный
Идентификатор источника данных.
Используется только для привязки к внешнему источнику
ORIGIN_ID
string
необязательный
Идентификатор элемента в источнике данных.
Используется только для привязки к внешнему источнику
UTM_SOURCE
string
необязательный
Рекламная система (Google-Adwords и другие)
UTM_MEDIUM
string
необязательный
Тип трафика. Возможные значения:
- CPC — объявления
- CPM — баннеры
UTM_CAMPAIGN
string
необязательный
Обозначение рекламной кампании
UTM_CONTENT
string
необязательный
Содержание кампании. Например, для контекстных объявлений
UTM_TERM
string
необязательный
Условие поиска кампании. Например, ключевые слова контекстной рекламы
TRACE
string
необязательный
Информация для сквозной аналитики — подробнее читайте в статье Info to analitics
UF_CRM_...
необязательный
Пользовательские поля. Например, UF_CRM_25534736.
В зависимости от настроек портала у сделок может быть набор пользовательских полей определенных типов.
Добавить пользовательское поле в сделку можно с помощью метода crm.deal.userfield.add
PARENT_ID_...
crm_entity
необязательный
Поля связей.
Если на портале есть смарт-процессы, связанные со сделками, для каждого такого смарт-процесса существует поле, хранящее связь между этим смарт-процессом и сделкой. Само поле хранит идентификатор элемента такого смарт-процесса.
Например, поле PARENT_ID_153 — связь со смарт-процессом entityTypeId=153, хранит идентификатор элемента этого смарт-процесса, связанного с текущей сделкой
Параметр params
REGISTER_SONET_EVENT
boolean
необязательный
Зарегистрировать ли событие добавления сделки в живой ленте. Возможные значения:
- Y — да
- N — нет
По умолчанию Y
Примеры запроса
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>
from b24pysdk.errors import BitrixAPIError, BitrixSDKException
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}")
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>';
// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "crm.deal.add", b24.Params{
"fields": b24.Params{
"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": []int{84, 83},
"BEGINDATE": time.Now().Format(time.RFC3339),
"CLOSEDATE": time.Now().AddDate(0, 0, 10).Format(time.RFC3339),
"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": b24.Params{
"REGISTER_SONET_EVENT": "N",
},
})
if err != nil {
return fmt.Errorf("crm.deal.add: %w", err)
}
var newID b24.ID
if err := json.Unmarshal(res.Result, &newID); err != nil {
return fmt.Errorf("разбор ответа: %w", err)
}
fmt.Println("идентификатор:", newID)
Ответ
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
integer
Корневой элемент ответа, содержит идентификатор созданной сделки
time
time
Информация о времени выполнения запроса
Обработка ошибок
HTTP-статус: 400
{
"error": "",
"error_description": "Parameter 'fields' must be array."
}
| Код | Описание | Значение |
|---|---|---|
| — | Parameter 'fields' must be array |
В параметр fields передан не объект |
| — | Parameter 'params' must be array |
В Параметр params передан не объект |
| — | Access denied |
У пользователя нет прав на «добавление» сделок |
| — | Исчерпан выделенный дисковый ресурс | |
| — | Неверное значение поля «Валюта» |

