# Изменения API: 24 июля 2026

[← Журнал изменений](/docs/changelog) · [Июль 2026](/docs/changelog/2026-07)

### FIX-0724-1: дела: нераспознанное имя поля фильтра теперь отклоняется с 400 UNKNOWN_FILTER_FIELD

**Было**

`GET /v1/activities` и `POST /v1/activities/search` молча отбрасывали неизвестный ключ фильтра: запрос возвращал `200 success` с фильтром, урезанным до пустого — то есть отдавал весь (owner-scoped или вообще весь) набор дел. Например `{"filter":{"ownerTypeId":2,"ownerId":3,"bogusField":123}}` игнорировал `bogusField` и возвращал все дела родительской сделки. Это расходилось с документацией и с поведением других сущностей CRM (компании, счета), где такой фильтр уже отклонялся.

**Стало**

Имя поля фильтра, которого нет в схеме дела — и которое не является пользовательским полем `UF_*`, ключом `id` или спец-токеном — теперь отклоняется до вызова Bitrix24 с `400 UNKNOWN_FILTER_FIELD` и списком доступных полей, как уже делают companies/quotes/contacts. Полный список фильтруемых полей возвращает `GET /v1/activities/fields`.

**Влияние на интеграторов**

Фильтрация по реальным полям дела (в camelCase или в родном ВЕРХНЕМ регистре Bitrix24), по полям `UF_*`, операторы (`>=`, `<`, `!` и т.п.), диапазоны и AND/NOT работают как прежде. Если вы полагались на молчаливый сброс нераспознанного ключа — уберите его из фильтра.

### NEW-0724-2: /fields бизнес-процессных действий и роботов отдаёт названия и описания полей

**Было**

`GET /v1/bizproc-activities/fields` и `GET /v1/bizproc-robots/fields` описывали каждое поле только типом и флагом readonly, без человекочитаемых подписей.

**Стало**

По каждому из 12 полей теперь приходят `label` и `description` по-русски, что упрощает построение форм и подсказок. Типы полей не изменились.

### FIX-0724-3: Скачивание своих файлов из хранилища больше не возвращает 403

**Было**

`GET /v1/storage/objects/:key` мог вернуть `403` при обращении к объекту, которым владелец ключа законно владеет, но который физически лежит под префиксом другого «семейства» хранилища (например, файлы сервера, видимые в списке разработчика). Объект показывался в списке, но скачать его, получить presigned-ссылку или сделать `HEAD` не удавалось.

**Стало**

Область доступа временных ключей учитывает фактическое семейство объекта (портал при этом остаётся привязан к контексту вызывающего), поэтому скачивание (`?download`), потоковая отдача (`?inline`) и `HEAD` для собственных объектов работают независимо от семейства. Проверка владения не изменилась — по чужому объекту по-прежнему приходит `404`.

### FIX-0724-4: GET /v1/workflows учитывает параметр limit

**Было**

`GET /v1/workflows` принимал `limit`, но молча его игнорировал — всегда возвращалась целая страница запущенных бизнес-процессов (до 50), сколько бы ни запросили.

**Стало**

`limit` уважается: в ответе не больше запрошенного числа записей. Значения больше 50 набираются постранично (потолок — 500); `meta.total` по-прежнему показывает общее число запущенных процессов.

### FIX-0724-5: деплой: приложение в оборачивающей папке архива больше не падает с ENOENT package.json

**Было**

Деплой (`POST /v1/infra/servers/:id/deploy`) на standalone-сервер архива, в котором проект завёрнут в единственную папку верхнего уровня (например, `myapp/package.json` вместо `package.json` в корне), падал на шаге установки:

```
npm error enoent Could not read package.json ... open '/opt/app/package.json'
```

Загруженный архив оставался соседом распакованного содержимого, поэтому авто-выравнивание единственной оборачивающей папки не срабатывало (в корне оказывалось две записи — архив и папка), и `package.json` оставался вложенным.

**Стало**

Загруженный архив удаляется до шага выравнивания, поэтому единственная оборачивающая папка «схлопывается», `package.json` оказывается в корне деплоя, и установка проходит штатно.

**Влияние на интеграторов**

Действий не требуется. Плоские архивы (файлы в корне архива) работают как прежде; для гарантии можно паковать плоско: `tar -czf build.tar.gz -C <папка_проекта> .`.

### FIX-0724-6: эндпоинты /v1/users* перестали возвращать 403 и 500 на ключах с доступом user

**Было**

На ключе только для чтения (READONLY) с доступом `user` вызов `GET /v1/users/me` возвращал `403 WRITE_BLOCKED_READONLY_KEY`, хотя это ридовый эндпоинт. Отдельно `GET /v1/users`, `GET /v1/users/:id`, `POST /v1/users/search` и `GET /v1/users/fields` возвращали `500 INTERNAL_ERROR` на порталах, где у одного из пользовательских полей (`UF_*`) пустое определение.

**Стало**

`GET /v1/users/me` работает на ключе только для чтения. Остальные `/v1/users*` возвращают данные и пропускают поле с пустым определением вместо падения.

**Влияние на интеграторов**

Действий не требуется — прежние вызовы продолжают работать, а ранее падавшие сценарии теперь отвечают корректно.

### NEW-0724-7: доставка callback bizproc-активити и роботов на Black Hole-приложение

Регистрация bizproc-активити или робота с `handler`, указывающим на ваш деплой-сервер Black Hole, теперь приводит к надёжной доставке callback выполнения (с токеном события, блоком авторизации, кодом и свойствами) в приложение. Раньше такой callback мог не дойти: онлайн-события Битрикс24 не повторяются, а спящий или просыпающийся сервер терял вызов. Платформа перехватывает `handler` при регистрации, ставит вызов в устойчивую очередь и повторяет доставку с будильником сервера и откатами.

Затрагивает [POST /v1/bizproc-activities](/docs/entities/bizproc-activities) и [POST /v1/bizproc-robots](/docs/entities/bizproc-robots) (а также их изменение). Новый код ошибки `SERVER_APP_MISMATCH` (400): сервер Black Hole за указанным `handler` должен принадлежать тому же приложению, что регистрирует активити. Регистрация такого `handler` через `/v1/batch` не поддерживается — используйте одиночный запрос (`BIZPROC_CALLBACK_BATCH_UNSUPPORTED`). Кроме того, `POST /v1/bizproc-robots` теперь заранее требует `code`, `name` и `handler` — при их отсутствии возвращается `400 MISSING_REQUIRED_FIELDS` вместо сырой ошибки Битрикс24 (как уже было у активити).

Возможность раскатывается постепенно и включается по аккаунтам: до включения на вашем аккаунте регистрация проходит как прежде, без управляемой доставки. **После включения меняется поведение batch-регистрации:** попытка зарегистрировать BH-`handler` через `/v1/batch` начинает отклоняться (`BIZPROC_CALLBACK_BATCH_UNSUPPORTED`) — переведите такие регистрации на одиночный `POST /v1/bizproc-activities` или `/v1/bizproc-robots`.