# Роботы бизнес-процессов

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

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

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

## Операции

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

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

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

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

Значение `documentType` — массив из трёх строк `[модуль, объект, тип]`. Робот применим только к сущностям CRM — набор уже, чем у [действий](/docs/entities/bizproc-activities) и [шаблонов](/docs/entities/bizproc-templates).

| Сущность | `documentType` |
|----------|----------------|
| Лиды | `["crm", "CCrmDocumentLead", "LEAD"]` |
| Сделки | `["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_XXX"]` |

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

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-robots`](./bizproc-robots/list.md) отдаёт массив строк — кодов зарегистрированных роботов, без остальных полей.
5. **Домен обработчика.** URL в `handler` и `placementHandler` должен быть на домене приложения — Битрикс24 вызывает обработчик по этому адресу во время автоматизации. Обработчик на субдомене Black Hole доставляет платформа — [Доставка вызовов действий и роботов](/docs/infra/bizproc-callbacks).

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

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

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

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

## Лимиты

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

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

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