метод REST scope: bizproc

bizproc.robot.add

Зарегистрировать нового робота

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

Описание

Метод bizproc.robot.add регистрирует нового робота.

Работает только в контексте приложения.

Параметры

CODE string обязательный

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

Допустимые символы — a-z, A-Z, 0-9, точка, дефис и нижнее подчеркивание _

HANDLER string обязательный

URL, на который робот будет отправлять данные через сервер очередей bitrix24.

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

AUTH_USER_ID integer необязательный

Идентификатор пользователя, токен которого будет передан приложению

USE_SUBSCRIPTION boolean необязательный

Должен ли робот ожидать ответа от приложения. Возможные значения:
- Y — да
- N — нет

По умолчанию параметр пустой, что равнозначно ожиданию ответа приложения. Робот не ожидает ответа только при явном значении N

NAME string обязательный

Название робота.

Может быть строкой или ассоциативным массивом локализированных строк вида:

'NAME': {
    'ru': 'название робота',
    'en': 'robot name',
    ...
},
DESCRIPTION string необязательный

Описание робота.

Может быть строкой или ассоциативным массивом локализированных строк вида:

'DESCRIPTION': {
    'ru': 'описание робота',
    'en': 'robot description',
    ...
},
PROPERTIES object необязательный

Объект с параметрами робота. Содержит объекты, каждый из которых описывает параметр робота.

Системное название параметра должно начинаться с буквы и может содержать символы a-z, A-Z, 0-9 и нижнее подчеркивание _

RETURN_PROPERTIES object необязательный

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

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

Системное название параметра должно начинаться с буквы и может содержать символы a-z, A-Z, 0-9 и нижнее подчеркивание _

DOCUMENT_TYPE array необязательный

Тип документа, который будет определять типы данных для параметров PROPERTIES и RETURN_PROPERTIES. Состоит из трех элементов типа строка:
- идентификатор модуля
- идентификатор объекта
- тип документа

Возможные варианты значений:

  • Модуль CRM
    ['crm', 'CCrmDocumentLead', 'LEAD'] — лиды
    ['crm', 'CCrmDocumentDeal', 'DEAL'] — сделки
    ['crm', 'Bitrix\Crm\Integration\BizProc\Document\Quote', 'QUOTE'] — коммерческие предложения
    ['crm', 'Bitrix\Crm\Integration\BizProc\Document\SmartInvoice', 'SMART_INVOICE'] — счета
    ['crm', 'Bitrix\Crm\Integration\BizProc\Document\Dynamic', 'DYNAMIC_XXX'] — смарт-процессы, где XXX — идентификатор смарт-процесса
FILTER object необязательный

Объект с правилами ограничения робота по типу документа и редакции.

Может содержать ключи:
- INCLUDE — массив правил, где робот будет отображен
- EXCLUDE — массив правил, где робот будет скрыт

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

Чтобы ограничить роботов по редакции Битрикс24 укажите:
- b24 — для облака
- box — для коробки

Примеры:
1. Исключить робота для коробочного Битрикс24

    'FILTER': {
        EXCLUDE: [ 'box' ]
    }
  1. Отображать робота только для сделок и лидов CRM
    'FILTER': {
        INCLUDE: [
            ['crm', 'CCrmDocumentDeal'],
            ['crm', 'CCrmDocumentLead']
        ]
    }
USE_PLACEMENT boolean необязательный

Дает возможность открывать дополнительные настройки робота в слайдере приложения. Возможные значения:
- Y — да
- N — нет

PLACEMENT_HANDLER string необязательный

URL обработчика встройки на стороне приложения. Обязательное, если USE_PLACEMENT = 'Y'

Объект PROPERTY

Name string необязательный

Наименование параметра

Description string необязательный

Описание параметра

Type string необязательный

Тип параметра. Базовые значения:
- bool — да или нет
- date — дата
- datetime — дата и время
- double — число
- file — файл
- int — целое число
- select — список
- string — строка
- text — текст
- user — пользователь

Options array необязательный

Массив значений параметра типа список 'TYPE': select' вида:

[
    'value1': 'title1',
    'value2': 'title2',
    'value3': 'title3',
    'value4': 'title4'
]
Required boolean необязательный

Обязательность параметра. Возможные значения:
- Y — да
- N — нет

Multiple boolean необязательный

Множественность параметра. Возможные значения:
- Y — да
- N — нет

Default any необязательный

Значение параметра по умолчанию. Для Type = 'select' указывайте ключ из Options

Примеры запроса

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"CODE":"test_robot","HANDLER":"https://your_domain/robot.php","AUTH_USER_ID":1,"USE_SUBSCRIPTION":"Y","NAME":"Отправить сообщение","PROPERTIES":{"datetime":{"Name":"Во сколько","Type":"datetime"},"text":{"Name":"Текст","Type":"text"},"user":{"Name":"Кому","Type":"user","Default":"Автор;"}},"FILTER":{"INCLUDE":[["crm","CCrmDocumentDeal"],["crm","CCrmDocumentLead"]]},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/bizproc.robot.add

Ответ

HTTP-статус: 200

{
    "result": true,
    "time": {
        "start": 1738148752.692647,
        "finish": 1738148752.749058,
        "duration": 0.056411027908325195,
        "processing": 0.018677949905395508,
        "date_start": "2025-01-29T14:05:52+03:00",
        "date_finish": "2025-01-29T14:05:52+03:00",
        "operating_reset_at": 1738149352,
        "operating": 0
    }
}

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

result boolean

Возвращает true, если робот добавлен успешно

time time

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

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

HTTP-статус: 400

{
    "error": "ERROR_ACTIVITY_VALIDATION_FAILURE",
    "error_description": "Empty activity code!"
}
Код Описание Значение
ACCESS_DENIED Application context required Необходим контекст приложения
ACCESS_DENIED Access denied! Метод выполнил не администратор
ERROR_ACTIVITY_VALIDATION_FAILURE Empty data! Не указаны поля с информацией
ERROR_ACTIVITY_VALIDATION_FAILURE Empty activity code! Не указан код робота
ERROR_ACTIVITY_VALIDATION_FAILURE Wrong activity code! Некорректный код робота
ERROR_UNSUPPORTED_PROTOCOL Unsupported handler protocol Некорректный протокол хендлера http, https
ERROR_WRONG_HANDLER_URL Wrong handler URL Невалидный урл хендлера
ERROR_ACTIVITY_VALIDATION_FAILURE Empty activity NAME! Не указано название робота
ERROR_ACTIVITY_VALIDATION_FAILURE Wrong properties array! Некорректно заполнены параметры PROPERTIES или RETURN_PROPERTIES
ERROR_ACTIVITY_VALIDATION_FAILURE Wrong property key <ключ>! Некорректный идентификатор свойства
ERROR_ACTIVITY_VALIDATION_FAILURE Empty property NAME <ключ>! Не указано название свойства
ERROR_ACTIVITY_VALIDATION_FAILURE Wrong activity FILTER! Некорректный фильтр
ERROR_ACTIVITY_VALIDATION_FAILURE Wrong activity DOCUMENT_TYPE! Некорректный DOCUMENT_TYPE
ERROR_ACTIVITY_ALREADY_INSTALLED Activity or Robot already installed! Робот с таким кодом уже установлен
ERROR_ACTIVITY_ADD_FAILURE Activity or Robot already added! Робот уже был добавлен
ERROR_ACTIVITY_ADD_FAILURE Activity save error! Не удалось сохранить робота, системная ошибка

Что будем искать? Например,Продвижение

Этот сайт использует куки-файлы. Оставаясь на сайте, Вы соглашаетесь на их использование. Для получения дополнительной информации, пожалуйста, ознакомьтесь с политикой в отношении персональных данных.