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

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

BC-1017-1: Проверка длины сообщений и подписей до записи

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

Было

Длинный текст пересылался в Битрикс24, где мог обрезаться. В обычном режиме несколько текстовых вариантов в теле могли переопределить проверенное значение.

Стало

После предшествующих проверок входа готовая строка длиннее 20 000 кодовых точек Unicode отклоняется с 400 MESSAGE_TOO_LONG до обращения к Битрикс24. В error.details приходят только field: "message", used, limit: 20000, unit: "unicode-code-points". Разметка, URL и упоминания входят в длину. Короткая строка передаётся без изменений.

В обычном режиме совпадающие message, MESSAGE, Message и вложенный fields.message, включая варианты регистра, дают один текст. Конфликт отклоняется с 400 INVALID_PARAMS. Объект не преобразуется в текст. Режим v2, пересылка и публикация загруженных файлов сохраняют плоское тело из разрешённых полей. Правка блока без текста в v2 сохраняется. Пустой текст правки по-прежнему даёт 400 MESSAGE_REQUIRED раньше проверки длины. У пересылки неверный тип и пустой комментарий, а также ошибки остальных полей по-прежнему дают 400 INVALID_PARAMS раньше проверки длины; без комментария пересылаются только сообщения. После отказа подписи файлы не загружаются, а uploadIds не расходуются.

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

Считайте кодовые точки готового текста, например Array.from(message).length в JavaScript. При превышении покажите ошибку пользователю и сохраните черновик. Передавайте одно поле message без конфликтующих вариантов, исправляйте подпись перед повторной публикацией. Автоматической обрезки, разбиения или отправки длинного текста файлом нет.

Затронутые эндпоинты: POST /v1/chats/{dialogId}/messages, PATCH /v1/chats/{dialogId}/messages/{messageId}, POST /v1/chats/{dialogId}/forward, POST /v1/chats/{chatId}/files, POST /v1/chats/{chatId}/files/uploads/publish.

FIX-1017-2: Пустой ход с инструментами получает объяснение

Было

Запрос к POST /v1/chat/completions с инструментами мог завершиться без ответа и вызова, а клиент принимал пустой ход за выполненную работу.

Стало

Платформа добавляет текстовое объяснение пустого хода или завершения вызова без самого вызова. В синхронном ответе также приходит предупреждение TOOL_CALL_MISSING, в потоке — отдельное событие с текстом перед финишем. HTTP 200 и finish_reason: stop не меняются; usage и списания сохраняются. Интеграторам ничего менять не нужно.

NEW-1017-3: Подготовка сервера для базы приложения

GET /v1/infra/servers/{id}/app-db/prepare возвращает состояние подготовки, шаги и недостающие компоненты. Нужны scope vibe:infra, доступ к приложению и включённая возможность app-db; чтение разрешено ключам READONLY.

POST /v1/infra/servers/{id}/app-db/prepare запускает подготовку по запросу владельца приложения или администратора аккаунта Битрикс24 с правом записи. Ключи READONLY и замороженный счёт блокируют запуск. Ответ — HTTP 200, если сервер уже готов, или HTTP 202 после принятия запроса. Опросите GET примерно раз в три секунды, учитывая Retry-After, до состояния ready или failed.

FIX-1017-4: Разделы каталога в схеме записи описаны массивом ID

Было

Поле iblockSection для товаров, SKU, торговых предложений и услуг описывалось как объект. Примеры создания показывали {} вместо массива ID разделов.

Стало

Схема записи и примеры показывают массив числовых ID разделов, например [47, 48]. Поле принимается при создании и обновлении. В ответе основной раздел по-прежнему представлен числовым iblockSectionId, а iblockSection не возвращается.

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

Существующие запросы с массивом ID продолжают работать. Используйте массив ID из GET /v1/catalog-sections.

Затронутые эндпоинты: POST /v1/catalog-products, PATCH /v1/catalog-products/{id}, POST /v1/catalog-skus, PATCH /v1/catalog-skus/{id}, POST /v1/catalog-offers, PATCH /v1/catalog-offers/{id}, POST /v1/catalog-services, PATCH /v1/catalog-services/{id}.

FIX-1017-5: закрытое соединение с базой приложения больше не отдаётся как «занято»

Чтение через GET /v1/infra/servers/:id/db, GET /v1/infra/servers/:id/db/schema, POST /v1/infra/servers/:id/db/query и GET /v1/infra/servers/:id/db/tables/:table/rows возвращает 409 APP_DB_WAL_CLOSED, если приложение закрыло соединение с базой в режиме WAL и оба файла -wal и -shm отсутствуют. Ответ содержит details.source: sqlite и details.hint, без retryable и Retry-After. Настройте приложение так, чтобы соединение оставалось открытым, — тогда базу можно будет смотреть и копировать.

Копия, принятая через POST /v1/infra/servers/:id/db/backups, при этой причине асинхронно завершается после одной попытки. В успешном ответе GET /v1/infra/servers/:id/db/backups у неё status: FAILED и errorCode: APP_DB_WAL_CLOSED.

Если так отказала защитная копия перед POST /v1/infra/servers/:id/db/execute или правкой строк, запись возвращает 409 APP_DB_WAL_CLOSED с той же безопасной подсказкой. SQL не отправляется, и запись не переходит в APP_DB_WRITE_OUTCOME_UNKNOWN.

NEW-1017-6: метка источника входа в device-flow

POST /v1/connect/device/authorize принимает необязательное поле login_source в JSON и form-urlencoded: аналитическую метку кнопки входа, значения которой определяет клиент. Строка обрезается по краям и должна соответствовать ^[a-z][a-z0-9_]{0,63}$. Некорректная метка не мешает входу и не влияет на права или выдачу ключа.

NEW-1017-7: Самоописание ключа сообщает правило дизайна нового интерфейса

GET /v1/me при доступности функции возвращает новый совместимый блок data.uiDesign: версию политики policyVersion, авторизованную привязку context, действия rules, инструкции instructions и описание CSS в css. Пока функция недоступна, сохраняется прежний ответ. Старые клиенты могут продолжать работать без чтения блока.

Для APP-ключа context.status: portal_bound содержит стабильный portalId и source: authorized_key_binding. MANAGEMENT-ключ всегда возвращает context.status: unresolved, portalId: null и source: none. Привязка к порталу не определяет назначение интерфейса, не доказывает запрос из iframe и не предоставляет прав на создание, встраивание или публикацию. При неопределённой привязке для внутреннего интерфейса нужно выбрать портал и прочитать самоописание его APP-ключом, а не брать первый элемент списка порталов.

Политика policyVersion: 2 отдельно обрабатывает стандартный запрос на создание нового приложения без указанного места: при portal_bound агент использует дизайн Битрикс24 и не задаёт повторных вопросов о месте или бренде; при unresolved выбирает аккаунт Битрикс24 либо уточняет назначение. Для внешней страницы агент уточняет оформление, а прочая задача с неизвестным назначением сохраняет короткое уточнение места. Дизайн существующего интерфейса сохраняется, для автоматизации без интерфейса CSS не подключается. Явное пожелание пользователя имеет приоритет; привязка не предоставляет прав и не доказывает iframe.

Блок css содержит закрепляемую version, путь href для приложения и публичный publicHref для собственного хостинга. Оба адреса указывают на CSS одной версии, доступный без API-ключа или сессии. Тема light-desktop использует системные токены шрифта без сетевого шрифта; локально подключаются только выбранные закреплённые официальные b24icons, не весь каталог. CSS подключается один раз, его версия закрепляется для нового интерфейса отдельно от policyVersion.

Перед выбором оформления и созданием интерфейса нужно прочитать полный ответ /v1/me и блок data.uiDesign. Если блок отсутствует, не поддерживается или прочитать его не удалось, агент сообщает, что правило не прочитано, и уточняет оформление у пользователя.

GET /v1/app/blueprints/:slug выдаёт русские и английские ТЗ с указателем на полный ответ /v1/me до выбора оформления. ТЗ остаётся markdown; неизвестная локаль возвращает английскую версию. Предметные требования чертежа сохраняются отдельно от оформления интерфейса: фоновая работа, сообщения бота и создаваемые документы не получают CSS автоматически.

FIX-1017-8: Поиск файлов принимает нужное количество результатов

Было

POST /v1/disk/search отклонял любое явно указанное limit, кроме 50, хотя схема разрешала значения от 1 до 1000.

Стало

limit от 1 до 1000 задаёт верхнюю границу выдачи. По умолчанию остаётся 50. Ответ может содержать меньше результатов: если hasMore=true, продолжайте с nextCursor, в том числе после пустой страницы. Продолжение сохраняет непрочитанный остаток. Ограничения поиска Битрикс24 сохраняются.

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

Вызовы с limit=10 и другими допустимыми значениями теперь работают. Существующие вызовы с 50 и без limit остаются допустимыми. Результаты могут смещаться при изменении индекса или прав доступа.