# Доставка вызовов действий и роботов

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

Скоуп: `bizproc`

Отдельного эндпоинта у механизма нет. Он включается сам, когда вы указываете адрес на субдомене Black Hole в поле `handler` — при [регистрации действия](/docs/entities/bizproc-activities/create), [регистрации робота](/docs/entities/bizproc-robots/create) или при смене обработчика у уже заведённых.

## Что происходит при регистрации

Платформа сопоставляет субдомен из `handler` с сервером вашего приложения и запоминает привязку — приложение, код действия или робота, сервер и путь обработчика. В Битрикс24 при этом сохраняется адрес приёмника платформы, а не переданный вами. Так и задумано: вызов приходит на приёмник, платформа доставляет его в приложение по тому же пути, который вы указали в `handler`. Из адреса берётся только путь — строка запроса после `?` в доставку не попадает, передавайте нужные значения отдельным путём обработчика.

Коды действий и роботов живут в разных реестрах, поэтому один и тот же `code` может быть зарегистрирован и действием, и роботом: платформа держит для них две отдельные привязки и не путает вызовы.

Если субдомена не существует, сервер за ним удалён или принадлежит другому приложению, регистрация отклоняется отказом `400 SERVER_APP_MISMATCH`. Регистрируйте обработчик ключом того приложения, к которому привязан сервер.

## Что приходит в обработчик

Платформа отправляет вызов POST-запросом на путь обработчика в формате `application/x-www-form-urlencoded`. Тело — ровно то, что прислал бы Битрикс24 при прямом вызове, включая `auth[application_token]` и `code`: обработчик, написанный под прямой вызов, менять не нужно.

Ответ платформа ждёт до 10 секунд — это окно уже, чем 30 секунд, которые даёт приложению [шлюз](/docs/infra/app-runtime) на запросе через субдомен. Ответ `2xx` считается доставкой, любой другой ответ или молчание — поводом повторить. Тяжёлую работу выносите в фон и отвечайте сразу.

Повтор приходит с тем же телом, поэтому обработчик должен быть готов увидеть уже обработанный вызов: приложение, которое ответило на двенадцатой секунде, свою работу выполнило, а платформа этого ответа не дождалась и вызов повторит. Отсеивайте повторы по `workflow_id` или `event_token`.

## Когда повторы заканчиваются

Повторы не бесконечны. Если доставка так и не удалась — приложение не ответило `2xx`, сервер не поднялся или его удалили, — платформа сообщает владельцу сервера в чат Битрикс24 и перестаёт доставлять вызовы этого обработчика. Следующие вызовы Битрикс24 приёмник примет, но до приложения они не дойдут, и повторного сообщения не будет. Доставка возобновляется, когда вы регистрируете обработчик заново или обновляете его с полем `handler`.

## Смена обработчика

Смена `handler` на субдомен Black Hole переключает действие или робота на надёжную доставку. Обратная смена — на адрес своего домена — возвращает прямые вызовы без повторов.

Запрос без поля `handler` привязку не меняет: обновление любых других полей оставляет доставку такой, какой она была после регистрации.

## Регистрация идёт одиночным запросом

Обработчик на субдомене Black Hole регистрируется и меняется только одиночным вызовом — платформе нужен отдельный запрос, чтобы завести доставку. [Пакетный вызов](/docs/batch) такую регистрацию отклоняет, и форма отказа зависит от того, куда отправлен пакет.

| Куда отправлен пакет | Что приходит |
|---|---|
| `POST /v1/batch` | `BIZPROC_CALLBACK_BATCH_UNSUPPORTED` в `data.errors` под `id` этого вызова. Остальные вызовы пакета выполняются, а если других вызовов в пакете нет — весь запрос отвечает `400` |
| `POST /v1/{entity}/batch` | `400 BATCH_ITEM_VALIDATION` на весь пакет. Имя `BIZPROC_CALLBACK_BATCH_UNSUPPORTED` и индекс элемента приходят внутри `message` |

Обработчик на своём домене проходит пакетным вызовом в обоих случаях.

## Включение по аккаунтам

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

## Публичный режим и авто-сон

[Публичный режим](/docs/infra/access/access-policy) для вызовов действий и роботов не нужен никогда: такой вызов проходит проверку доступа по своему признаку, при любой политике сервера.

Отключать авто-сон тоже не нужно, но только при включённой надёжной доставке: вызов приходит на приёмник платформы, она сама будит спящий сервер и довозит вызов через туннель. Пока доставка на аккаунте не включена, Битрикс24 обращается к субдомену напрямую, и вызов, пришедший на спящий сервер, теряется — повторов у прямого вызова нет. До включения держите сервер онлайн, как для [событий Битрикс24](/docs/infra/app-runtime).

Коды отказов каждой операции перечислены на её странице, полный список общих ошибок API — [Ошибки](/docs/errors).

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

- [Действия бизнес-процессов](/docs/entities/bizproc-activities)
- [Роботы бизнес-процессов](/docs/entities/bizproc-robots)
- [Что приходит в приложение](/docs/infra/app-runtime)
- [Подписки на события портала](/docs/infra/event-subscriptions)
- [Batch](/docs/batch)