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

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

FIX-1005-1: на демо снова доступен тариф bc-agent, разрешённых тарифов может быть несколько

Было

На демо-доступе POST /v1/infra/servers создавал сервер только на bc-micro: запрос с bc-agent получал 402 PLAN_NOT_ALLOWED_ON_TRIAL, а GET /v1/me называл в capabilities.servers.create.limits.allowedPlans и в note один тариф.

Стало

bc-agent на демо разрешён. Список разрешённых тарифов может содержать несколько значений: limits.allowedPlans в GET /v1/me и error.details.allowedPlans в ответе 402 PLAN_NOT_ALLOWED_ON_TRIAL перечисляют все, note называет каждый. Берите список из ответа, а не зашивайте один тариф в код.

FIX-1005-2: повторная подписка на событие больше не отвечает ошибкой

Было

Повторный вызов POST /v1/infra/servers/:id/event-subscriptions для события, обработчик которого уже был зарегистрирован в Битрикс24 (повтор после сбоя, смена appPath), отвечал 502 BIND_FAILED, и подписка не сохранялась. Если подписку заново оформлял другой установщик приложения, Битрикс24 заводил вторую регистрацию, и каждое событие приходило в приложение дважды.

Стало

Повторный вызов отвечает HTTP 200 и обновляет подписку: уже зарегистрированный обработчик считается успехом. Лишние регистрации того же события под другим пользователем снимаются, событие приходит один раз.

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

Действий не требуется. Повтор запроса после 502 BIND_FAILED теперь безопасен.

FIX-1005-3: операция деплоя спящего сервера доступна во время пробуждения

Было

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

Стало

После успешной авторизации запуск виден в списке операций как running уже во время пробуждения, в том числе до получения клиентом HTTP-ответа. Если пробуждение или последующая подготовка завершаются отказом, ответ при наличии операции содержит её идентификатор в X-Vibe-Operation-Id и error.operationId. При успешной фоновой записи исхода список показывает код отказа. Учёт операции остаётся best-effort: сразу после ответа она может оставаться running, а при сбое записи после истечения срока перейти в unknown без кода отказа. Отсутствие идентификатора не доказывает, что деплой не запускался.

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

При потере ответа найдите последний запуск через список операций сервера и прочитайте его исход перед повтором деплоя.

FIX-1005-4: Чтение страниц без явного выбора полей

Было

GET /v1/pages, GET /v1/pages/:id и POST /v1/pages/search без явного select могли возвращать 422 BITRIX_ERROR с кодом Битрикс24 SYSTEM_ERROR.

Стало

Поле domainId не запрашивается по умолчанию, чтобы чтение страниц не завершалось этой ошибкой. Менять обычные запросы не требуется. Поле остаётся в GET /v1/pages/fields.

В списке (GET /v1/pages) и поиске (POST /v1/pages/search) явный выбор domainId передаётся в Битрикс24 и по-прежнему может вернуть указанную ошибку.

В карточке (GET /v1/pages/:id) domainId не возвращается даже при явном select: карточка запрашивает у Битрикс24 поля по умолчанию, а select только сужает ответ. Поле id возвращается всегда.

BC-1005-5: список комментариев задачи читает старое хранилище и применяет к нему постраничность

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

Было

GET /v1/tasks/:taskId/comments на задаче с чатом читал только чат. Комментарии, оставленные до перехода портала на новую карточку, в чат не переезжают, поэтому такая задача отвечала 200 с пустым data при живых комментариях — и клиент не мог отличить «комментариев нет» от «мы посмотрели не туда». Одиночный GET /v1/tasks/:taskId/comments/:id те же комментарии находил.

Когда ответ собирался из старого хранилища, limit и offset к нему не применялись: что Битрикс24 отдал на один вызов, то и возвращалось целиком, а meta.hasMore на таком ответе всегда был false.

Стало

Если чат прочитан до конца и не дал ни одного комментария, список дочитывает старое хранилище и отвечает из него — один дополнительный вызов Битрикс24 и только там, где ответ иначе был бы пустым.

В meta появилось поле sources — массив хранилищ, содержимое которых ответ узнал. Хранилище попадает в список, если отдало комментарии либо было прочитано до конца и оказалось пустым; не попадает то, про которое ответ не узнал ничего. Попадание в список не значит «прочитано целиком»: полноту несёт meta.truncated, и чат попадает в sources вместе с truncated: true, если обход оборвался, собрав хотя бы один комментарий. Окончательное «комментариев у задачи нет» даёт набор ["chat", "legacy"] без meta.truncated. Набор ["legacy"] значит, что чат НЕ ПРОЧИТАН — метод отказал, скоупа нет, форму ответа не разобрали или обход оборвался. ⚠️ truncated на таком ответе может ОТСУТСТВОВАТЬ: он говорит только о том, что ПРОЧИТАННОЕ прочитано не целиком, а про непрочитанный чат сообщает сам набор. Поэтому проверка if (!meta.truncated) → ответ полный неверна: судите по набору И по флагу вместе. Задача, которой чат не выделен, сюда НЕ относится: чат-комментариев там нет по построению, поэтому набор полный. Доказательством служит только свежая проверка — в пределах пятиминутного кэша та же задача честно отвечает ["legacy"], потому что за это время чат мог появиться. ["chat"] — не ответило старое хранилище, [] — не ответило ни одно.

limit и offset теперь действуют и на ответе из старого хранилища: приходит запрошенная страница, а не всё, что Битрикс24 отдал одним вызовом. Ответ остаётся 200.

⚠️ Старое хранилище Битрикс24 отдаёт на один вызов не больше 50 комментариев и постраничной навигации по ним не предоставляет. Поэтому два поля meta отвечают на РАЗНЫЕ вопросы. meta.hasMore — «в том наборе, из которого собран этот ответ, есть ещё строки»: его можно листать offset'ом. meta.truncated — «вызов вернулся полным, и за ним могут быть ещё комментарии, которые спросить нечем». hasMore: false вместе с truncated: true значит «окно вы прошли до конца, но это не конец комментариев задачи».

meta.total на этом пути — счётчик Битрикс24, и считает он НЕ всегда всю задачу: filter уходит в Битрикс24 как есть, поэтому с фильтром это число подошедших под фильтр. Без фильтра счётчиком по задаче оно тоже НЕ становится: task.commentitem.getlist зовётся один раз, без start/NAV, и когда Битрикс24 своего счётчика не вернул, total вырождается в число строк этой единственной страницы. Превышать длину data оно может, дотянуться дальше одного вызова — нет. Читайте его вместе с truncated: «столько есть по этому запросу, столько пришло, это не всё». ⚠️ Не читайте total как «у задачи столько комментариев» — ни с filter, ни без него. Полноту судите по truncated и meta.sources, а не сравнением с total.

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

Если вы передавали limit или offset на задаче, комментарии которой лежат в старом хранилище, раньше они не действовали и приходило всё, что Битрикс24 отдал одним вызовом. Теперь придёт ровно запрошенная страница — проверьте такие места.

На длинной истории старого хранилища не считайте meta.hasMore: false концом списка: на этом пути поле описывает только то, что пришло одним вызовом Битрикс24. Полный набор комментариев такой задачи этот эндпоинт сейчас не отдаёт.

FIX-1005-6: OpenAPI описывает передачу объектных фильтров

Было

Для части объектных query-фильтров OpenAPI не задавал способ сериализации. Клиент, созданный по спецификации, мог передать поля отдельно от filter.

Стало

Чисто объектные query-параметры объявлены с style: deepObject и explode: true: например, filter[amount]=1000. Это касается общих списков сущностей, /v1/requisite-links, /v1/openline-configs и /v1/voximplant-sip. Вложенные объекты и массивы остаются расширением, поддержка которого зависит от клиента; для сложных фильтров в списках сущностей используйте POST /search.

BC-1005-7: общий лимит запросов в минуту на ключ и на владельца ключей

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

Было

Суммарного ограничения на клиента не было: лимиты считались отдельно на каждом методе.

Стало

Запросы к /v1 считаются в общем счётчике: 600 в минуту на ключ и 1200 в минуту на все ключи одного владельца. Опрос событий бота (GET /v1/bots/{botId}/events) считается отдельными счётчиками и общий счётчик остальных запросов не расходует: 120 в минуту на бота, а также с теми же порогами 600 на все опросы одного ключа и 1200 на все опросы ключей одного владельца. При превышении — 429 с кодом CALLER_RATE_LIMITED. Заголовок X-RateLimit-Scope называет сработавший счётчик (key, user, bot), Retry-After — секунды до конца минутного окна. Повтор раньше этого срока окно не продлевает. Ключ приложения считается иначе: 600 в минуту на каждого пользователя приложения на портале, общего счётчика владельца у него нет. AI-методы в этот счётчик не входят, кроме управления ключами AI-провайдеров (/v1/ai/credentials и /v1/ai/providers) — оно считается наравне с остальными запросами. Названные числа — платформенные потолки: они делятся между репликами бэкенда, и клиент на одном соединении может получить отказ раньше названного числа; эффективное число в заголовке не публикуется. Подробности — Лимиты, очереди и паузы.

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

При 429 с кодом CALLER_RATE_LIMITED дождаться срока из Retry-After и повторить запрос, повтор записи безопасен. Для выгрузок читать записи страницами через поиск и объединять вызовы через POST /v1/batch. Держать темп заметно ниже потолков (120 в минуту на бота, 600 на ключ, 1200 на владельца) и при 429 ждать Retry-After.

NEW-1005-8: Режим «Только чтение» для чатов Коворка: ключи чата и выбор режима

Десктоп Коворк получил три метода для чатов в режиме «Только чтение». GET /v1/cowork/portal-access и PATCH /v1/cowork/portal-access читают и меняют выбор режима следующих чатов человека в этом Битрикс24: только чтение или с изменениями. Изменение передаёт номер прочитанной версии и при устаревшей версии получает 409 COWORK_PREFERENCE_CONFLICT. POST /v1/cowork/chat-key выдаёт ключ чата выбранного режима, и десктоп отдаёт его агенту вместо своего ключа. Ключ чата не шире текущих прав ключа устройства и перестаёт работать вместе с ним (401 COWORK_CHAT_KEY_INACTIVE). Ключ чата «только чтение» не меняет данные Битрикс24: такая попытка получает 403 COWORK_READONLY до отправки в Битрикс24. Ключ чата не управляет ключами и выбором режима (403 COWORK_CHAT_KEY_FORBIDDEN), а GET /v1/me с этим ключом отдаёт поле coworkPortalAccess с фактическим режимом чата. Вызывать новые методы может только ключ десктопа Коворк, другой ключ получает 403 COWORK_DESKTOP_KEY_REQUIRED. Пока функция не включена для аккаунта, все три метода отвечают 403 COWORK_CHAT_KEY_DISABLED.

NEW-1005-9: чаты одного проекта отдельным списком

Новый эндпоинт GET /v1/chats/projects/{projectId}/recent возвращает чаты одного проекта (коллабы) из списка недавних: собственный чат проекта и вложенные в него чаты. projectId — идентификатор чата проекта, тот же chatId, что у его строки в GET /v1/chats/recent/collabs. Нужен скоуп im.

Ответ построен как у GET /v1/chats/recent с format=v2 — recentItems, chats, users, messages, files, hasNextPage — и на первой странице дополнен объектом data.sectionMeta со сведениями о проекте. Непустой data.sectionMeta.fixedChatIds — признак того, что projectId указывает на чат проекта: ID другого чата отвечает 200 с пустыми коллекциями. В data.chats у собственного чата проекта parentChatId равен 0, у вложенных чатов — projectId. Постраничный обход — как у списка коллаб: limit от 50 до 200, следующая страница по lastMessageDate. Другие параметры запроса эндпоинт не принимает и отвечает 400 INVALID_PARAMS.

Первая страница — не чистое чтение: при первом чтении проекта Битрикс24 создаёт для владельца ключа чат CoPilot этого проекта, один раз на проект и только участнику. Поэтому ключу, режим доступа которого запрещает запись, первая страница отвечает 403 WRITE_BLOCKED_READONLY_KEY. Страницы с lastMessageDate только читают и такому ключу доступны.

BC-1005-10: предел устройств при выдаче ключа десктопа Коворк/Код и код COWORK_DEVICE_LIMIT_REACHED

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

Было

Выдача ключа настольного приложения Коворк/Код через Connect (вход по коду устройства, страница согласия, обмен токена Атласа) не ограничивала число живых ключей десктопа у пары «пользователь и портал»: каждый вход добавлял новый ключ.

Стало

У пары «пользователь и портал» может быть не больше 10 живых ключей десктопа. Отозванные, заблокированные и истёкшие ключи место не занимают, повторное подключение той же установки место не тратит.

Сверх предела вход клиента, который не сообщает идентификатор установки, отзывает самые давно не использовавшиеся ключи таких же клиентов без идентификатора установки — столько, сколько нужно, чтобы вернуться к пределу (обычно один). Если таких ключей у пары не хватает, в том числе когда все места заняты ключами с идентификатором установки, выдача отклоняется кодом COWORK_DEVICE_LIMIT_REACHED (HTTP 409, details.used и details.limit). При возврате на redirect_uri приложение получает error=access_denied и этот код в error_description.

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

Передавайте идентификатор установки при входе: тогда повторное подключение того же компьютера место не тратит, а ключи клиента не попадают под вытеснение. На COWORK_DEVICE_LIMIT_REACHED покажите человеку, что нужно отключить неиспользуемое устройство в разделе Коворк/Код кабинета Вайбкод, и повторите вход.

BC-1005-11: авто-сон больше не выключает приложение с fetch-ботом

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

Было

Обычный сервер или galaxy-приложение с активным fetch-ботом могло хранить числовой порог простоя и отображаться в режиме IDLE. Запросы PATCH /v1/infra/servers/:id/sleep и PATCH /v1/infra/servers/:id/run-mode принимали этот режим, хотя исходящий опрос Битрикс24 не считался входящей активностью и приложение засыпало.

Стало

GET /v1/infra/servers и GET /v1/infra/servers/:id возвращают новое поле idleSleepProtected. Для приложения с активным fetch-ботом оно равно true, а режим без расписания — ALWAYS, даже если сохранён числовой порог. Запрос числового sleepAfterMinutes или режима IDLE теперь отвечает 400 AGENT_IDLE_SLEEP_FORBIDDEN. Это относится и к POST /v1/infra/servers с явным runMode: IDLE, если ключ связан с активным fetch-ботом: отказ приходит до создания сервера. null и режим SCHEDULE остаются доступны. При удалении назначенного расписания с reassign=true такое приложение переходит в эффективный ALWAYS и сохраняет порог простоя; серверы агентов и ботов переходят в ALWAYS с очищенным порогом.

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

Перед изменением авто-сна проверяйте idleSleepProtected. При значении true используйте null для круглосуточной работы или назначайте расписание. При создании сервера с ключом активного fetch-бота не запрашивайте runMode: IDLE. Обрабатывайте AGENT_IDLE_SLEEP_FORBIDDEN и при создании, и при изменении сервера. Перед удалением назначенного расписания с reassign=true учитывайте переход защищённых приложений в круглосуточный режим.

FIX-1005-12: примеры запросов в справочнике и спецификации больше не показывают тело, которое ручка не принимает

Было

Сгенерированные примеры на платформе Вайбкод показывали поле-массив и поле-объект пустыми там, где такое тело отправлять бессмысленно.

В примерах обновления: PATCH /v1/bookings/{id} печатал "resourceIds":[], а PATCH /v1/bizproc-templates/{id} — "documentType":[]. Скопировав такой пример ради переименования записи, читатель получал не результат, а одно из двух: бронирование отвечало 422 с кодом BITRIX_ERROR и сообщением Empty resource collection, а у шаблона бизнес-процесса поле documentType обновлением не применяется вовсе — запрос возвращал 200, не изменив тип документа.

В примерах создания пустыми печатались обязательные поля: POST /v1/bookings отправлял "resourceIds":[] и "datePeriod":{}, POST /v1/bizproc-templates — "templateData":[] и "documentType":[]. Такие запросы тоже отвергались: templateData — кодом MISSING_REQUIRED_FIELDS, остальные — на стороне Битрикс24.

Стало

Пример обновления не показывает поля, которые заменяются целиком, — ни массивы, ни объекты с описанной вложенной структурой. Пример создания показывает у обязательных полей рабочие значения: список идентификаторов ресурсов, период брони из from и to, тип документа из модуля, объекта и типа. У файла шаблона стоит явный плейсхолдер <base64-encoded .bpt file contents> — содержимое конкретного файла подставляет вызывающий, и образец написан так, чтобы его нельзя было принять за готовое значение. Те же значения появились в спецификации GET /v1/openapi.json как example соответствующих полей и в примерах ответа. Единственное исключение — documentType у шаблона бизнес-процесса: в схеме записи образца у него нет, потому что обновление это поле не применяет, и готовое значение там читалось бы как приглашение отправить запись, которая вернёт 200 и ничего не изменит. В схеме чтения образец остался, а описание поля в обеих схемах называет поведение словами. Пустой массив остался там, где он осмыслен, — у необязательных полей он по-прежнему значит «список пуст».

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

Поведение ручек не изменилось ни в одной из перечисленных: и раньше эти тела отвергались или не применялись, коды и сообщения об ошибках прежние. Менять в работающем коде ничего не нужно. Клиент, сгенерированный по спецификации, получит у перечисленных полей заполненный example.

FIX-1005-13: OpenAPI описывает все маршруты адресов

Было

В OpenAPI и справочнике API у адресов был описан только GET /v1/addresses/fields. Список, поиск, создание и операции по составному ключу работали, но генераторы клиентов и ИИ-агенты, читающие спецификацию, их не видели.

Стало

В полной спецификации, срезе crm и справочнике на обоих языках описаны GET /v1/addresses, POST /v1/addresses, POST /v1/addresses/search, а также GET, PATCH и DELETE /v1/addresses/{typeId}/{entityTypeId}/{entityId}. Поведение маршрутов не изменилось. Чтобы операции появились в генерируемом клиенте, обновите его из актуальной спецификации.

BC-1005-14: удаление записи журнала звонков ищет её среди 5000 последних записей

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

Было

DELETE /v1/calls/log/{callId} удалял запись на любой глубине личного журнала звонков: перед удалением обёртка читала журнал постранично до нахождения записи или конца журнала, без предела на число страниц. Ответ — 200.

Стало

Перед удалением просматриваются 5000 последних записей журнала (не больше 50 страниц). Запись глубже даёт 422 CALL_LOG_PREREAD_LIMIT_EXCEEDED, и ничего не удаляется: через API такую запись не удалить. Для записей среди 5000 последних ответ остаётся 200, отсутствующая запись по-прежнему даёт 404 ENTITY_NOT_FOUND.

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

Обрабатывать 422 CALL_LOG_PREREAD_LIMIT_EXCEEDED как окончательный отказ без повтора.

NEW-1005-15: Ресурсы календаря, занятость и статус участия во встрече

Добавлены ресурсы календаря: список, создание, переименование и удаление; бронирования ресурсов и занятость сотрудников. Интервалы со временем возвращают ISO-8601 со смещением часового пояса, интервалы на весь день — календарные даты без часового пояса. Статус участия позволяет получить и изменить ответ текущего пользователя: accepted, declined или invited. Требуется скоуп calendar; операции записи недоступны ключу READONLY. Несуществующий ресурс или событие возвращает 404 ENTITY_NOT_FOUND; неподтверждённая запись статуса возвращает 422 BITRIX_ERROR.

FIX-1005-16: OpenAPI описывает деактивацию сотрудника

Было

Работающий DELETE /v1/users/{id} отсутствовал в OpenAPI и справочнике API Вайбкод, поэтому генераторы клиентов не видели операцию.

Стало

Операция включена в полную спецификацию, срез user и справочник на обоих языках. Ответ остаётся HTTP 200 с success: true и data: { id, active: false, deactivated: true }; поле user необязательно. Тело запроса не требуется. Это деактивация сотрудника через ACTIVE=N, обратимая через PATCH /v1/users/{id} с active: true. Для появления операции в генерируемом клиенте обновите его из актуальной спецификации.