REST: бизнес-процессы (bizproc)

Scope bizproc — это программный доступ к движку бизнес-процессов Битрикс24. Через REST запускают процессы, читают экземпляры, регистрируют собственные действия и CRM-роботы и возвращают результат из внешнего сервиса. Разберём практическую механику.

Что доступно в scope bizproc

Методы делятся на несколько групп: управление экземплярами процессов, шаблоны, пользовательские действия (activity) для дизайнера БП и роботы CRM. Ключевая идея — REST-приложение может расширять движок своими действиями, которые исполняются на вашем сервере.

• bizproc.workflow.* — старт, список, остановка процессов;
• bizproc.template.* — управление шаблонами БП;
• bizproc.activity.* — свои действия в дизайнере;
• bizproc.robot.* — свои роботы в CRM;
• bizproc.event.send — вернуть результат ожидающему действию.

Принципиальное отличие от локальных бизнес-процессов в том, что REST-приложение не пишет PHP-код на портале. Вместо этого оно объявляет действие или робота с внешним HANDLER, и движок Битрикс24 в нужный момент отправляет на этот адрес HTTP-запрос. Логика исполняется на вашей стороне, а портал лишь оркестрирует процесс. Это позволяет подключать к воронкам продаж любые внешние вычисления — скоринг, проверку контрагента, расчёт цены — не нарушая обновляемость облака.

Ключевой параметр DOCUMENT_ID

Процесс всегда запускается над «документом» — сущностью определённого модуля. Её адресует массив DOCUMENT_ID из трёх элементов: модуль, класс сущности, идентификатор.

Тип сущности задаётся параметром DOCUMENT_TYPE той же тройкой, но с ID-справочником вместо конкретного элемента.

Запуск и остановка процесса

Запуск шаблона выполняет bizproc.workflow.start. Обязательны TEMPLATE_ID и DOCUMENT_ID, дополнительно передают PARAMETERS:

bizproc.workflow.start(TEMPLATE_ID: 154, DOCUMENT_ID: ["crm","CCrmDocumentDeal","DEAL_145"], PARAMETERS: {"reason":"reorder"})

Метод вернёт WORKFLOW_ID. Дальше:

• bizproc.workflow.instances — список запущенных экземпляров;
• bizproc.workflow.terminate — корректно завершить процесс по ID;
• bizproc.workflow.kill — принудительно убрать «зависший» экземпляр.

Разница между terminate и kill существенна: первый проводит процесс по штатному завершению (отрабатывают финальные действия, снимаются задачи), второй жёстко вычищает экземпляр из очереди, не выполняя завершающую логику. В продакшене по умолчанию используют terminate, а kill оставляют для аварийных ситуаций с застрявшими процессами. Параметр PARAMETERS при запуске соответствует полям, которые шаблон запрашивает у инициатора, — их состав виден в bizproc.template.list.

Свои роботы CRM

Робот — это действие, которое менеджер вставляет в автоматизацию воронки без программирования, а исполняется оно на вашем сервере. Регистрация:

bizproc.robot.add(CODE: "scoring", HANDLER: "https://you.app/robot", NAME: {"ru":"Скоринг"}, PROPERTIES: {...}, RETURN_PROPERTIES: {"score":{"NAME":{"ru":"Балл"},"TYPE":"int"}})

1. при срабатывании робота Битрикс24 шлёт POST на HANDLER с параметрами и event_token;
2. сервер выполняет расчёт;
3. результат возвращается методом bizproc.event.send с этим токеном.

Асинхронный ответ через event.send

И робот, и пользовательское действие могут быть «ждущими»: процесс приостанавливается, пока внешняя система не ответит. Ответ отправляют так:

bizproc.event.send(event_token: "eyJ0...", return_values: {"score": 87})

У ожидания есть предел по времени: если внешний сервис не ответит, процесс может зависнуть на этом шаге, поэтому в надёжных интеграциях предусматривают таймаут и запасную ветку. Токен event_token одноразовый и привязан к конкретному экземпляру — повторный event.send с тем же токеном вернёт ошибку. В return_values кладут ровно те поля, которые объявлены в RETURN_PROPERTIES робота, иначе движок не сможет их подставить в последующие действия воронки.

Шаблоны и задачи процессов

Шаблонами тоже управляют из REST — это удобно для тиражирования типовых процессов между порталами:

• bizproc.template.list — получить шаблоны с фильтром по DOCUMENT_TYPE;
• bizproc.template.add / bizproc.template.update — создать или обновить шаблон;
• bizproc.task.list — задачи БП, ожидающие действия пользователя;
• bizproc.task.complete — завершить задачу с решением (утвердить/отклонить).

Через bizproc.task.complete удобно строить внешние интерфейсы согласований — например, кнопки «Одобрить» в мобильном приложении.

При завершении задачи важно передать правильные параметры решения: идентификатор действия и статус (обычно поля вида TASK_ID и данные утверждения в FIELDS). Ошибка здесь приводит к тому, что процесс остаётся на месте, а пользователь думает, что согласовал документ. Поэтому внешние интерфейсы согласований всегда проверяют ответ метода и показывают явный результат. Список шаблонов с bizproc.template.add удобно вести в системе контроля версий и накатывать на новые порталы — это упрощает тиражирование типовых регламентов между филиалами.

Итог

Scope bizproc — мощный инструмент: он не только запускает и останавливает процессы, но и позволяет расширить движок собственными роботами и действиями, которые считают что угодно на вашем сервере и возвращают результат через bizproc.event.send. Правильно выбранный DOCUMENT_ID и флаг USE_SUBSCRIPTION — половина успеха.

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