Изменения API: 20 октября 2026

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

FIX-1020-1: справочник и OpenAPI показывают фактический ответ пяти операций

Было

Схема ответа GET /v1/users/me в OpenAPI перечисляла пять полей (id, name, lastName, email, isAdmin), хотя запрос возвращает всю запись пользователя. Карточка этого запроса в справочнике печатала поле userType, которого в ответе нет. Карточки POST /v1/chats/{chatId}/mute, GET /v1/activities/{activityId}/transcript и POST /v1/leads/{id}/convert показывали в примере ответа и в списке полей запись чата, дела или лида вместо того, что возвращает операция. В примере POST /v1/crm-documents/{id}/public-url стояла длинная ссылка, а Битрикс24 отдаёт короткую.

Стало

Схема GET /v1/users/me описывает поля записи пользователя под теми же именами, что GET /v1/users/{id}, без userType, и допускает ключи сверх них: WORK_*, часть PERSONAL_* и поля UF_* аккаунта Битрикс24 приходят в UPPER_SNAKE_CASE. Карточка печатает ровно эти поля. Карточки mute, transcript и convert показывают ответ операции: { chatId, muted }, { transcription } и { lead, deal, contact, company }. Пример public-url — короткая ссылка вида https://<адрес Битрикс24>/~a1B2c. Документация догнала фактический ответ: ответ HTTP 200 этих операций и его содержимое не меняются.

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

Правка клиента не нужна. Клиент, собранный по прежней карточке, мог ждать поля записи чата, дела или лида, а у GET /v1/users/me — поле userType. Их в ответе не было и нет: читайте поля, которые теперь перечисляет справочник.

FIX-1020-2: Нейтральные сообщения об ошибках ремонта сервера

Было

Поле error в GET /v1/infra/servers/{id}/repair-status при отказе ремонта могло содержать внутренний текст ошибки облачного управления.

Стало

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

FIX-1020-3: Публичные причины отказа при изменении бота и опросе событий

Изменение касается только PATCH /v1/bots/{botId} и GET /v1/bots/{botId}/events. Регистрация бота, восстановление регистрации и повторная подписка сохраняют прежние контракты.

Было

PATCH /v1/bots/{botId} мог возвращать HTTP 409 с внутренней причиной отказа и Retry-After: 5, даже когда повтор не мог помочь. GET /v1/bots/{botId}/events формировал ответ о восстановлении бота отдельно от общего обработчика.

Стало

На PATCH отказы из-за состояния бота возвращаются в трёх публичных классах: BOT_RECOVERY_IN_PROGRESS с Retry-After: 5, BOT_EFFECT_IN_PROGRESS с Retry-After: 30 и BOT_UNAVAILABLE без Retry-After. Последний означает, что состояние бота требует исправления через поддержку. Опрос событий использует тот же обработчик после освобождения слота опроса. Его текущий путь порождает только отказ восстановления BOT_RECOVERY_IN_PROGRESS с прежними пятью секундами ожидания. Незавершённое изменение бота само по себе не блокирует опрос.

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

Для PATCH используйте публичный класс и соответствующую задержку повтора. Общая нормализация защищает и границу ошибок опроса, но не добавляет ему новых причин отказа. Ответы BOT_EVENTS_BUSY и BOT_ID_REPLACED сохраняют прежнее поведение.

FIX-1020-4: отметка уведомлений прочитанными принимает пустое тело с заголовком JSON

Было

POST /v1/notifications/read с заголовком Content-Type: application/json и пустым телом отклонялся кодом 400 FST_ERR_CTP_EMPTY_JSON_BODY ещё до обработки запроса. Тот же запрос без заголовка проходил.

Стало

Пустое тело и тело из одних пробелов с заголовком Content-Type: application/json обрабатываются как {}. Ответ такой же, как на тело {}. Запрос без тела и без заголовка, как и раньше, обрабатывается как {}. В режиме format=v2 пустое тело проверяется как тело без поля ids и отклоняется кодом 400 INVALID_PARAMS. Тело, которое не разбирается как JSON, по-прежнему отклоняется кодом 400 FST_ERR_CTP_INVALID_JSON_BODY.

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

Действий не требуется. Клиент, который отправляет заголовок Content-Type: application/json на каждый запрос, больше не обязан добавлять тело {}.

FIX-1020-5: выкладка Compose показывает сбой контейнера за ответом 200

Было

POST /v1/infra/servers/{id}/deploy при выкладке Docker Compose мог закончиться успехом, если на опубликованном порту ответил HTTP 200, хотя контейнер того же проекта перезапускался и API не держался. Текст шага healthcheck не называл этот контейнер и не прикладывал журнал его запуска. Статус HTTP самого ответа деплоя при этом оставался 200.

Стало

Если контейнер проекта Compose из каталога extractTo перезапускается — в том числе давно, ещё с момента до выкладки, — или контейнер, стартовавший во время этой выкладки, после старта перезапускался, завершился с ненулевым кодом, перешёл в состояние dead или помечен Docker как unhealthy, шаг healthcheck завершается ошибкой, а в error.message есть имя сервиса, его состояние и журнал запуска контейнера. Успешная выкладка, где контейнеры проекта держатся, по-прежнему возвращает success: true. У POST /v1/infra/servers/{id}/deploy ответ HTTP 200 не изменился: сбой по-прежнему приходит в теле как success: false.

FIX-1020-6: удаление ключа больше не застревает после изменения бота

Было

Если бот ключа незадолго до удаления менялся через PATCH /v1/bots/{botId}, например при смене имени, DELETE /v1/keys/{id} бесконечно отвечал 409 KEY_BOT_CLEANUP_PENDING. Повтор запроса не помогал, ключ и бот оставались на месте.

Стало

Принятое Битрикс24 изменение бота, сделанное через PATCH /v1/bots/{botId}, больше не мешает удалению: платформа снимает бота в Битрикс24 и удаляет ключ, ответ — 204. Изменение, которое платформа ещё не завершила — ответ от Битрикс24 не получен либо по изменению продолжается работа, — по-прежнему даёт 409 KEY_BOT_CLEANUP_PENDING до завершения.

Исключение — изменение, которое задаёт боту новый токен: запрос с полем fields.botToken либо переключение в режим webhook, при котором платформа сама выдаёт боту новый токен. Пока такое изменение не доведено до конца, ответ остаётся 409 KEY_BOT_CLEANUP_PENDING, и повтор запроса этого не меняет.

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

Ничего менять не нужно. Ключи, удаление которых застряло после обычного изменения бота, удаляются повторным запросом. Если снять бота в Битрикс24 не удалось или последним изменением бота была смена токена, ответ остаётся 409 KEY_BOT_CLEANUP_PENDING.

NEW-1020-7: Подключения компании: проверка готовности на каждом этапе

В /v1/connect/authorize и /v1/connect/token операции CREATE и RECONNECT требуют включённого доступа и подтверждённой готовности. Отказы CONNECT_COMPANY_DISABLED и CONNECT_COMPANY_NOT_READY возвращаются без секрета. CONNECT_COMPANY_ATTEMPT_LIMITED сопровождается Retry-After.

CREATE возвращает секрет один раз. RECONNECT сохраняет его и возвращает credential_unchanged: true без api_key. ROTATE_SECRET работает для существующего подключения при выключенной новой выдаче, проверяет credential_version и возвращает новый секрет один раз. Повторный обмен кода возвращает invalid_grant. bitrix_ready отражает фактическую готовность к запросам, включая ожидание удаления старых вебхуков. AI и остальные scopes vibe:* для компании пока не поддерживаются.

NEW-1020-8: ИИ для подключения компании с отдельным согласием администратора

Подключения COMPANY поддерживают vibe:ai, если доступ к ИИ разрешён для портала и администратора, а scope разрешён приложению. При CREATE и первом добавлении ИИ через RECONNECT администратор явно отмечает дополнительное согласие. Без него подключение не начинается: CONNECTION_SCOPE_CONSENT_REQUIRED.

После каждого CREATE или RECONNECT с согласием на ИИ выполняется попытка создать отдельное разрешение ИИ, если его ещё нет. Если его запись не удалась, успешный ответ /v1/connect/token и выдача ключа сохраняются; администратор может повторить попытку, переподключив компанию с согласием на ИИ. Проверяйте доступность через capabilities.ai в статусе подключения. Отозванное разрешение администратор восстанавливает в настройках ИИ портала. RECONNECT его не восстанавливает; отзыв не отключает доступ к Битрикс24. vibe:storage остаётся недоступным для COMPANY.

FIX-1020-9: исправлена очистка портала при удалении приложения без права на встройки

Было

После DELETE /v1/apps/:id облачное приложение без права placement могло оставаться в Битрикс24, а повторы очистки прекращались после нескольких неудачных попыток.

Стало

Очистка такого приложения может выполняться с ключом разработчика подтверждённого создателя. Снятие регистрации происходит только после полной проверки и подтверждённого удаления встроек. Если такую проверку завершить нельзя, попытки продолжаются с интервалом до суток. Ответ остаётся HTTP 204 No Content: он подтверждает удаление в Вайбкод и отзыв парного API-ключа, а очистка Битрикс24 может продолжаться в фоне.

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

Менять запросы и обработку HTTP-статуса не требуется.

FIX-1020-10: повторное изменение бота после подтверждённой записи

Было

Если Bitrix24 подтверждал изменение бота, но новое имя ещё не появлялось при чтении, последующие PATCH /v1/bots/{botId} могли бессрочно возвращать 409 BOT_EFFECT_IN_PROGRESS.

Стало

Платформа повторно применяет подтверждённое изменение и проверяет результат. После совпадения имени следующий PATCH /v1/bots/{botId} снова выполняется; форма успешного ответа не изменилась.

FIX-1020-11: ключ хранилища с пустым сегментом или сегментом «.» отклоняется на входе

Было

POST /v1/storage/objects/upload и POST /v1/storage/objects/multipart/create принимали ключ вида docs//a.txt, docs/./a.txt или docs/a/.: проверка ключа ловила только .., лишний разделитель и сегмент . проходили в путь объекта.

Стало

Такой ключ отклоняется так же, как ключ с ..: ответ 400 с кодом STORAGE_INVALID_KEY, объект не создаётся. Ключи без пустых сегментов и без сегментов . и .. работают как раньше.

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

Если ключ собирается склейкой частей, уберите лишний разделитель и сегменты . перед отправкой.

FIX-1020-12: Пакетное создание товаров возвращает их идентификаторы

Было

Успешное создание товаров через POST /v1/catalog-products/batch могло не возвращать id в data.results. Чтобы обратиться к созданному товару, требовался отдельный поиск.

Стало

При action: "create" результаты возвращают числовой id, полученный при создании соответствующего товара. index связывает результат с элементом входного массива. Формат data.summary и обработка отказов сохранены.

FIX-1020-13: чтение и копирование базы спящего приложения

Было

Закрытая WAL-база без файлов -wal и -shm возвращала APP_DB_WAL_CLOSED даже у спящего приложения. Это мешало просмотру базы, созданию копий и восстановлению, которому нужна защитная копия текущих данных.

Стало

Если остановка приложения подтверждена, закрытую базу можно читать и копировать без пробуждения приложения. Исправление затрагивает GET /v1/infra/servers/{id}/db, GET /v1/infra/servers/{id}/db/schema, GET /v1/infra/servers/{id}/db/tables/{table}/rows, POST /v1/infra/servers/{id}/db/query, POST /v1/infra/servers/{id}/db/backups и POST /v1/infra/servers/{id}/db/restore, включая защитную копию перед восстановлением.

Для работающего приложения с закрытой WAL-базой отказ APP_DB_WAL_CLOSED сохраняется: соединение с базой должно оставаться открытым. Если приложение проснулось во время чтения или копирования, результат отбрасывается с APP_DB_BUSY; операцию можно повторить.

BC-1020-14: Новая версия уже созданного приложения требует того же доступа, что и новое приложение

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

Было

POST /v1/infra/servers/:id/deploy и POST /v1/infra/servers/:id/upload проверяли только ключ и права на сервер. Портал, у которого закончились подписка или нужный тариф, получал отказ при создании нового приложения, но продолжал выкладывать новые версии уже созданного.

Стало

Оба вызова отвечают тем же отказом, что и создание нового приложения: 402 MARKETPLACE_REQUIRED, 402 BY_PAID_ONLY, 402 KZ_PAID_ONLY или 402 UZ_PAID_ONLY, а когда подписку или тариф прочитать не удалось — 403 PORTAL_SUBSCRIPTION_UNREADABLE или 403 PORTAL_TARIFF_UNREADABLE. Тело то же, что у создания приложения: userMessage, alternatives и hint. Когда отказ снимает покупка, в error.details.upgradeUrl лежит ссылка на оформление, а 402 MARKETPLACE_REQUIRED может нести блок error.details.activation: если он есть, он говорит, откроет ли доступ пробный период Маркетплейса. Когда платформа не прочитала тариф или подписку — у обоих 403 и у 402 MARKETPLACE_REQUIRED с error.details.subscriptionUnverified — ссылки на покупку нет: error.details.remedy равен refresh_tariff, а в alternatives — перепроверка через GET /v1/me?refresh=tariff. Проверка идёт первой, до пробуждения сервера и до приёма архива, поэтому отказ ничего за собой не оставляет и номера операции не несёт. Уже работающее приложение продолжает отвечать, команды на сервере, логи и скачивание исходников остаются доступны.

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

Обрабатывайте эти коды на выкладке так же, как при создании приложения, и выбирайте действие по error.details.remedy. Если он равен refresh_tariff — вызовите GET /v1/me?refresh=tariff и повторите выкладку: после того как платформа прочитает тариф или подписку, повтор может пройти. Иначе покажите человеку userMessage и путь из alternatives: повтор без изменения подписки или тарифа даст тот же ответ. Заранее состояние видно в capabilities.servers.deploy в GET /v1/me. Слот строится по сохранённым тарифу и подписке, поэтому сразу после оплаты он может отвечать false чуть дольше, чем сама выкладка.

FIX-1020-15: Явный выбор bitrix-search в схеме исследования

Было

Схема OpenAPI для POST /v1/research не включала bitrix-search в допустимые значения provider, хотя этот выбор мог поддерживать исследование.

Стало

bitrix-search добавлен в перечень. Его доступность для исследования зависит от текущих возможностей провайдера: проверяйте capabilities.modes.research в GET /v1/search/providers. Условия доступа и требования к учётным данным сохраняются.

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

Клиенты, проверяющие тело по OpenAPI, могут явно указать bitrix-search. Прежние значения и выбор без provider сохраняются.

BC-1020-16: Быстрые ответы принимают только разделы своей линии

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

Было

POST /v1/openline-configs/:lineId/quick-replies и PATCH /v1/openline-configs/:lineId/quick-replies/:id принимали sectionId раздела другой линии или несуществующего раздела и возвращали успешный ответ. Такой быстрый ответ не появлялся в списке ни одной линии, а изменить или удалить его через API было нельзя.

Стало

sectionId, отличный от 0, сверяется с data.sections списка быстрых ответов этой линии. Раздел не из списка отклоняется с 400 INVALID_PARAMS, ответ не создаётся и не меняется. PATCH по-прежнему принимает текущий раздел ответа. Если быстрые ответы линии пользователю ключа недоступны, POST с sectionId возвращает 403 BITRIX_ACCESS_DENIED. Запросы без sectionId и с 0 работают как раньше.

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

Берите sectionId из data.sections ответа GET /v1/openline-configs/:lineId/quick-replies той же линии или передавайте 0, чтобы создать ответ без раздела.

NEW-1020-17: Страницы, поиск и фильтры списка коннекторов

Список коннекторов GET /v1/connectors принимает cursor, limit от 1 до 100, q, category, scope, type, view=mine, mode и sort. Запрос с параметрами списка возвращает nextCursor, total, счетчики counts и признак truncated: следующая страница доступна, пока он равен true. mode принимается без фильтрации до появления данных режимов; type=own возвращает пустой список. Сортировка popular пока использует порядок по названию. Без параметров сохраняются поля элементов и порядок по slug, добавляется только truncated.

BC-1020-18: обновление дела отклоняет крайний срок вместо ответа без изменений

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

Было

PATCH /v1/activities/:id с полем deadline в теле отвечал 200 с success: true, но срок дела не менялся: в ответе и при повторном чтении оставался прежний deadline. Пакетное обновление POST /v1/activities/batch с action: "update" вело себя так же.

Стало

Запрос обновления с deadline отвечает 400 READONLY_FIELD и не применяет ни одно поле тела. В ответе error.hint указывает на POST /v1/activities/:id/deadline. Пакетное обновление отклоняет такой элемент с 400 BATCH_ITEM_VALIDATION. В ответе GET /v1/activities/fields поле deadline помечено readonlyOnUpdate: true. Создание дела с deadline не изменилось.

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

Уберите deadline из тела обновления и меняйте срок вызовом POST /v1/activities/:id/deadline, а сдвиг на заданное время — POST /v1/activities/:id/postpone. Остальные поля передавайте в PATCH как раньше.

NEW-1020-19: Коннекторы сообщают тип и режимы сеанса

GET /v1/connectors возвращает в каждом элементе type: "connector" и modes — разрешенные поставщиком режимы cowork и code. По умолчанию доступны оба режима, в том числе у ранее опубликованных коннекторов. Прежние поля и порядок списка сохранены; поле mode по-прежнему обозначает доступ на чтение или запись.

NEW-1020-20: рантайм node24 на поддерживаемой версии Node.js

Каталог GET /v1/infra/runtimes пополнился рантаймами node24, node24-pg, node24-mysql, node24-redis, node24-mysql-redis, node24-pg-redis и node24-rag. Они идут в списке первыми, и новым приложениям на Node.js предлагается node24: поддержка Node.js 20 закончилась 30.04.2026. В галактике рантайм собирается из официального образа node:24-slim. На отдельной виртуальной машине каждый деплой ставит последнюю версию линии 24 из официального архива Node.js с проверкой подписи релизной команды Node.js. Рантаймы node20* остаются в каталоге и работают как прежде. У каждого элемента каталога появились поля deprecated и replacement: у node20* это true и ID замены той же комплектации, например node24-pg для node20-pg, у остальных — false и null.

NEW-1020-21: замена сервера приложения через API

Добавлены GET /v1/applications/{id}/available-servers и POST /v1/applications/{id}/replace-server. Первый метод возвращает серверы владельца карточки, на которые можно перенести приложение, и признак canCreateNew: можно ли завести новый сервер. Если нельзя, createNewBlocked называет причину. По ответу клиент заранее решает, показывать ли кнопку замены.

Второй метод переносит приложение на существующий сервер ({ "serverId": "…" }) или создаёт новый ({ "provider": "…", "plan": "…", "region": "…" }, значения те же, что у POST /v1/infra/servers). Старый сервер не удаляется, он остаётся у владельца. Ключ вызова не переназначается: поле callerKeyManagesServer говорит, управляет ли им этот ключ. Если сбой случился после переноса приложения, ответ остаётся 200, а проблемы перечислены в warnings: KEY_ASSIGN_FAILED, APP_URL_MOVE_FAILED, APP_URL_MANUAL, CATALOG_STALE, SERVER_KEY_STALE.

Заменить сервер может только владелец карточки.

Режим сна сервера переключается существующим PATCH /v1/infra/servers/{id}/run-mode.

NEW-1020-22: Выбор коннекторов для Коворка

Необязательные ASCII-заголовки X-Cowork-Connectors-Enabled и X-Cowork-Mode на каждом запросе к POST /v1/connectors/mcp сужают набор коннекторов и выбирают режим cowork или code. Фильтр действует до порога прямых инструментов, при поиске и direct/meta-вызовах. Некорректный заголовок возвращает 400 INVALID_BODY; без заголовков ответ сохраняется. Подключение и настройка остаются в веб-кабинете.

Карточка GET /v1/connectors/{slug} показывает инструменты опубликованной версии с признаком readOnly, компанию и разработчика, режимы и состояние без секретов. Запрещённый порталом коннектор скрыт и от администратора.

BC-1020-23: PHP 8.3 на отдельном сервере ставится из репозитория Ubuntu

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

Было

POST /v1/infra/servers/:id/deploy с runtime php83 или php83-mysql подключал на отдельном сервере сторонний PPA-репозиторий ppa:ondrej/php и ставил PHP 8.3 из него. Недоступность этого репозитория могла сорвать установку рантайма.

Стало

На новом сервере PHP 8.3 ставится из штатного репозитория Ubuntu 24.04: версия 8.3.6 с исправлениями безопасности Canonical. Команда php8.3, сервис php8.3-fpm и Composer остаются прежними. На серверах, где PPA уже подключён, ничего не меняется.

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

Если в composer.json приложения указано "php": ">=8.3.7" или выше, ослабьте ограничение до ^8.3: иначе на новом сервере composer install не пройдёт. Запросы к API менять не нужно. Серверы, где PPA уже подключён, не затронуты.

NEW-1020-29: Отметка официального коннектора в страницах каталога

При запросе списка коннекторов с параметрами каждый элемент содержит verified — отметку официального коннектора каталога. Карточка возвращает ту же отметку.

NEW-1020-30: Компания сервиса и режимы коннектора в мастерской

При создании и редактировании коннектора можно указать компанию сервиса отдельно от издателя и выбрать режимы Коворк и Код. Пустые поля компании можно очистить; для сохранения нужен хотя бы один режим.

NEW-1020-31: Компания сервиса в каталоге коннекторов

Компания сервиса хранится отдельно от издателя и задаётся через API мастерской. Карточка, список раздела и список хоста показывают компанию; серверный поиск учитывает её название. Для старых коннекторов без заполненной компании возвращается null.

FIX-1020-32: Счетчики групп коннекторов в Коворке

Счетчик «Доступные» совпадает с серверным отбором группы. Информационные строки ранее подключенных коннекторов, выключенных администратором, остаются во вкладке Коворка и не входят в эту группу или её счетчик.

FIX-1020-33: Retry-After отказа сверки бота — время до следующей плановой проверки

Было

Пока изменение бота ждало сверки с Битрикс24, повтор POST /v1/bots с тем же code получал 409 с заголовком Retry-After: 5, а другие изменения бота — 409 BOT_EFFECT_IN_PROGRESS с Retry-After: 30. Каждый повтор заново обращался к Битрикс24, даже когда до следующей плановой проверки оставалось несколько минут. Повтор DELETE /v1/bots/:botId, пока прошлое удаление того же бота ещё сверялось, отвечал как отказ Битрикс24: 502 BOT_DELETE_PARTIAL без Retry-After (с ?force=true — 409 BOT_DELETE_PENDING с Retry-After: 5) и делал лишний проверочный вызов в Битрикс24.

Стало

Заголовок Retry-After в таком отказе несёт время до следующей плановой проверки записи, не больше 300 секунд. Повтор раньше этого срока получает тот же отказ без обращения к Битрикс24. Коды ошибок и статус 409 не изменились. DELETE /v1/bots/:botId в этом случае, с ?force=true и без, отвечает 409 BOT_EFFECT_IN_PROGRESS с Retry-After и в Битрикс24 не обращается, запись бота сохраняется. Отказ самого Битрикс24 по-прежнему возвращает 502 BOT_DELETE_PARTIAL или 409 BOT_DELETE_PENDING.