# Изменения API: 11 сентября 2026

[← Журнал изменений](/docs/changelog) · [Сентябрь 2026](/docs/changelog/2026-09)

### FIX-0911-1: срез спецификации OpenAPI по скоупу перестал включать чужие рукописные разделы

**Было**

Параметр `?scope=<скоуп>` у [GET /v1/openapi.json](/docs/cli) резал только сгенерированные сущности. Рукописные разделы — боты, отзывы, инфраструктура, ИИ, файлы платформы, поиск, 1С, места встраивания — оставались в КАЖДОМ срезе целиком, независимо от запрошенного скоупа. Срез `?scope=tasks` весил 725 100 байт и содержал 284 пути, включая полные разделы `/v1/apps`, `/v1/placements`, `/v1/bots`, `/v1/feedback`.

**Стало**

Срез оставляет сущности запрошенного скоупа, рукописные пути того же раздела и служебные `/v1/me`, `/v1/guide`, `/v1/batch` — остальное вырезается. `?scope=tasks` теперь отдаёт 34 пути вместо 284. У рукописных разделов свои значения `?scope=`: `imbot` — боты, `vibe:feedback` — отзывы, `vibe:infra` — инфраструктура, `vibe:ai` — ИИ, `vibe:storage` — файлы платформы, `vibe:search` — поиск, `vibe:onec` — 1С, `placement` — места встраивания. Кто раньше читал чужой раздел из чужого среза — например, ботов из `?scope=crm`, — теперь получит его отдельным запросом по собственному скоупу раздела: несколько разделов сразу требуют по одному GET на каждый, объединение через запятую по-прежнему не поддержано. Полная спецификация без `?scope=` и ответ на мусорное, пустое или несводимое к одному скоупу значение не изменились. Семейства `apps`, `applications`, `cowork`, `oauth`, `partner-connect`, `coupons`, `portals`, `app-blueprints`, `agents` собственного значения `?scope=` не получили и остаются только в полной спецификации.

### FIX-0911-2: отказы POST /v1/doc-templates ведут к полю file, а не на Диск

**Было**

Отказ `MISSING_FILE_OR_FILE_ID` и отказ `UNSUPPORTED_MEDIA_TYPE` предлагали второй путь: загрузить файл на Диск и сослаться на него полем `fileId`. Шаблон по такому пути создавался, но документ по нему не формировался — `POST /v1/documents` отвечал `422 BITRIX_ERROR` с признаком `FILE_NOT_PROCESSABLE`.

**Стало**

Оба сообщения называют рабочий путь: содержимое `.docx` строкой base64 в поле `file`. Коды отказов, статусы и условия срабатывания прежние, изменён только текст сообщения. Поле `fileId` по-прежнему принимается — описание в `GET /v1/guide` теперь прямо говорит, что документ по такому шаблону не формируется.

### NEW-0911-3: у причины недоступности пробного периода Маркета появилось восьмое значение

Поле `unavailableReason` в блоке `activation.marketTrial` ответа [GET /v1/cowork/state](/docs/cowork/state) принимает новое значение `not_required_for_data` в дополнение к семи прежним.

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

Значение приходит только на облачных аккаунтах подписочной модели и только после включения соответствующей настройки платформы. Остальные значения и их смысл не изменились, поле по-прежнему присутствует всегда, а правило «значение `false` окончательно, неизвестное значение читайте как „активацию не предлагать“» действует без изменений — благодаря ему клиент, собранный до этой правки, ведёт себя корректно и без обновления.

Подписка по-прежнему нужна для вызовов ботов, развёртывания и пробуждения приложений, создания приложения и замены его ключа, привязки встроек и выдачи ключа агента.

### FIX-0911-4: Пакетный вызов сохраняет запрошенные поля

**Было**

[POST /v1/batch](/docs/batch) с действиями `list` и `search` мог пропускать поля из `select`, которые одиночный запрос возвращал: пользовательские поля задач, например `ufCrmTask`, и объявленные алиасы CRM, например `statusId`, `amount` и `currency`. Отбор задач по `UF_CRM_TASK` также терял поле в ответе одиночного запроса.

**Стало**

Одинаковый именованный `select` сохраняет одинаковые поля при одиночном и пакетном чтении. Пользовательские поля задач сохраняются и при выборе по имени `UF_CRM_TASK`, включая значение `null`.

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

Можно использовать именованный `select` вместо обхода через `select: ["*"]`. Написание пользовательских полей остальных сущностей не меняется.

### FIX-0911-5: расшифровка аудио отличает ошибку во входных данных от сбоя сервиса

**Было**

[POST /v1/audio/transcriptions](/docs/ai/audio/transcriptions) на файл, содержимое которого заведомо не аудио — текст, документ, картинка или архив, — отвечал `502 ai_provider_unavailable`, как на сбой сервиса распознавания. Клиенты повторяли такой запрос, и каждый повтор снова заканчивался ошибкой. Неизвестный ID в поле `model` уходил на распознавание и возвращался как `400 ai_provider_rejected`.

**Стало**

Содержимое, которое заведомо не аудио, отклоняется с `400 invalid_audio` до распознавания, списания нет. Неизвестный ID модели отклоняется с `404 ai_model_not_found` до распознавания — тем же кодом, что на `POST /v1/embeddings`. Ответ `HTTP 200` на аудиофайлы и известные модели не меняется.

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

Повторять запрос с `400 invalid_audio` без замены файла бессмысленно: такую ошибку стоит показать пользователю. Клиент, который не повторяет ответы `4xx`, продолжает работать без изменений. Если обработчик сверяет конкретные коды, добавьте в него `invalid_audio` и `ai_model_not_found`.

### FIX-0911-6: ответ на запись подсказывает, какие поля не были распознаны

**Было**

Опечатка в имени поля в теле `POST /v1/{entity}` или `PATCH /v1/{entity}/{id}` проходила молча: ответ успешный, а поле — например, сумма с ошибкой в названии — нигде не появлялось.

**Стало**

Ответ одиночной записи остаётся успешным с тем же статусом, а в `meta.warnings` приходит по записи `UNRECOGNIZED_WRITE_FIELD` на каждый ключ тела, которого нет ни в описании сущности, ни в списке полей вашего портала; `field` называет ключ. Это подсказка, не отказ: запись создаётся или меняется как прежде, `meta` появляется только когда есть что сказать, не больше десяти подсказок на ответ. Если список полей портала недоступен, подсказки не будет — платформа Вайбкод не предупреждает наугад.

### NEW-0911-7: Поле flow_ref в ответе запроса кода устройства

`POST /v1/connect/device/authorize` отдаёт новое необязательное поле `flow_ref` — идентификатор ЭТОЙ попытки входа, одинаковый у клиента и у платформы Вайбкод.

Нужен только для сведения статистики. Одно устройство входит много раз — переподключение, смена аккаунта, повтор после отказа, — и без общего имени попытки события одного входа не отличить от событий соседнего. Клиент штампует `flow_ref` в свои события и получает точное соответствие вместо подбора по времени.

Поле секретом не является, прав доступа не несёт, и восстановить по нему `user_code` нельзя. Клиент, который его не читает, работает как прежде.

### BC-0911-9: сумма налога у сделок и предложений объявлена только для чтения

> Поддержка старого формата до: не предусмотрена

**Было**

Поле `taxValue` у [сделок](/docs/entities/deals/fields) и [предложений](/docs/entities/quotes/fields) было объявлено доступным для записи и принималось с ответом `200`/`201`, но Битрикс24 его не сохранял: значение оставалось `0` при создании — в том числе в ручном режиме суммы, — при изменении и при импорте. Отличить это от успешной записи по ответу было нельзя.

**Стало**

Поле объявлено назначаемым сервером: Битрикс24 считает его по товарным позициям. Попытка записи отклоняется до обращения к Битрикс24 на каждой двери: создание и изменение возвращают `400 READONLY_FIELD`, импорт — `400 IMPORT_ITEM_VALIDATION`, пакетный запрос сущности — `400 BATCH_ITEM_VALIDATION`, а в общем пакетном запросе отказ приходит под соответствующим вызовом в `data.errors` с кодом `READONLY_FIELD`, пока остальные вызовы конверта исполняются. Описание поля прямо говорит, где задаётся налог: через товарные позиции. Замер 2026-09-11 на живых порталах обеих платформ: создание и изменение в обоих режимах суммы, импорт в обоих режимах.

**Что делать интеграторам**

Уберите `taxValue` из тела запросов на создание, изменение и импорт сделок и предложений — в том числе там, где запись читается целиком и отправляется обратно. Значение и раньше не сохранялось; налог задаётся товарными позициями, а поле остаётся в ответах на чтение.

**Затронутые эндпоинты:** [POST /v1/deals](/docs/entities/deals/create), [PATCH /v1/deals/{id}](/docs/entities/deals/update), [POST /v1/quotes](/docs/entities/quotes/create), [PATCH /v1/quotes/{id}](/docs/entities/quotes/update), [POST /v1/{entity}/import](/docs/import), [POST /v1/{entity}/batch](/docs/batch), [POST /v1/batch](/docs/batch).

### FIX-0911-10: описание API мессенджера совпадает с тем, что отвечают ручки

**Было**

Машинное описание (`/v1/openapi.json`) ручек чатов, уведомлений, базы знаний и ленты расходилось с их поведением, и клиент, собранный по нему генератором, ломался на первом же вызове.

`GET /v1/chats/find` описывался с параметрами `entityTypeId` и `entityId` (числа) — ручка читает `entityType` и `entityId` (строки, например `CRM` и `DEAL|123`) и на описанную форму отвечала `400 MISSING_PARAMS` всегда. `GET /v1/chats/search` описывался с параметром `query` — ручка читает `search`. `POST /v1/posts` описывался с телом `message` — ручка требует `text`.

Тридцать четыре операции этих семей не описывали ни одного отказа: только `200`, `201` или `204`, хотя ручки отвечают `400`, `401`, `403`, `404` и `422`. Генератор клиента не строил для отказов ни типов, ни обработчиков. Четыре операции (`POST /v1/chats/{chatId}/files`, `POST /v1/posts`, `POST /v1/posts/{id}/comments`, `DELETE /v1/posts/{id}/comments/{commentId}`) описывали успех как `200`, тогда как ручки отвечают `201` и `204`.

**Стало**

В части параметров и кодов успеха поведение ручек не менялось — исправлено описание (что поменялось в поведении, названо ниже отдельно). Параметры `GET /v1/chats/find` — `entityType` и `entityId`, строки, обязательные; `GET /v1/chats/search` — `search`; тело `POST /v1/posts` — `text` (обязательное), `title`, `recipients`, `files`. Успех четырёх операций описан тем кодом, которым ручка и отвечает: `201` и `204`. Успешный ответ по-прежнему `200`, `201` или `204` — ровно там, где и был: меняется описание, не ответ.

У каждой операции семей чатов, уведомлений, базы знаний и ленты, а также у `GET /v1/bots`, `POST /v1/bots` и `GET /v1/bots/revision`, описаны те отказы, которыми она отвечает, — из набора: `401` (`MISSING_API_KEY`, `INVALID_API_KEY`, `TOKEN_MISSING`), `403` (`SCOPE_DENIED`, `WRITE_BLOCKED_READONLY_KEY` на записях, `BITRIX_ACCESS_DENIED`), `404` (`ENTITY_NOT_FOUND` и коды конкретных ручек), `422` (`BITRIX_ERROR`), а где ручка проверяет вход сама — `400` с её кодами (`MISSING_PARAMS`, `MESSAGE_REQUIRED`, `INVALID_PARAMS`, `INVALID_POST_ID` и другие).

Попутно выправлено поведение — оба выправления только в сторону клиента, ни один прежде успешный вызов не отказывает: `POST /v1/chats/messages/bulk` — чистое чтение историй пачкой — отвечал ключу «только чтение» `403 WRITE_BLOCKED_READONLY_KEY`: общий контейнер `batch` считался записью; теперь такой ключ читает пачкой так же, как и по одному. Часть записывающих ручек чатов и ленты, вызванных вовсе без тела запроса (и без заголовка `Content-Type`), отвечала `500`; теперь такой вызов идёт тем же путём, что и с пустым телом `{}`: там, где поле обязательно, ручка отказывает сама (`DELETE /v1/chats/{chatId}/users` — `400 MISSING_PARAMS` про `userId`, `POST /v1/posts` — про `text`), а у создания чата, где все поля необязательны, запрос уходит в Битрикс24 как есть. Правка сообщения (`PATCH /v1/chats/{dialogId}/messages/{messageId}`) в это исправление не входит и выправляется отдельным изменением.

Семья ботов описана целиком: у каждой операции над конкретным ботом (`/v1/bots/{botId}…`, кроме удаления, повторной авторизации, переподписки и передачи бота, у которых свой набор) объявлены `400 INVALID_BOT_ID`, `404 BOT_NOT_FOUND`, `410 BOT_DISABLED` и `422` — отказы, которые даёт общий шаг поиска бота и обращение к порталу, — а также `401`.

Интерактивный справочник (`/docs` → API reference) перегенерирован из исправленного описания: карточки `GET /v1/chats/find`, `GET /v1/chats/search` и пример `POST /v1/posts` показывают рабочие параметры.

Что описание этих операций ПО-ПРЕЖНЕМУ не называет — сознательно, потому что решение общее для всего API, а не для мессенджера: отказ по балансу (`402 ACCOUNT_FROZEN`) и ответы `429 RATE_LIMITED`, `502 BITRIX_UNAVAILABLE`, `503` при недоступности или перегрузке Битрикс24 — они возможны на любой операции, обращающейся к порталу, и будут объявлены одним правилом на всё описание отдельным изменением. Обработчик клиента должен быть к ним готов уже сейчас.