Для 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 — при которых недоступно. Правило — начало типа документа, например ["crm", "CCrmDocumentDeal"], или редакция Битрикс24: "b24" — облако, "box" — коробка.
Пример: {"INCLUDE": [["crm", "CCrmDocumentDeal"], ["crm", "CCrmDocumentLead"]]}.
Ключи пишутся заглавными: со строчными поле принимается, но ничего не ограничивает. Значение не объект — 422 BITRIX_ERROR
ПолеusePlacement Типstring Обяз.нет ОписаниеОткрывать настройки действия в выдвижной панели: Y или N
ПолеplacementHandler Типstring Обяз.нет ОписаниеURL выдвижной панели настроек. Обязателен при usePlacement: "Y"

Примеры

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

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

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 — OAuth-приложение

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()

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata.id Типstring ОписаниеАдресуемый идентификатор. Если Битрикс24 вернул code, используется он. Иначе равен переданному code. Используется как :code в PATCH и DELETE

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

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

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

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 Код Описание
HTTP403 КодOAUTH_REQUIRED ОписаниеЗапрос отправлен API-ключом. Регистрировать действия можно только ключом авторизации
HTTP401 КодTOKEN_MISSING ОписаниеПередан ключ авторизации без заголовка Authorization: Bearer
HTTP401 КодWRONG_AUTH_SCHEME ОписаниеКлюч авторизации отправлен в заголовке Authorization: Bearer. Сам ключ передаётся в X-Api-Key, а Authorization: Bearer несёт токен сессии
HTTP401 КодINVALID_SESSION ОписаниеТокен сессии истёк или недействителен — пройдите авторизацию заново
HTTP403 КодSCOPE_DENIED ОписаниеКлючу не хватает скоупа bizproc
HTTP400 КодMISSING_REQUIRED_FIELDS ОписаниеНе передано обязательное поле — code, name или handler
HTTP400 КодSERVER_APP_MISMATCH Описаниеhandler ведёт на субдомен Black Hole, за которым нет сервера этого приложения — субдомена не существует либо сервер принадлежит другому приложению. Регистрируйте обработчик ключом того приложения, к которому привязан сервер
HTTP409 КодBIZPROC_MODULE_NOT_ENABLED ОписаниеБизнес-процессов на портале нет: модуль не входит в тариф либо выключен в настройках портала. Попросите администратора портала включить бизнес-процессы — до этого метод отвечает так же при любом числе повторов
HTTP503 КодBIZPROC_CALLBACK_RESOLVE_FAILED ОписаниеПлатформе не удалось сопоставить обработчик с сервером. Действие не зарегистрировано — повторите запрос
HTTP422 КодBITRIX_ERROR ОписаниеБитрикс24 отклонил регистрацию — причина в error.message

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

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

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

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