Бизнес-процессы в Битрикс24: как создать и запустить

Что такое бизнес-процессы в Битрикс24 и когда без них не обойтись

Автоматизация этих процессов позволяет сократить время на рутину. Бизнес-процесс в Битрикс24 — это сценарий из блоков , который выполняется автоматически по событию (например, создание лида или смена стадии сделки) или запускается вручную из карточки. Блоки соединяются в цепочку, внутри которой работают переменные, условия и задания. Дизайнер бизнес-процессов позволяет создавать шаблоны для базовых сценариев без написания кода.

С помощью инструментов платформы можно настроить программный запуск бизнес-процессов (например, через метод CBPDocument::StartWorkflow или REST API), которые автоматизируют создание сделок, привязку товаров и постановку задач. В CRM-контуре это позволяет эффективно распределять лиды: входящий запрос сразу попадает в нужную воронку, ответственный получает уведомление, а руководитель видит актуальные данные в отчетах, что исключает потерю информации в почте.

Когда к нам приходят с задачей «автоматизировать продажи», мы первым делом смотрим, какие операции повторяются каждый день и где теряются заявки. Если ответственный за сделку меняется вручную, если согласование скидки идёт в мессенджере, если после оплаты никто не ставит задачу на отгрузку — это кандидаты на бизнес-процесс. Дальше — либо собираем шаблон в дизайнере, либо, если логика сложная, запускаем программно через CBPDocument::StartWorkflow (об этом ниже).

Типовые сценарии, где бизнес-процессы закрывают задачу:

• Согласование скидки — менеджер запрашивает, руководитель подтверждает или отклоняет прямо в карточке сделки, без чатов и звонков.
• Автозадачи после смены стадии — сделка перешла в «Оплачено», система сама ставит задачу логисту и бухгалтеру с дедлайном.
• Уведомления — ответственный, клиент или группа получают письмо или сообщение в Битрикс24 при наступлении события.
• Интеграция с 1С — бизнес-процесс выгружает данные сделки или товара в учётную систему и возвращает статус обратно.
• Обработка заявок — заявка с сайта превращается в лид, распределяется по менеджерам и получает первый ответ в течение минуты, а не часа.

Подробнее: события календаря битрикс.

Подробнее: массовое редактирование задач Битрикс24.

Как создать бизнес-процесс в Битрикс24 через дизайнер

Дизайнер бизнес-процессов — это инструмент для создания и редактирования шаблонов, доступный администраторам портала и пользователям с соответствующими правами. Для проектирования новых алгоритмов необходимо перейти в настройки CRM или раздел автоматизации, где визуальный конструктор позволяет выстраивать логику работы с помощью блоков и переменных без написания кода.

По нашему опыту, именно на этом шаге чаще всего спотыкаются интеграторы: настраивают REST, пишут код запуска, а шаблон в интерфейсе не появляется — потому что у учётки нет прав или выбран не тот тип документа.

Дизайнер работает не с абстрактными «процессами», а с конкретным типом документа. Сделки, лиды, смарт-процессы, счета, элементы инфоблоков — у каждого своя схема полей, свои стадии и стартовые события. Шаблон, собранный под сделку, не переносится на лид одним кликом. Поэтому первое, что стоит зафиксировать до открытия редактора: под какую сущность вы собираете логику и как она будет запускаться — вручную менеджером, автоматически при создании или при смене стадии. От этого зависит набор блоков и то, понадобится ли вообще программный запуск через CBPDocument::StartWorkflow — об этом ниже.

1. Выбрать тип документа и открыть дизайнер. Заходим в карточку сделки, лида или элемента смарт-процесса, вкладка «Бизнес-процессы» → «Добавить». В списке типов документов выбираем нужную сущность. Для смарт-процесса тип появится только если в его настройках включена опция использования в бизнес-процессах — иначе его в списке просто не будет.
2. Добавить стартовое событие. Определяем, как шаблон будет запускаться: вручную (пользователь жмёт «Запустить»), при добавлении документа или при изменении стадии. Стартовое событие — точка входа, от него тянется вся остальная цепочка.
3. Собрать блоки. Перетаскиваем на холст нужные действия: условие (ветвление по полям документа), задача (постановка поручения ответственному), уведомление (письмо или сообщение в чат), пауза (ожидание), REST-запрос (обращение к внешнему сервису). Блоки соединяются стрелками в том порядке, в котором должны выполняться.
4. Задать переменные и параметры шаблона. Переменные хранят промежуточные значения внутри процесса, параметры — входные данные, которые можно передать при программном запуске. Если планируете стартовать шаблон через REST или CBPDocument::StartWorkflow, параметры обязательны: без них нечего будет подставить в arParameters.
5. Опубликовать шаблон и запомнить его код. После публикации шаблон получает числовой идентификатор — он понадобится как workflowTemplateId для программного запуска и как TEMPLATE_ID для REST-метода bizproc.workflow.start. Код виден в списке шаблонов и в настройках конкретного шаблона.

Какие блоки дизайнера закрывают 80% задач

На практике большая часть шаблонов собирается из пяти-шести типов блоков.

Условие разводит логику по веткам: если сумма сделки больше порога, отправить на согласование руководителю, иначе сразу в работу. Задача ставит поручение конкретному сотруднику или роли с дедлайном. Уведомление шлёт письмо или сообщение в чат — часто дублирует задачу, чтобы ответственный не пропустил. Пауза притормаживает процесс до нужного момента или до реакции пользователя. REST-запрос дёргает внешний сервис: CRM, склад, биллинг. Этого набора хватает, чтобы закрыть типовые сценарии продаж, согласований и обработки заявок без единой строки кода. Код подключается позже — когда нужно стартовать процесс извне или добавить свой REST-метод.

Как устроены переменные и параметры шаблона

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

При запуске через CBPDocument::StartWorkflow параметры уходят в массиве arParameters — ключи должны совпадать с кодами параметров, заданными в дизайнере. Через REST то же самое передаётся в теле запроса к bizproc.workflow.start. Правило простое: собираете шаблон под программный запуск — сразу заводите параметры, а не хардкодьте значения в блоках.

Шаблон бизнес-процесса Битрикс24: из чего он состоит и как его переиспользовать

Самый частый запрос на эту тему звучит так: «сделали процесс в дизайнере, а как теперь запустить его из кода или переиспользовать на второй воронке?». Тут важно развести два понятия, которые в интерфейсе выглядят почти одинаково, а в API ведут себя по-разному — шаблон и запущенный экземпляр процесса. Шаблон — это опубликованный сценарий: граф блоков, код, тип документа, к которому он привязан, и набор параметров (переменные, константы, права). Экземпляр — конкретный «прогон» этого сценария по конкретной сделке или лиду, со своим состоянием и своей историей.

У нас в проектах это разделение всплывает постоянно. Клиент просит «добавить согласование в сделку» — мы правим шаблон, и все новые запуски идут уже по новой логике. А процессы, которые уже крутятся на сделках, продолжают идти по той версии, с которой стартовали.

Если этого не понимать, легко попасть в ситуацию, когда в дизайнере всё поправили, а менеджер в карточке видит старую цепочку. Поэтому дальше разберём, из чего шаблон состоит, что из этого меняется на лету, а что требует перезапуска, и как программно получить список шаблонов под нужный тип документа.

То есть правка шаблона — это правка «чертежа». Уже запущенные процессы держат собственную копию состояния и живут своей жизнью, пока не завершатся или их не остановят вручную.

Когда шаблонов становится больше десятка и они разложены по разным воронкам, руками искать нужный код в дизайнере неудобно. Для этого в модуле bizproc есть метод CBPDocument::GetWorkflowTemplatesForDocumentType() — он возвращает все шаблоны, привязанные к конкретному типу документа. Первым аргументом идёт массив-описание типа (модуль, класс сущности, ID документа), вторым — фильтр по автоматизации, третьим — признак «только активные».

В ответ приходит массив шаблонов, и в каждом — то, что нам обычно и нужно: ID шаблона, NAME, DESCRIPTION, DOCUMENT_TYPE, AUTO_EXECUTE (запуск автоматический или ручной) и PARAMETERS с описанием входных переменных. Именно ID из этого массива потом уходит первым аргументом в CBPDocument::StartWorkflow() — об этом ниже в статье.

<?php
use Bitrix\Main\Loader;

Loader::includeModule('bizproc');

// Тип документа: модуль CRM, сущность — сделка, ID документа
$documentType = ['crm', 'CCrmDocumentDeal', 'DEAL'];

// Получаем все активные шаблоны, привязанные к сделкам
$templates = CBPDocument::GetWorkflowTemplatesForDocumentType(
    $documentType,
    [],
    'Y' // только активные
);

foreach ($templates as $template) {
    // $template['ID']        — код шаблона для StartWorkflow
    // $template['NAME']      — человекочитаемое имя
    // $template['AUTO_EXECUTE'] — 1 = автозапуск, 0 = ручной
    // $template['PARAMETERS']   — описание входных переменных
}

Автоматизация бизнес-процессов Битрикс24: стартовые события и роботы

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

В дизайнере стартовое событие выбирается на первом блоке шаблона. Доступны такие варианты:

• Вручную — запуск кнопкой из карточки сущности, подходит для разовых согласований и сценариев с участием человека.
• При добавлении — срабатывает сразу после создания элемента, удобно для онбординга лида или сделки.
• При изменении поля — триггер на конкретное поле, например смену стадии или ответственного.
• По расписанию — периодический запуск через агента, для отчётов и регулярных проверок.
• Из REST-метода — внешний вызов через bizproc.workflow.start, когда старт инициирует интеграция или сторонняя система.

Когда речь заходит о коротких действиях после смены стадии, тут начинается развилка. У нас в практике правило простое: сначала смотрим на роботов, и только если их не хватает — идём в дизайнер бизнес процессов. Робот — это атомарное действие внутри карточки: отправить письмо, поставить задачу, изменить поле, вызвать вебхук. Настраивается за пару минут прямо в CRM. Публиковать шаблон не нужно, отдельной сущности «процесс», за которой надо следить, тоже не появляется.

Бизнес-процесс берут, когда сценарий длинный и нелинейный: есть паузы ожидания (например, «подождать ответа клиента три дня»), ветвления по условиям, параллельные ветки, участие нескольких согласующих по очереди. Роботами такое не собрать — они выполняются последовательно и не умеют «зависать» в ожидании события. Ещё один признак: если результат нужно вернуть во внешнюю систему или передать данные между сущностями через REST — тоже бизнес-процесс. Комбинировать их можно: робот в карточке запускает бизнес-процесс через блок «Запустить бизнес-процесс», а тот уже разворачивает длинный сценарий.

Как запустить бизнес-процесс программно через CBPDocument::StartWorkflow

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

В ядре Bitrix Framework за это отвечает модуль bizproc и класс CBPDocument — вспомогательная обёртка над API бизнес-процессов. Рекомендуемый метод запуска — CBPDocument::StartWorkflow. Он принимает четыре аргумента: workflowTemplateId (ID шаблона, целое число), documentId (массив из трёх элементов), arParameters (массив входных параметров) и arErrors (массив для ошибок, передаётся по ссылке). Проще говоря, вы даёте методу «что запускать», «на каком документе» и «с какими данными» — а он стартует экземпляр процесса и возвращает его ID.

Дальше разберём три вещи, на которых спотыкаются чаще всего: как собрать documentId, как передать параметры и как не пропустить ошибки запуска.

<?php
use Bitrix\Main\Loader;

// Модуль bizproc обязателен — без него класса CBPDocument просто не будет
Loader::includeModule('bizproc');

// documentId — массив из трёх элементов: модуль, класс сущности, ID документа
$documentId = [
    'crm',                              // модуль, которому принадлежит сущность
    'CCrmDocumentLead',                 // класс-описание сущности (для лида)
    'LEAD_'.$leadId,                    // ID документа с префиксом
];

Как собрать documentId правильно

documentId — это не просто ID записи, а тройка «где искать документ». Первый элемент — код модуля (crm, iblock, lists, tasks). Второй — класс-описание сущности: для лида это CCrmDocumentLead, для сделки CCrmDocumentDeal, для элемента инфоблока CIBlockDocument, для смарт-процесса — динамический класс вида CCrmDocumentDynamic_XXX. Третий элемент — ID документа с префиксом, который зависит от сущности.

У нас в практике путаница возникает ровно на втором элементе: разработчик копирует пример из документации для лида и подставляет его же для сделки — процесс молча не стартует. Универсальный способ узнать правильный класс — вызвать CBPDocument::GetDocumentType или посмотреть список шаблонов через CBPDocument::GetWorkflowTemplatesForDocumentType. Этот метод возвращает только те шаблоны, что привязаны к конкретному типу документа, и заодно подсказывает корректное имя класса.

Для смарт-процессов отдельный нюанс: в настройках самого смарт-процесса должна быть включена опция использования в бизнес-процессах. Иначе шаблон к нему не привяжется, и StartWorkflow вернёт ошибку.

Как передать параметры в arParameters

arParameters — ассоциативный массив входных значений для шаблона. Ключи — это коды параметров, которые вы задали в дизайнере на старте процесса: например, ApproverId, DiscountPercent, Comment. Значения — в том виде, который ожидает тип параметра: число, строка, массив, дата в формате Y-m-d H:i:s.

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

Ещё момент: arParameters не заменяет поля самого документа. Если нужно, чтобы процесс увидел актуальное значение поля сделки, сначала сохраните документ через CCrmDeal::Update, а потом запускайте процесс — иначе он стартует на старом состоянии.

<?php
use Bitrix\Main\Loader;

Loader::includeModule('bizproc');

$templateId = 42; // ID шаблона бизнес-процесса — замените на ваш
$documentId = ['crm', 'CCrmDocumentDeal', 'DEAL_'.$dealId];

$arParameters = [
    'ApproverId'      => $userId,
    'DiscountPercent' => 15,
    'Comment'         => 'Согласование скидки для сделки '.$dealId,
];

$arErrors = [];

$wfId = CBPDocument::StartWorkflow(
    $templateId,
    $documentId,
    $arParameters,
    $arErrors
);

if (!empty($arErrors)) {
    // arErrors — массив объектов/массивов с описанием ошибок
    foreach ($arErrors as $error) {
        AddMessage2Log('BP start error: '.print_r($error, true));
    }
} else {
    AddMessage2Log('Workflow started, ID = '.$wfId);
}

Как добавить свой REST-метод для бизнес-процессов через OnRestServiceBuildDescription

Когда внешняя система — CRM на стороне заказчика, мобильное приложение, интеграция с логистикой — должна запускать бизнес-процесс, отдавать ей штатный bizproc.workflow.start неудобно. Клиенту пришлось бы самому собирать documentId из трёх частей, знать ID модуля и класс сущности, разбираться с правами на шаблон. Одна опечатка в массиве — и процесс не стартует, а ошибка прилетит невнятная. Мы в таких случаях заворачиваем запуск в свой REST-метод: снаружи — простой вызов вида mycompany.deal.startApproval с одним понятным параметром, внутри — вся возня с CBPDocument::StartWorkflow, проверкой прав и маппингом полей.

Штатная точка расширения для этого — событие OnRestServiceBuildDescription. Оно вызывается, когда модуль rest собирает карту доступных методов, и позволяет добавить в неё свои. Патчить ядро не нужно, обновления Битрикс24 метод не сломают. Дальше разберём три вещи: как подписаться на событие, как описать метод в массиве и как реализовать callback.

<?php
// init.php
use Bitrix\Main\EventManager;
use Bitrix\Main\Loader;

Loader::includeModule('rest');

EventManager::getInstance()->addEventHandler(
    'rest',
    'OnRestServiceBuildDescription',
    ['MyCompanyRest', 'onBuildDescription']
);

class MyCompanyRest
{
    public static function onBuildDescription(): array
    {
        return [
            'mycompany.deal.startApproval' => [
                'callback' => [self::class, 'startApproval'],
                'options'  => [],
            ],
        ];
    }
}

Как описать метод в массиве события

Обработчик возвращает ассоциативный массив, где ключ — полное имя метода в формате scope.methodName, а значение — его дескриптор. Обязательный элемент один — callback: ссылка на вызываемую функцию или статический метод класса. Всё остальное опционально, но именно от него зависит, насколько удобно методом пользоваться снаружи.

В options обычно кладут описание параметров — типы, обязательность, значения по умолчанию. Это не жёсткая валидация на уровне ядра, но она попадает в документацию метода и помогает клиенту понять контракт. Если метод должен быть доступен только определённым приложениям, добавляют scope и ограничения по правам — тогда чужой OAuth-токен получить доступ не сможет. Для внутренних интеграций, где метод вызывается доверенной системой, хватит минимального дескриптора: имя, callback и пара ключей в options для читаемости.

Как реализовать callback и вернуть результат

Callback получает на вход массив параметров, пришедших от клиента, и должен вернуть результат в формате, который REST-слой отдаст наружу. Внутри — вся логика: валидация, поиск шаблона, сборка documentId, вызов CBPDocument::StartWorkflow. Метод StartWorkflow принимает четыре аргумента: ID шаблона, массив documentId из трёх элементов (модуль, класс сущности, ID документа), параметры запуска и ссылку на массив ошибок. Последний аргумент идёт по ссылке, поэтому ошибки собираем в отдельную переменную и проверяем её после вызова.

Если процесс стартовал, возвращаем клиенту идентификатор запущенного workflow — по нему потом можно отслеживать статус. Если нет — отдаём false и текст ошибок. Такой контракт понятен любой внешней системе и не заставляет её разбираться во внутренних классах модуля.

public static function startApproval(array $params): array
{
    $dealId = (int)($params['dealId'] ?? 0);
    if ($dealId <= 0) {
        return ['result' => false, 'error' => 'dealId is required'];
    }

    $templateId = (int)($params['templateId'] ?? 0);
    if ($templateId <= 0) {
        return ['result' => false, 'error' => 'templateId is required'];
    }

    $documentId = ['crm', 'CCrmDocumentDeal', 'DEAL_' . $dealId];
    $arParameters = [
        'approver' => (int)($params['approver'] ?? 0),
        'comment'  => (string)($params['comment'] ?? ''),
    ];

    $arErrors = [];
    $workflowId = CBPDocument::StartWorkflow(
        $templateId,
        $documentId,
        $arParameters,
        $arErrors
    );

    if (!empty($arErrors)) {
        return [
            'result' => false,
            'error'  => implode('; ', array_column($arErrors, 'message')),
        ];
    }

    return ['result' => true, 'workflowId' => $workflowId];
}

Запуск бизнес-процесса через REST API: bizproc.workflow.start и bizproc.workflow.template.add

REST-путь для бизнес-процессов — это история про интеграции, которые живут вне коробки. Пока вы работаете внутри одного портала, хватает PHP-вызова CBPDocument::StartWorkflow, о котором мы говорили выше. Но как только появляется внешний сервис — лендинг на отдельном хостинге, мобильное приложение, CRM заказчика в другом контуре, скрипт-коннектор к 1С, — PHP-метод становится недоступен: он выполняется только внутри ядра Bitrix. Здесь выходят на сцену REST-методы: bizproc.workflow.start для запуска и bizproc.workflow.template.add для создания шаблонов. Разбираем оба — что делают, какие параметры принимают, где их применять и на каких граблях спотыкаются интеграторы.

Ниже — рабочий пример запуска. Сначала получаем ID шаблона, потом стартуем с параметрами.

{
    "method": "bizproc.workflow.start",
    "params": {
        "TEMPLATE_ID": 17,
        "DOCUMENT_ID": ["crm", "CCrmDocumentDeal", "DEAL_421"],
        "PARAMETERS": {
            "Approver": "user_12",
            "DiscountPercent": 15,
            "Comment": "Скидка согласована с руководителем отдела"
        }
    }
}

При успехе метод возвращает {"result": {"workflow_id": "abc123..."}} — этот идентификатор стоит сохранить: по нему потом можно запросить статус или отменить процесс. Если что-то пошло не так, в ответе придёт блок error с полями error, error_description и error_internal. Читать надо в первую очередь error_description, там человеко-читаемая причина: «Workflow template not found», «Access denied», «Invalid document ID». Классические причины: TEMPLATE_ID принадлежит другому типу документа, шаблон не опубликован, или у токена нет прав на модуль bizproc и на CRM-сущность. Токену нужны скоупы bizproc и crm — без любого из них получите insufficient_scope. Для template.add дополнительно требуется право на редактирование шаблонов в портале: обычный пользовательский токен такое не пропустит, нужен административный вебхук или OAuth-приложение с расширенными правами.

Где разместить код запуска: init.php, свой модуль или агент

Место, куда вы положите вызов CBPDocument::StartWorkflow или регистрацию обработчика стартового события, определяет две вещи: когда код подхватится и переживёт ли он обновления платформы. Это не косметика — от выбора зависит, придётся ли вам через полгода объяснять заказчику, почему после апдейта ядра запуск сделок молча перестал работать. В облаке вопрос не стоит: там физического доступа к файлам нет, всё живёт в REST и роботах. В коробке вариантов ровно три.

Разберём их по возрастанию «правильности» — от быстрого хака до продуктового решения.

• Файл /local/init.php — самый быстрый способ: положил вызов, он подхватился при каждом хите. Минус — грузится всегда, даже когда бизнес-процесс не нужен, и размазывает логику по проекту.
• Свой модуль в /local/modules — правильнее для повторного использования: код изолирован, версионируется, подключается через Loader::includeModule только там, где нужен.
• Агент — для отложенного запуска: ставите задачу в очередь через CAgent::AddAgent, и процесс стартует не в момент запроса, а по расписанию или с задержкой.

Рекомендация простая и зависит от горизонта жизни кода. Если это одноразовая интеграция — разовый скрипт, который запускает согласование по кнопке из админки, — кладите в /local/init.php. Быстро, читаемо, не требует структуры модуля. Но как только запуск становится частью продукта — обрабатывает поток заявок, вызывается из нескольких мест, требует настроек — выносите в модуль под /local/modules с автозагрузкой классов и своим include.php. Тогда логика запуска живёт в одном месте, её видно в Loader::includeModule('vendor.module'), и она не мешает остальным хитам портала.

Агент стоит выбирать, когда запуск процесса не должен блокировать основной запрос: например, после создания лида через REST вы не хотите держать пользователя в ожидании, пока отработает StartWorkflow. Ставите агент с задержкой — и процесс стартует в фоне.

Комбинировать варианты тоже нормально: регистрация в init.php, а тяжёлая логика — в модуле.

Самые частые ошибки при запуске бизнес-процессов и как их отловить

За годы работы с Битрикс24 мы собрали небольшой «музей» грабель, на которые наступают почти все, кто запускает бизнес-процессы из кода. Самая коварная ошибка — пустой arErrors: метод CBPDocument::StartWorkflow возвращает false, но если массив ошибок не передан по ссылке или не прочитан, вы не увидите ни строчки причины. Процесс молча не стартует — и вы час ищете проблему там, где её нет.

Вторая классика — неверный documentId. Это массив из трёх элементов: модуль, класс сущности и ID документа. Передадите ['crm', 'CCrmDocumentDeal', 0] или забудете модуль — старт не пройдёт.

Третья — отключённая опция смарт-процесса: пока в настройках смарт-процесса не включена поддержка бизнес-процессов, шаблон для него не найдётся, и GetWorkflowTemplatesForDocumentType вернёт пустой массив. И четвёртая — лимиты REST: на облачных тарифах запросы к bizproc.workflow.start упираются в квоту (для Enterprise — 5 запросов в секунду с всплеском до 250), и часть запусков тихо отваливается по 429.

Настроить логирование просто, и делать это надо правильно. Главное правило: не пишите в echo и не выводите на экран — если код запускается внутри AJAX-обработчика или REST-запроса, любой вывод сломает JSON-ответ, и клиент получит «битый» результат вместо данных. Логируем через Bitrix\Main\Diag\Logger — он пишет в файл, не трогая поток вывода.

Ключевые места, которые вы захотите адаптировать под свой проект: путь к файлу лога (по умолчанию — в /bitrix/modules/, лучше вынести в /local/ или /upload/), уровень логирования и то, что именно фиксировать. Мы обычно пишем три вещи: код шаблона, собранный documentId и содержимое $arErrors после вызова. Нужно больше контекста — добавьте arParameters, но не тащите туда весь $arFields: получите мегабайты на каждый запуск. Для высоконагруженных сценариев имеет смысл ротация логов или отдельный канал для ошибок старта — тогда рабочие запуски не смешиваются с проблемными.

use Bitrix\Main\Diag\Logger;
use Bitrix\Main\Loader;

Loader::includeModule('bizproc');

$logger = new Logger('bizproc_start');

$templateId = 42; // замените на ID вашего шаблона
$documentId = ['crm', 'CCrmDocumentDeal', $dealId];
$arErrors = [];

$logger->info('StartWorkflow: попытка запуска', [
        'template'   => $templateId,
        'documentId' => $documentId,
]);

$result = CBPDocument::StartWorkflow(
    $templateId,
    $documentId,
    [],
    $arErrors
);

if (!$result && !empty($arErrors)) {
    $logger->error('StartWorkflow: ошибка запуска', [
            'template'   => $templateId,
            'documentId' => $documentId,
            'errors'     => $arErrors,
    ]);
}

Такой лог окупается с первого же разбора: вместо блуждания по коду вы открываете файл и видите точную причину.

Подробнее об услуге: внедрение и доработка Битрикс24 CRM.