Создать новую сделку crm.deal.add

Scope: crm

Кто может выполнять метод: любой пользователь с правом «добавления» сделок

Метод crm.deal.add создает новую сделку.

Параметры метода

#| || Название тип | Описание || || fields object | Объект формата:

{
    field_1: value_1,
    field_2: value_2,
    ...,
    field_n: value_n,
}

где:

field_n — название поля
value_n — значение поля

Список доступных полей описан ниже || || params object | Объект, содержащий дополнительный набор параметров (подробное описание) || |#

Параметр fields {#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 | Информация для сквозной аналитики — подробнее читайте в статье {#T} || || UF_CRM_... | Пользовательские поля. Например, UF_CRM_25534736.

В зависимости от настроек портала у сделок может быть набор пользовательских полей определенных типов.

Добавить пользовательское поле в сделку можно с помощью метода crm.deal.userfield.add || || PARENT_ID_... crm_entity | Поля связей.

Если на портале есть смарт-процессы, связанные со сделками, для каждого такого смарт-процесса существует поле, хранящее связь между этим смарт-процессом и сделкой. Само поле хранит идентификатор элемента такого смарт-процесса.

Например, поле PARENT_ID_153 — связь со смарт-процессом entityTypeId=153, хранит идентификатор элемента этого смарт-процесса, связанного с текущей сделкой || |#

Параметр params {#params}

#| || Название тип | Описание || || REGISTER_SONET_EVENT boolean | Зарегистрировать ли событие добавления сделки в живой ленте. Возможные значения:

Y — да
N — нет

По умолчанию Y || |#

Примеры кода

{% include Сноска о примерах %}

{% list tabs %}

cURL (Webhook)

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_webbhook_here**/crm.deal.add

cURL (OAuth)

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

JS

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())
        ;
    },
);

PHP

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>';

PHP (B24PhpSdk)

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());
}

{% endlist %}

Обработка ответа

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."
}

{% include notitle обработка ошибок %}

Возможные коды ошибок

#| || Код | Описание | Значение || || - | Parameter 'fields' must be array | В параметр fields передан не объект || || - | Parameter 'params' must be array | В Параметр params передан не объект || || - | Access denied | У пользователя нет прав на «добавление» сделок || || - | Исчерпан выделенный дисковый ресурс |> || || - | Неверное значение поля «Валюта» |> || |#

{% include системные ошибки %}

Продолжите изучение

{#T}
{#T}
{#T}
{#T}
{#T}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

crm-deal-add.md

crm-deal-add.md

Создать новую сделку crm.deal.add

Параметры метода

Параметр fields {#fields}

Параметр params {#params}

Примеры кода

Обработка ответа

Возвращаемые данные

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

Возможные коды ошибок

Продолжите изучение

Files

crm-deal-add.md

Latest commit

History

crm-deal-add.md

File metadata and controls

Создать новую сделку crm.deal.add

Параметры метода

Параметр fields {#fields}

Параметр params {#params}

Примеры кода

Обработка ответа

Возвращаемые данные

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

Возможные коды ошибок

Продолжите изучение