REST: crm.automation (роботы через API)

Роботы и триггеры — визуальный движок автоматизации CRM Битрикс24. Через REST его можно и запускать извне (метод crm.automation.trigger), и расширять собственными роботами (bizproc.robot.add), которые вызывают ваш обработчик и возвращают результат обратно в сделку.

Триггеры, роботы и бизнес-процессы

В автоматизации Битрикс24 есть три уровня, и важно их не смешивать:

• Триггер — реагирует на внешнее событие и двигает сделку по стадии; извне запускается через crm.automation.trigger;
• Робот — действие, выполняемое на стадии; свой робот регистрируется через bizproc.robot.add;
• Бизнес-процесс — полноценный воркфлоу; управляется семейством bizproc.*.

Запуск триггера: crm.automation.trigger

Внешний триггер удобен, когда событие происходит вне Битрикс24 — например, клиент оплатил счёт на стороннем сервисе или прошёл шаг на сайте. Вы заранее добавляете в автоматизацию триггер с определённым кодом, а затем дёргаете его по REST:

POST /rest/1/xxxxxxxx/crm.automation.trigger.json
{
  "code": "PAYMENT_DONE",
  "owner_type_id": 2,
  "owner_id": 340
}

Параметр code должен совпадать с кодом триггера в настройках автоматизации, а owner_type_id / owner_id указывают на сделку или другую сущность. При срабатывании триггер выполнит привязанное к нему условие перехода на следующую стадию.

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

Собственный робот — это внешнее действие, которое можно добавить в конструктор автоматизации как обычный шаг. Приложение регистрирует робота, указывая URL обработчика и набор входных/выходных свойств:

POST /rest/1/xxxxxxxx/bizproc.robot.add.json
{
  "CODE": "score_check",
  "HANDLER": "https://service.example.com/b24/robot",
  "AUTH_USER_ID": 1,
  "NAME": "Проверка скоринга",
  "USE_SUBSCRIPTION": "Y",
  "PROPERTIES": {
    "inn": { "Name": "ИНН", "Type": "string", "Required": "Y" }
  },
  "RETURN_PROPERTIES": {
    "score": { "Name": "Оценка", "Type": "int" }
  }
}

После регистрации робот появится в списке действий на стадиях, и его можно добавить в автоматизацию через интерфейс.

Обработчик робота и возврат данных

Когда автоматизация доходит до вашего робота, Битрикс24 отправляет POST на указанный HANDLER с параметрами робота, идентификатором процесса и токеном авторизации. Важнейший параметр — event_token: он нужен, чтобы вернуть результат.

Флаг USE_SUBSCRIPTION определяет режим работы:

Для отложенного ответа обработчик выполняет свою работу и вызывает bizproc.event.send, передавая event_token и значения выходных свойств:

POST /rest/1/xxxxxxxx/bizproc.event.send.json
{
  "event_token": "...",
  "return_values": { "score": 87 }
}

Роботы и активити бизнес-процессов

Помимо роботов автоматизации CRM, через REST можно регистрировать действия классических бизнес-процессов:

• bizproc.robot.add / update / list / delete — роботы автоматизации;
• bizproc.activity.add — действие для дизайнера бизнес-процессов;
• bizproc.workflow.start — запуск шаблона бизнес-процесса на сущности;
• bizproc.event.send — возврат результата долгого действия.

Практические сценарии

Где связка триггеров и роботов через REST особенно полезна:

1. Оплата на стороннем сервисе — веб-хук платёжки дергает crm.automation.trigger, сделка автоматически переходит на стадию «Оплачено»;
2. Внешний скоринг или проверка контрагента — робот отправляет ИНН в ваш сервис и возвращает оценку в поле сделки;
3. Синхронный запуск процесса — при смене стадии робот инициирует выгрузку заказа в 1С.

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

При проектировании учитывайте надёжность обработчика. Если робот работает в режиме USE_SUBSCRIPTION = Y, а ваш сервис не вызовет bizproc.event.send, автоматизация зависнет на этой стадии до истечения таймаута. Поэтому обработчик должен гарантированно возвращать ответ даже при внутренней ошибке — хотя бы с нейтральным значением выходного свойства. Для триггеров важна идемпотентность: внешняя система может прислать событие оплаты повторно, и повторный вызов crm.automation.trigger не должен ломать логику — условие перехода стоит проектировать так, чтобы двойное срабатывание не откатывало сделку назад и не запускало дублирующие действия.

Итог

REST-автоматизация Битрикс24 работает в двух направлениях: crm.automation.trigger запускает заранее настроенные триггеры из внешних событий, а bizproc.robot.add добавляет ваши действия прямо в конструктор стадий. Ключевые детали — совпадение кода триггера с настройкой, режим USE_SUBSCRIPTION и возврат результата через bizproc.event.send по event_token.

Мы проектируем и внедряем автоматизацию бизнес-процессов на Битрикс24: внешние триггеры, собственные роботы и связку CRM с сайтом и 1С. Если рутину пора перевести на автоматические сценарии с внешней логикой — поможем спроектировать и разработать решение.