Для 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-приложение
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-приложение
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 |
Пример ответа
{
"success": true,
"data": {
"id": "notify_manager"
}
}
Пример ответа при ошибке
403 — вызов API-ключом:
{
"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 сохраняет адрес своего приёмника вместо переданного вами. Такой обработчик регистрируется только одиночным запросом, а сама доставка включается по аккаунтам — Доставка вызовов действий и роботов.