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

← Журнал изменений · Сентябрь 2026

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

Было

Параметр ?scope=<скоуп> у GET /v1/openapi.json резал только сгенерированные сущности. Рукописные разделы — боты, отзывы, инфраструктура, ИИ, файлы платформы, поиск, 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 принимает новое значение not_required_for_data в дополнение к семи прежним.

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

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

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

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

Было

POST /v1/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 на файл, содержимое которого заведомо не аудио — текст, документ, картинка или архив, — отвечал 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 у сделок и предложений было объявлено доступным для записи и принималось с ответом 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, PATCH /v1/deals/{id}, POST /v1/quotes, PATCH /v1/quotes/{id}, POST /v1/{entity}/import, POST /v1/{entity}/batch, POST /v1/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 — они возможны на любой операции, обращающейся к порталу, и будут объявлены одним правилом на всё описание отдельным изменением. Обработчик клиента должен быть к ним готов уже сейчас.