Добавить системное дело crm.activity.add

Scope: crm

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

DEPRECATED

Развитие метода остановлено. Используйте crm.activity.todo.add.

Метод crm.activity.add создает новое системное дело.

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

Обязательные параметры отмечены *

Название
тип

Описание

fields*
array

Массив значений полей дела в виде структуры:

fields:
        {
            "OWNER_TYPE_ID": 2, 
            "OWNER_ID": 102, 
            "TYPE_ID": 2, 
            "SUBJECT": "Новый звонок",
        }
        

Имеется дополнительное поле DISABLE_SENDING_MESSAGE_COPY. Оно предназначено для принудительного отключения отправки копии сообщения адресату из MESSAGE_FROM. Если параметр не заполнен или указано любое значение отличное от Y - копия отправлена будет. Пример:

[
            'fields'=> array(
                'SETTINGS'=> array(
                    'DISABLE_SENDING_MESSAGE_COPY'=>'Y'
                )
            )
        ]
        

Параметр fields

Обязательные параметры отмечены *

Поле тип

Описание

OWNER_ID*
integer

Идентификатор элемента CRM

OWNER_TYPE_ID*
integer

Идентификатор типа объекта CRM

TYPE_ID*
crm_enum_activitytype

Тип дела. Чтобы получить доступные типы дел, используйте метод crm.enum.activitytype.

Чтобы создать дело с типом «задача», используйте метод создания или изменения задачи и укажите элемент CRM в поле UF_CRM_TASK

ASSOCIATED_ENTITY_ID
integer

Идентификатор связанного с делом элемента

COMMUNICATIONS*
crm_activity_communication

Описание коммуникации

DEADLINE
datetime

Дата и время срока исполнения дела. Поле напрямую не устанавливается, значение берётся из START_TIME для звонка и встречи и из END_TIME для задачи

DESCRIPTION
string

Текстовое описание дела

DESCRIPTION_TYPE
crm.enum.contenttype

Тип описания

DIRECTION
crm.enum.activitydirection

Направление дела: входящее/исходящее. Актуально для звонков и писем, для встреч не используется

END_TIME
datetime

Время завершения дела

FILES
diskfile

Добавленные в дело файлы

LOCATION
string

Местоположение

NOTIFY_TYPE
crm.enum.activitynotifytype

Тип уведомления

ORIGINATOR_ID
string

Идентификатор источника данных, используется только для привязки к внешнему источнику

ORIGIN_ID
string

Идентификатор элемента в источнике данных, используется только для привязки к внешнему источнику

ORIGIN_VERSION
string

Оригинальная версия, используется для защиты данных от случайного перетирания внешней системой. Если данные были импортированы и не изменялись во внешней системе, то такие данные могут быть редактированы в CRM без опасения, что следующая выгрузка приведет к перетиранию данных

PRIORITY
crm.enum.activitypriority

Приоритет

PROVIDER_DATA
string

Дополнительные данные провайдера

PROVIDER_GROUP_ID
string

Идентификатор группы провайдера

PROVIDER_ID
string

Идентификатор провайдера

PROVIDER_TYPE_ID
string

Идентификатор типа провайдера, статус из справочника

PROVIDER_PARAMS
object

Дополнительные параметры провайдера

RESPONSIBLE_ID*
user

Идентификатор пользователя, ответственного за дело

SETTINGS
object

Дополнительные настройки

START_TIME
datetime

Время начала выполнения дела

STATUS
crm_enum_activitystatus

Статус дела

SUBJECT
string

Дополнительное описание дела

WEBDAV_ELEMENTS
diskfile

Добавленные файлы. Устарел, сохраняется для совместимости

IS_INCOMING_CHANNEL
char

Флаг, говорящий дело создано из входящего канала или нет (Y/N)

Варианты использования значений полей

Для дел типа e-mail:

  • если письмо не должно быть отправлено, устанавливайте параметры DIRECTION=2 и COMPLETED='N';
  • если необходимо пометить письма как завершенные, выполните обновление дел с выставлением флага завершения.

Примеры кода

Как использовать примеры в документации

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"fields":{"OWNER_TYPE_ID":2,"OWNER_ID":102,"TYPE_ID":2,"COMMUNICATIONS":[{"VALUE":"+79832322323","ENTITY_ID":134,"ENTITY_TYPE_ID":3}],"SUBJECT":"Новый звонок","START_TIME":"2023-12-31T12:00:00+00:00","END_TIME":"2023-12-31T12:30:00+00:00","COMPLETED":"N","PRIORITY":3,"RESPONSIBLE_ID":1,"DESCRIPTION":"Важный звонок","DESCRIPTION_TYPE":3,"DIRECTION":2,"FILES":[{"fileData":["example.jpg","base64_encoded_content_here"]}]} }' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.activity.add
        
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"fields":{"OWNER_TYPE_ID":2,"OWNER_ID":102,"TYPE_ID":2,"COMMUNICATIONS":[{"VALUE":"+79832322323","ENTITY_ID":134,"ENTITY_TYPE_ID":3}],"SUBJECT":"Новый звонок","START_TIME":"2023-12-31T12:00:00+00:00","END_TIME":"2023-12-31T12:30:00+00:00","COMPLETED":"N","PRIORITY":3,"RESPONSIBLE_ID":1,"DESCRIPTION":"Важный звонок","DESCRIPTION_TYPE":3,"DIRECTION":2,"FILES":[{"fileData":["example.jpg","base64_encoded_content_here"]}]},"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/crm.activity.add
        
try
        {
        	const response = await $b24.callMethod(
        		"crm.activity.add",
        		{
        			fields: {
        				"OWNER_TYPE_ID": 2,
        				"OWNER_ID": 102,
        				"TYPE_ID": 2,
        				"COMMUNICATIONS": [
        					{ VALUE: "+79832322323", ENTITY_ID: 134, ENTITY_TYPE_ID: 3 }
        				],
        				"SUBJECT": "Новый звонок",
        				"START_TIME": "2023-12-31T12:00:00+00:00", // Пример даты и времени
        				"END_TIME": "2023-12-31T12:30:00+00:00", // Пример даты и времени
        				"COMPLETED": "N",
        				"PRIORITY": 3,
        				"RESPONSIBLE_ID": 1,
        				"DESCRIPTION": "Важный звонок",
        				"DESCRIPTION_TYPE": 3,
        				"DIRECTION": 2,
        				"FILES": [
        					{
        						fileData: [
        							"example.jpg", // Имя файла
        							"base64_encoded_content_here" // Контент файла в формате base64
        						]
        					}
        				]
        			}
        		}
        	);
        	
        	const result = response.getData().result;
        	console.dir(result);
        }
        catch( error )
        {
        	console.error(error);
        }
        
try {
            $response = $b24Service
                ->core
                ->call(
                    'crm.activity.add',
                    [
                        'fields' => [
                            'OWNER_TYPE_ID'    => 2,
                            'OWNER_ID'         => 102,
                            'TYPE_ID'          => 2,
                            'COMMUNICATIONS'   => [
                                ['VALUE' => '+79832322323', 'ENTITY_ID' => 134, 'ENTITY_TYPE_ID' => 3]
                            ],
                            'SUBJECT'          => 'Новый звонок',
                            'START_TIME'       => '2023-12-31T12:00:00+00:00',
                            'END_TIME'         => '2023-12-31T12:30:00+00:00',
                            'COMPLETED'        => 'N',
                            'PRIORITY'         => 3,
                            'RESPONSIBLE_ID'   => 1,
                            'DESCRIPTION'      => 'Важный звонок',
                            'DESCRIPTION_TYPE' => 3,
                            'DIRECTION'        => 2,
                            'FILES'            => [
                                [
                                    'fileData' => [
                                        'example.jpg',
                                        'base64_encoded_content_here'
                                    ]
                                ]
                            ]
                        ]
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            echo 'Success: ' . print_r($result, true);
            // Нужная вам логика обработки данных
            processData($result);
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error adding activity: ' . $e->getMessage();
        }
        
BX24.callMethod(
            "crm.activity.add",
            {
                fields: {
                    "OWNER_TYPE_ID": 2,
                    "OWNER_ID": 102,
                    "TYPE_ID": 2,
                    "COMMUNICATIONS": [
                        { VALUE: "+79832322323", ENTITY_ID: 134, ENTITY_TYPE_ID: 3 }
                    ],
                    "SUBJECT": "Новый звонок",
                    "START_TIME": "2023-12-31T12:00:00+00:00", // Пример даты и времени
                    "END_TIME": "2023-12-31T12:30:00+00:00", // Пример даты и времени
                    "COMPLETED": "N",
                    "PRIORITY": 3,
                    "RESPONSIBLE_ID": 1,
                    "DESCRIPTION": "Важный звонок",
                    "DESCRIPTION_TYPE": 3,
                    "DIRECTION": 2,
                    "FILES": [
                        {
                            fileData: [
                                "example.jpg", // Имя файла
                                "base64_encoded_content_here" // Контент файла в формате base64
                            ]
                        }
                    ]
                }
            },
            result => {
                if (result.error()) {
                    console.error(result.error());
                } else {
                    console.dir(result.data());
                }
            }
        );
        
require_once('crest.php');
        
        $result = CRest::call(
            'crm.activity.add',
            [
                'fields' => [
                    'OWNER_TYPE_ID' => 2,
                    'OWNER_ID' => 102,
                    'TYPE_ID' => 2,
                    'COMMUNICATIONS' => [
                        [
                            'VALUE' => '+79832322323',
                            'ENTITY_ID' => 134,
                            'ENTITY_TYPE_ID' => 3
                        ]
                    ],
                    'SUBJECT' => 'Новый звонок',
                    'START_TIME' => '2023-12-31T12:00:00+00:00', // Пример даты и времени
                    'END_TIME' => '2023-12-31T12:30:00+00:00', // Пример даты и времени
                    'COMPLETED' => 'N',
                    'PRIORITY' => 3,
                    'RESPONSIBLE_ID' => 1,
                    'DESCRIPTION' => 'Важный звонок',
                    'DESCRIPTION_TYPE' => 3,
                    'DIRECTION' => 2,
                    'FILES' => [
                        [
                            'fileData' => [
                                'example.jpg', // Имя файла
                                'base64_encoded_content_here' // Контент файла в формате base64
                            ]
                        ]
                    ]
                ]
            ]
        );
        
        if (isset($result['error'])) {
            echo 'Ошибка: ' . $result['error_description'];
        } else {
            echo '<PRE>';
            print_r($result['result']);
            echo '</PRE>';
        }
        

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

HTTP-статус: 200

{
            "result": 999,
            "time": {
                "start": 1712132792.910734,
                "finish": 1712132793.530359,
                "duration": 0.6196250915527344,
                "processing": 0.032338857650756836,
                "date_start": "2024-04-03T10:26:32+02:00",
                "date_finish": "2024-04-03T10:26:33+02:00",
                "operating_reset_at": 1705765533,
                "operating": 3.3076241016387939
            }
        }
        

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

Название
тип

Описание

result
boolean

Результат операции. Возвращает идентификатор дела в таймлайне в случае успеха, иначе — false

time
time

Информация о времени выполнения запроса

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

HTTP-статус: 400

{
            "error": "",
            "error_description": "Access denied."
        }
        

Название
тип

Описание

error
string

Строковый код ошибки. Может состоять из цифр, латинских букв и знака подчеркивания

error_description
error_description

Текстовое описание ошибки. Описание не предназначено для показа конечному пользователю в необработанном виде

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

Код

Описание

The field SUBJECT is not defined or empty

Поле SUBJECT не установлено

The field RESPONSIBLE_ID is not defined or invalid

Поле RESPONSIBLE_ID не установлено

The field TYPE_ID is not defined or invalid

Поле TYPE_ID не установлено

The field COMMUNICATIONS is not defined or invalid

Поле COMMUNICATIONS не установлено

The only one communication is allowed for activity of specified type

Количество контактов более 1

Could not build binding. Please ensure that owner info and communications are defined correctly

Связи для дела не указаны

  • Email send error. Failed to load module "subscribe"
  • Email send error. Invalid data
  • Email send error. Invalid email is specified
  • Email send error. "From" is not found
  • Email send error. "To" is not found
  • Email send error. Failed to add posting. Please see details below
  • Email send error. Failed to save posting file. Please see details below
  • Email send error. Failed to update activity
  • Email send error. General error

Ошибки "почтовых" дел

The custom activity without provider is not supported in current context

Тип дела не поддерживается в заданном контексте

Use crm.activity.configurable.add for this activity provider

Некорректный вызов метода для конфигурируемого дела

Access denied

Отсутствуют права на добавление сущности в CRM

Application context required

Некорректный параметр PROVIDER_ID для дела, созданного в контексте приложения

Статусы и коды системных ошибок

HTTP-статус: 20x, 40x, 50x

Описанные ниже ошибки могут возникнуть при вызове любого метода

Статус

Код
Текст ошибки

Описание

500

INTERNAL_SERVER_ERROR
Internal server error

Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24

500

ERROR_UNEXPECTED_ANSWER
Server returned an unexpected response

Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24

503

QUERY_LIMIT_EXCEEDED
Too many requests

Превышен лимит на интенсивность запросов

405

ERROR_BATCH_METHOD_NOT_ALLOWED
Method is not allowed for batch usage

Текущий метод не разрешен для вызова с помощью batch

400

ERROR_BATCH_LENGTH_EXCEEDED
Max batch length exceeded

Превышена максимальная длина параметров, переданных в метод batch

401

NO_AUTH_FOUND
Wrong authorization data

Неверный access-токен или код вебхука

400

INVALID_REQUEST
Https required

Для вызовов методов требуется использовать протокол HTTPS

503

OVERLOAD_LIMIT
REST API is blocked due to overload

REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка, для снятия необходимо обращаться в техническую поддержку Битрикс24

403

ACCESS_DENIED
REST API is available only on commercial plans

REST API доступен только на коммерческих планах

403

INVALID_CREDENTIALS
Invalid request credentials

У пользователя, с чьим access-токеном или вебхуком был вызван метод, не хватает прав

404

ERROR_MANIFEST_IS_NOT_AVAILABLE
Manifest is not available

Манифест недоступен

403

insufficient_scope
The request requires higher privileges than provided by the webhook token

Запрос требует более высоких привилегий, чем предоставляет токен вебхука

401

expired_token
The access token provided has expired

Предоставленный access-токен доступа истек

403

user_access_error
The user does not have access to the application

Пользователь не имеет доступа к приложению. Это означает, что приложение установлено, но администратор портала разрешил доступ к этому приложению только конкретным пользователям

500

PORTAL_DELETED
Portal was deleted

Публичная часть сайта закрыта. Чтобы открыть публичную часть сайта на коробочной установке отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

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