Для AI-агентов: markdown этой страницы — /docs-content/entities/bizproc-activities/create.md индекс документации — /llms.txt

Зарегистрировать действие

POST /v1/bizproc-activities

Регистрирует новое действие для дизайнера бизнес-процессов Битрикс24. Поля передаются плоско в корне JSON — без обёртки fields. Вызывается только ключом авторизации вместе с заголовком Authorization: Bearer.

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

Поле Тип Обяз. Описание
code string да Уникальный код действия. Разрешены символы a-z, A-Z, 0-9, ., -, _. Служит идентификатором в путях обновления и удаления
name string | object да Название действия. Строка или локализованный объект вида {"ru": "...", "en": "..."}
handler string да URL обработчика действия. Домен совпадает с доменом приложения
description string | object нет Описание действия. Строка или локализованный объект
authUserId number нет ID пользователя, чей токен передаётся приложению при вызове действия. Список: GET /v1/users
useSubscription string нет Ждать ли ответа от приложения перед продолжением процесса: Y или N
properties object нет Входные параметры действия — поля, которые заполняются в дизайнере
returnProperties object нет Выходные параметры действия — значения, которые действие возвращает в процесс
documentType array нет Тип документа, к которому применимо действие — модуль, объект, тип. Значения: Типы документов
filter object нет Правила INCLUDE / EXCLUDE по типу документа
usePlacement string нет Открывать настройки действия в выдвижной панели: Y или N
placementHandler string нет URL выдвижной панели настроек. Обязателен при usePlacement: "Y"

Примеры

Токен сессии выдаёт OAuth-авторизация и живёт 24 часа без продления — Передача ключа.

curl — ключ авторизации

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/bizproc-activities" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "notify_manager",
    "name": { "ru": "Уведомить руководителя", "en": "Notify manager" },
    "handler": "https://your-app.example.com/bizproc/notify"
  }'

JavaScript — ключ авторизации

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/bizproc-activities', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    code: 'notify_manager',
    name: { ru: 'Уведомить руководителя', en: 'Notify manager' },
    handler: 'https://your-app.example.com/bizproc/notify',
  }),
})

const { success, data } = await res.json()

Поля ответа

Поле Тип Описание
id boolean true — Битрикс24 подтвердил регистрацию действия. Это признак успеха, а не числовой идентификатор. Идентификатор действия — заданный вами code

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

JSON 
{
  "success": true,
  "data": {
    "id": true
  }
}

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

403 — вызов API-ключом:

JSON 
{
  "success": false,
  "error": {
    "code": "OAUTH_REQUIRED",
    "message": "bizproc-activities require an OAuth app key (vibe_app_*) with an Authorization: Bearer session — a personal vibe_api_* key lacks the per-user OAuth context Bitrix24 needs for these methods. Create an OAuth app (POST /v1/apps) and retry with its key. On this 403 switch keys — do NOT delete or recreate the app (that discards anything already registered under it, e.g. a bizproc robot you just registered)."
  }
}

Ошибки

HTTP Код Описание
403 OAUTH_REQUIRED Запрос отправлен API-ключом. Регистрировать действия можно только ключом авторизации
401 TOKEN_MISSING Передан ключ авторизации без заголовка Authorization: Bearer
401 WRONG_AUTH_SCHEME Ключ авторизации отправлен в заголовке Authorization: Bearer. Сам ключ передаётся в X-Api-Key, а Authorization: Bearer несёт токен сессии
401 INVALID_SESSION Токен сессии истёк или недействителен — пройдите авторизацию заново
403 SCOPE_DENIED Ключу не хватает скоупа bizproc
400 MISSING_REQUIRED_FIELDS Не передано обязательное поле — code, name или handler
400 SERVER_APP_MISMATCH handler ведёт на субдомен Black Hole, за которым нет сервера этого приложения — субдомена не существует либо сервер принадлежит другому приложению. Регистрируйте обработчик ключом того приложения, к которому привязан сервер
503 BIZPROC_CALLBACK_RESOLVE_FAILED Платформе не удалось сопоставить обработчик с сервером. Действие не зарегистрировано — повторите запрос
422 BITRIX_ERROR Битрикс24 отклонил регистрацию — причина в error.message

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

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

Обработчик на субдомене Black Hole получает надёжную доставку. Если handler ведёт на субдомен Black Hole вашего приложения, платформа берёт доставку вызовов на себя: ставит их в очередь, будит спящий сервер и повторяет попытки. Битрикс24 при этом хранит адрес приёмника платформы, а не переданный вами, — так и задумано, вызовы всё равно доходят до вашего пути. Обработчик на своём домене платформа не трогает: Битрикс24 обращается к нему напрямую и повторных попыток не делает.

Такой обработчик регистрируется одиночным запросом. Регистрация обработчика на субдомене Black Hole через пакетный вызов отклоняется — платформе нужен одиночный POST, чтобы завести доставку.

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

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