Как написать своего робота для Битрикс24 через REST API

Робот в бизнес-процессах Битрикс24 — это внешний обработчик, который появляется в конструкторе БП как обычный шаг наравне со встроенными («Задача», «Уведомление», «Ждать событие»), но логику выполняет ваш сервер. Через роботов удобно вшивать во внутренние процессы компании внешние действия: отправить SMS, создать документ во внешней системе, проверить контрагента по ИНН, посчитать скидку по сложной формуле. Ниже — полный цикл: от регистрации робота до обработки его вызова и возврата результата обратно в процесс.

Чем робот отличается от обычного REST-вызова

Обычная интеграция дёргает Битрикс24 снаружи: ваш сервис сам решает, когда вызвать crm.deal.update. Робот работает в обратную сторону — портал сам обращается к вашему серверу в момент, когда исполнение бизнес-процесса доходит до соответствующего шага, передаёт значения свойств документа (сделки, лида), а ваш обработчик должен вернуть результат и явно сообщить порталу, что шаг завершён. Пока вы не пришлёте подтверждение, процесс стоит на этом шаге — это ключевое отличие, ломающее логику у тех, кто пишет робота как синхронный REST-метод.

Регистрация робота методом bizproc.robot.add

Робот регистрируется один раз (обычно в обработчике установки приложения) вызовом bizproc.robot.add. Указываете CODE (уникальный внутри приложения идентификатор), HANDLER (URL, который Битрикс24 будет вызывать), AUTH_USER_ID (от чьего имени робот получает права на портале), список PROPERTIES (входные параметры, которые администратор БП сможет замапить на поля документа) и, отдельно, RETURN_PROPERTIES — то, что робот сможет вернуть и передать дальше по процессу.

POST /rest/1/xxxxxxxxxxxxxxxx/bizproc.robot.add.json

{
  "CODE": "send_sms_notification",
  "HANDLER": "https://yourservice.example.com/bp/robot/sms",
  "AUTH_USER_ID": 1,
  "NAME": "Отправить SMS клиенту",
  "PROPERTIES": {
    "phone": { "Name": "Номер телефона", "Type": "string", "Required": "Y" },
    "text": { "Name": "Текст сообщения", "Type": "string", "Multiple": "N" }
  },
  "RETURN_PROPERTIES": {
    "status": { "Name": "Статус отправки", "Type": "string" },
    "message_id": { "Name": "ID сообщения в SMS-шлюзе", "Type": "string" }
  },
  "USE_SUBSCRIPTION": "Y"
}

Что приходит на HANDLER при запуске шага

Когда бизнес-процесс доходит до шага с вашим роботом, портал делает POST-запрос на HANDLER с параметрами event_token, document_id, PROPERTIES (уже подставленные значения — например, реальный телефон из карточки сделки), а также auth (набор данных для последующих вызовов REST от имени портала, включая domain и access_token, если приложение зарегистрировано с USE_SUBSCRIPTION). event_token — обязательный параметр, который нужно сохранить: именно им вы будете подтверждать завершение шага.

Возврат результата: bizproc.event.send

После того как ваш сервер выполнил бизнес-логику (отправил SMS, получил ответ от внешнего API), нужно явно вызвать bizproc.event.send с тем же event_token и параметрами return_values, заполненными по схеме RETURN_PROPERTIES. Только после этого вызова бизнес-процесс продвигается дальше. Если не вызвать событие вообще, процесс так и останется висеть на этом шаге бесконечно — с точки зрения администратора БП это выглядит как зависшая задача без объяснения причины.

POST /rest/1/xxxxxxxxxxxxxxxx/bizproc.event.send.json

{
  "event_token": "eyJhbGciOi...",
  "return_values": {
    "status": "sent",
    "message_id": "sms-88213"
  },
  "log_message": "SMS отправлено успешно через шлюз SMSC"
}

Обработка ошибок внутри робота

Если внешний сервис, к которому обращается робот (SMS-шлюз, платёжный API), временно недоступен, у вас два варианта: вернуть событие с ошибкой через тот же bizproc.event.send с параметром error_message — тогда процесс попробует пойти по обработчику ошибок, если он настроен в конструкторе, либо остановится с пометкой «завершён с ошибкой». Второй вариант — не подтверждать шаг вообще и повторить попытку на своей стороне (через очередь с retry), подтвердив успех позже. Второй подход надёжнее для интеграций с нестабильными внешними API, но требует персистентного хранения event_token до момента успешного завершения.

Асинхронное выполнение и таймауты

Регистрация с USE_SUBSCRIPTION=Y переводит робота в асинхронный режим: HTTP-ответ на исходный запрос от портала может быть мгновенным (просто 200 OK, подтверждающий приём), а фактическое завершение шага придёт позже отдельным вызовом bizproc.event.send — это единственный жизнеспособный вариант, если ваша бизнес-логика занимает больше нескольких секунд. Без этого флага Битрикс24 ждёт ответа на сам HTTP-запрос синхронно и может считать шаг зависшим при долгой обработке на вашей стороне.

Свойства и типы полей робота

Каждое свойство робота имеет тип: string, int, double, bool, select (с заданным списком вариантов), user (выбор сотрудника), date, file. Тип select особенно полезен, когда роботу нужно жёстко ограничить набор входных значений — например, «канал доставки»: sms, email, push. Свойства с Multiple=Y позволяют администратору БП передать в робота массив значений, например список email-адресов получателей.

• string — обычная строка, самый частый тип для текстов и телефонов
• select — выпадающий список с фиксированными Options, снижает риск опечаток у администратора БП
• user — выбор сотрудника портала, удобно для полей типа «ответственный за уведомление»
• bool — да/нет, для флагов вроде «отправлять дубль на email»
• file — передача файла из документа-носителя (например, приложенного к сделке)

Курс школы: Вебхуки в Битрикс24 без программирования — от 9 990 ₽

Тестирование робота на песочнице

Роботов нельзя протестировать без реального бизнес-процесса — нужно создать тестовый БП на тестовом портале, добавить туда робота вручную через конструктор и прогнать сделку по цепочке. Полезная практика — временно логировать весь входящий payload на HANDLER в файл или отдельную таблицу, потому что набор полей auth и PROPERTIES по факту отличается от документации в деталях (например, отсутствие каких-то полей при пустом значении в карточке).

1. 1.Зарегистрировать робота через bizproc.robot.add на тестовом портале
2. 2.Создать тестовый бизнес-процесс со шагом-роботом в конструкторе
3. 3.Запустить процесс на тестовой сделке и посмотреть журнал выполнения БП
4. 4.Проверить, что event.send реально продвигает процесс дальше, а не оставляет его висеть
5. 5.Только после этого регистрировать робота на боевом портале и включать в реальные БП

Правило одного event_token. event_token одноразовый и предназначен ровно для одного вызова bizproc.event.send. Попытка повторно подтвердить тот же шаг или подтвердить его после долгой паузы (Битрикс24 ограничивает время жизни токена) приведёт к ошибке — храните статус подтверждения на своей стороне, чтобы не пытаться закрыть шаг дважды при повторной доставке события от вашей же очереди.

Удаление и обновление робота

Робот обновляется методом bizproc.robot.update по тому же CODE — это позволяет менять HANDLER, добавлять новые PROPERTIES без разрыва уже настроенных на порталах клиентов бизнес-процессов (правда, новые обязательные поля потребуют донастройки БП администратором). Удаление — bizproc.robot.delete, обязательно вызывайте его в обработчике деинсталляции приложения, иначе робот останется зарегистрирован в системе, ссылаясь на несуществующий HANDLER, и все процессы с ним начнут падать с таймаутом.

Робот, который не подтверждает шаг явным событием, с точки зрения бизнес-процесса просто завис — и это выглядит как баг Битрикс24, хотя причина всегда на стороне обработчика.

Практические сценарии применения

Типичные продакшен-роботы: проверка контрагента по ИНН через API ФНС с автоматическим заполнением реквизитов компании, генерация и отправка договора через сервис электронного документооборота, расчёт скидки по нестандартной формуле, недоступной во встроенном конструкторе условий, синхронный запрос остатков товара на складе перед подтверждением сделки. Во всех случаях экономия по сравнению с внешним REST-опросом в том, что бизнес-логика становится видимой и настраиваемой прямо в конструкторе БП силами администратора компании, без правки кода.

Права доступа и AUTH_USER_ID

Значение AUTH_USER_ID определяет, от чьего имени робот будет выполнять последующие вызовы REST внутри своей логики (например, если роботу нужно дополнительно обновить поле в той же сделке). Указывать здесь администратора «на всякий случай» — плохая практика: если сотрудник с этим ID уволится и его учётную запись деактивируют, все роботы, зарегистрированные на него, перестанут работать без явной ошибки в интерфейсе БП, только с тихими таймаутами в логах. Лучше заводить отдельного технического пользователя специально для интеграций и роботов и указывать его ID.

Отличие робота от простого исходящего вебхука в бизнес-процессах

Начинающие разработчики часто путают робота с исходящим вебхуком (event.bind на событие ONCRMDEALUPDATE): вебхук — это уведомление о факте, которое не встраивается в редактор БП как визуальный шаг и не может влиять на дальнейшую логику процесса, вернуть значение в поле или заблокировать переход дальше. Робот — полноценный участник графа выполнения: у него есть входные параметры, настраиваемые прямо в интерфейсе конструктора, условные переходы по его RETURN_PROPERTIES (например, «если status равен failed — перейти в ветку эскалации на руководителя»), и видимое в журнале процесса время выполнения шага. Если вам нужно, чтобы результат внешнего вызова влиял на дальнейший путь процесса — это всегда робот, а не событие.

Локализация робота для мультиязычных порталов

Название робота, названия свойств и подписи к RETURN_PROPERTIES можно и нужно локализовать, если приложение публикуется в Маркете для порталов на разных языках. Вместо жёстких строк в NAME и Name передаётся структура с кодами языков (en, ru, de, la — латиница для порталов СНГ вне России). Без этого шага робот на английском портале клиента будет называться «Отправить SMS клиенту» — мелочь, которая тем не менее выглядит непрофессионально и снижает доверие к остальной части интеграции при модерации в Маркете.

Производительность: не плодите роботов на каждый чих

Регистрация отдельного робота под каждое небольшое действие (отдельно «отправить email», отдельно «отправить SMS», отдельно «записать лог») раздувает список доступных шагов в конструкторе БП до состояния, в котором администратор компании не может найти нужный шаг среди полусотни похожих. Лучше проектировать одного универсального робота с select-параметром «канал» и веткой обработки внутри вашего сервера, чем размножать однотипные сущности только потому, что это проще для вашего кода. Пользователь конструктора БП — не программист, и для него читаемость списка доступных действий важнее вашей внутренней архитектуры.

Мониторинг зависших шагов на проде

После запуска в продакшен заведите отдельный мониторинг по шагам с вашими роботами: если событие event.send не пришло в течение ожидаемого времени (например, 5 минут для SMS-шлюза, который в норме отвечает за секунды), это сигнал о повисшем внешнем вызове или потерянном event_token из-за падения вашего сервиса между приёмом запроса и отправкой подтверждения. Такие зависшие шаги накапливаются на портале клиента незаметно для вас, но заметно для него — сделки просто не двигаются по воронке, и разбираться с этим обычно приходится через тикет в поддержку, а не через ваши собственные алерты, если мониторинга нет.