# Действия бизнес-процессов

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

Читать, регистрировать, обновлять и удалять действия можно только ключом авторизации `vibe_app_…` — API-ключ `vibe_api_…` для этих методов не подходит. Управлять действиями может только администратор портала.

Битрикс24 API: `bizproc.activity.*`
Скоуп: `bizproc`

## Операции

- [Зарегистрировать действие](./bizproc-activities/create.md) — `POST /v1/bizproc-activities`
- [Список действий](./bizproc-activities/list.md) — `GET /v1/bizproc-activities`
- [Обновить действие](./bizproc-activities/update.md) — `PATCH /v1/bizproc-activities/:code`
- [Удалить действие](./bizproc-activities/delete.md) — `DELETE /v1/bizproc-activities/:code`
- [Поля действия](./bizproc-activities/fields.md) — `GET /v1/bizproc-activities/fields`

## Ключевые поля

| Поле | Тип | Описание |
|------|-----|---------|
| `code` | string | Уникальный код действия. Служит идентификатором в путях обновления и удаления |
| `handler` | string | URL обработчика действия. Домен должен совпадать с доменом приложения |
| `name` | string \| object | Название действия. Строка или локализованный объект |
| `properties` | object | Входные параметры действия — поля, которые заполняются в дизайнере |
| `returnProperties` | object | Выходные параметры действия — значения, которые действие возвращает в процесс |
| `documentType` | array | Тип документа, к которому применимо действие — модуль, объект, тип |
| `authUserId` | number | Пользователь, чей токен передаётся приложению при вызове. Список: `GET /v1/users` |

Полный список полей — [Поля действия](./bizproc-activities/fields.md). Все они передаются при [регистрации](./bizproc-activities/create.md) и [обновлении](./bizproc-activities/update.md). Идентификатор действия — символьный код `code`, а не числовой `id`.
### Типы документов

Значение `documentType` — массив из трёх строк `[модуль, объект, тип]`.

| Сущность | `documentType` |
|----------|----------------|
| Лиды | `["crm", "CCrmDocumentLead", "LEAD"]` |
| Контакты | `["crm", "CCrmDocumentContact", "CONTACT"]` |
| Компании | `["crm", "CCrmDocumentCompany", "COMPANY"]` |
| Сделки | `["crm", "CCrmDocumentDeal", "DEAL"]` |
| Предложения | `["crm", "Bitrix\\Crm\\Integration\\BizProc\\Document\\Quote", "QUOTE"]` |
| Счета | `["crm", "Bitrix\\Crm\\Integration\\BizProc\\Document\\SmartInvoice", "SMART_INVOICE"]` |
| Смарт-процессы | `["crm", "Bitrix\\Crm\\Integration\\BizProc\\Document\\Dynamic", "DYNAMIC_<entityTypeId>"]` |
| Процессы в ленте новостей | `["lists", "BizprocDocument", "iblock_<id>"]` |
| Списки в группах | `["lists", "Bitrix\\Lists\\BizprocDocumentLists", "iblock_<id>"]` |
| Документы Диска | `["disk", "Bitrix\\Disk\\BizProcDocument", "STORAGE_<id>"]` |

Набор шире, чем у [роботов](/docs/entities/bizproc-robots) — те применимы только к сущностям CRM.

## Что нужно знать перед работой

1. **Нужен ключ авторизации `vibe_app_…`, не API-ключ `vibe_api_…`.** Все пять операций требуют контекст приложения. API-ключ на любой из них вернёт `403 OAUTH_REQUIRED`. Отправляйте ключ авторизации вместе с заголовком `Authorization: Bearer <сессия>` — см. [Ключи и авторизация](/docs/keys-auth). Токен сессии выдаёт OAuth-авторизация, живёт 24 часа и не продлевается — после истечения вызовы возвращают `401 INVALID_SESSION` и нужна повторная авторизация. Как получить и передать токен — [Передача ключа](/docs/keys-auth#передача-ключа).
2. **Только администратор.** Управлять действиями может пользователь с правами администратора портала. У остальных Битрикс24 вернёт ошибку доступа.
3. **Идентификатор — символьный `code`.** В путях обновления и удаления указывается `code` (строка), а не числовой идентификатор. Получения одного действия по коду нет — операция `get` недоступна.
4. **Список возвращает только коды.** [`GET /v1/bizproc-activities`](./bizproc-activities/list.md) отдаёт массив строк — кодов зарегистрированных действий, без остальных полей.
5. **Домен обработчика.** URL в `handler` и `placementHandler` должен быть на домене приложения — Битрикс24 вызывает обработчик по этому адресу во время выполнения процесса. Обработчик на субдомене Black Hole доставляет платформа — [Доставка вызовов действий и роботов](/docs/infra/bizproc-callbacks).

## Связанные сущности

| Сущность | Эндпоинт | Назначение |
|----------|----------|-----------|
| Роботы | [`/v1/bizproc-robots`](/docs/entities/bizproc-robots) | Роботы автоматизации. Появляются и в конструкторе роботов, и в дизайнере процессов — рекомендуемый Битрикс24 формат вместо действий |
| Журнал процесса | [`POST /v1/workflows/activity-log`](/docs/automation/workflows/activity-log) | Запись сообщения обработчика в журнал бизнес-процесса |

## Типичный сценарий

1. Зарегистрируйте действие через [`POST /v1/bizproc-activities`](./bizproc-activities/create.md): задайте `code`, `name`, `handler` на домене приложения и входные параметры `properties`.
2. Действие появляется в дизайнере бизнес-процессов. Когда процесс доходит до него, Битрикс24 вызывает `handler` с заполненными параметрами.
3. При `useSubscription: "Y"` процесс ждёт ответа приложения, при `"N"` — продолжается сразу.
4. Проверить список зарегистрированных действий — [`GET /v1/bizproc-activities`](./bizproc-activities/list.md). Ненужное действие удалите по коду через [`DELETE /v1/bizproc-activities/:code`](./bizproc-activities/delete.md).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Batch-запросы | до 50 операций в [`POST /v1/batch`](/docs/batch) |
| Частота запросов | общий лимит API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [Роботы](/docs/entities/bizproc-robots)
- [Журнал бизнес-процесса](/docs/automation/workflows/activity-log)
- [Доставка вызовов действий и роботов](/docs/infra/bizproc-callbacks)
- [Ключи и авторизация](/docs/keys-auth)
- [Справочник API](/docs/api-reference)