Бизнес-процессы

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

Жизненный цикл: запуск (start) → выполнение → просмотр экземпляров (list) → обработка приостановок через событие (event) или запись в журнал (activity-log) → завершение (terminate).

Bitrix24 API: bizproc.workflow.*, bizproc.event.*, bizproc.activity.* Скоуп: bizproc

Запустить бизнес-процесс

POST /v1/workflows/start

Запускает экземпляр бизнес-процесса по шаблону для CRM-сущности, элемента списка или другого документа Битрикс24. Документ задаётся одной из двух форм: типом и ID для сделки, лида, контакта и компании либо явным идентификатором документа Битрикс24 для остальных.

Поля запроса (body)

Передайте templateId и ровно одну форму документа. Тело с entityType или entityId вместе с documentId отклоняется кодом 400 CONFLICTING_PARAMS.

Значения documentId по модулям:

Класс — второй элемент documentType шаблона в ответе GET /v1/bizproc-templates, а iblockId для источника элементов — число из третьего элемента iblock_<id>. Передавайте класс как есть: у обычного списка и у процесса в ленте новостей модуль один, lists, а классы разные. Шаблоны читаются только ключом OAuth-приложения. Если запрос шаблонов передаёт select, включите в него moduleId и entity, иначе первые два элемента documentType придут как null.

Класс и идентификатор передаются в Битрикс24 без изменений. В JSON обратная косая черта в имени класса экранируется удвоением, как в примере для Bitrix\Lists\BizprocDocumentLists.

Примеры

curl — личный ключ

curl -X POST https://vibecode.bitrix24.tech/v1/workflows/start \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"templateId":713,"entityType":"deal","entityId":5141}'

curl — OAuth-приложение

curl -X POST https://vibecode.bitrix24.tech/v1/workflows/start \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"templateId":713,"entityType":"deal","entityId":5141}'

JavaScript — личный ключ

const res = await fetch('https://vibecode.bitrix24.tech/v1/workflows/start', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    templateId: 713,
    entityType: 'deal',
    entityId: 5141,
  }),
})
const data = await res.json()
console.log(data.data.workflowId)

JavaScript — OAuth-приложение

const res = await fetch('https://vibecode.bitrix24.tech/v1/workflows/start', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    templateId: 713,
    entityType: 'deal',
    entityId: 5141,
  }),
})
const data = await res.json()

Поля ответа

Пример ответа

HTTP 201 Created

{
  "success": true,
  "data": {
    "workflowId": "69f0c2d5ade389.22457798"
  }
}

Пример ответа при ошибке

400 — в одном теле переданы обе формы документа:

{
  "success": false,
  "error": {
    "code": "CONFLICTING_PARAMS",
    "message": "Pass either { entityType, entityId } OR { documentId }, not both. Pick the shape that matches your target document namespace."
  }
}

Ошибки

Полный список общих ошибок API — Ошибки.

Известные особенности

• Один шаблон — несколько экземпляров. Один и тот же templateId можно запустить для разных сущностей одновременно. Каждый запуск получает отдельный уникальный workflowId.
• Повторный вызов запускает ещё один экземпляр. Запрос с тем же телом не отклоняется и не возвращает уже запущенный процесс: каждый ответ 201 означает новый экземпляр над тем же документом. Если запрос мог дойти, но ответ потерян, перед повтором проверьте список запущенных процессов. В нём видны только активные экземпляры: процесс, который уже завершился, туда не попадает. Завершённые экземпляры не возвращает ни один метод API Вайбкод, поэтому пустой список не доказывает, что запуска не было.

Смотрите также

• Список запущенных процессов
• Завершить бизнес-процесс
• Бизнес-процессы
• Шаблоны бизнес-процессов